org.topoweb.io
Class StreamFragmenter

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--org.topoweb.io.StreamFragmenter

public class StreamFragmenter

extends java.io.InputStream

Fragments an underlying stream according to a delimiter sequence. This end-of-stream sequence is described by an array of integers with each integer standing in for a byte value. The EOS sequence of bytes is not filtered out. This allows the implementation to avoid reading ahead from the underlying stream. That is, this class does not buffer the underlying stream.

Example Usage

Suppose you're processing a stream containing a sequence of XML elements, each element ending with exactly with the following closing tag:

      <xyz ..>
          .. <!-- other elements but no nested xyz sub-elements -->
      </xyz>
 

Suppose furthur (in order to make the example simpler), that you know that the stream contains 10,000 xyz elements. In order to process each of these xyz elements one at a time, you can set up an instance of this class that will break your stream into a series of XML fragments, as follows:

      InputStream base = .. // get the base stream
      StreamFragmenter frag = StreamFragmenter.newUtfInstance("</xyz>");
      for (int i = 0; i < 10000; ++i) {
          // read and process the next fragment
          // e.g. ..
          javax.xml.transform.Source src =
          new javax.xml.transform.stream.StreamSource(frag);
          ..
          frag.enableNext();
      }
 

Author:

Babak Farhang

Constructor Summary

StreamFragmenter(java.io.InputStream base, int[] eos)
Construct an instance with the given underlying stream and the given end-of-stream sequence.

Method Summary

int	available() Returns the available bytes.
void	enableNext() Enables the next fragment for reading.
int[]	getEosSequence() Returns the end-of-stream sequence passed in at instantiation.
boolean	isEndOfBase() Tests whether the end of the base stream was reached in the last read.
static StreamFragmenter	newUtfInstance(java.io.InputStream base, java.lang.String eos) Creates and returns a new instance using the given end-of-stream (eos) sequence.
int	read() Reads and returns the next byte in the current fragment.

Methods inherited from class java.io.InputStream

close, mark, markSupported, read, read, reset, skip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamFragmenter

public StreamFragmenter(java.io.InputStream base,
                        int[] eos)
                 throws java.lang.IllegalArgumentException

Construct an instance with the given underlying stream and the given end-of-stream sequence.

Parameters:

base - the base input stream

eos - the end-of-stream sequence

Throws:

java.lang.IllegalArgumentException - if either of the parameters is null; if eos.length is zero

Method Detail

newUtfInstance

public static StreamFragmenter newUtfInstance(java.io.InputStream base,
                                              java.lang.String eos)

Creates and returns a new instance using the given end-of-stream (eos) sequence. The EOS sequence is the UTF-8 representation of the given eos string.

Parameters:

base - the base input stream

eos - the EOS sequence expressed as a UTF-8 string

Returns:

a new StreamFragmenter instance over the given base input stream

getEosSequence

public int[] getEosSequence()

Returns the end-of-stream sequence passed in at instantiation.

Returns:

a copy of the end-of-stream sequence

available

public int available()

Returns the available bytes.

Overrides:

available in class java.io.InputStream

Returns:

0 if at the end of the fragment; 1, o.w.

read

public int read()
         throws java.io.IOException

Reads and returns the next byte in the current fragment. If the end of the fragment has been reached, -1 is returned.

Specified by:

read in class java.io.InputStream

java.io.IOException

isEndOfBase

public boolean isEndOfBase()

Tests whether the end of the base stream was reached in the last read.

Returns:

true, if the end of the base stream has been reached; false, o.w.

enableNext

public void enableNext()
                throws java.lang.IllegalStateException

Enables the next fragment for reading. This method should be invoked only if the last fragment was completely read.

Throws:

java.lang.IllegalStateException - if the current fragment is not yet finished