Package com.ctc.wstx.io
Class WstxInputSource
- java.lang.Object
-
- com.ctc.wstx.io.WstxInputSource
-
- Direct Known Subclasses:
BaseInputSource
public abstract class WstxInputSource extends Object
Interface that defines API actual parsers (stream readers) 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
Fields Modifier and Type Field Description protected int
mEntityDepth
Number of parent entities that have been expanded to get to this input source; 0 for root-level input that is not generated via entity expansion.protected String
mFromEntity
Name/id of the entity that was expanded to produce this input source; null if not entity-originated.protected WstxInputSource
mParent
Parent in input source stackprotected int
mScopeId
Scope of the reader when this entity was initially expanded.
-
Constructor Summary
Constructors Modifier Constructor Description protected
WstxInputSource(WstxInputSource parent, String fromEntity)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
close()
Method reader calls for this input source when it has encountered EOF.abstract void
closeCompletely()
Method reader MAY call to force full closing of the underlying input stream(s)/reader(s).protected abstract void
doInitInputLocation(WstxInputData reader)
abstract boolean
fromInternalEntity()
int
getEntityDepth()
String
getEntityId()
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 String
getPublicId()
int
getScopeId()
abstract URL
getSource()
abstract String
getSystemId()
void
initInputLocation(WstxInputData reader, int currScopeId, int entityDepth)
Method called by Reader when current input has changed to come from this input source.boolean
isOrIsExpandedFrom(String entityId)
Method that checks if this input source expanded from the specified entity id, directly or by ancestor.abstract void
overrideSource(URL url)
Method that can be called to override originally defined 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).String
toString()
-
-
-
Field Detail
-
mParent
protected final WstxInputSource mParent
Parent in input source stack
-
mFromEntity
protected final String mFromEntity
Name/id of the entity that was expanded to produce this input source; null if not entity-originated. Used for catching recursive expansions of entities.
-
mScopeId
protected int mScopeId
Scope of the reader when this entity was initially expanded. Snapshot that will generally be used by the reader to match scoping limitations, such as proper nesting entity expansion with respect to element and declaration nesting.
-
mEntityDepth
protected int mEntityDepth
Number of parent entities that have been expanded to get to this input source; 0 for root-level input that is not generated via entity expansion.
-
-
Constructor Detail
-
WstxInputSource
protected WstxInputSource(WstxInputSource parent, String fromEntity)
-
-
Method Detail
-
overrideSource
public abstract void overrideSource(URL url)
Method that can be called to override originally defined source.- Parameters:
url
- New base URL to set; may be null.- Since:
- 4.0
-
getParent
public final WstxInputSource getParent()
-
isOrIsExpandedFrom
public boolean isOrIsExpandedFrom(String entityId)
Method that checks if this input source expanded from the specified entity id, directly or by ancestor.Note that entity ids are expected to have been interned (using whatever uniqueness mechanism used), and thus can be simply identity checked.
-
fromInternalEntity
public abstract boolean fromInternalEntity()
- Returns:
- True, if this input source was directly expanded from an internal entity (general, parsed); false if not (from external entity, DTD ext. subset, main document)
-
getSource
public abstract URL getSource() throws IOException
- Throws:
IOException
-
getPublicId
public abstract String getPublicId()
-
getSystemId
public abstract 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)
-
getEntityId
public String getEntityId()
-
getScopeId
public int getScopeId()
-
getEntityDepth
public int getEntityDepth()
-
initInputLocation
public final void initInputLocation(WstxInputData reader, int currScopeId, int entityDepth)
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.- Parameters:
reader
- Reader whose data structures are to be used for returning data readcurrScopeId
-
-
doInitInputLocation
protected abstract void doInitInputLocation(WstxInputData reader)
-
readInto
public abstract int readInto(WstxInputData reader) throws IOException, XMLStreamException
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:
IOException
XMLStreamException
-
readMore
public abstract boolean readMore(WstxInputData reader, int minAmount) throws IOException, XMLStreamException
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:
IOException
XMLStreamException
-
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 IOException
Method reader calls for this input source when it has encountered EOF. This may or may not close the underlying stream/reader; what happens depends on configuration- Throws:
IOException
-
closeCompletely
public abstract void closeCompletely() throws IOException
Method reader MAY call to force full closing of the underlying input stream(s)/reader(s). No checks are done regarding configuration, but input source object is to deal gracefully with multiple calls (ie. it's not an error for reader to call this more than once).- Throws:
IOException
-
-