GXPARSE hosted by SourceForge.net Logo

ca.gorman.util.scan.spi
Class AbstractScanBuffer

java.lang.Object
  extended by ca.gorman.util.scan.spi.AbstractScanBuffer
All Implemented Interfaces:
Expandable, InputScanBuffer, ScanBuffer, CharSequence

public abstract class AbstractScanBuffer
extends Object
implements InputScanBuffer

A ScanBuffer factory.

AbstractScanBuffer holds only references and indices to the data in the CharSequence. Consequently, a change in the content of a CharSequence can produce a change in the content of any buffer or sub-buffer. If a non-volatile character sequence is required, from a buffer or sub-buffer, the sequence should be obtained by invoking the toString() method on the buffer, sub-buffer, or a subsequence of the buffer or sub-buffer. Sub-sequences and strings are obtained directly from the underlying CharSequence, thereby exploiting all of the efficiencies in the implementation of the CharSequence.


Constructor Summary
protected AbstractScanBuffer(CharSequence charSequence)
          Construct on a CharSequence that has a fixed length.
protected AbstractScanBuffer(CharSequence charSequence, InputControl inputControl)
          Construct on a CharSequence with a length that can be increased by a request from the AbstractScanBuffer.
 
Method Summary
 MatchedText accept(int length)
           Remove a prefix of the ScanBuffer from the ScanBuffer and create a MatchedText containing the same characters.
 MatchedText act(ScanRule scanRule)
           Test a ScanRule for a match against a leading prefix of the ScanBuffer and invoke the corresponding action if the match succeeds.
 char charAt(int index)
           
 void discardMatchedText()
           Release all previously accepted input data.
 boolean expand()
           Increase the amount of data in the buffer, if the buffer supports expansion.
 int fill()
           Read characters into free space in the buffer.
 Map<String,CharSequence> getMap()
           Get the map that supports saving and retrieving character sequences as temporary values.
 boolean hitLast()
           Indicate whether the last character in the buffer has been accessed since the previous invocation of this function.
 int length()
           
static AbstractScanBuffer newInstance(CharSequence charSequence)
          Create a AbstractScanBuffer for scanning and matching on a CharSequence that has a fixed length.
static AbstractScanBuffer newInstance(CharSequence charSequence, InputControl inputControl)
          Create a AbstractScanBuffer for scanning and matching on a CharSequence with a length that can be increased by a request from the AbstractScanBuffer.
 CharSequence put(String key, CharSequence value)
           Save a CharSequence for later retrieval in an action.
 ScanState setScanState(ScanState scanState)
           Set a reference to the scanner state for use by the buffer match and act method.
 ScanBuffer subBuffer(int offset)
           Get a new buffer, beginning at the specified offset from the beginning of the buffer, and continuing to the end of the parent buffer.
 CharSequence subSequence(int start, int end)
           
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractScanBuffer

protected AbstractScanBuffer(CharSequence charSequence)
Construct on a CharSequence that has a fixed length.

Parameters:
charSequence - The data to be scanned
Throws:
NullPointerException - if any parameter is null

AbstractScanBuffer

protected AbstractScanBuffer(CharSequence charSequence,
                             InputControl inputControl)
Construct on a CharSequence with a length that can be increased by a request from the AbstractScanBuffer.

Parameters:
charSequence - The data to be scanned
inputControl - Callback interface for increasing the length
Throws:
NullPointerException - if any parameter is null
Method Detail

newInstance

public static AbstractScanBuffer newInstance(CharSequence charSequence,
                                             InputControl inputControl)
Create a AbstractScanBuffer for scanning and matching on a CharSequence with a length that can be increased by a request from the AbstractScanBuffer.

Parameters:
charSequence - The data to be scanned
inputControl - Callback interface for increasing the length
Throws:
NullPointerException - if any parameter is null G

newInstance

public static AbstractScanBuffer newInstance(CharSequence charSequence)
Create a AbstractScanBuffer for scanning and matching on a CharSequence that has a fixed length.

Parameters:
charSequence - The data to be scanned
Throws:
NullPointerException - if any parameter is null

length

public int length()
Specified by:
length in interface CharSequence

charAt

public char charAt(int index)
Specified by:
charAt in interface CharSequence

hitLast

public boolean hitLast()
Description copied from interface: InputScanBuffer

Indicate whether the last character in the buffer has been accessed since the previous invocation of this function.

Resets the indicator to false until the next time that the last character is accessed.

Specified by:
hitLast in interface InputScanBuffer

subSequence

public CharSequence subSequence(int start,
                                int end)
Specified by:
subSequence in interface CharSequence

toString

public String toString()
Specified by:
toString in interface CharSequence
Overrides:
toString in class Object

accept

public MatchedText accept(int length)
Description copied from interface: ScanBuffer

Remove a prefix of the ScanBuffer from the ScanBuffer and create a MatchedText containing the same characters.

Although the prefix is no longer available in this ScanBuffer any ancestors of this ScanBuffer will remain unchanged.

Specified by:
accept in interface ScanBuffer
Parameters:
length - the number (zero or more) of characters to accept and remove.
Returns:
an instance of MatchedText, containing the accepted characters

discardMatchedText

public void discardMatchedText()
                        throws IOException
Description copied from interface: InputScanBuffer

Release all previously accepted input data.

Warning: In some implementations, the previously accepted MatchedText instances will no longer contain valid data.

Specified by:
discardMatchedText in interface InputScanBuffer
Throws:
IOException

fill

public int fill()
         throws IOException
Description copied from interface: InputScanBuffer

Read characters into free space in the buffer.

This method may block until characters become available.

Specified by:
fill in interface InputScanBuffer
Returns:
The number of new characters read in, or -1 if the buffer is empty and no more characters will ever be available.
Throws:
IOException

expand

public boolean expand()
               throws IOException
Description copied from interface: Expandable

Increase the amount of data in the buffer, if the buffer supports expansion.

Expansion is not guaranteed, because the buffer may not support expansion or because the current state of the buffer (or its data source) may not permit expansion.

A successful expansion of a full buffer will increase the memory used by the buffer. A buffer with free space may simply add more data to the free space instead of acquiring and filling additional memory.

Specified by:
expand in interface Expandable
Returns:
true if more data has been made available in the buffer
Throws:
IOException

subBuffer

public ScanBuffer subBuffer(int offset)
Description copied from interface: ScanBuffer

Get a new buffer, beginning at the specified offset from the beginning of the buffer, and continuing to the end of the parent buffer.

The new buffer shares the characters from the offset to the end of the parent buffer.

Specified by:
subBuffer in interface ScanBuffer

put

public CharSequence put(String key,
                        CharSequence value)
Description copied from interface: ScanBuffer

Save a CharSequence for later retrieval in an action. The data will be discarded when the Scanner completes the next action.

Specified by:
put in interface ScanBuffer
Returns:
Previous value, or null if no value has been set since the completion of the last action.

getMap

public Map<String,CharSequence> getMap()
Description copied from interface: InputScanBuffer

Get the map that supports saving and retrieving character sequences as temporary values.

Specified by:
getMap in interface InputScanBuffer

setScanState

public ScanState setScanState(ScanState scanState)
Description copied from interface: InputScanBuffer

Set a reference to the scanner state for use by the buffer match and act method.

Specified by:
setScanState in interface InputScanBuffer
Returns:
previous scanner state

act

public MatchedText act(ScanRule scanRule)
                throws IOException
Description copied from interface: ScanBuffer

Test a ScanRule for a match against a leading prefix of the ScanBuffer and invoke the corresponding action if the match succeeds.

Specified by:
act in interface ScanBuffer
Returns:
the sequence of characters matched (zero or more) or null if the match did not succeed.
Throws:
IOException
See Also:
InputScanBuffer.setScanState(ScanState)

GXPARSE download

GXPARSE Generic XML Stream Parser API and supporting tools.   Release $Name: gxparse-sf-alpha-2_0 $
Copyright 2003-2004 Ian E. Gorman
Released under GNU Lesser General Public License