Java Doc for FastStringBuffer.java in  » XML » xalan » org » apache » xml » utils » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

For coding convenience, I've expressed both allocation sizes in terms of a number of bits.

Note too that there is no promise that the output will be sent as a single call.

The insertion point for append operations is addressed by the combination of m_lastChunk and m_firstFree.

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 allocationof a chunk, expressed in log-base-2. (That is, 10 means allocate 1024characters.) Later chunks will use larger allocation units, to trade offallocation speed of large document against storage efficiency of smallones.
Parameters:
  maxChunkBits - Number of character-offset bits that should be used foraddressing within a chunk. Maximum length of a chunk is 2^chunkBitscharacters.
Parameters:
  rebundleBits - Number of character-offset bits that addressing shouldadvance before we attempt to take a step from initChunkBits to maxChunkBits

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

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.
Parameters:
  value - character to be appended.

NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.
Parameters:
  value - String whose contents are to be appended.

NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.
Parameters:
  value - StringBuffer whose contents are to be appended.

NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.
Parameters:
  chars - character array from which data is to be copied
Parameters:
  start - offset in chars of first character to be copied,zero-based.
Parameters:
  length - number of characters to be copied

NOTE THAT after calling append(), previously obtained references to m_array[] may no longer be valid.
Parameters:
  value - FastStringBuffer whose contents areto be appended.

Note that this operation has been somewhat deoptimized by the shift to a chunked array, as there is no factory method to produce a String object directly from an array of arrays and hence a double copy is needed. By presetting length we hope to minimize the heap overhead of building the intermediate StringBuffer.

(It really is a pity that Java didn't design String as a final subclass of MutableString, rather than having StringBuffer be a separate hierarchy. We'd avoid a lot of double-buffering.)
Parameters:
  sb -
Parameters:
  startChunk -
Parameters:
  startColumn -
Parameters:
  length - the contents of the FastStringBuffer as a standard Java string.

CURRENTLY DOES NOT CHECK FOR OUT-OF-RANGE.
Parameters:
  start - Offset of first character in the range.
Parameters:
  length - Number of characters to send.

0

if this output did not end in retained whitespace, and thus whitespaceat the start of the following chunk (if any) should be converted to asingle space.

SUPPRESS_LEADING_WS

if this output ended in retained whitespace, and thus whitespaceat the start of the following chunk (if any) should be completelysuppressed.

SUPPRESS_LEADING_WS

When false, causes leading whitespace to be converted to a singlespace; when true, causes it to be discarded entirely.Should be set TRUE for the first chunk, and (in multi-chunk output)whenever the previous chunk ended in retained whitespace.

SUPPRESS_TRAILING_WS

When false, causes trailing whitespace to be converted to a singlespace; when true, causes it to be discarded entirely.Should be set TRUE for the last or only chunk.

0

if this output did not end in retained whitespace, and thus whitespaceat the start of the following chunk (if any) should be converted to asingle space.

SUPPRESS_LEADING_WS

if this output ended in retained whitespace, and thus whitespaceat the start of the following chunk (if any) should be completelysuppressed.

Note that, unlike sendSAXcharacters, this has to be done as a single call to LexicalHandler#comment.
Parameters:
  ch - SAX LexicalHandler object to receive the event.
Parameters:
  start - Offset of first character in the range.
Parameters:
  length - Number of characters to send.
exception:
  org.xml.sax.SAXException - may be thrown by handler'scharacters() method.

Note too that there is no promise that the output will be sent as a single call. As is always true in SAX, one logical string may be split across multiple blocks of memory and hence delivered as several successive events.
Parameters:
  ch - SAX ContentHandler object to receive the event.
Parameters:
  start - Offset of first character in the range.
Parameters:
  length - Number of characters to send.
exception:
  org.xml.sax.SAXException - may be thrown by handler'scharacters() method.

(It really is a pity that Java didn't design String as a final subclass of MutableString, rather than having StringBuffer be a separate hierarchy. We'd avoid a lot of double-buffering.) the contents of the FastStringBuffer as a standard Java string.