Class IoBuffer
- java.lang.Object
-
- com.google.code.yanf4j.buffer.IoBuffer
-
- All Implemented Interfaces:
java.lang.Comparable<IoBuffer>
- Direct Known Subclasses:
AbstractIoBuffer,IoBufferWrapper
public abstract class IoBuffer extends java.lang.Object implements java.lang.Comparable<IoBuffer>
A byte buffer used by MINA applications.This is a replacement for
ByteBuffer. Please refer toByteBufferdocumentation for preliminary usage. MINA does not use NIOByteBufferdirectly for two reasons:- It doesn't provide useful getters and putters such as
fill,get/putString, andget/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.
IoBufferintroduces autoExpand property. If autoExpand property is true, you never getBufferOverflowExceptionorIndexOutOfBoundsException(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 underlyingByteBufferis reallocated byIoBufferbehind 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.
IoBufferprovides autoShrink property to take care of this issue. If autoShrink is turned on,IoBufferhalves the capacity of the buffer whencompact()is invoked and only 1/4 or less of the current capacity is being used.You can also
shrink()method manually to shrink the capacity of the buffer.The underlying
ByteBufferis reallocated byIoBufferbehind the scene, and thereforebuf()will return a differentByteBufferinstance once capacity changes. Please also notecompact()orshrink()will not decrease the capacity if the new capacity is less than theminimumCapacity()of the buffer.Derived Buffers
Derived buffers are the buffers which were created by
duplicate(),slice(), orasReadOnlyBuffer(). They are useful especially when you broadcast the same messages to multipleIoSessions. Please note that the buffer derived from and its derived buffers are not both auto-expandable neither auto-shrinkable. Trying to callsetAutoExpand(boolean)orsetAutoShrink(boolean)with true parameter will raise anIllegalStateException.Changing Buffer Allocation Policy
IoBufferAllocatorinterface lets you override the default buffer management behavior. There are two allocators provided out-of-the-box:SimpleBufferAllocator(default)CachedBufferAllocator
setAllocator(IoBufferAllocator).- Version:
- $Rev: 748525 $, $Date: 2009-02-27 14:45:31 +0100 (Fri, 27 Feb 2009) $
-
-
Field Summary
Fields Modifier and Type Field Description private static IoBufferAllocatorallocatorThe allocator used to create new buffersprivate static booleanuseDirectBufferA flag indicating which type of buffer we are using : heap or direct
-
Constructor Summary
Constructors Modifier Constructor Description protectedIoBuffer()Creates a new instance.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static IoBufferallocate(int capacity)Returns the direct or heap buffer which is capable to store the specified amount of bytes.static IoBufferallocate(int capacity, boolean direct)Returns the buffer which is capable of the specified size.abstract byte[]array()abstract intarrayOffset()abstract java.nio.CharBufferasCharBuffer()abstract java.nio.DoubleBufferasDoubleBuffer()abstract java.nio.FloatBufferasFloatBuffer()abstract java.io.InputStreamasInputStream()Returns anInputStreamthat reads the data from this buffer.abstract java.nio.IntBufferasIntBuffer()abstract java.nio.LongBufferasLongBuffer()abstract java.io.OutputStreamasOutputStream()Returns anOutputStreamthat appends the data into this buffer.abstract IoBufferasReadOnlyBuffer()abstract java.nio.ShortBufferasShortBuffer()abstract java.nio.ByteBufferbuf()Returns the underlying NIO buffer instance.abstract intcapacity()abstract IoBuffercapacity(int newCapacity)Increases the capacity of this buffer.abstract IoBufferclear()abstract IoBuffercompact()abstract IoBufferduplicate()abstract IoBufferexpand(int expectedRemaining)Changes the capacity and limit of this buffer so this buffer get the specified expectedRemaining room from the current position.abstract IoBufferexpand(int position, int expectedRemaining)Changes the capacity and limit of this buffer so this buffer get the specified expectedRemaining room from the specified position.abstract IoBufferfill(byte value, int size)Fills this buffer with the specified value.abstract IoBufferfill(int size)Fills this buffer withNUL (0x00).abstract IoBufferfillAndReset(byte value, int size)Fills this buffer with the specified value.abstract IoBufferfillAndReset(int size)Fills this buffer withNUL (0x00).abstract IoBufferflip()abstract voidfree()Declares this buffer and all its derived buffers are not used anymore so that it can be reused by someIoBufferAllocatorimplementations.abstract byteget()abstract IoBufferget(byte[] dst)abstract IoBufferget(byte[] dst, int offset, int length)abstract byteget(int index)static IoBufferAllocatorgetAllocator()Returns the allocator used by existing and new buffersabstract chargetChar()abstract chargetChar(int index)abstract doublegetDouble()abstract doublegetDouble(int index)abstract <E extends java.lang.Enum<E>>
EgetEnum(int index, java.lang.Class<E> enumClass)Reads a byte from the buffer and returns the correlating enum constant defined by the specified enum type.abstract <E extends java.lang.Enum<E>>
EgetEnum(java.lang.Class<E> enumClass)Reads a byte from the buffer and returns the correlating enum constant defined by the specified enum type.abstract <E extends java.lang.Enum<E>>
EgetEnumInt(int index, java.lang.Class<E> enumClass)Reads an int from the buffer and returns the correlating enum constant defined by the specified enum type.abstract <E extends java.lang.Enum<E>>
EgetEnumInt(java.lang.Class<E> enumClass)Reads an int from the buffer and returns the correlating enum constant defined by the specified enum type.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSet(int index, java.lang.Class<E> enumClass)Reads a byte sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSet(java.lang.Class<E> enumClass)Reads a byte sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetInt(int index, java.lang.Class<E> enumClass)Reads an int sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetInt(java.lang.Class<E> enumClass)Reads an int sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetLong(int index, java.lang.Class<E> enumClass)Reads a long sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetLong(java.lang.Class<E> enumClass)Reads a long sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetShort(int index, java.lang.Class<E> enumClass)Reads a short sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
java.util.EnumSet<E>getEnumSetShort(java.lang.Class<E> enumClass)Reads a short sized bit vector and converts it to anEnumSet.abstract <E extends java.lang.Enum<E>>
EgetEnumShort(int index, java.lang.Class<E> enumClass)Reads a short from the buffer and returns the correlating enum constant defined by the specified enum type.abstract <E extends java.lang.Enum<E>>
EgetEnumShort(java.lang.Class<E> enumClass)Reads a short from the buffer and returns the correlating enum constant defined by the specified enum type.abstract floatgetFloat()abstract floatgetFloat(int index)abstract java.lang.StringgetHexDump()Returns hexdump of this buffer.abstract java.lang.StringgetHexDump(int lengthLimit)Return hexdump of this buffer with limited length.abstract intgetInt()abstract intgetInt(int index)abstract longgetLong()abstract longgetLong(int index)abstract intgetMediumInt()Relative get method for reading a medium int value.abstract intgetMediumInt(int index)Absolute get method for reading a medium int value.abstract java.lang.ObjectgetObject()Reads a Java object from the buffer using the contextClassLoaderof the current thread.abstract java.lang.ObjectgetObject(java.lang.ClassLoader classLoader)Reads a Java object from the buffer using the specified classLoader.abstract java.lang.StringgetPrefixedString(int prefixLength, java.nio.charset.CharsetDecoder decoder)Reads a string which has a length field before the actual encoded string, using the specifieddecoderand returns it.abstract java.lang.StringgetPrefixedString(java.nio.charset.CharsetDecoder decoder)Reads a string which has a 16-bit length field before the actual encoded string, using the specifieddecoderand returns it.abstract shortgetShort()abstract shortgetShort(int index)abstract IoBuffergetSlice(int length)TODO document me.abstract IoBuffergetSlice(int index, int length)TODO document me.abstract java.lang.StringgetString(int fieldSize, java.nio.charset.CharsetDecoder decoder)Reads aNUL-terminated string from this buffer using the specifieddecoderand returns it.abstract java.lang.StringgetString(java.nio.charset.CharsetDecoder decoder)Reads aNUL-terminated string from this buffer using the specifieddecoderand returns it.abstract shortgetUnsigned()Reads one unsigned byte as a short integer.abstract shortgetUnsigned(int index)Reads one byte as an unsigned short integer.abstract longgetUnsignedInt()Reads four bytes unsigned integer.abstract longgetUnsignedInt(int index)Reads four bytes unsigned integer.abstract intgetUnsignedMediumInt()Relative get method for reading an unsigned medium int value.abstract intgetUnsignedMediumInt(int index)Absolute get method for reading an unsigned medium int value.abstract intgetUnsignedShort()Reads two bytes unsigned integer.abstract intgetUnsignedShort(int index)Reads two bytes unsigned integer.abstract booleanhasArray()abstract booleanhasRemaining()abstract intindexOf(byte b)Returns the first occurence position of the specified byte from the current position to the current limit.abstract booleanisAutoExpand()Returns true if and only if autoExpand is turned on.abstract booleanisAutoShrink()Returns true if and only if autoShrink is turned on.abstract booleanisDerived()returns true if and only if this buffer is derived from other buffer viaduplicate(),slice()orasReadOnlyBuffer().abstract booleanisDirect()abstract booleanisReadOnly()static booleanisUseDirectBuffer()Returns true if and only if a direct buffer is allocated by default when the type of the new buffer is not specified.abstract intlimit()abstract IoBufferlimit(int newLimit)abstract IoBuffermark()abstract intmarkValue()Returns the position of the current mark.abstract intminimumCapacity()abstract IoBufferminimumCapacity(int minimumCapacity)protected static intnormalizeCapacity(int requestedCapacity)Normalizes the specified capacity of the buffer to power of 2, which is often helpful for optimal memory usage and performance.abstract java.nio.ByteOrderorder()abstract IoBufferorder(java.nio.ByteOrder bo)abstract intposition()abstract IoBufferposition(int newPosition)abstract booleanprefixedDataAvailable(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.abstract booleanprefixedDataAvailable(int prefixLength, int maxDataLength)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.abstract IoBufferput(byte b)abstract IoBufferput(byte[] src)abstract IoBufferput(byte[] src, int offset, int length)abstract IoBufferput(int index, byte b)abstract IoBufferput(IoBuffer src)Writes the content of the specified src into this buffer.abstract IoBufferput(java.nio.ByteBuffer src)Writes the content of the specified src into this buffer.abstract IoBufferputChar(char value)abstract IoBufferputChar(int index, char value)abstract IoBufferputDouble(double value)abstract IoBufferputDouble(int index, double value)abstract IoBufferputEnum(int index, java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as a byte.abstract IoBufferputEnum(java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as a byte.abstract IoBufferputEnumInt(int index, java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as an integer.abstract IoBufferputEnumInt(java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as an integer.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSet(int index, java.util.Set<E> set)Writes the specifiedSetto the buffer as a byte sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSet(java.util.Set<E> set)Writes the specifiedSetto the buffer as a byte sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetInt(int index, java.util.Set<E> set)Writes the specifiedSetto the buffer as an int sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetInt(java.util.Set<E> set)Writes the specifiedSetto the buffer as an int sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetLong(int index, java.util.Set<E> set)Writes the specifiedSetto the buffer as a long sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetLong(java.util.Set<E> set)Writes the specifiedSetto the buffer as a long sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetShort(int index, java.util.Set<E> set)Writes the specifiedSetto the buffer as a short sized bit vector.abstract <E extends java.lang.Enum<E>>
IoBufferputEnumSetShort(java.util.Set<E> set)Writes the specifiedSetto the buffer as a short sized bit vector.abstract IoBufferputEnumShort(int index, java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as a short.abstract IoBufferputEnumShort(java.lang.Enum<?> e)Writes an enum's ordinal value to the buffer as a short.abstract IoBufferputFloat(float value)abstract IoBufferputFloat(int index, float value)abstract IoBufferputInt(int value)abstract IoBufferputInt(int index, int value)abstract IoBufferputLong(int index, long value)abstract IoBufferputLong(long value)abstract IoBufferputMediumInt(int value)Relative put method for writing a medium int value.abstract IoBufferputMediumInt(int index, int value)Absolute put method for writing a medium int value.abstract IoBufferputObject(java.lang.Object o)Writes the specified Java object to the buffer.abstract IoBufferputPrefixedString(java.lang.CharSequence val, int prefixLength, int padding, byte padValue, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder.abstract IoBufferputPrefixedString(java.lang.CharSequence in, int prefixLength, int padding, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder.abstract IoBufferputPrefixedString(java.lang.CharSequence in, int prefixLength, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder.abstract IoBufferputPrefixedString(java.lang.CharSequence in, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder.abstract IoBufferputShort(int index, short value)abstract IoBufferputShort(short value)abstract IoBufferputString(java.lang.CharSequence val, int fieldSize, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer as aNUL-terminated string using the specifiedencoder.abstract IoBufferputString(java.lang.CharSequence val, java.nio.charset.CharsetEncoder encoder)Writes the content ofininto this buffer using the specifiedencoder.abstract intremaining()abstract IoBufferreset()abstract IoBufferrewind()static voidsetAllocator(IoBufferAllocator newAllocator)Sets the allocator used by existing and new buffersabstract IoBuffersetAutoExpand(boolean autoExpand)Turns on or off autoExpand.abstract IoBuffersetAutoShrink(boolean autoShrink)Turns on or off autoShrink.static voidsetUseDirectBuffer(boolean useDirectBuffer)Sets if a direct buffer should be allocated by default when the type of the new buffer is not specified.abstract IoBuffershrink()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.abstract IoBufferskip(int size)Forwards the position of this buffer as the specifiedsizebytes.abstract IoBufferslice()abstract IoBuffersweep()Clears this buffer and fills its content with NUL.abstract IoBuffersweep(byte value)double Clears this buffer and fills its content with value.static IoBufferwrap(byte[] byteArray)Wraps the specified byte array into MINA heap buffer.static IoBufferwrap(byte[] byteArray, int offset, int length)Wraps the specified byte array into MINA heap buffer.static IoBufferwrap(java.nio.ByteBuffer nioBuffer)Wraps the specified NIOByteBufferinto MINA buffer.
-
-
-
Field Detail
-
allocator
private static IoBufferAllocator allocator
The allocator used to create new buffers
-
useDirectBuffer
private static boolean useDirectBuffer
A flag indicating which type of buffer we are using : heap or direct
-
-
Method Detail
-
getAllocator
public static IoBufferAllocator getAllocator()
Returns the allocator used by existing and new buffers
-
setAllocator
public static void setAllocator(IoBufferAllocator newAllocator)
Sets the allocator used by existing and new buffers
-
isUseDirectBuffer
public static boolean isUseDirectBuffer()
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.
-
setUseDirectBuffer
public static void setUseDirectBuffer(boolean 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.
-
allocate
public static IoBuffer allocate(int capacity)
Returns the direct or heap buffer which is capable to store the specified amount of bytes.- Parameters:
capacity- the capacity of the buffer- See Also:
setUseDirectBuffer(boolean)
-
allocate
public static IoBuffer allocate(int capacity, boolean direct)
Returns the buffer which is capable of the specified size.- Parameters:
capacity- the capacity of the bufferdirect- true to get a direct buffer, false to get a heap buffer.
-
wrap
public static IoBuffer wrap(java.nio.ByteBuffer nioBuffer)
Wraps the specified NIOByteBufferinto MINA buffer.
-
wrap
public static IoBuffer wrap(byte[] byteArray)
Wraps the specified byte array into MINA heap buffer.
-
wrap
public static IoBuffer wrap(byte[] byteArray, int offset, int length)
Wraps the specified byte array into MINA heap buffer.
-
normalizeCapacity
protected static int normalizeCapacity(int requestedCapacity)
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 toInteger.MAX_VALUE, it returnsInteger.MAX_VALUE. If it is zero, it returns zero.
-
free
public abstract void free()
Declares this buffer and all its derived buffers are not used anymore so that it can be reused by someIoBufferAllocatorimplementations. It is not mandatory to call this method, but you might want to invoke this method for maximum performance.
-
buf
public abstract java.nio.ByteBuffer buf()
Returns the underlying NIO buffer instance.
-
isDirect
public abstract boolean isDirect()
- See Also:
ByteBuffer.isDirect()
-
isDerived
public abstract boolean isDerived()
returns true if and only if this buffer is derived from other buffer viaduplicate(),slice()orasReadOnlyBuffer().
-
isReadOnly
public abstract boolean isReadOnly()
- See Also:
Buffer.isReadOnly()
-
minimumCapacity
public abstract int minimumCapacity()
-
minimumCapacity
public abstract IoBuffer minimumCapacity(int minimumCapacity)
-
capacity
public abstract int capacity()
- See Also:
Buffer.capacity()
-
capacity
public abstract IoBuffer capacity(int newCapacity)
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.
-
isAutoExpand
public abstract boolean isAutoExpand()
Returns true if and only if autoExpand is turned on.
-
setAutoExpand
public abstract IoBuffer setAutoExpand(boolean autoExpand)
Turns on or off autoExpand.
-
isAutoShrink
public abstract boolean isAutoShrink()
Returns true if and only if autoShrink is turned on.
-
setAutoShrink
public abstract IoBuffer setAutoShrink(boolean autoShrink)
Turns on or off autoShrink.
-
expand
public abstract IoBuffer expand(int expectedRemaining)
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.
-
expand
public abstract IoBuffer expand(int position, 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.
-
shrink
public abstract IoBuffer shrink()
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 thanminimumCapacity(). The mark is discarded once the capacity changes.
-
position
public abstract int position()
- See Also:
Buffer.position()
-
position
public abstract IoBuffer position(int newPosition)
- See Also:
Buffer.position(int)
-
limit
public abstract int limit()
- See Also:
Buffer.limit()
-
limit
public abstract IoBuffer limit(int newLimit)
- See Also:
Buffer.limit(int)
-
mark
public abstract IoBuffer mark()
- See Also:
Buffer.mark()
-
markValue
public abstract int markValue()
Returns the position of the current mark. This method returns -1 if no mark is set.
-
reset
public abstract IoBuffer reset()
- See Also:
Buffer.reset()
-
clear
public abstract IoBuffer clear()
- See Also:
Buffer.clear()
-
sweep
public abstract IoBuffer sweep()
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.
-
sweep
public abstract IoBuffer sweep(byte value)
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.
-
flip
public abstract IoBuffer flip()
- See Also:
Buffer.flip()
-
rewind
public abstract IoBuffer rewind()
- See Also:
Buffer.rewind()
-
remaining
public abstract int remaining()
- See Also:
Buffer.remaining()
-
hasRemaining
public abstract boolean hasRemaining()
- See Also:
Buffer.hasRemaining()
-
duplicate
public abstract IoBuffer duplicate()
- See Also:
ByteBuffer.duplicate()
-
slice
public abstract IoBuffer slice()
- See Also:
ByteBuffer.slice()
-
asReadOnlyBuffer
public abstract IoBuffer asReadOnlyBuffer()
- See Also:
ByteBuffer.asReadOnlyBuffer()
-
hasArray
public abstract boolean hasArray()
- See Also:
ByteBuffer.hasArray()
-
array
public abstract byte[] array()
- See Also:
ByteBuffer.array()
-
arrayOffset
public abstract int arrayOffset()
- See Also:
ByteBuffer.arrayOffset()
-
get
public abstract byte get()
- See Also:
ByteBuffer.get()
-
getUnsigned
public abstract short getUnsigned()
Reads one unsigned byte as a short integer.
-
put
public abstract IoBuffer put(byte b)
- See Also:
ByteBuffer.put(byte)
-
get
public abstract byte get(int index)
- See Also:
ByteBuffer.get(int)
-
getUnsigned
public abstract short getUnsigned(int index)
Reads one byte as an unsigned short integer.
-
put
public abstract IoBuffer put(int index, byte b)
- See Also:
ByteBuffer.put(int, byte)
-
get
public abstract IoBuffer get(byte[] dst, int offset, int length)
- See Also:
ByteBuffer.get(byte[], int, int)
-
get
public abstract IoBuffer get(byte[] dst)
- See Also:
ByteBuffer.get(byte[])
-
getSlice
public abstract IoBuffer getSlice(int index, int length)
TODO document me.
-
getSlice
public abstract IoBuffer getSlice(int length)
TODO document me.
-
put
public abstract IoBuffer put(java.nio.ByteBuffer src)
Writes the content of the specified src into this buffer.
-
put
public abstract IoBuffer put(IoBuffer src)
Writes the content of the specified src into this buffer.
-
put
public abstract IoBuffer put(byte[] src, int offset, int length)
- See Also:
ByteBuffer.put(byte[], int, int)
-
put
public abstract IoBuffer put(byte[] src)
- See Also:
ByteBuffer.put(byte[])
-
compact
public abstract IoBuffer compact()
- See Also:
ByteBuffer.compact()
-
order
public abstract java.nio.ByteOrder order()
- See Also:
ByteBuffer.order()
-
order
public abstract IoBuffer order(java.nio.ByteOrder bo)
- See Also:
ByteBuffer.order(ByteOrder)
-
getChar
public abstract char getChar()
- See Also:
ByteBuffer.getChar()
-
putChar
public abstract IoBuffer putChar(char value)
- See Also:
ByteBuffer.putChar(char)
-
getChar
public abstract char getChar(int index)
- See Also:
ByteBuffer.getChar(int)
-
putChar
public abstract IoBuffer putChar(int index, char value)
- See Also:
ByteBuffer.putChar(int, char)
-
asCharBuffer
public abstract java.nio.CharBuffer asCharBuffer()
- See Also:
ByteBuffer.asCharBuffer()
-
getShort
public abstract short getShort()
- See Also:
ByteBuffer.getShort()
-
getUnsignedShort
public abstract int getUnsignedShort()
Reads two bytes unsigned integer.
-
putShort
public abstract IoBuffer putShort(short value)
- See Also:
ByteBuffer.putShort(short)
-
getShort
public abstract short getShort(int index)
- See Also:
ByteBuffer.getShort()
-
getUnsignedShort
public abstract int getUnsignedShort(int index)
Reads two bytes unsigned integer.
-
putShort
public abstract IoBuffer putShort(int index, short value)
- See Also:
ByteBuffer.putShort(int, short)
-
asShortBuffer
public abstract java.nio.ShortBuffer asShortBuffer()
- See Also:
ByteBuffer.asShortBuffer()
-
getInt
public abstract int getInt()
- See Also:
ByteBuffer.getInt()
-
getUnsignedInt
public abstract long getUnsignedInt()
Reads four bytes unsigned integer.
-
getMediumInt
public abstract int getMediumInt()
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.
- Returns:
- The medium int value at the buffer's current position
-
getUnsignedMediumInt
public abstract int getUnsignedMediumInt()
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.
- Returns:
- The unsigned medium int value at the buffer's current position
-
getMediumInt
public abstract int getMediumInt(int index)
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.
- Parameters:
index- The index from which the medium int will be read- Returns:
- The medium int value at the given index
- Throws:
java.lang.IndexOutOfBoundsException- If index is negative or not smaller than the buffer's limit
-
getUnsignedMediumInt
public abstract int getUnsignedMediumInt(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.
- Parameters:
index- The index from which the unsigned medium int will be read- Returns:
- The unsigned medium int value at the given index
- Throws:
java.lang.IndexOutOfBoundsException- If index is negative or not smaller than the buffer's limit
-
putMediumInt
public abstract IoBuffer putMediumInt(int value)
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.
- Parameters:
value- The medium int value to be written- Returns:
- This buffer
- Throws:
java.nio.BufferOverflowException- If there are fewer than three bytes remaining in this bufferjava.nio.ReadOnlyBufferException- If this buffer is read-only
-
putMediumInt
public abstract IoBuffer putMediumInt(int index, 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.
- Parameters:
index- The index at which the bytes will be writtenvalue- The medium int value to be written- Returns:
- This buffer
- Throws:
java.lang.IndexOutOfBoundsException- If index is negative or not smaller than the buffer's limit, minus threejava.nio.ReadOnlyBufferException- If this buffer is read-only
-
putInt
public abstract IoBuffer putInt(int value)
- See Also:
ByteBuffer.putInt(int)
-
getInt
public abstract int getInt(int index)
- See Also:
ByteBuffer.getInt(int)
-
getUnsignedInt
public abstract long getUnsignedInt(int index)
Reads four bytes unsigned integer.
-
putInt
public abstract IoBuffer putInt(int index, int value)
- See Also:
ByteBuffer.putInt(int, int)
-
asIntBuffer
public abstract java.nio.IntBuffer asIntBuffer()
- See Also:
ByteBuffer.asIntBuffer()
-
getLong
public abstract long getLong()
- See Also:
ByteBuffer.getLong()
-
putLong
public abstract IoBuffer putLong(long value)
- See Also:
ByteBuffer.putLong(int, long)
-
getLong
public abstract long getLong(int index)
- See Also:
ByteBuffer.getLong(int)
-
putLong
public abstract IoBuffer putLong(int index, long value)
- See Also:
ByteBuffer.putLong(int, long)
-
asLongBuffer
public abstract java.nio.LongBuffer asLongBuffer()
- See Also:
ByteBuffer.asLongBuffer()
-
getFloat
public abstract float getFloat()
- See Also:
ByteBuffer.getFloat()
-
putFloat
public abstract IoBuffer putFloat(float value)
- See Also:
ByteBuffer.putFloat(float)
-
getFloat
public abstract float getFloat(int index)
- See Also:
ByteBuffer.getFloat(int)
-
putFloat
public abstract IoBuffer putFloat(int index, float value)
- See Also:
ByteBuffer.putFloat(int, float)
-
asFloatBuffer
public abstract java.nio.FloatBuffer asFloatBuffer()
- See Also:
ByteBuffer.asFloatBuffer()
-
getDouble
public abstract double getDouble()
- See Also:
ByteBuffer.getDouble()
-
putDouble
public abstract IoBuffer putDouble(double value)
- See Also:
ByteBuffer.putDouble(double)
-
getDouble
public abstract double getDouble(int index)
- See Also:
ByteBuffer.getDouble(int)
-
putDouble
public abstract IoBuffer putDouble(int index, double value)
- See Also:
ByteBuffer.putDouble(int, double)
-
asDoubleBuffer
public abstract java.nio.DoubleBuffer asDoubleBuffer()
- See Also:
ByteBuffer.asDoubleBuffer()
-
asInputStream
public abstract java.io.InputStream asInputStream()
Returns anInputStreamthat reads the data from this buffer.InputStream.read()returns -1 if the buffer position reaches to the limit.
-
asOutputStream
public abstract java.io.OutputStream asOutputStream()
Returns anOutputStreamthat appends the data into this buffer. Please note that theOutputStream.write(int)will throw aBufferOverflowExceptioninstead of anIOExceptionin case of buffer overflow. Please set autoExpand property by callingsetAutoExpand(boolean)to prevent the unexpected runtime exception.
-
getHexDump
public abstract java.lang.String getHexDump()
Returns hexdump of this buffer. The data and pointer are not changed as a result of this method call.- Returns:
- hexidecimal representation of this buffer
-
getHexDump
public abstract java.lang.String getHexDump(int lengthLimit)
Return hexdump of this buffer with limited length.- Parameters:
lengthLimit- The maximum number of bytes to dump from the current buffer position.- Returns:
- hexidecimal representation of this buffer
-
getString
public abstract java.lang.String getString(java.nio.charset.CharsetDecoder decoder) throws java.nio.charset.CharacterCodingExceptionReads aNUL-terminated string from this buffer using the specifieddecoderand returns it. This method reads until the limit of this buffer if no NUL is found.- Throws:
java.nio.charset.CharacterCodingException
-
getString
public abstract java.lang.String getString(int fieldSize, java.nio.charset.CharsetDecoder decoder) throws java.nio.charset.CharacterCodingExceptionReads aNUL-terminated string from this buffer using the specifieddecoderand returns it.- Parameters:
fieldSize- the maximum number of bytes to read- Throws:
java.nio.charset.CharacterCodingException
-
putString
public abstract IoBuffer putString(java.lang.CharSequence val, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer using the specifiedencoder. This method doesn't terminate string with NUL. You have to do it by yourself.- Throws:
java.nio.BufferOverflowException- if the specified string doesn't fitjava.nio.charset.CharacterCodingException
-
putString
public abstract IoBuffer putString(java.lang.CharSequence val, int fieldSize, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer as aNUL-terminated string using the specifiedencoder.If the charset name of the encoder is UTF-16, you cannot specify odd
fieldSize, and this method will append twoNULs as a terminator.Please note that this method doesn't terminate with
NULif the input string is longer than fieldSize.- Parameters:
fieldSize- the maximum number of bytes to write- Throws:
java.nio.charset.CharacterCodingException
-
getPrefixedString
public abstract java.lang.String getPrefixedString(java.nio.charset.CharsetDecoder decoder) throws java.nio.charset.CharacterCodingExceptionReads a string which has a 16-bit length field before the actual encoded string, using the specifieddecoderand returns it. This method is a shortcut for getPrefixedString(2, decoder).- Throws:
java.nio.charset.CharacterCodingException
-
getPrefixedString
public abstract java.lang.String getPrefixedString(int prefixLength, java.nio.charset.CharsetDecoder decoder) throws java.nio.charset.CharacterCodingExceptionReads a string which has a length field before the actual encoded string, using the specifieddecoderand returns it.- Parameters:
prefixLength- the length of the length field (1, 2, or 4)- Throws:
java.nio.charset.CharacterCodingException
-
putPrefixedString
public abstract IoBuffer putPrefixedString(java.lang.CharSequence in, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder. This method is a shortcut for putPrefixedString(in, 2, 0, encoder).- Throws:
java.nio.BufferOverflowException- if the specified string doesn't fitjava.nio.charset.CharacterCodingException
-
putPrefixedString
public abstract IoBuffer putPrefixedString(java.lang.CharSequence in, int prefixLength, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder. This method is a shortcut for putPrefixedString(in, prefixLength, 0, encoder).- Parameters:
prefixLength- the length of the length field (1, 2, or 4)- Throws:
java.nio.BufferOverflowException- if the specified string doesn't fitjava.nio.charset.CharacterCodingException
-
putPrefixedString
public abstract IoBuffer putPrefixedString(java.lang.CharSequence in, int prefixLength, int padding, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder. This method is a shortcut for putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder) .- Parameters:
prefixLength- the length of the length field (1, 2, or 4)padding- the number of padded NULs (1 (or 0), 2, or 4)- Throws:
java.nio.BufferOverflowException- if the specified string doesn't fitjava.nio.charset.CharacterCodingException
-
putPrefixedString
public abstract IoBuffer putPrefixedString(java.lang.CharSequence val, int prefixLength, int padding, byte padValue, java.nio.charset.CharsetEncoder encoder) throws java.nio.charset.CharacterCodingException
Writes the content ofininto this buffer as a string which has a 16-bit length field before the actual encoded string, using the specifiedencoder.- Parameters:
prefixLength- the length of the length field (1, 2, or 4)padding- the number of padded bytes (1 (or 0), 2, or 4)padValue- the value of padded bytes- Throws:
java.nio.BufferOverflowException- if the specified string doesn't fitjava.nio.charset.CharacterCodingException
-
getObject
public abstract java.lang.Object getObject() throws java.lang.ClassNotFoundExceptionReads a Java object from the buffer using the contextClassLoaderof the current thread.- Throws:
java.lang.ClassNotFoundException
-
getObject
public abstract java.lang.Object getObject(java.lang.ClassLoader classLoader) throws java.lang.ClassNotFoundExceptionReads a Java object from the buffer using the specified classLoader.- Throws:
java.lang.ClassNotFoundException
-
putObject
public abstract IoBuffer putObject(java.lang.Object o)
Writes the specified Java object to the buffer.
-
prefixedDataAvailable
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. 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 useprefixedDataAvailable(int, int)instead.- Parameters:
prefixLength- the length of the prefix field (1, 2, or 4)- Throws:
java.lang.IllegalArgumentException- if prefixLength is wrongBufferDataException- if data length is negative
-
prefixedDataAvailable
public abstract boolean prefixedDataAvailable(int prefixLength, int maxDataLength)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.- Parameters:
prefixLength- the length of the prefix field (1, 2, or 4)maxDataLength- the allowed maximum of the read data length- Throws:
java.lang.IllegalArgumentException- if prefixLength is wrongBufferDataException- if data length is negative or greater then maxDataLength
-
indexOf
public abstract int indexOf(byte b)
Returns the first occurence position of the specified byte from the current position to the current limit.- Returns:
- -1 if the specified byte is not found
-
skip
public abstract IoBuffer skip(int size)
Forwards the position of this buffer as the specifiedsizebytes.
-
fill
public abstract IoBuffer fill(byte value, int size)
Fills this buffer with the specified value. This method moves buffer position forward.
-
fillAndReset
public abstract IoBuffer fillAndReset(byte value, int size)
Fills this buffer with the specified value. This method does not change buffer position.
-
fill
public abstract IoBuffer fill(int size)
Fills this buffer withNUL (0x00). This method moves buffer position forward.
-
fillAndReset
public abstract IoBuffer fillAndReset(int size)
Fills this buffer withNUL (0x00). This method does not change buffer position.
-
getEnum
public abstract <E extends java.lang.Enum<E>> E getEnum(java.lang.Class<E> enumClass)
Reads a byte from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
enumClass- The enum's class object
-
getEnum
public abstract <E extends java.lang.Enum<E>> E getEnum(int index, java.lang.Class<E> enumClass)Reads a byte from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
index- the index from which the byte will be readenumClass- The enum's class object
-
getEnumShort
public abstract <E extends java.lang.Enum<E>> E getEnumShort(java.lang.Class<E> enumClass)
Reads a short from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
enumClass- The enum's class object
-
getEnumShort
public abstract <E extends java.lang.Enum<E>> E getEnumShort(int index, java.lang.Class<E> enumClass)Reads a short from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
index- the index from which the bytes will be readenumClass- The enum's class object
-
getEnumInt
public abstract <E extends java.lang.Enum<E>> E getEnumInt(java.lang.Class<E> enumClass)
Reads an int from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
enumClass- The enum's class object
-
getEnumInt
public abstract <E extends java.lang.Enum<E>> E getEnumInt(int index, java.lang.Class<E> enumClass)Reads an int from the buffer and returns the correlating enum constant defined by the specified enum type.- Type Parameters:
E- The enum type to return- Parameters:
index- the index from which the bytes will be readenumClass- The enum's class object
-
putEnum
public abstract IoBuffer putEnum(java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as a byte.- Parameters:
e- The enum to write to the buffer
-
putEnum
public abstract IoBuffer putEnum(int index, java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as a byte.- Parameters:
index- The index at which the byte will be writtene- The enum to write to the buffer
-
putEnumShort
public abstract IoBuffer putEnumShort(java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as a short.- Parameters:
e- The enum to write to the buffer
-
putEnumShort
public abstract IoBuffer putEnumShort(int index, java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as a short.- Parameters:
index- The index at which the bytes will be writtene- The enum to write to the buffer
-
putEnumInt
public abstract IoBuffer putEnumInt(java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as an integer.- Parameters:
e- The enum to write to the buffer
-
putEnumInt
public abstract IoBuffer putEnumInt(int index, java.lang.Enum<?> e)
Writes an enum's ordinal value to the buffer as an integer.- Parameters:
index- The index at which the bytes will be writtene- The enum to write to the buffer
-
getEnumSet
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSet(java.lang.Class<E> enumClass)
Reads a byte sized bit vector and converts it to anEnumSet.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.
- Type Parameters:
E- the enum type- Parameters:
enumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
-
getEnumSet
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSet(int index, java.lang.Class<E> enumClass)Reads a byte sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
index- the index from which the byte will be readenumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetShort
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetShort(java.lang.Class<E> enumClass)
Reads a short sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
enumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetShort
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetShort(int index, java.lang.Class<E> enumClass)Reads a short sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
index- the index from which the bytes will be readenumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetInt
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetInt(java.lang.Class<E> enumClass)
Reads an int sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
enumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetInt
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetInt(int index, java.lang.Class<E> enumClass)Reads an int sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
index- the index from which the bytes will be readenumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetLong
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetLong(java.lang.Class<E> enumClass)
Reads a long sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
enumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
getEnumSetLong
public abstract <E extends java.lang.Enum<E>> java.util.EnumSet<E> getEnumSetLong(int index, java.lang.Class<E> enumClass)Reads a long sized bit vector and converts it to anEnumSet.- Type Parameters:
E- the enum type- Parameters:
index- the index from which the bytes will be readenumClass- the enum class used to create the EnumSet- Returns:
- the EnumSet representation of the bit vector
- See Also:
getEnumSet(Class)
-
putEnumSet
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSet(java.util.Set<E> set)
Writes the specifiedSetto the buffer as a byte sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
set- the enum set to write to the buffer
-
putEnumSet
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSet(int index, java.util.Set<E> set)
Writes the specifiedSetto the buffer as a byte sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
index- the index at which the byte will be writtenset- the enum set to write to the buffer
-
putEnumSetShort
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetShort(java.util.Set<E> set)
Writes the specifiedSetto the buffer as a short sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
set- the enum set to write to the buffer
-
putEnumSetShort
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetShort(int index, java.util.Set<E> set)
Writes the specifiedSetto the buffer as a short sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
index- the index at which the bytes will be writtenset- the enum set to write to the buffer
-
putEnumSetInt
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetInt(java.util.Set<E> set)
Writes the specifiedSetto the buffer as an int sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
set- the enum set to write to the buffer
-
putEnumSetInt
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetInt(int index, java.util.Set<E> set)
Writes the specifiedSetto the buffer as an int sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
index- the index at which the bytes will be writtenset- the enum set to write to the buffer
-
putEnumSetLong
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetLong(java.util.Set<E> set)
Writes the specifiedSetto the buffer as a long sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
set- the enum set to write to the buffer
-
putEnumSetLong
public abstract <E extends java.lang.Enum<E>> IoBuffer putEnumSetLong(int index, java.util.Set<E> set)
Writes the specifiedSetto the buffer as a long sized bit vector.- Type Parameters:
E- the enum type of the Set- Parameters:
index- the index at which the bytes will be writtenset- the enum set to write to the buffer
-
-