org.asnlab.asndt.runtime.type
Class Buffer

java.lang.Object
  extended by org.asnlab.asndt.runtime.type.Buffer
All Implemented Interfaces:
EncodingRules

public abstract class Buffer
extends java.lang.Object
implements EncodingRules

A container for data of a specific primitive type.

A buffer is a linear, finite sequence of elements of a specific primitive type. Aside from its content, the essential properties of a buffer are its capacity, limit, and position:

A buffer's capacity is the number of elements it contains. The capacity of a buffer is never negative and never changes.

A buffer's limit is the index of the first element that should not be read or written. A buffer's limit is never negative and is never greater than its capacity.

A buffer's position is the index of the next element to be read or written. A buffer's position is never negative and is never greater than its limit.

Invariants

The following invariant holds for the position, limit, and capacity values:

0 <= position <= limit <= capacity

A newly-created buffer always has a position of zero. The initial limit may be zero, or it may be some other value that depends upon the type of the buffer and the manner in which it is constructed. The initial content of a buffer is, in general, undefined.

Thread safety

Buffers are not safe for use by multiple concurrent threads. If a buffer is to be used by more than one thread then access to the buffer should be controlled by appropriate synchronization.

Invocation chaining

Methods in this class that do not otherwise have a value to return are specified to return the buffer upon which they are invoked. This allows method invocations to be chained; for example, the sequence of statements

 b.flip();
 b.position(23);
 b.limit(42);
can be replaced by the single, more compact statement
 b.flip().position(23).limit(42);

Since:
3.0
Version:
3.14
Author:
Ryan Hubert

Field Summary
 
Fields inherited from interface org.asnlab.asndt.runtime.conv.EncodingRules
ALIGNED_PACKED_ENCODING_RULES, BASIC_ENCODING_RULES, CANONICAL_ENCODING_RULES, DISTINGUISHED_ENCODING_RULES, UNALIGNED_PACKED_ENCODING_RULES
 
Constructor Summary
Buffer()
           
 
Method Summary
static Buffer allocate(int length, byte encodingRules)
          Allocates a new buffer.
abstract  byte[] array()
          Returns the actual array content of this buffer; that is, a new array containing actual content.
 Buffer autoExpand()
          Sets this buffer to auto-expandable.
 Buffer autoExpand(int byIncrement)
          Sets this buffer to auto-expandable.
 int capacity()
          Returns this buffer's capacity.
 Buffer clear()
          Clears this buffer.
abstract  java.lang.Object decode(AsnType type, AsnConverter converter)
          Decode object from this buffer
abstract  void encode(java.lang.Object object, AsnType type, AsnConverter converter)
          Encode object to this buffer
 byte encodingRules()
          Returns this buffer's encoding rules.
 Buffer flip()
          Flips this buffer.
 void flush()
          Flushes the buffer to the underlying output stream as needed.
 boolean hasRemaining()
          Tells whether there are any elements between the current position and the limit.
protected static byte[] int2bytes(int number)
           
 int limit()
          Returns this buffer's limit.
 Buffer limit(int newLimit)
          Sets this buffer's limit.
protected static byte[] long2bytes(long number)
           
static Buffer newStreamBuffer(java.io.InputStream in, int length, byte encodingRules)
          Create a new buffer with the specific underlying input stream
static Buffer newStreamBuffer(java.io.OutputStream out, int length, byte encodingRules)
          Create a new buffer with the specific underlying output stream
protected static int numOfBits(int n)
           
protected static int numOfBits(long n)
           
protected static int numOfBytes(int number)
           
protected static int numOfBytes(long number)
           
protected static int numOfBytes(short number)
           
protected static int numOfOcts(int n)
           
protected static int numOfOcts(long n)
           
 int position()
          Returns this buffer's position.
 Buffer position(int newPosition)
          Sets this buffer's position.
 int remaining()
          Returns the number of elements between the current position and the limit.
protected static byte[] short2bytes(short number)
           
static java.lang.String toHexString(byte[] octets)
           
protected static byte[] unsignedint2bytes(int number)
           
protected static byte[] unsignedlong2bytes(long number)
           
protected static byte[] unsignint2seplets(int value)
           
static Buffer wrap(byte[] array, byte encodingRules)
          Wraps a byte array into a buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Buffer

public Buffer()
Method Detail

allocate

public static Buffer allocate(int length,
                              byte encodingRules)
Allocates a new buffer.

The new buffer's position will be zero, its limit will be zero, for basic encoding rules its capacity will be length, for packed encoding rules its capacity will be length*8. It will have a backing array.

Parameters:
length - The new length of the buffer's backing array, in bytes
encodingRules - The encoding rules
Returns:
The new buffer
Throws:
java.lang.IllegalArgumentException - If the length is a negative integer

wrap

public static Buffer wrap(byte[] array,
                          byte encodingRules)
Wraps a byte array into a buffer.

The new buffer will be backed by the given byte array; that is, modifications to the buffer will cause the array to be modified and vice versa. The new buffer's position will be zero, for basic encoding rules, its capacity and limit will be array.length, for packed encoding rules, its capacity and limit will be array.length*8. Its backing array will be the given array.

Parameters:
array - The array that will back this buffer
encodingRules - The encoding rules
Returns:
The new buffer

newStreamBuffer

public static Buffer newStreamBuffer(java.io.OutputStream out,
                                     int length,
                                     byte encodingRules)
Create a new buffer with the specific underlying output stream

Parameters:
out - The underlying output stream
length - The length of the working buffer
encodingRules - The encoding rules
Returns:
The new buffer

newStreamBuffer

public static Buffer newStreamBuffer(java.io.InputStream in,
                                     int length,
                                     byte encodingRules)
Create a new buffer with the specific underlying input stream

Parameters:
in - The underlying input stream
length - The length of the working buffer
encodingRules - The encoding rules
Returns:
The new buffer

encode

public abstract void encode(java.lang.Object object,
                            AsnType type,
                            AsnConverter converter)
Encode object to this buffer

Parameters:
object - The object to encode
type - The ASN.1 metadata type
converter - The ASN.1 metadata converter

decode

public abstract java.lang.Object decode(AsnType type,
                                        AsnConverter converter)
Decode object from this buffer

Parameters:
type - The ASN.1 metadata type
converter - The ASN.1 metadata converter
Returns:
The decoded object

array

public abstract byte[] array()
Returns the actual array content of this buffer; that is, a new array containing actual content.

Returns:
The actual content of this buffer

flush

public void flush()
           throws java.io.IOException
Flushes the buffer to the underlying output stream as needed. Do nothing by default.

Throws:
java.io.IOException

position

public int position()
Returns this buffer's position.

Returns:
The position of this buffer

position

public Buffer position(int newPosition)
Sets this buffer's position.

Parameters:
newPosition - The new position value; must be non-negative and no larger than the current limit
Returns:
This buffer
Throws:
java.lang.IllegalArgumentException - If the preconditions on newPosition do not hold

limit

public final int limit()
Returns this buffer's limit.

Returns:
The limit of this buffer

limit

public final Buffer limit(int newLimit)
Sets this buffer's limit. If the position is larger than the new limit then it is set to the new limit.

Parameters:
newLimit - The new limit value; must be non-negative and no larger than this buffer's capacity
Returns:
This buffer
Throws:
java.lang.IllegalArgumentException - If the preconditions on newLimit do not hold

capacity

public final int capacity()
Returns this buffer's capacity.

Returns:
The capacity of this buffer

remaining

public final int remaining()
Returns the number of elements between the current position and the limit.

Returns:
The number of elements remaining in this buffer

hasRemaining

public final boolean hasRemaining()
Tells whether there are any elements between the current position and the limit.

Returns:
true if, and only if, there is at least one element remaining in this buffer

autoExpand

public final Buffer autoExpand()
Sets this buffer to auto-expandable.

Returns:
This buffer

autoExpand

public final Buffer autoExpand(int byIncrement)
Sets this buffer to auto-expandable.

Parameters:
byIncrement - The amount if increment by which to expand
Returns:
This buffer

clear

public final Buffer clear()
Clears this buffer. The position is set to zero, the limit is set to the capacity.

Invoke this method to reuse buffer in encoding. For example:

 type.encode(object, buffer, converter); // Encode the object
 buffer.flip();                          // Flip buffer 
 byte[] array = buffer.array();          // Retrieve the actual encoding array
 ...                                     // Do something with the encoding array
 buffer.clear();                         // Clear buffer now for reuse
 type1.encode(o1, buffer, converter1);   // Encode the object

Returns:
This buffer

flip

public final Buffer flip()
Flips this buffer. The limit is set to the current position and then the position is set to zero.

After a encoding operations, invoke this method to prepare for retrieve array operations. For example:

 buffer.encode(object, type, converter); // Encode the object
 buffer.flip();                          // Flip buffer 
 byte[] array = buffer.array();          // Retrieve the actual encoding array

This method is not often used as the AsnType.encode(Object object, Buffer buffer, AsnConverter converter) method has invoke this method alread.

Returns:
This buffer

encodingRules

public byte encodingRules()
Returns this buffer's encoding rules.

Returns:
The encoding rules of this buffer

short2bytes

protected static byte[] short2bytes(short number)

int2bytes

protected static byte[] int2bytes(int number)

unsignedint2bytes

protected static byte[] unsignedint2bytes(int number)

long2bytes

protected static byte[] long2bytes(long number)

unsignedlong2bytes

protected static byte[] unsignedlong2bytes(long number)

unsignint2seplets

protected static byte[] unsignint2seplets(int value)

numOfBytes

protected static int numOfBytes(short number)

numOfBytes

protected static int numOfBytes(int number)

numOfBytes

protected static int numOfBytes(long number)

numOfOcts

protected static int numOfOcts(int n)

numOfOcts

protected static int numOfOcts(long n)

numOfBits

protected static int numOfBits(int n)

numOfBits

protected static int numOfBits(long n)

toHexString

public static java.lang.String toHexString(byte[] octets)


Copyright �2009-2012 ASN Lab