com.google.code.yanf4j.buffer.IoBuffer Maven / Gradle / Ivy
Show all versions of xmemcached Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional information regarding
* copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License. You may obtain a
* copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.code.yanf4j.buffer;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.BufferOverflowException;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.CharBuffer;
import java.nio.DoubleBuffer;
import java.nio.FloatBuffer;
import java.nio.IntBuffer;
import java.nio.LongBuffer;
import java.nio.ReadOnlyBufferException;
import java.nio.ShortBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CharsetDecoder;
import java.nio.charset.CharsetEncoder;
import java.util.EnumSet;
import java.util.Set;
/**
* A byte buffer used by MINA applications.
*
* This is a replacement for {@link ByteBuffer}. Please refer to {@link ByteBuffer} documentation
* for preliminary usage. MINA does not use NIO {@link ByteBuffer} directly for two reasons:
*
* - It doesn't provide useful getters and putters such as
fill,
* get/putString, and get/putAsciiInt() enough.
* - It is difficult to write variable-length data due to its fixed capacity
*
*
*
* Allocation
*
* You can allocate a new heap buffer.
*
*
* IoBuffer buf = IoBuffer.allocate(1024, false);
*
*
* you can also allocate a new direct buffer:
*
*
* IoBuffer buf = IoBuffer.allocate(1024, true);
*
*
* or you can set the default buffer type.
*
*
* // Allocate heap buffer by default.
* IoBuffer.setUseDirectBuffer(false);
* // A new heap buffer is returned.
* IoBuffer buf = IoBuffer.allocate(1024);
*
*
*
*
* Wrapping existing NIO buffers and arrays
*
* This class provides a few wrap(...) methods that wraps any NIO buffers and byte arrays.
*
*
AutoExpand
*
* Writing variable-length data using NIO ByteBuffers is not really easy, and it is because
* its size is fixed. {@link IoBuffer} introduces autoExpand property. If
* autoExpand property is true, you never get {@link BufferOverflowException} or
* {@link IndexOutOfBoundsException} (except when index is negative). It automatically expands its
* capacity and limit value. For example:
*
*
* String greeting = messageBundle.getMessage("hello");
* IoBuffer buf = IoBuffer.allocate(16);
* // Turn on autoExpand (it is off by default)
* buf.setAutoExpand(true);
* buf.putString(greeting, utf8encoder);
*
*
* The underlying {@link ByteBuffer} is reallocated by {@link IoBuffer} behind the scene if the
* encoded data is larger than 16 bytes in the example above. Its capacity will double, and its
* limit will increase to the last position the string is written.
*
*
* AutoShrink
*
* You might also want to decrease the capacity of the buffer when most of the allocated memory area
* is not being used. {@link IoBuffer} provides autoShrink property to take care of this
* issue. If autoShrink is turned on, {@link IoBuffer} halves the capacity of the buffer
* when {@link #compact()} is invoked and only 1/4 or less of the current capacity is being used.
*
* You can also {@link #shrink()} method manually to shrink the capacity of the buffer.
*
* The underlying {@link ByteBuffer} is reallocated by {@link IoBuffer} behind the scene, and
* therefore {@link #buf()} will return a different {@link ByteBuffer} instance once capacity
* changes. Please also note {@link #compact()} or {@link #shrink()} will not decrease the capacity
* if the new capacity is less than the {@link #minimumCapacity()} of the buffer.
*
*
Derived Buffers
*
* Derived buffers are the buffers which were created by {@link #duplicate()}, {@link #slice()}, or
* {@link #asReadOnlyBuffer()}. They are useful especially when you broadcast the same messages to
* multiple {@link IoSession}s. Please note that the buffer derived from and its derived buffers are
* not both auto-expandable neither auto-shrinkable. Trying to call {@link #setAutoExpand(boolean)}
* or {@link #setAutoShrink(boolean)} with true parameter will raise an
* {@link IllegalStateException}.
*
*
* Changing Buffer Allocation Policy
*
* {@link IoBufferAllocator} interface lets you override the default buffer management behavior.
* There are two allocators provided out-of-the-box:
*
* - {@link SimpleBufferAllocator} (default)
* - {@link CachedBufferAllocator}
*
* You can implement your own allocator and use it by calling
* {@link #setAllocator(IoBufferAllocator)}.
*
*
* @author The Apache MINA Project ([email protected])
* @version $Rev: 748525 $, $Date: 2009-02-27 14:45:31 +0100 (Fri, 27 Feb 2009) $
*/
public abstract class IoBuffer implements Comparable {
/** The allocator used to create new buffers */
private static IoBufferAllocator allocator = new SimpleBufferAllocator();
/** A flag indicating which type of buffer we are using : heap or direct */
private static boolean useDirectBuffer = false;
/**
* Returns the allocator used by existing and new buffers
*/
public static IoBufferAllocator getAllocator() {
return allocator;
}
/**
* Sets the allocator used by existing and new buffers
*/
public static void setAllocator(IoBufferAllocator newAllocator) {
if (newAllocator == null) {
throw new NullPointerException("allocator");
}
IoBufferAllocator oldAllocator = allocator;
allocator = newAllocator;
if (null != oldAllocator) {
oldAllocator.dispose();
}
}
/**
* Returns true if and only if a direct buffer is allocated by default when the type of
* the new buffer is not specified. The default value is false.
*/
public static boolean isUseDirectBuffer() {
return useDirectBuffer;
}
/**
* Sets if a direct buffer should be allocated by default when the type of the new buffer is not
* specified. The default value is false.
*/
public static void setUseDirectBuffer(boolean useDirectBuffer) {
IoBuffer.useDirectBuffer = useDirectBuffer;
}
/**
* Returns the direct or heap buffer which is capable to store the specified amount of bytes.
*
* @param capacity the capacity of the buffer
*
* @see #setUseDirectBuffer(boolean)
*/
public static IoBuffer allocate(int capacity) {
return allocate(capacity, useDirectBuffer);
}
/**
* Returns the buffer which is capable of the specified size.
*
* @param capacity the capacity of the buffer
* @param direct true to get a direct buffer, false to get a heap buffer.
*/
public static IoBuffer allocate(int capacity, boolean direct) {
if (capacity < 0) {
throw new IllegalArgumentException("capacity: " + capacity);
}
return allocator.allocate(capacity, direct);
}
/**
* Wraps the specified NIO {@link ByteBuffer} into MINA buffer.
*/
public static IoBuffer wrap(ByteBuffer nioBuffer) {
return allocator.wrap(nioBuffer);
}
/**
* Wraps the specified byte array into MINA heap buffer.
*/
public static IoBuffer wrap(byte[] byteArray) {
return wrap(ByteBuffer.wrap(byteArray));
}
/**
* Wraps the specified byte array into MINA heap buffer.
*/
public static IoBuffer wrap(byte[] byteArray, int offset, int length) {
return wrap(ByteBuffer.wrap(byteArray, offset, length));
}
/**
* Normalizes the specified capacity of the buffer to power of 2, which is often helpful for
* optimal memory usage and performance. If it is greater than or equal to
* {@link Integer#MAX_VALUE}, it returns {@link Integer#MAX_VALUE}. If it is zero, it returns
* zero.
*/
protected static int normalizeCapacity(int requestedCapacity) {
switch (requestedCapacity) {
case 0:
case 1 << 0:
case 1 << 1:
case 1 << 2:
case 1 << 3:
case 1 << 4:
case 1 << 5:
case 1 << 6:
case 1 << 7:
case 1 << 8:
case 1 << 9:
case 1 << 10:
case 1 << 11:
case 1 << 12:
case 1 << 13:
case 1 << 14:
case 1 << 15:
case 1 << 16:
case 1 << 17:
case 1 << 18:
case 1 << 19:
case 1 << 21:
case 1 << 22:
case 1 << 23:
case 1 << 24:
case 1 << 25:
case 1 << 26:
case 1 << 27:
case 1 << 28:
case 1 << 29:
case 1 << 30:
case Integer.MAX_VALUE:
return requestedCapacity;
}
int newCapacity = 1;
while (newCapacity < requestedCapacity) {
newCapacity <<= 1;
if (newCapacity < 0) {
return Integer.MAX_VALUE;
}
}
return newCapacity;
}
/**
* Creates a new instance. This is an empty constructor.
*/
protected IoBuffer() {}
/**
* Declares this buffer and all its derived buffers are not used anymore so that it can be reused
* by some {@link IoBufferAllocator} implementations. It is not mandatory to call this method, but
* you might want to invoke this method for maximum performance.
*/
public abstract void free();
/**
* Returns the underlying NIO buffer instance.
*/
public abstract ByteBuffer buf();
/**
* @see ByteBuffer#isDirect()
*/
public abstract boolean isDirect();
/**
* returns true if and only if this buffer is derived from other buffer via
* {@link #duplicate()}, {@link #slice()} or {@link #asReadOnlyBuffer()}.
*/
public abstract boolean isDerived();
/**
* @see ByteBuffer#isReadOnly()
*/
public abstract boolean isReadOnly();
/**
* Returns the minimum capacity of this buffer which is used to determine the new capacity of the
* buffer shrunk by {@link #compact()} and {@link #shrink()} operation. The default value is the
* initial capacity of the buffer.
*/
public abstract int minimumCapacity();
/**
* Sets the minimum capacity of this buffer which is used to determine the new capacity of the
* buffer shrunk by {@link #compact()} and {@link #shrink()} operation. The default value is the
* initial capacity of the buffer.
*/
public abstract IoBuffer minimumCapacity(int minimumCapacity);
/**
* @see ByteBuffer#capacity()
*/
public abstract int capacity();
/**
* Increases the capacity of this buffer. If the new capacity is less than or equal to the current
* capacity, this method returns silently. If the new capacity is greater than the current
* capacity, the buffer is reallocated while retaining the position, limit, mark and the content
* of the buffer.
*/
public abstract IoBuffer capacity(int newCapacity);
/**
* Returns true if and only if autoExpand is turned on.
*/
public abstract boolean isAutoExpand();
/**
* Turns on or off autoExpand.
*/
public abstract IoBuffer setAutoExpand(boolean autoExpand);
/**
* Returns true if and only if autoShrink is turned on.
*/
public abstract boolean isAutoShrink();
/**
* Turns on or off autoShrink.
*/
public abstract IoBuffer setAutoShrink(boolean autoShrink);
/**
* Changes the capacity and limit of this buffer so this buffer get the specified
* expectedRemaining room from the current position. This method works even if you didn't
* set autoExpand to true.
*/
public abstract IoBuffer expand(int expectedRemaining);
/**
* Changes the capacity and limit of this buffer so this buffer get the specified
* expectedRemaining room from the specified position. This method works even if
* you didn't set autoExpand to true.
*/
public abstract IoBuffer expand(int position, int expectedRemaining);
/**
* Changes the capacity of this buffer so this buffer occupies as less memory as possible while
* retaining the position, limit and the buffer content between the position and limit. The
* capacity of the buffer never becomes less than {@link #minimumCapacity()}. The mark is
* discarded once the capacity changes.
*/
public abstract IoBuffer shrink();
/**
* @see java.nio.Buffer#position()
*/
public abstract int position();
/**
* @see java.nio.Buffer#position(int)
*/
public abstract IoBuffer position(int newPosition);
/**
* @see java.nio.Buffer#limit()
*/
public abstract int limit();
/**
* @see java.nio.Buffer#limit(int)
*/
public abstract IoBuffer limit(int newLimit);
/**
* @see java.nio.Buffer#mark()
*/
public abstract IoBuffer mark();
/**
* Returns the position of the current mark. This method returns -1 if no mark is set.
*/
public abstract int markValue();
/**
* @see java.nio.Buffer#reset()
*/
public abstract IoBuffer reset();
/**
* @see java.nio.Buffer#clear()
*/
public abstract IoBuffer clear();
/**
* Clears this buffer and fills its content with NUL. The position is set to zero, the
* limit is set to the capacity, and the mark is discarded.
*/
public abstract IoBuffer sweep();
/**
* double Clears this buffer and fills its content with value. The position is set to
* zero, the limit is set to the capacity, and the mark is discarded.
*/
public abstract IoBuffer sweep(byte value);
/**
* @see java.nio.Buffer#flip()
*/
public abstract IoBuffer flip();
/**
* @see java.nio.Buffer#rewind()
*/
public abstract IoBuffer rewind();
/**
* @see java.nio.Buffer#remaining()
*/
public abstract int remaining();
/**
* @see java.nio.Buffer#hasRemaining()
*/
public abstract boolean hasRemaining();
/**
* @see ByteBuffer#duplicate()
*/
public abstract IoBuffer duplicate();
/**
* @see ByteBuffer#slice()
*/
public abstract IoBuffer slice();
/**
* @see ByteBuffer#asReadOnlyBuffer()
*/
public abstract IoBuffer asReadOnlyBuffer();
/**
* @see ByteBuffer#hasArray()
*/
public abstract boolean hasArray();
/**
* @see ByteBuffer#array()
*/
public abstract byte[] array();
/**
* @see ByteBuffer#arrayOffset()
*/
public abstract int arrayOffset();
/**
* @see ByteBuffer#get()
*/
public abstract byte get();
/**
* Reads one unsigned byte as a short integer.
*/
public abstract short getUnsigned();
/**
* @see ByteBuffer#put(byte)
*/
public abstract IoBuffer put(byte b);
/**
* @see ByteBuffer#get(int)
*/
public abstract byte get(int index);
/**
* Reads one byte as an unsigned short integer.
*/
public abstract short getUnsigned(int index);
/**
* @see ByteBuffer#put(int, byte)
*/
public abstract IoBuffer put(int index, byte b);
/**
* @see ByteBuffer#get(byte[], int, int)
*/
public abstract IoBuffer get(byte[] dst, int offset, int length);
/**
* @see ByteBuffer#get(byte[])
*/
public abstract IoBuffer get(byte[] dst);
/**
* TODO document me.
*/
public abstract IoBuffer getSlice(int index, int length);
/**
* TODO document me.
*/
public abstract IoBuffer getSlice(int length);
/**
* Writes the content of the specified src into this buffer.
*/
public abstract IoBuffer put(ByteBuffer src);
/**
* Writes the content of the specified src into this buffer.
*/
public abstract IoBuffer put(IoBuffer src);
/**
* @see ByteBuffer#put(byte[], int, int)
*/
public abstract IoBuffer put(byte[] src, int offset, int length);
/**
* @see ByteBuffer#put(byte[])
*/
public abstract IoBuffer put(byte[] src);
/**
* @see ByteBuffer#compact()
*/
public abstract IoBuffer compact();
/**
* @see ByteBuffer#order()
*/
public abstract ByteOrder order();
/**
* @see ByteBuffer#order(ByteOrder)
*/
public abstract IoBuffer order(ByteOrder bo);
/**
* @see ByteBuffer#getChar()
*/
public abstract char getChar();
/**
* @see ByteBuffer#putChar(char)
*/
public abstract IoBuffer putChar(char value);
/**
* @see ByteBuffer#getChar(int)
*/
public abstract char getChar(int index);
/**
* @see ByteBuffer#putChar(int, char)
*/
public abstract IoBuffer putChar(int index, char value);
/**
* @see ByteBuffer#asCharBuffer()
*/
public abstract CharBuffer asCharBuffer();
/**
* @see ByteBuffer#getShort()
*/
public abstract short getShort();
/**
* Reads two bytes unsigned integer.
*/
public abstract int getUnsignedShort();
/**
* @see ByteBuffer#putShort(short)
*/
public abstract IoBuffer putShort(short value);
/**
* @see ByteBuffer#getShort()
*/
public abstract short getShort(int index);
/**
* Reads two bytes unsigned integer.
*/
public abstract int getUnsignedShort(int index);
/**
* @see ByteBuffer#putShort(int, short)
*/
public abstract IoBuffer putShort(int index, short value);
/**
* @see ByteBuffer#asShortBuffer()
*/
public abstract ShortBuffer asShortBuffer();
/**
* @see ByteBuffer#getInt()
*/
public abstract int getInt();
/**
* Reads four bytes unsigned integer.
*/
public abstract long getUnsignedInt();
/**
* Relative get method for reading a medium int value.
*
*
* Reads the next three bytes at this buffer's current position, composing them into an int value
* according to the current byte order, and then increments the position by three.
*
*
* @return The medium int value at the buffer's current position
*/
public abstract int getMediumInt();
/**
* Relative get method for reading an unsigned medium int value.
*
*
* Reads the next three bytes at this buffer's current position, composing them into an int value
* according to the current byte order, and then increments the position by three.
*
*
* @return The unsigned medium int value at the buffer's current position
*/
public abstract int getUnsignedMediumInt();
/**
* Absolute get method for reading a medium int value.
*
*
* Reads the next three bytes at this buffer's current position, composing them into an int value
* according to the current byte order.
*
*
* @param index The index from which the medium int will be read
* @return The medium int value at the given index
*
* @throws IndexOutOfBoundsException If index is negative or not smaller than the
* buffer's limit
*/
public abstract int getMediumInt(int index);
/**
* Absolute get method for reading an unsigned medium int value.
*
*
* Reads the next three bytes at this buffer's current position, composing them into an int value
* according to the current byte order.
*
*
* @param index The index from which the unsigned medium int will be read
* @return The unsigned medium int value at the given index
*
* @throws IndexOutOfBoundsException If index is negative or not smaller than the
* buffer's limit
*/
public abstract int getUnsignedMediumInt(int index);
/**
* Relative put method for writing a medium int value.
*
*
* Writes three bytes containing the given int value, in the current byte order, into this buffer
* at the current position, and then increments the position by three.
*
*
* @param value The medium int value to be written
*
* @return This buffer
*
* @throws BufferOverflowException If there are fewer than three bytes remaining in this buffer
*
* @throws ReadOnlyBufferException If this buffer is read-only
*/
public abstract IoBuffer putMediumInt(int value);
/**
* Absolute put method for writing a medium int value.
*
*
* Writes three bytes containing the given int value, in the current byte order, into this buffer
* at the given index.
*
*
* @param index The index at which the bytes will be written
*
* @param value The medium int value to be written
*
* @return This buffer
*
* @throws IndexOutOfBoundsException If index is negative or not smaller than the
* buffer's limit, minus three
*
* @throws ReadOnlyBufferException If this buffer is read-only
*/
public abstract IoBuffer putMediumInt(int index, int value);
/**
* @see ByteBuffer#putInt(int)
*/
public abstract IoBuffer putInt(int value);
/**
* @see ByteBuffer#getInt(int)
*/
public abstract int getInt(int index);
/**
* Reads four bytes unsigned integer.
*/
public abstract long getUnsignedInt(int index);
/**
* @see ByteBuffer#putInt(int, int)
*/
public abstract IoBuffer putInt(int index, int value);
/**
* @see ByteBuffer#asIntBuffer()
*/
public abstract IntBuffer asIntBuffer();
/**
* @see ByteBuffer#getLong()
*/
public abstract long getLong();
/**
* @see ByteBuffer#putLong(int, long)
*/
public abstract IoBuffer putLong(long value);
/**
* @see ByteBuffer#getLong(int)
*/
public abstract long getLong(int index);
/**
* @see ByteBuffer#putLong(int, long)
*/
public abstract IoBuffer putLong(int index, long value);
/**
* @see ByteBuffer#asLongBuffer()
*/
public abstract LongBuffer asLongBuffer();
/**
* @see ByteBuffer#getFloat()
*/
public abstract float getFloat();
/**
* @see ByteBuffer#putFloat(float)
*/
public abstract IoBuffer putFloat(float value);
/**
* @see ByteBuffer#getFloat(int)
*/
public abstract float getFloat(int index);
/**
* @see ByteBuffer#putFloat(int, float)
*/
public abstract IoBuffer putFloat(int index, float value);
/**
* @see ByteBuffer#asFloatBuffer()
*/
public abstract FloatBuffer asFloatBuffer();
/**
* @see ByteBuffer#getDouble()
*/
public abstract double getDouble();
/**
* @see ByteBuffer#putDouble(double)
*/
public abstract IoBuffer putDouble(double value);
/**
* @see ByteBuffer#getDouble(int)
*/
public abstract double getDouble(int index);
/**
* @see ByteBuffer#putDouble(int, double)
*/
public abstract IoBuffer putDouble(int index, double value);
/**
* @see ByteBuffer#asDoubleBuffer()
*/
public abstract DoubleBuffer asDoubleBuffer();
/**
* Returns an {@link InputStream} that reads the data from this buffer. {@link InputStream#read()}
* returns -1 if the buffer position reaches to the limit.
*/
public abstract InputStream asInputStream();
/**
* Returns an {@link OutputStream} that appends the data into this buffer. Please note that the
* {@link OutputStream#write(int)} will throw a {@link BufferOverflowException} instead of an
* {@link IOException} in case of buffer overflow. Please set autoExpand property by
* calling {@link #setAutoExpand(boolean)} to prevent the unexpected runtime exception.
*/
public abstract OutputStream asOutputStream();
/**
* Returns hexdump of this buffer. The data and pointer are not changed as a result of this method
* call.
*
* @return hexidecimal representation of this buffer
*/
public abstract String getHexDump();
/**
* Return hexdump of this buffer with limited length.
*
* @param lengthLimit The maximum number of bytes to dump from the current buffer position.
* @return hexidecimal representation of this buffer
*/
public abstract String getHexDump(int lengthLimit);
// //////////////////////////////
// String getters and putters //
// //////////////////////////////
/**
* Reads a NUL-terminated string from this buffer using the specified
* decoder and returns it. This method reads until the limit of this buffer if no
* NUL is found.
*/
public abstract String getString(CharsetDecoder decoder) throws CharacterCodingException;
/**
* Reads a NUL-terminated string from this buffer using the specified
* decoder and returns it.
*
* @param fieldSize the maximum number of bytes to read
*/
public abstract String getString(int fieldSize, CharsetDecoder decoder)
throws CharacterCodingException;
/**
* Writes the content of in into this buffer using the specified encoder
* . This method doesn't terminate string with NUL. 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 in into this buffer as a NUL-terminated string
* using the specified encoder.
*
* If the charset name of the encoder is UTF-16, you cannot specify odd fieldSize,
* and this method will append two NULs as a terminator.
*
* Please note that this method doesn't terminate with NUL if the input string is
* longer than fieldSize.
*
* @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 decoder and returns it. This method is a shortcut for
* getPrefixedString(2, decoder).
*/
public abstract String getPrefixedString(CharsetDecoder decoder) throws CharacterCodingException;
/**
* Reads a string which has a length field before the actual encoded string, using the specified
* decoder 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 in into this buffer as a string which has a 16-bit length
* field before the actual encoded string, using the specified encoder. This method
* is a shortcut for putPrefixedString(in, 2, 0, encoder).
*
* @throws BufferOverflowException if the specified string doesn't fit
*/
public abstract IoBuffer putPrefixedString(CharSequence in, CharsetEncoder encoder)
throws CharacterCodingException;
/**
* Writes the content of in into this buffer as a string which has a 16-bit length
* field before the actual encoded string, using the specified encoder. This method
* is a shortcut for putPrefixedString(in, prefixLength, 0, encoder).
*
* @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 in into this buffer as a string which has a 16-bit length
* field before the actual encoded string, using the specified encoder. This method
* is a shortcut for putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder) .
*
* @param prefixLength the length of the length field (1, 2, or 4)
* @param padding the number of padded NULs (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 in into this buffer as a string which has a 16-bit length
* field before the actual encoded string, using the specified encoder.
*
* @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 classLoader.
*/
public abstract Object getObject(final ClassLoader classLoader) throws ClassNotFoundException;
/**
* Writes the specified Java object to the buffer.
*/
public abstract IoBuffer putObject(Object o);
/**
* Returns true 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 prefixedDataAvailable( prefixLength, Integer.MAX_VALUE ). 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 true 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 maxDataLength
*/
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 -1 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 size 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 NUL (0x00). This method moves buffer position forward.
*/
public abstract IoBuffer fill(int size);
/**
* Fills this buffer with NUL (0x00). 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 The enum type to return
* @param enumClass The enum's class object
*/
public abstract > E getEnum(Class enumClass);
/**
* Reads a byte from the buffer and returns the correlating enum constant defined by the specified
* enum type.
*
* @param 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 getEnum(int index, Class enumClass);
/**
* Reads a short from the buffer and returns the correlating enum constant defined by the
* specified enum type.
*
* @param The enum type to return
* @param enumClass The enum's class object
*/
public abstract > E getEnumShort(Class enumClass);
/**
* Reads a short from the buffer and returns the correlating enum constant defined by the
* specified enum type.
*
* @param 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 getEnumShort(int index, Class enumClass);
/**
* Reads an int from the buffer and returns the correlating enum constant defined by the specified
* enum type.
*
* @param The enum type to return
* @param enumClass The enum's class object
*/
public abstract > E getEnumInt(Class enumClass);
/**
* Reads an int from the buffer and returns the correlating enum constant defined by the specified
* enum type.
*
* @param 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 getEnumInt(int index, Class 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}.
*
*
* 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.
*
*
* @param the enum type
* @param enumClass the enum class used to create the EnumSet
* @return the EnumSet representation of the bit vector
*/
public abstract > EnumSet getEnumSet(Class enumClass);
/**
* Reads a byte sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param 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 > EnumSet getEnumSet(int index, Class enumClass);
/**
* Reads a short sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param the enum type
* @param enumClass the enum class used to create the EnumSet
* @return the EnumSet representation of the bit vector
*/
public abstract > EnumSet getEnumSetShort(Class enumClass);
/**
* Reads a short sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param 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 > EnumSet getEnumSetShort(int index, Class enumClass);
/**
* Reads an int sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param the enum type
* @param enumClass the enum class used to create the EnumSet
* @return the EnumSet representation of the bit vector
*/
public abstract > EnumSet getEnumSetInt(Class enumClass);
/**
* Reads an int sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param 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 > EnumSet getEnumSetInt(int index, Class enumClass);
/**
* Reads a long sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param the enum type
* @param enumClass the enum class used to create the EnumSet
* @return the EnumSet representation of the bit vector
*/
public abstract > EnumSet getEnumSetLong(Class enumClass);
/**
* Reads a long sized bit vector and converts it to an {@link EnumSet}.
*
* @see #getEnumSet(Class)
* @param 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 > EnumSet getEnumSetLong(int index, Class enumClass);
/**
* Writes the specified {@link Set} to the buffer as a byte sized bit vector.
*
* @param the enum type of the Set
* @param set the enum set to write to the buffer
*/
public abstract > IoBuffer putEnumSet(Set set);
/**
* Writes the specified {@link Set} to the buffer as a byte sized bit vector.
*
* @param 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 > IoBuffer putEnumSet(int index, Set set);
/**
* Writes the specified {@link Set} to the buffer as a short sized bit vector.
*
* @param the enum type of the Set
* @param set the enum set to write to the buffer
*/
public abstract > IoBuffer putEnumSetShort(Set set);
/**
* Writes the specified {@link Set} to the buffer as a short sized bit vector.
*
* @param 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 > IoBuffer putEnumSetShort(int index, Set set);
/**
* Writes the specified {@link Set} to the buffer as an int sized bit vector.
*
* @param the enum type of the Set
* @param set the enum set to write to the buffer
*/
public abstract > IoBuffer putEnumSetInt(Set set);
/**
* Writes the specified {@link Set} to the buffer as an int sized bit vector.
*
* @param 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 > IoBuffer putEnumSetInt(int index, Set set);
/**
* Writes the specified {@link Set} to the buffer as a long sized bit vector.
*
* @param the enum type of the Set
* @param set the enum set to write to the buffer
*/
public abstract > IoBuffer putEnumSetLong(Set set);
/**
* Writes the specified {@link Set} to the buffer as a long sized bit vector.
*
* @param 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 > IoBuffer putEnumSetLong(int index, Set set);
}