## org.exist.util
Class FastByteBuffer

    java.lang.Object
      org.exist.util.FastByteBuffer

All Implemented Interfaces:
  ByteArray

public class FastByteBuffer
extends java.lang.Object
implements ByteArray

Copied this class from Xalan and adopted it for eXist. Bare-bones, unsafe, fast string buffer. No thread-safety, no parameter range checking, exposed fields. Note that in typical applications, thread-safety of a StringBuffer is a somewhat dubious concept in any case.

Note that Stree and DTM used a single FastStringBuffer as a string pool, by recording start and length indices within this single buffer. This minimizes heap overhead, but of course requires more work when retrieving the data.

FastStringBuffer operates as a "chunked buffer". Doing so reduces the need to recopy existing information when an append exceeds the space available; we just allocate another chunk and flow across to it. (The array of chunks may need to grow, admittedly, but that's a much smaller object.) Some excess recopying may arise when we extract Strings which cross chunk boundaries; larger chunks make that less frequent.

The size values are parameterized, to allow tuning this code. In theory, Result Tree Fragments might want to be tuned differently from the main document's text.

%REVIEW% An experiment in self-tuning is included in the code (using nested FastStringBuffers to achieve variation in chunk sizes), but this implementation has proven to be problematic when data may be being copied from the FSB into itself. We should either re-architect that to make this safe (if possible) or remove that code and clean up for performance/maintainability reasons.

Constructor Summary
`FastByteBuffer()` Construct a FastStringBuffer, using a default allocation policy.
`FastByteBuffer(int initChunkBits)` Construct a FastStringBuffer, using default maxChunkBits and rebundleBits values.
`FastByteBuffer(int initChunkBits, int maxChunkBits)` Construct a FastStringBuffer, using a default rebundleBits value.
`FastByteBuffer(int initChunkBits, int maxChunkBits, int rebundleBits)` Construct a FastStringBuffer, with allocation policy as per parameters.

Method Summary
`void` `append(byte value)` Append a single character onto the FastStringBuffer, growing the storage if necessary.
`void` `append(byte[] chars)` Append the contents of the array onto the buffer.
`void` `append(byte[] chars, int start, int length)` Append part of the contents of a Character Array onto the FastStringBuffer, growing the storage if necessary.
`void` `append(FastByteBuffer value)` Append the contents of another FastStringBuffer onto this FastStringBuffer, growing the storage if necessary.
`void` `copyTo(byte[] newBuf, int offset)`
`void` `copyTo(ByteArray newBuf)`
`void` `copyTo(java.nio.ByteBuffer newBuf)`
`void` `copyTo(int start, byte[] newBuf, int offset, int len)`
`void` `copyTo(int start, java.nio.ByteBuffer buf, int len)`
`int` `length()` Get the length of the list.
`void` `reset()` Discard the content of the FastStringBuffer, and most of the memory that was allocated by it, restoring the initial state.
`void` `set(int position, byte b)`
`void` `setLength(int l)` Directly set how much of the FastStringBuffer's storage is to be considered part of its content.
`int` `size()` Get the length of the list.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### FastByteBuffer

    public FastByteBuffer(int initChunkBits,
                          int maxChunkBits,
                          int rebundleBits)

  Construct a FastStringBuffer, with allocation policy as per parameters.

  For coding convenience, I've expressed both allocation sizes in terms of a number of bits. That's needed for the final size of a chunk, to permit fast and efficient shift-and-mask addressing. It's less critical for the inital size, and may be reconsidered.

  An alternative would be to accept integer sizes and round to powers of two; that really doesn't seem to buy us much, if anything.

Parameters:
  `initChunkBits` - Length in characters of the initial allocation of a chunk, expressed in log-base-2. (That is, 10 means allocate 1024 characters.) Later chunks will use larger allocation units, to trade off allocation speed of large document against storage efficiency of small ones.
  `maxChunkBits` - Number of character-offset bits that should be used for addressing within a chunk. Maximum length of a chunk is 2^chunkBits characters.
  `rebundleBits` - Number of character-offset bits that addressing should advance before we attempt to take a step from initChunkBits to maxChunkBits

### FastByteBuffer

    public FastByteBuffer(int initChunkBits,
                          int maxChunkBits)

  Construct a FastStringBuffer, using a default rebundleBits value. NEEDSDOC

Parameters:
  `initChunkBits` - NEEDSDOC
  `maxChunkBits` -

### FastByteBuffer

    public FastByteBuffer(int initChunkBits)

  Construct a FastStringBuffer, using default maxChunkBits and rebundleBits values.

  ISSUE: Should this call assert initial size, or fixed size? Now configured as initial, with a default for fixed.

Parameters:
  `initChunkBits` -

### FastByteBuffer

    public FastByteBuffer()

  Construct a FastStringBuffer, using a default allocation policy.

Method Detail

### append

    public final void append(byte value)

  Append a single character onto the FastStringBuffer, growing the storage if necessary.

  NOTE THAT after calling append(), previously obtained references to m_array[][] may no longer be valid.... though in fact they should be in this instance.

  Specified by:
    `append` in interface `ByteArray`
  Parameters:
    `value` - character to be appended.

### append

    public final void append(byte[] chars)

  Append the contents of the array onto the buffer.

  Specified by:
    `append` in interface `ByteArray`
  Parameters:
    `chars` - Description of the Parameter

### append

    public final void append(byte[] chars,
                             int start,
                             int length)

  Append part of the contents of a Character Array onto the FastStringBuffer, growing the storage if necessary.

  NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.

  Specified by:
    `append` in interface `ByteArray`
  Parameters:
    `chars` - character array from which data is to be copied
    `start` - offset in chars of first character to be copied, zero-based.
    `length` - number of characters to be copied

### append

    public final void append(FastByteBuffer value)

  Append the contents of another FastStringBuffer onto this FastStringBuffer, growing the storage if necessary.

  NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.

  Parameters:
    `value` - FastStringBuffer whose contents are to be appended.

### copyTo

    public void copyTo(byte[] newBuf,
                       int offset)

  Specified by:
    `copyTo` in interface `ByteArray`

### copyTo

    public void copyTo(ByteArray newBuf)

  Specified by:
    `copyTo` in interface `ByteArray`

### copyTo

    public void copyTo(java.nio.ByteBuffer newBuf)

  Specified by:
    `copyTo` in interface `ByteArray`

### copyTo

    public void copyTo(int start,
                       byte[] newBuf,
                       int offset,
                       int len)

  Specified by:
    `copyTo` in interface `ByteArray`

### copyTo

    public void copyTo(int start,
                       java.nio.ByteBuffer buf,
                       int len)

  Specified by:
    `copyTo` in interface `ByteArray`

### set

    public void set(int position,
                    byte b)

### length

    public final int length()

  Get the length of the list. Synonym for size().

  Returns:
    the number of characters in the FastStringBuffer's content.

### reset

    public final void reset()

  Discard the content of the FastStringBuffer, and most of the memory that was allocated by it, restoring the initial state. Note that this may eventually be different from setLength(0), which see.

### setLength

    public final void setLength(int l)

  Directly set how much of the FastStringBuffer's storage is to be considered part of its content. This is a fast but hazardous operation. It is not protected against negative values, or values greater than the amount of storage currently available... and even if additional storage does exist, its contents are unpredictable. The only safe use for our setLength() is to truncate the FastStringBuffer to a shorter string.

  Specified by:
    `setLength` in interface `ByteArray`
  Parameters:
    `l` - New length. If l<0 or l>=getLength(), this operation will not report an error but future operations will almost certainly fail.

### size

    public final int size()

  Get the length of the list. Synonym for length().

  Specified by:
    `size` in interface `ByteArray`
  Returns:
    the number of characters in the FastStringBuffer's content.

Copyright (C) Wolfgang Meier. All rights reserved.