com.ctc.wstx.io
Class WstxInputSource

java.lang.Object
  com.ctc.wstx.io.WstxInputSource

Direct Known Subclasses:

BaseInputSource

public abstract class WstxInputSource

extends java.lang.Object

Interface that defines API actual parsers (or, "readers" in StAX lingo) can use to read input from various input sources. Needed to abstract out details of getting input from primary input files, secondary (potentially cached) referenced documents, and from parsed entities, as well as for allowing hierarchic location information for error reporting.

Field Summary

protected WstxInputSource

mParent Parent in input source stack

Constructor Summary

protected

WstxInputSource(WstxInputSource parent, java.lang.String fromEntity)

Method Summary

abstract void	close()
abstract int	getInputBufferLength()
protected abstract WstxInputLocation	getLocation() Method usually called to get a parent location for another input source.
abstract WstxInputLocation	getLocation(long total, int row, int col)
WstxInputSource	getParent()
abstract java.lang.String	getPublicId()
abstract java.net.URL	getSource()
abstract java.lang.String	getSystemId()
boolean	hasRecursion() Method that recursively checks if this input source has been expanded -- directly or indirectly -- from specified entity.
abstract void	initInputLocation(WstxInputData reader) Method called by Reader when current input has changed to come from this input source.
abstract int	readInto(WstxInputData reader) Method called to read at least one more char from input source, and update input data appropriately.
abstract boolean	readMore(WstxInputData reader, int minAmount) Method called by reader when it has to have at least specified number of consequtive input characters in its buffer, and it currently does not have.
abstract void	restoreContext(WstxInputData reader) Method Reader calls when this input source is resumed as the current source.
abstract void	saveContext(WstxInputData reader) Method Reader calls when this input source is being stored, when a nested input source gets used instead (due to entity expansion).
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

mParent

protected final WstxInputSource mParent

Parent in input source stack

Constructor Detail

WstxInputSource

protected WstxInputSource(WstxInputSource parent,
                          java.lang.String fromEntity)

Method Detail

getInputBufferLength

public abstract int getInputBufferLength()

Returns:

Length of suggested input buffer (if source needs one); used for passing default buffer size down the input source line.

getParent

public final WstxInputSource getParent()

hasRecursion

public boolean hasRecursion()

Method that recursively checks if this input source has been expanded -- directly or indirectly -- from specified entity. Note that entity ids are expected to have been interned (using whatever uniqueness mechanism used), and thus can be simply equality checked.

getSource

public abstract java.net.URL getSource()

getPublicId

public abstract java.lang.String getPublicId()

getSystemId

public abstract java.lang.String getSystemId()

getLocation

protected abstract WstxInputLocation getLocation()

Method usually called to get a parent location for another input source. Works since at this point context (line, row, chars) information has already been saved to this object.

getLocation

public abstract WstxInputLocation getLocation(long total,
                                              int row,
                                              int col)

initInputLocation

public abstract void initInputLocation(WstxInputData reader)

Method called by Reader when current input has changed to come from this input source. Should reset/initialize input location information Reader keeps, for error messages to work ok.

readInto

public abstract int readInto(WstxInputData reader)
                      throws java.io.IOException

Method called to read at least one more char from input source, and update input data appropriately.

Returns:

Number of characters read from the input source (at least 1), if it had any input; -1 if input source has no more input.

Throws:

java.io.IOException

readMore

public abstract boolean readMore(WstxInputData reader,
                                 int minAmount)
                          throws java.io.IOException

Method called by reader when it has to have at least specified number of consequtive input characters in its buffer, and it currently does not have. If so, it asks input source to do whatever it has to do to try to get more data, if possible (including moving stuff in input buffer if necessary and possible).

Returns:

True if input source was able to provide specific number of characters or more; false if not. In latter case, source is free to return zero or more characters any way.

Throws:

java.io.IOException

saveContext

public abstract void saveContext(WstxInputData reader)

Method Reader calls when this input source is being stored, when a nested input source gets used instead (due to entity expansion). Needs to get location info from Reader and store it in this Object.

restoreContext

public abstract void restoreContext(WstxInputData reader)

Method Reader calls when this input source is resumed as the current source. Needs to update Reader's input location data used for error messages etc.

close

public abstract void close()
                    throws java.io.IOException

Throws:

java.io.IOException

toString

public java.lang.String toString()