iobuffer.java

mina是以Java实现的一个开源的网络程序框架

     * Writes the content of <code>in</code> into this buffer using the
     * specified <code>encoder</code>.  This method doesn't terminate
     * string with <tt>NUL</tt>.  You have to do it by yourself.
     *
     * @throws BufferOverflowException if the specified string doesn't fit
     */
    public abstract IoBuffer putString(CharSequence val, CharsetEncoder encoder)
            throws CharacterCodingException;

    /**
     * Writes the content of <code>in</code> into this buffer as a
     * <code>NUL</code>-terminated string using the specified
     * <code>encoder</code>.
     * <p>
     * If the charset name of the encoder is UTF-16, you cannot specify
     * odd <code>fieldSize</code>, and this method will append two
     * <code>NUL</code>s as a terminator.
     * <p>
     * Please note that this method doesn't terminate with <code>NUL</code>
     * if the input string is longer than <tt>fieldSize</tt>.
     *
     * @param fieldSize the maximum number of bytes to write
     */
    public abstract IoBuffer putString(CharSequence val, int fieldSize,
            CharsetEncoder encoder) throws CharacterCodingException;

    /**
     * Reads a string which has a 16-bit length field before the actual
     * encoded string, using the specified <code>decoder</code> and returns it.
     * This method is a shortcut for <tt>getPrefixedString(2, decoder)</tt>.
     */
    public abstract String getPrefixedString(CharsetDecoder decoder)
            throws CharacterCodingException;

    /**
     * Reads a string which has a length field before the actual
     * encoded string, using the specified <code>decoder</code> and returns it.
     *
     * @param prefixLength the length of the length field (1, 2, or 4)
     */
    public abstract String getPrefixedString(int prefixLength, CharsetDecoder decoder)
            throws CharacterCodingException;

    /**
     * Writes the content of <code>in</code> into this buffer as a
     * string which has a 16-bit length field before the actual
     * encoded string, using the specified <code>encoder</code>.
     * This method is a shortcut for <tt>putPrefixedString(in, 2, 0, encoder)</tt>.
     *
     * @throws BufferOverflowException if the specified string doesn't fit
     */
    public abstract IoBuffer putPrefixedString(CharSequence in, CharsetEncoder encoder)
            throws CharacterCodingException;

    /**
     * Writes the content of <code>in</code> into this buffer as a
     * string which has a 16-bit length field before the actual
     * encoded string, using the specified <code>encoder</code>.
     * This method is a shortcut for <tt>putPrefixedString(in, prefixLength, 0, encoder)</tt>.
     *
     * @param prefixLength the length of the length field (1, 2, or 4)
     *
     * @throws BufferOverflowException if the specified string doesn't fit
     */
    public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength,
            CharsetEncoder encoder) throws CharacterCodingException;

    /**
     * Writes the content of <code>in</code> into this buffer as a
     * string which has a 16-bit length field before the actual
     * encoded string, using the specified <code>encoder</code>.
     * This method is a shortcut for <tt>putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder)</tt>.
     *
     * @param prefixLength the length of the length field (1, 2, or 4)
     * @param padding      the number of padded <tt>NUL</tt>s (1 (or 0), 2, or 4)
     *
     * @throws BufferOverflowException if the specified string doesn't fit
     */
    public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength,
            int padding, CharsetEncoder encoder)
            throws CharacterCodingException;

    /**
     * Writes the content of <code>in</code> into this buffer as a
     * string which has a 16-bit length field before the actual
     * encoded string, using the specified <code>encoder</code>.
     *
     * @param prefixLength the length of the length field (1, 2, or 4)
     * @param padding      the number of padded bytes (1 (or 0), 2, or 4)
     * @param padValue     the value of padded bytes
     *
     * @throws BufferOverflowException if the specified string doesn't fit
     */
    public abstract IoBuffer putPrefixedString(CharSequence val, int prefixLength,
            int padding, byte padValue, CharsetEncoder encoder)
            throws CharacterCodingException;

    /**
     * Reads a Java object from the buffer using the context {@link ClassLoader}
     * of the current thread.
     */
    public abstract Object getObject() throws ClassNotFoundException;

    /**
     * Reads a Java object from the buffer using the specified <tt>classLoader</tt>.
     */
    public abstract Object getObject(final ClassLoader classLoader)
            throws ClassNotFoundException;

    /**
     * Writes the specified Java object to the buffer.
     */
    public abstract IoBuffer putObject(Object o);

    /**
     * Returns <tt>true</tt> if this buffer contains a data which has a data
     * length as a prefix and the buffer has remaining data as enough as
     * specified in the data length field.  This method is identical with
     * <tt>prefixedDataAvailable( prefixLength, Integer.MAX_VALUE )</tt>.
     * Please not that using this method can allow DoS (Denial of Service)
     * attack in case the remote peer sends too big data length value.
     * It is recommended to use {@link #prefixedDataAvailable(int, int)}
     * instead.
     *
     * @param prefixLength the length of the prefix field (1, 2, or 4)
     *
     * @throws IllegalArgumentException if prefixLength is wrong
     * @throws BufferDataException      if data length is negative
     */
    public abstract boolean prefixedDataAvailable(int prefixLength);

    /**
     * Returns <tt>true</tt> if this buffer contains a data which has a data
     * length as a prefix and the buffer has remaining data as enough as
     * specified in the data length field.
     *
     * @param prefixLength  the length of the prefix field (1, 2, or 4)
     * @param maxDataLength the allowed maximum of the read data length
     *
     * @throws IllegalArgumentException if prefixLength is wrong
     * @throws BufferDataException      if data length is negative or greater then <tt>maxDataLength</tt>
     */
    public abstract boolean prefixedDataAvailable(int prefixLength, int maxDataLength);

    /////////////////////
    // IndexOf methods //
    /////////////////////

    /**
     * Returns the first occurence position of the specified byte from the current position to
     * the current limit.
     *
     * @return <tt>-1</tt> if the specified byte is not found
     */
    public abstract int indexOf(byte b);

    //////////////////////////
    // Skip or fill methods //
    //////////////////////////

    /**
     * Forwards the position of this buffer as the specified <code>size</code>
     * bytes.
     */
    public abstract IoBuffer skip(int size);

    /**
     * Fills this buffer with the specified value.
     * This method moves buffer position forward.
     */
    public abstract IoBuffer fill(byte value, int size);

    /**
     * Fills this buffer with the specified value.
     * This method does not change buffer position.
     */
    public abstract IoBuffer fillAndReset(byte value, int size);

    /**
     * Fills this buffer with <code>NUL (0x00)</code>.
     * This method moves buffer position forward.
     */
    public abstract IoBuffer fill(int size);

    /**
     * Fills this buffer with <code>NUL (0x00)</code>.
     * This method does not change buffer position.
     */
    public abstract IoBuffer fillAndReset(int size);

    //////////////////////////
    // Enum methods         //
    //////////////////////////

    /**
     * Reads a byte from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnum(Class<E> enumClass);

    /**
     * Reads a byte from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param index  the index from which the byte will be read
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnum(int index, Class<E> enumClass);

    /**
     * Reads a short from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnumShort(Class<E> enumClass);

    /**
     * Reads a short from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param index  the index from which the bytes will be read
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnumShort(int index, Class<E> enumClass);

    /**
     * Reads an int from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnumInt(Class<E> enumClass);

    /**
     * Reads an int from the buffer and returns the correlating enum constant defined
     * by the specified enum type.
     *
     * @param <E> The enum type to return
     * @param index  the index from which the bytes will be read
     * @param enumClass  The enum's class object
     */
    public abstract <E extends Enum<E>> E getEnumInt(int index, Class<E> enumClass);

    /**
     * Writes an enum's ordinal value to the buffer as a byte.
     *
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnum(Enum<?> e);

    /**
     * Writes an enum's ordinal value to the buffer as a byte.
     *
     * @param index The index at which the byte will be written
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnum(int index, Enum<?> e);

    /**
     * Writes an enum's ordinal value to the buffer as a short.
     *
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnumShort(Enum<?> e);

    /**
     * Writes an enum's ordinal value to the buffer as a short.
     *
     * @param index The index at which the bytes will be written
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnumShort(int index, Enum<?> e);

    /**
     * Writes an enum's ordinal value to the buffer as an integer.
     *
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnumInt(Enum<?> e);

    /**
     * Writes an enum's ordinal value to the buffer as an integer.
     *
     * @param index The index at which the bytes will be written
     * @param e  The enum to write to the buffer
     */
    public abstract IoBuffer putEnumInt(int index, Enum<?> e);

    //////////////////////////
    // EnumSet methods      //
    //////////////////////////

    /**
     * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
     *
     * <p>Each bit is mapped to a value in the specified enum.  The least significant
     * bit maps to the first entry in the specified enum and each subsequent bit maps
     * to each subsequent bit as mapped to the subsequent enum value.</p>
     *
     * @param <E>  the enum type
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSet(Class<E> enumClass);

    /**
     * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param index  the index from which the byte will be read
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSet(int index,
            Class<E> enumClass);

    /**
     * Reads a short sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetShort(Class<E> enumClass);

    /**
     * Reads a short sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param index  the index from which the bytes will be read
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetShort(int index,
            Class<E> enumClass);

    /**
     * Reads an int sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetInt(Class<E> enumClass);

    /**
     * Reads an int sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param index  the index from which the bytes will be read
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetInt(int index,
            Class<E> enumClass);

    /**
     * Reads a long sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetLong(Class<E> enumClass);

    /**
     * Reads a long sized bit vector and converts it to an {@link EnumSet}.
     *
     * @see #getEnumSet(Class)
     * @param <E>  the enum type
     * @param index  the index from which the bytes will be read
     * @param enumClass  the enum class used to create the EnumSet
     * @return the EnumSet representation of the bit vector
     */
    public abstract <E extends Enum<E>> EnumSet<E> getEnumSetLong(int index,
            Class<E> enumClass);

    /**
     * Writes the specified {@link Set} to the buffer as a byte sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSet(Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as a byte sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param index  the index at which the byte will be written
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSet(int index, Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as a short sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as a short sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param index  the index at which the bytes will be written
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(int index, Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as an int sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as an int sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param index  the index at which the bytes will be written
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(int index, Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as a long sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(Set<E> set);

    /**
     * Writes the specified {@link Set} to the buffer as a long sized bit vector.
     *
     * @param <E> the enum type of the Set
     * @param index  the index at which the bytes will be written
     * @param set  the enum set to write to the buffer
     */
    public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(int index, Set<E> set);
}