com.sun.grizzly.streams.StreamWriter Maven / Gradle / Ivy

Go to download
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License. You can obtain
 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
 * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
 * Sun designates this particular file as subject to the "Classpath" exception
 * as provided by Sun in the GPL Version 2 section of the License file that
 * accompanied this code.  If applicable, add the following below the License
 * Header, with the fields enclosed by brackets [] replaced by your own
 * identifying information: "Portions Copyrighted [year]
 * [name of copyright owner]"
 *
 * Contributor(s):
 *
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */
package com.sun.grizzly.streams;

import java.io.Closeable;

import java.io.IOException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import com.sun.grizzly.Buffer;
import com.sun.grizzly.CompletionHandler;
import com.sun.grizzly.Connection;

/**
 * Write the primitive Java types and arrays of primitives to some data sink.
 * This may include internal buffering for efficiency reasons.
 *
 * Note, that StreamWriter implementation may not be thread-safe.
 *
 * @author Ken Cavanaugh
 * @author Alexey Stashok
 */
public interface StreamWriter extends Closeable {

    /**
     * Returns the {@link StreamReader} mode.
     * true, if {@link StreamReader} is operating in blocking mode, or
     * false otherwise.
     *
     * @return the {@link StreamReader} mode.
     */
    public boolean isBlocking();

    /**
     * Sets the {@link StreamReader} mode.
     *
     * @param isBlocking true, if {@link StreamReader} is operating in
     * blocking mode, or false otherwise.
     */
    public void setBlocking(boolean isBlocking);

    /**
     * Make sure that all data that has been written is
     * flushed from the stream to its destination.
     */
    Future flush() throws IOException;

    /**
     * Make sure that all data that has been written is
     * flushed from the stream to its destination.
     */
    Future flush(CompletionHandler completionHandler)
            throws IOException;

    /**
     * Close the {@link StreamWriter} and make sure all data was flushed.
     */
    Future close(CompletionHandler completionHandler)
            throws IOException;

    /**
     * Write the boolean value to the StreamWriter.
     * 
     * @param data boolean value.
     * @throws java.io.IOException
     */
    void writeBoolean(boolean data) throws IOException;

    /**
     * Write the byte value to the StreamWriter.
     *
     * @param data byte value.
     * @throws java.io.IOException
     */
    void writeByte(byte data) throws IOException;

    /**
     * Write the char value to the StreamWriter.
     *
     * @param data char value.
     * @throws java.io.IOException
     */
    void writeChar(char data) throws IOException;

    /**
     * Write the short value to the StreamWriter.
     *
     * @param data short value.
     * @throws java.io.IOException
     */
    void writeShort(short data) throws IOException;

    /**
     * Write the int value to the StreamWriter.
     *
     * @param data int value.
     * @throws java.io.IOException
     */
    void writeInt(int data) throws IOException;

    /**
     * Write the long value to the StreamWriter.
     *
     * @param data long value.
     * @throws java.io.IOException
     */
    void writeLong(long data) throws IOException;

    /**
     * Write the float value to the StreamWriter.
     *
     * @param data float value.
     * @throws java.io.IOException
     */
    void writeFloat(float data) throws IOException;

    /**
     * Write the double value to the StreamWriter.
     *
     * @param data double value.
     * @throws java.io.IOException
     */
    void writeDouble(double data) throws IOException;

    /**
     * Write the array of boolean values to the StreamWriter.
     *
     * @param data array of boolean values.
     * @throws java.io.IOException
     */
    void writeBooleanArray(final boolean[] data) throws IOException;

    /**
     * Write the array of byte values to the StreamWriter.
     *
     * @param data array of byte values.
     * @throws java.io.IOException
     */
    void writeByteArray(final byte[] data) throws IOException;

    /**
     * Write the part of array of byte values to the
     * StreamWriter, using specific offset and length values.
     *
     * @param data array of byte values.
     * @param offset array offset to start from.
     * @param length number of bytes to write.
     * 
     * @throws java.io.IOException
     */
    void writeByteArray(final byte[] data, int offset, int length)
            throws IOException;

    /**
     * Write the array of char values to the StreamWriter.
     *
     * @param data array of char values.
     * @throws java.io.IOException
     */
    void writeCharArray(final char[] data) throws IOException;

    /**
     * Write the array of short values to the StreamWriter.
     *
     * @param data array of short values.
     * @throws java.io.IOException
     */
    void writeShortArray(short[] data) throws IOException;

    /**
     * Write the array of int values to the StreamWriter.
     *
     * @param data array of int values.
     * @throws java.io.IOException
     */
    void writeIntArray(int[] data) throws IOException;

    /**
     * Write the array of long values to the StreamWriter.
     *
     * @param data array of long values.
     * @throws java.io.IOException
     */
    void writeLongArray(long[] data) throws IOException;

    /**
     * Write the array of float values to the StreamWriter.
     *
     * @param data array of float values.
     * @throws java.io.IOException
     */
    void writeFloatArray(float[] data) throws IOException;

    /**
     * Write the array of double values to the StreamWriter.
     *
     * @param data array of double values.
     * @throws java.io.IOException
     */
    void writeDoubleArray(double[] data) throws IOException;

    /**
     * Write the {@link Buffer} to the StreamWriter.
     *
     * @param buffer {@link Buffer}.
     * 
     * @throws java.io.IOException
     */
    public void writeBuffer(Buffer buffer) throws IOException;

    /**
     * Puts {@link StreamReader} available data to this StreamWriter
     * This method will make possible direct writing from {@link StreamReader},
     * avoiding {@link Buffer} copying.
     *
     * @param stream {@link StreamReader}
     */
    void writeStream(StreamReader stream) throws IOException;

    /**
     * Get the {@link Connection} this StreamWriter belongs to.
     *
     * @return the {@link Connection} this StreamWriter belongs to.
     */
    Connection getConnection();

    /**
     * Get the current {@link Buffer}, where the StreamWriter buffers
     * output.
     * 
     * @return the current {@link Buffer}, where the StreamWriter buffers
     * output.
     */
    Buffer getBuffer();

    /**
     * Get the preferred {@link Buffer} size to be used for StreamWriter
     * write operations.
     *
     * @return the preferred {@link Buffer} size to be used for StreamWriter
     * write operations.
     */
    int getBufferSize();

    /**
     * Set the preferred {@link Buffer} size to be used for StreamWriter
     * write operations.
     *
     * @param size the preferred {@link Buffer} size to be used for
     * StreamWriter write operations.
     */
    void setBufferSize(int size);

    /**
     * Get the timeout for StreamWriter I/O operations.
     *
     * @param timeunit timeout unit {@link TimeUnit}.
     * @return the timeout for StreamWriter I/O operations.
     */
    long getTimeout(TimeUnit timeunit);

    /**
     * Set the timeout for StreamWriter I/O operations.
     *
     * @param timeout the timeout for StreamWriter I/O operations.
     * @param timeunit timeout unit {@link TimeUnit}.
     */
    void setTimeout(long timeout, TimeUnit timeunit);
}