net.sf.asyncobjects.io
Class BinaryData

java.lang.Object
  extended by net.sf.asyncobjects.io.BinaryData
All Implemented Interfaces:
Serializable, Comparable<BinaryData>, BatchedData<BinaryData>

public final class BinaryData
extends Object
implements Serializable, BatchedData<BinaryData>

Immutable binary data class. The class avoids copying of data during concat(BinaryData[]), subrange(int, int) operators. However copying could be forced using flatten().

Depending on situation there are three different representations of the data:

Empty
There is exactly one node that represents empty node. It is created by the method empty()}. This version has no data, so access times in that case is 0(1).
Direct
This is implementation is similar to String implementation. There is a backing array, offset, and length. It is created by the method fromBytes(byte[], int, int)}. Note that method copies data to internal array to prevent modification. Access times in that case is 0(1).
Concatenated
This implementation represed by array of segments. It is created using concat(BinaryData[]). Access time in that case is 0(log(n)) (n is amount of data nodes used to represent binary, in normal situations it is about 2-3) when byteAt(int) and friends are used. However it is possible to use iterator() and iterator(int, int) to have 0(1) amortized cost (when accesssing O(length()) elements.

The class implements Comparable interface. Bytes are compared using unsigned comparison. So 0xFF is bigger that 0x7F.

Author:
const
See Also:
Serialized Form

Nested Class Summary
static class BinaryData.ByteIterator
          A base class for byte iterators.
 
Method Summary
 byte byteAt(int i)
          Byte at specified position
 int compareTo(BinaryData data)
          Compare an object to another binary data
 BinaryData concat(BinaryData data)
          Concatenate
static BinaryData concat(BinaryData[] other)
          Concatenate binary data into large binary data
 BinaryData drop(int n)
          Get new data with first n elements dropped
 BinaryData dropTo(int n, byte[] target, int startOffset)
          Copy data to array and drop copied data.
static BinaryData empty()
           
 boolean endsWith(BinaryData data)
          Check if one binary data ends with another
 boolean equals(Object other)
           
 BinaryData flatten()
          Defragment the node and ensure that it uses minimal amound of allocated data.
static BinaryData fromBytes(byte... data)
          Get binary data wrapper from specified byte array
static BinaryData fromBytes(byte[] data, int offset, int length)
          Get binary data wrapper from specified byte array
static BinaryData get(ByteBuffer buffer)
          Get data from NIO buffer.
 int hashCode()
           
 BinaryData head(int n)
          Get data with first n elements
 int intAt(int i)
          Get big endian int at the specified posion.
 boolean isEmpty()
           
 boolean isValidPosition(int i)
          Check if position is a vaild one
 boolean isValidRange(int start, int limit)
          Check if range is completly within this object
 BinaryData.ByteIterator iterator()
           
 BinaryData.ByteIterator iterator(int start, int limit)
          Get iterator.
 int length()
           
 long longAt(int i)
          Get big endian long at the specified posion.
 Promise<BinaryData> promise()
          Return a promise that wraps this value
static BinaryData put(ByteBuffer buffer, BinaryData data)
          Put binary data into the buffer
 short shortAt(int i)
          Get big endian short at the specified posion.
 BinaryData subrange(int start, int limit)
          Get subrange of data
 byte[] toArray()
           
 byte[] toArray(int srcStart, byte[] target, int targetStart, int length)
          Copy data to byte array
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

concat

public static BinaryData concat(BinaryData[] other)
Concatenate binary data into large binary data

Parameters:
other - binary outputs
Returns:
a binary data

empty

public static BinaryData empty()
Returns:
empty data, it is also available as constant EMPTY

fromBytes

public static BinaryData fromBytes(byte... data)
Get binary data wrapper from specified byte array

Parameters:
data - a data to wrap
Returns:
wrapped data

fromBytes

public static BinaryData fromBytes(byte[] data,
                                   int offset,
                                   int length)
Get binary data wrapper from specified byte array

Parameters:
data - a data to wrap
offset - an offset in the data
length - an length in the data
Returns:
wrapped data

byteAt

public byte byteAt(int i)
Byte at specified position

Parameters:
i - a position
Returns:
a byte at position

intAt

public int intAt(int i)
Get big endian int at the specified posion. The operation cost is O(log(n) where n is amount of data nodes whithin node. If there is a need to examine a sequence of bytes, use iterator(int, int) instead.

Parameters:
i - a posiion
Returns:
integer at position

longAt

public long longAt(int i)
Get big endian long at the specified posion. The operation cost is O(log(n) where n is amount of data nodes whithin node. If there is a need to examine a sequence of bytes, use iterator(int, int) instead.

Parameters:
i - a posiion
Returns:
integer at position

shortAt

public short shortAt(int i)
Get big endian short at the specified posion. The operation cost is O(log(n) where n is amount of data nodes whithin node. If there is a need to examine a sequence of bytes, use iterator(int, int) instead.

Parameters:
i - a posiion
Returns:
integer at position

isValidPosition

public boolean isValidPosition(int i)
Check if position is a vaild one

Parameters:
i - a position
Returns:
true if it getByte(int i) would be successful.

isValidRange

public boolean isValidRange(int start,
                            int limit)
Check if range is completly within this object

Parameters:
start - a start posion
limit - a position right after last byte of the range
Returns:
true if range is valid

length

public int length()
Specified by:
length in interface BatchedData<BinaryData>
Returns:
length of data
See Also:
BatchedData.length()

subrange

public BinaryData subrange(int start,
                           int limit)
Description copied from interface: BatchedData
Get subrange of data

Specified by:
subrange in interface BatchedData<BinaryData>
Parameters:
start - a start posiion
limit - a limit
Returns:
a data that represents subrange
See Also:
BatchedData.subrange(int, int)

head

public BinaryData head(int n)
Description copied from interface: BatchedData
Get data with first n elements

Specified by:
head in interface BatchedData<BinaryData>
Parameters:
n - amount to cut from beginning of the data
Returns:
data with first n bytes of the data
See Also:
BatchedData.head(int)

drop

public BinaryData drop(int n)
Description copied from interface: BatchedData
Get new data with first n elements dropped

Specified by:
drop in interface BatchedData<BinaryData>
Parameters:
n - cut point
Returns:
data after position
See Also:
BatchedData.drop(int)

dropTo

public BinaryData dropTo(int n,
                         byte[] target,
                         int startOffset)
Copy data to array and drop copied data.

Parameters:
n - amount to copy
target - target array
startOffset - start offset in array
Returns:
data object with droped n bytes

toArray

public byte[] toArray(int srcStart,
                      byte[] target,
                      int targetStart,
                      int length)
Copy data to byte array

Parameters:
srcStart - start of data region in this sequence
target - a target array
targetStart - a start posion in target
length - amount to copy
Returns:
target argument

toArray

public byte[] toArray()
Returns:
an array that contains all data from sequence

flatten

public BinaryData flatten()
Defragment the node and ensure that it uses minimal amound of allocated data. This only makes sense for nodes that are expected to be kept for extended period of time. The flattening happes only when needed. If data is already flattened, the same object is returned.

Returns:
flattened node that is represnted by single data node and tha contains exactly require amount of data

iterator

public BinaryData.ByteIterator iterator(int start,
                                        int limit)
Get iterator. The operation cost is O(log(n) where n is amount of data nodes whin node.

Parameters:
start - start position
limit - limit position
Returns:
an iterator

iterator

public BinaryData.ByteIterator iterator()
Returns:
iterator for entire sequence

equals

public boolean equals(Object other)
Overrides:
equals in class Object
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Overrides:
hashCode in class Object
See Also:
Object.hashCode()

compareTo

public int compareTo(BinaryData data)
Compare an object to another binary data

Specified by:
compareTo in interface Comparable<BinaryData>
Parameters:
data - a data to compre to
Returns:
a comparison result
See Also:
Comparable.compareTo(Object)

toString

public String toString()
Overrides:
toString in class Object
See Also:
Object.toString()

concat

public BinaryData concat(BinaryData data)
Concatenate

Specified by:
concat in interface BatchedData<BinaryData>
Parameters:
data - a data to append
Returns:
a concatentated data
See Also:
concat(BinaryData[]), BatchedData.concat(net.sf.asyncobjects.io.BatchedData)

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface BatchedData<BinaryData>
Returns:
true if data is empty
See Also:
BatchedData.isEmpty()

endsWith

public boolean endsWith(BinaryData data)
Check if one binary data ends with another

Parameters:
data - a possible suffix
Returns:
true if this data ends with supplied data

promise

public Promise<BinaryData> promise()
Description copied from interface: BatchedData
Return a promise that wraps this value

Specified by:
promise in interface BatchedData<BinaryData>
Returns:
a promise
See Also:
BatchedData.promise()

get

public static BinaryData get(ByteBuffer buffer)
Get data from NIO buffer.

Parameters:
buffer - a buffer to update
Returns:
data from the buffer

put

public static BinaryData put(ByteBuffer buffer,
                             BinaryData data)
Put binary data into the buffer

Parameters:
buffer - a NIO buffer to change
data - a data to put
Returns:
remaining data


Copyright 2002-2007 Constantine Plotnikov. All Rights Reserved.