com.neeve.util

Class UtlBuffer

java.lang.Object

com.neeve.util.UtlBuffer

public final class UtlBuffer
extends Object

Utility class containing methods to manipulate IO buffers.

This class contains runtime utility methods to create and manipulate IO buffers.

This class provides support for using both Unsafe and X Platform native libraries speed up memory copies. See PROP_BUFFERMANAGEMENT_USEUNSAFE and PROP_BUFFERMANAGEMENT_USENATIVE properties on how to enable each. When both are enabled Unsafe takes precedence when available.

This class IS NOT intended to be used by end users.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROP_BUFFERMANAGEMENT_USENATIVE Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USENATIVE_PROPNAME instead.
static boolean	PROP_BUFFERMANAGEMENT_USENATIVE_DEFAULT Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USENATIVE_DEFAULT instead.
static String	PROP_BUFFERMANAGEMENT_USEUNSAFE Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USEUNSAFE_PROPNAME instead.
static boolean	PROP_BUFFERMANAGEMENT_USEUNSAFE_DEFAULT Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USEUNSAFE_DEFAULT instead.

Constructor Summary

Constructors

Constructor and Description
UtlBuffer()

Method Summary

Methods

Modifier and Type	Method and Description
static ByteBuffer	clone(ByteBuffer buffer) Clone a byte buffer
static void	copy(byte[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial byte array to a byte buffer
static void	copy(ByteBuffer srcBuffer, int srcOffset, byte[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a byte array
static void	copy(ByteBuffer srcBuffer, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial byte buffer to another byte buffer
static void	copy(ByteBuffer srcBuffer, int srcOffset, char[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a char array
static void	copy(ByteBuffer srcBuffer, int srcOffset, double[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a double array
static void	copy(ByteBuffer srcBuffer, int srcOffset, float[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a float array
static void	copy(ByteBuffer srcBuffer, int srcOffset, int[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a int array
static void	copy(ByteBuffer srcBuffer, int srcOffset, long[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a long array
static void	copy(ByteBuffer srcBuffer, int srcOffset, short[] destArray, int destOffset, int length) Copy a whole or partial byte buffer to a short array
static void	copy(char[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial char array to a byte buffer
static void	copy(double[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial double array to a byte buffer
static void	copy(float[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial float array to a byte buffer
static void	copy(int[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial int array to a byte buffer
static void	copy(long[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial long array to a byte buffer
static void	copy(short[] srcArray, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy a whole or partial short array to a byte buffer
static void	copyFromNative(long srcAddress, int srcOffset, ByteBuffer destBuffer, int destOffset, int length) Copy from native memory into a buffer.
static void	copyToNative(ByteBuffer srcBuffer, int srcOffset, long destAddress, int destOffset, int length) Copy from buffer to native memory.
static String	dump(ByteBuffer buffer) Dump a byte buffer
static String	dump(String prefix, ByteBuffer buffer, int offset, int len) Dump the contents of a byte buffer.
static String	flipAndDump(ByteBuffer buffer) Flip and dump a byte buffer
static ByteBuffer	fromDump(String hexDump) Reconstitutes a ByteBuffer dumped via dump(ByteBuffer).
static long	getNativeBufferAddress(ByteBuffer directBuffer) Gets the native address of the provided direct byte buffer.
static InputStream	inputStream(ByteBuffer buffer) Create an input stream over a byte buffer
static boolean	isNativeBufferManagementEnabled()
static boolean	isUnsafeBufferManagementEnabled()
static OutputStream	outputStream(ByteBuffer buffer) Create an out[ut stream over a byte buffer.
static long	readLong(byte[] source, int offset, boolean bigEndian)
static void	releaseBuffer(ByteBuffer buffer) Invokes the buffer cleaner for a Direct buffer.
static String	toString(ByteBuffer buffer) Return a string representation of a buffer
static void	wipe(ByteBuffer buffer, int len) Wipe a byte buffer clean
static void	wipe(ByteBuffer buffer, int offset, int len) Wipe a byte buffer clean
static void	writeLong(long value, byte[] target, int offset, boolean bigEndian) Writes a long value into the byte array at the given offset and endianess.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_BUFFERMANAGEMENT_USEUNSAFE

@Deprecated
public static final String PROP_BUFFERMANAGEMENT_USEUNSAFE

Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USEUNSAFE_PROPNAME instead.

See Also:

Constant Field Values

PROP_BUFFERMANAGEMENT_USEUNSAFE_DEFAULT

@Deprecated
public static final boolean PROP_BUFFERMANAGEMENT_USEUNSAFE_DEFAULT

Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USEUNSAFE_DEFAULT instead.

See Also:

Constant Field Values

PROP_BUFFERMANAGEMENT_USENATIVE

@Deprecated
public static final String PROP_BUFFERMANAGEMENT_USENATIVE

Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USENATIVE_PROPNAME instead.

See Also:

Constant Field Values

PROP_BUFFERMANAGEMENT_USENATIVE_DEFAULT

@Deprecated
public static final boolean PROP_BUFFERMANAGEMENT_USENATIVE_DEFAULT

Deprecated. Use UtlConstants.BUFFERMANAGEMENT_USENATIVE_DEFAULT instead.

See Also:

Constant Field Values

Constructor Detail

UtlBuffer

public UtlBuffer()

Method Detail

isNativeBufferManagementEnabled

public static final boolean isNativeBufferManagementEnabled()

Returns:

true if native buffer management is enabled

isUnsafeBufferManagementEnabled

public static final boolean isUnsafeBufferManagementEnabled()

Returns:

true if unsafe buffer management is enabled

clone

public static final ByteBuffer clone(ByteBuffer buffer)

Clone a byte buffer

Parameters:

buffer - The buffer to clone

Returns:

Returns the cloned buffer

This method clones a byte buffer. The new buffer is direct if and only if the source buffer is direct. The returned buffer has the entire contents and the same pos, limit and capacity markers of the source buffer. The returned buffer is always no read only and has its mark undefined.

Threading:

This method is safe for concurrent access by multiple threads

copyFromNative

public static final void copyFromNative(long srcAddress,
                  int srcOffset,
                  ByteBuffer destBuffer,
                  int destOffset,
                  int length)

Copy from native memory into a buffer.

Parameters:

srcAddress - the source address of the first byte to copy.

srcOffset - the source offset.

destBuffer - the destination buffer into which to copy.

destOffset - The offset into the the destination to copy to.

length - The number of bytes to copy.

getNativeBufferAddress

public static final long getNativeBufferAddress(ByteBuffer directBuffer)

Gets the native address of the provided direct byte buffer.

Parameters:

directBuffer - The direct byte buffer.

Returns:

The native address of the given direct byte buffer.

Throws:

IllegalArgumentException - If the the buffer is not a direct byte buffer

UnsupportedOperationException - If the address of the buffer can't be determined for the given JVM or platform.

copyToNative

public static final void copyToNative(ByteBuffer srcBuffer,
                int srcOffset,
                long destAddress,
                int destOffset,
                int length)

Copy from buffer to native memory.

Parameters:

srcBuffer - the source buffer from which to copy.

srcOffset - The offset into the the source to copy from.

destAddress - The destination address.

destOffset - The offset into the destination to copy to.

length - The number of bytes to copy.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to another byte buffer

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(byte[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial byte array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        byte[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a byte array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(char[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial char array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        char[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a char array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(short[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial short array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        short[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a short array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(int[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial int array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        int[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a int array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(float[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial float array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        float[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a float array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(long[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial long array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        long[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a long array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(double[] srcArray,
        int srcOffset,
        ByteBuffer destBuffer,
        int destOffset,
        int length)

Copy a whole or partial double array to a byte buffer

Parameters:

srcArray - The source array

srcOffset - The offset in the source array to copy from

destBuffer - The destination buffer

destOffset - The offset in the destination buffer to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

copy

public static final void copy(ByteBuffer srcBuffer,
        int srcOffset,
        double[] destArray,
        int destOffset,
        int length)

Copy a whole or partial byte buffer to a double array

Parameters:

srcBuffer - The source buffer

srcOffset - The offset in the source buffer to copy from

destArray - The destination array

destOffset - The offset in the destination array to copy from

length - The number of bytes to copy

This method disregards the buffer markers and works around them to facilitate the copy. The markers remain unchanged upon return from this method even if data is copied outside of the markers.

wipe

public static final void wipe(ByteBuffer buffer,
        int offset,
        int len)

Wipe a byte buffer clean

Parameters:

buffer - The buffer to clean

offset - The offset into the buffer to clean from

len - The length to clean

wipe

public static final void wipe(ByteBuffer buffer,
        int len)

Wipe a byte buffer clean

Parameters:

buffer - The buffer to clean

len - The length to clean

inputStream

public static final InputStream inputStream(ByteBuffer buffer)

Create an input stream over a byte buffer

Parameters:

buffer - The buffer around which to wrap the input stream

outputStream

public static final OutputStream outputStream(ByteBuffer buffer)

Create an out[ut stream over a byte buffer.

Parameters:

buffer - The buffer around which to wrap the output stream

dump

public static final String dump(ByteBuffer buffer)

Dump a byte buffer

Parameters:

buffer - The buffer to dump

Threading:

This method is safe for concurrent access by multiple threads

This method dumps the remaining contents of a buffer.

fromDump

public static final ByteBuffer fromDump(String hexDump)

Reconstitutes a ByteBuffer dumped via dump(ByteBuffer).

This method reconstitues a string of hex encoded bytes. It will search for a string of hex encoded words enclosed between '<' and '>' characters grouped into 4 byte words for example:
"<0403434d 41ba0403 434d41b2 04034942 4dfa0307>"

Parameters:

hexDump - The hexDump from dump(ByteBuffer)

Returns:

A Byte buffer positioned and limited for reading the reconstituted bytes.

Threading:

This method is safe for concurrent access by multiple threads

dump

public static final String dump(String prefix,
          ByteBuffer buffer,
          int offset,
          int len)

Dump the contents of a byte buffer.

This method dumps the contents of a buffer starting at an offset limited by a particular length

flipAndDump

public static final String flipAndDump(ByteBuffer buffer)

Flip and dump a byte buffer

Parameters:

buffer - The buffer to dump

Threading:

This method is safe for concurrent access by multiple threads

This method flips a buffer, dumps its contents, restores buffer markers to pre-flip state ans returns to the caller.

toString

public static final String toString(ByteBuffer buffer)

Return a string representation of a buffer

Parameters:

buffer - The buffer to get a string rep of

Threading:

This method is safe for concurrent access by multiple threads

writeLong

public static final void writeLong(long value,
             byte[] target,
             int offset,
             boolean bigEndian)

Writes a long value into the byte array at the given offset and endianess.

Parameters:

value - The long to write.

target - The target byte array.

offset - The offset into the array.

bigEndian - to write in big endian format.

readLong

public static final long readLong(byte[] source,
            int offset,
            boolean bigEndian)

releaseBuffer

public static final void releaseBuffer(ByteBuffer buffer)

Invokes the buffer cleaner for a Direct buffer.

Calling this method is not generally needed, and should only be done for buffers that may have mapped a portion of a file or are holding large chunks of memory that should be released expeditiously.

Parameters:

buffer - The buffer to clean.

Throws:

RuntimeException - if there is an error invoking the buffer's cleaner.

UnsupportedOperationException - if direct buffer cleaning is not available e.g. isDirectBufferCleaningAvailable()=false.