Class Buffer

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

public abstract class Buffer extends 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 Hu
  • Constructor Details

    • Buffer

      public Buffer()
  • Method Details

    • 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:
      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(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(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
    • asInputStream

      protected InputStream asInputStream()
    • asOutputStream

      protected OutputStream asOutputStream()
    • 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 IOException
      Flushes the buffer to the underlying output stream as needed. Do nothing by default.
      Throws:
      IOException - If underlying exception IO operation
    • 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:
      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:
      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
    • offset

      public final Buffer offset(int offset)
    • verbose

      public final Buffer verbose()
    • 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 already.

      Returns:
      This buffer
    • encodingRules

      public byte encodingRules()
      Returns this buffer's encoding rules.
      Returns:
      The encoding rules of this buffer
    • getBytes

      public void getBytes(byte[] dst)
    • getBytes

      public void getBytes(byte[] dst, int offset, int length)
    • putBytes

      public void putBytes(byte[] src)
    • putBytes

      public void putBytes(byte[] src, int offset, int length)
    • rputBytes

      public void rputBytes(byte[] src, int length)
    • rputBytes

      public void rputBytes(byte[] src, int offset, int length)
    • getBitField

      public org.asnlab.asndt.runtime.diag.BitField getBitField()
    • setBitField

      public void setBitField(org.asnlab.asndt.runtime.diag.BitField bitField)
    • 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)
    • bytes2unsignedlong

      protected static long bytes2unsignedlong(byte[] bytes)
    • 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 String toHexString(byte[] octets)
    • toHexString

      public static String toHexString(byte[] octets, String separator)
    • parseHexString

      public static byte[] parseHexString(String hex)