SAXBuilder which listens for SAX events.
People overriding this class are cautioned to ensure that the implementation of the cleanUp() method resets to a virgin state. The cleanUp() method will be called when this SAXHandler is reset(), which may happen multiple times between parses. The cleanUp() method must ensure that there are no references remaining to any external instances.
Overriding of this class is permitted to allow for different handling of SAX
events. Once you have created a subclass of this, you also need to create a
custom implementation of SAXHandlerFactory to supply your instances
to SAXBuilder
If the XMLReader producing the SAX Events supports a document Locator, then this instance will use the locator to supply the line and column data from the SAX locator to the JDOMFactory
Note
the SAX
specification for the SAX Locator indicates that the line and column
represent the position of the end of the SAX Event. For
example, the line and column of the simple XML <root />
would be line 1, column 9.
org.jdom2.input.sax
| Modifier and Type | Field and Description |
|---|---|
| private boolean | atRoot
Indicator of where in the document we are - must be reset() |
| private Document | currentDocument
|
| private Element | currentElement
|
| private Locator | currentLocator
The SAX Locator object provided by the parser |
| private final List | declaredNamespaces
Temporary holder for namespaces that have been declared with startPrefixMapping, but are not yet available on the element |
| private int | entityDepth
How many nested entities we're currently within - must be reset() |
| private boolean | expand
Indicator of whether we should expand entities - must be reset() |
| private final Map | externalEntities
The external entities defined in this document |
| private final JDOMFactory | factory
The JDOMFactory used for JDOM object creation |
| private boolean | ignoringBoundaryWhite
Whether to ignore text containing all whitespace |
| private boolean | ignoringWhite
Whether to ignore ignorable whitespace |
| private boolean | inCDATA
Indicator of whether we are in a CDATA - must be reset() |
| private boolean | inDTD
Indicator of whether we are in the DocType. |
| private boolean | inInternalSubset
Indicator of whether we are in the internal subset - must be reset() |
| private final StringBuilder | internalSubset
Temporary holder for the internal subset |
| private int | |
| private int | |
| private boolean | previousCDATA
Indicator of whether we previously were in a CDATA - must be reset() |
| private boolean | suppress
Indicator of whether we are actively suppressing (non-expanding) a current entity - must be reset() |
| private final TextBuffer | textBuffer
Temporary holder for Text and CDATA |
| Access | Constructor and Description |
|---|---|
| public | SAXHandler()
This will create a new |
| public | SAXHandler(final JDOMFactory
JDOMFactory to be used for constructing objectsThis will create a new |
| Modifier and Type | Method and Description |
|---|---|
| private void | appendExternalId(final String
the public ID publicID, final String the system ID systemID)Appends an external ID to the internal subset buffer. |
| public void | attributeDecl(final String
String element name of attributeString attribute nameString attribute typeString default value of attributeString value of attributeImplements org. |
| public void | characters(final char[]
char[] character array with character dataint index in array where data starts.int length of data.Overrides org. Implements org. |
| public void | comment(final char[]
ch[] array of comment characters.int index to start reading from.int length of data.Implements org. |
| public void | elementDecl(final String
String name of elementString model of the element in DTD syntaxImplements org. |
| public void | |
| public void | endDTD()
Implements org. |
| public void | endElement(final String
String URI of namespace this element is associated
withString name of element without prefixString name of element in XML 1.0 formOverrides org. Implements org. </[element name]>) is
reached.
|
| public void | endEntity(final String
The name of the entity that is ending. name)Implements org. |
| public void | externalEntityDecl(final String
entity name name, final String public id publicID, final String system id systemID)Implements org. |
| protected void | |
| protected void | |
| public Element | |
| public Document | |
| public Locator | Returns: Locator an object that can return the location of
any SAX document event.Provides access to the |
| public boolean | Returns: boolean - whether entity expansion will occur during
build.Returns whether or not entities will be expanded during the build. |
| public JDOMFactory | Returns: JDOMFactory - the factory used for constructing
objects.Returns the factory used for constructing objects. |
| public boolean | Returns: boolean - whether only whitespace content will be
ignored during build.Returns whether or not the parser will eliminate element content containing only whitespace. |
| public boolean | Returns: boolean - whether ignorable whitespace will be
ignored during build.Returns whether or not the parser will eliminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document. |
| public void | ignorableWhitespace(final char[]
[] - char array of ignorable whitespaceint - starting position within arrayint - length of whitespace after startOverrides org. Implements org. |
| public void | internalEntityDecl(final String
String name of entityString value of the entityImplements org. |
| public void | notationDecl(final String
name of the notation name, final String the public ID of the notation publicID, final String the system ID of the notation systemID)Overrides org. Implements org. |
| public void | processingInstruction(final String
String target of PIString containing all data sent to the PI. This
typically looks like one or more attribute value pairs.Overrides org. Implements org. |
| protected void | pushElement(final Element
root element under which content will be built element)Pushes an element onto the tree under construction. |
| public final void | |
| protected void | resetSubCLass()
Override this method if you are a subclasser, and you want to clear the state of your SAXHandler instance in preparation for a new parse. |
| public void | setDocumentLocator(final Locator
Locator an object that can return the location of any
SAX document event.Overrides org. Implements org. |
| public void | setExpandEntities(final boolean
boolean indicating whether entity expansion should
occur.This sets whether or not to expand entities during the build. |
| public void | setIgnoringBoundaryWhitespace(final boolean
Whether to ignore only whitespace content ignoringBoundaryWhite)Specifies whether or not the parser should eliminate text() nodes containing only whitespace when building the document. |
| public void | setIgnoringElementContentWhitespace(final boolean
Whether to ignore ignorable whitespace ignoringWhite)Specifies whether or not the parser should eliminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document. |
| public void | skippedEntity(final String
String name of entityOverrides org. Implements org. |
| public void | |
| public void | startDocument()
Overrides org. Implements org. |
| public void | startDTD(final String
String name of element listed in DTDString public ID of DTDString system ID of DTDImplements org. Document object.
|
| public void | startElement(final String
String namespace URI this element is associated with,
or an empty StringString name of element (with no namespace prefix, if
one is present)String XML 1.0 version of element name: [namespace
prefix]:[localName]Attributes list for this elementOverrides org. Implements org. |
| public void | startEntity(final String
The name of the entity. If it is a parameter
entity, the name will begin with '%', and if it is the
external DTD subset, it will be "[dtd]". name)Implements org. |
| public void | startPrefixMapping(final String
String namespace prefix.String namespace URI.Overrides org. Implements org. Document
object.
|
| private void | transferNamespaces(final Element
Element to read namespaces from.This will take the supplied |
| public void | unparsedEntityDecl(final String
String of the unparsed entity declString of the unparsed entity declString of the unparsed entity declString of the unparsed entity declOverrides org. Implements org. |
| atRoot | back to summary |
|---|---|
| private boolean atRoot Indicator of where in the document we are - must be reset() | |
| currentDocument | back to summary |
|---|---|
| private Document currentDocument
| |
| currentElement | back to summary |
|---|---|
| private Element currentElement
| |
| currentLocator | back to summary |
|---|---|
| private Locator currentLocator The SAX Locator object provided by the parser | |
| declaredNamespaces | back to summary |
|---|---|
| private final List<Namespace> declaredNamespaces Temporary holder for namespaces that have been declared with startPrefixMapping, but are not yet available on the element | |
| entityDepth | back to summary |
|---|---|
| private int entityDepth How many nested entities we're currently within - must be reset() | |
| expand | back to summary |
|---|---|
| private boolean expand Indicator of whether we should expand entities - must be reset() | |
| externalEntities | back to summary |
|---|---|
| private final Map<String, String[]> externalEntities The external entities defined in this document | |
| factory | back to summary |
|---|---|
| private final JDOMFactory factory The JDOMFactory used for JDOM object creation | |
| ignoringBoundaryWhite | back to summary |
|---|---|
| private boolean ignoringBoundaryWhite Whether to ignore text containing all whitespace | |
| ignoringWhite | back to summary |
|---|---|
| private boolean ignoringWhite Whether to ignore ignorable whitespace | |
| inCDATA | back to summary |
|---|---|
| private boolean inCDATA Indicator of whether we are in a CDATA - must be reset() | |
| inDTD | back to summary |
|---|---|
| private boolean inDTD Indicator of whether we are in the DocType. Note that the DTD consists of both the internal subset (inside the <!DOCTYPE> tag) and the external subset (in a separate .dtd file). - must be reset() | |
| inInternalSubset | back to summary |
|---|---|
| private boolean inInternalSubset Indicator of whether we are in the internal subset - must be reset() | |
| internalSubset | back to summary |
|---|---|
| private final StringBuilder internalSubset Temporary holder for the internal subset | |
| lastcol | back to summary |
|---|---|
| private int lastcol | |
| lastline | back to summary |
|---|---|
| private int lastline | |
| previousCDATA | back to summary |
|---|---|
| private boolean previousCDATA Indicator of whether we previously were in a CDATA - must be reset() | |
| suppress | back to summary |
|---|---|
| private boolean suppress Indicator of whether we are actively suppressing (non-expanding) a current entity - must be reset() | |
| textBuffer | back to summary |
|---|---|
| private final TextBuffer textBuffer Temporary holder for Text and CDATA | |
| SAXHandler | back to summary |
|---|---|
| public SAXHandler() This will create a new | |
| SAXHandler | back to summary |
|---|---|
| public SAXHandler(final JDOMFactory factory) This will create a new
| |
| appendExternalId | back to summary |
|---|---|
| private void appendExternalId(final String publicID, final String systemID) Appends an external ID to the internal subset buffer. Either publicID or systemID may be null, but not both. | |
| attributeDecl | back to summary |
|---|---|
| public void attributeDecl(final String eName, final String aName, final String type, final String valueDefault, final String value) Implements org. This handles an attribute declaration in the internal subset. | |
| characters | back to summary |
|---|---|
| public void characters(final char[] ch, final int start, final int length) throws SAXException Overrides org. Implements org. This will report character data (within an element).
| |
| comment | back to summary |
|---|---|
| public void comment(final char[] ch, final int start, final int length) throws SAXException Implements org. This reports that a comments is parsed. If not in the DTD, this comment
is added to the current JDOM
| |
| elementDecl | back to summary |
|---|---|
| public void elementDecl(final String name, final String model) Implements org. Handle an element declaration in a DTD. | |
| endCDATA | back to summary |
|---|---|
| public void endCDATA() throws SAXException Implements org. Report a CDATA section
| |
| endDTD | back to summary |
|---|---|
| public void endDTD() Implements org. This signifies that the reading of the DTD is complete.
| |
| endElement | back to summary |
|---|---|
| public void endElement(final String namespaceURI, final String localName, final String qName) throws SAXException Overrides org. Implements org. Indicates the end of an element (
| |
| endEntity | back to summary |
|---|---|
| public void endEntity(final String name) throws SAXException Implements org. Doc from org. Report the end of an entity.
| |
| externalEntityDecl | back to summary |
|---|---|
| public void externalEntityDecl(final String name, final String publicID, final String systemID) throws SAXException Implements org. This is called when the parser encounters an external entity declaration.
| |
| flushCharacters | back to summary |
|---|---|
| protected void flushCharacters() throws SAXException This will flush any characters from SAX character calls we've been buffering.
| |
| flushCharacters | back to summary |
|---|---|
| protected void flushCharacters(final String data) throws SAXException Flush the given string into the document. This is a protected method so subclassers can control text handling without knowledge of the internals of this class.
| |
| getCurrentElement | back to summary |
|---|---|
| public Element getCurrentElement() throws SAXException Returns the being-parsed element.
| |
| getDocument | back to summary |
|---|---|
| public Document getDocument() Returns the document. Should be called after parsing is complete.
| |
| getDocumentLocator | back to summary |
|---|---|
| public Locator getDocumentLocator() Provides access to the
| |
| getExpandEntities | back to summary |
|---|---|
| public boolean getExpandEntities() Returns whether or not entities will be expanded during the build.
| |
| getFactory | back to summary |
|---|---|
| public JDOMFactory getFactory() Returns the factory used for constructing objects.
| |
| getIgnoringBoundaryWhitespace | back to summary |
|---|---|
| public boolean getIgnoringBoundaryWhitespace() Returns whether or not the parser will eliminate element content containing only whitespace.
| |
| getIgnoringElementContentWhitespace | back to summary |
|---|---|
| public boolean getIgnoringElementContentWhitespace() Returns whether or not the parser will eliminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.
| |
| ignorableWhitespace | back to summary |
|---|---|
| public void ignorableWhitespace(final char[] ch, final int start, final int length) throws SAXException Overrides org. Implements org. Capture ignorable whitespace as text. If setIgnoringElementContentWhitespace(true) has been called then this method does nothing.
| |
| internalEntityDecl | back to summary |
|---|---|
| public void internalEntityDecl(final String name, final String value) Implements org. Handle an internal entity declaration in a DTD. | |
| notationDecl | back to summary |
|---|---|
| public void notationDecl(final String name, final String publicID, final String systemID) throws SAXException Overrides org. Implements org. Handle the declaration of a Notation in a DTD
| |
| processingInstruction | back to summary |
|---|---|
| public void processingInstruction(final String target, final String data) throws SAXException Overrides org. Implements org. This will indicate that a processing instruction has been encountered. (The XML declaration is not a processing instruction and will not be reported.)
| |
| pushElement | back to summary |
|---|---|
| protected void pushElement(final Element element) Pushes an element onto the tree under construction. Allows subclasses to put content under a dummy root element which is useful for building content that would otherwise be a non-well formed document.
| |
| reset | back to summary |
|---|---|
| public final void reset() Restore this SAXHandler to a clean state ready for another parse round. All internal variables are cleared to an initialized state, and then the resetSubClass() method is called to clear any methods that a subclass may need to have reset. | |
| resetSubCLass | back to summary |
|---|---|
| protected void resetSubCLass() Override this method if you are a subclasser, and you want to clear the state of your SAXHandler instance in preparation for a new parse. | |
| setDocumentLocator | back to summary |
|---|---|
| public void setDocumentLocator(final Locator locator) Overrides org. Implements org. Receives an object for locating the origin of SAX document events. This method is invoked by the SAX parser.
| |
| setExpandEntities | back to summary |
|---|---|
| public void setExpandEntities(final boolean expand) This sets whether or not to expand entities during the build. A true
means to expand entities as normal content. A false means to leave
entities unexpanded as
| |
| setIgnoringBoundaryWhitespace | back to summary |
|---|---|
| public void setIgnoringBoundaryWhitespace(final boolean ignoringBoundaryWhite) Specifies whether or not the parser should eliminate text() nodes
containing only whitespace when building the document. See
| |
| setIgnoringElementContentWhitespace | back to summary |
|---|---|
| public void setIgnoringElementContentWhitespace(final boolean ignoringWhite) Specifies whether or not the parser should eliminate whitespace in element
content (sometimes known as "ignorable whitespace") when building the
document. Only whitespace which is contained within element content that
has an element only content model will be eliminated (see XML Rec 3.2.1).
For this setting to take effect requires that validation be turned on.
The default value of this setting is
| |
| skippedEntity | back to summary |
|---|---|
| public void skippedEntity(final String name) throws SAXException Overrides org. Implements org. This indicates that an unresolvable entity reference has been encountered, normally because the external DTD subset has not been read.
| |
| startCDATA | back to summary |
|---|---|
| public void startCDATA() Implements org. Report a CDATA section
| |
| startDocument | back to summary |
|---|---|
| public void startDocument() Overrides org. Implements org. Doc from org. Receive notification of the beginning of the document. By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as allocating the root node of a tree or creating an output file).
| |
| startDTD | back to summary |
|---|---|
| public void startDTD(final String name, final String publicID, final String systemID) throws SAXException Implements org. This will signify that a DTD is being parsed, and can be used to ensure
that comments and other lexical structures in the DTD are not added to
the JDOM
| |
| startElement | back to summary |
|---|---|
| public void startElement(final String namespaceURI, String localName, final String qName, final Attributes atts) throws SAXException Overrides org. Implements org. This reports the occurrence of an actual element. It will include the
element's attributes, with the exception of XML vocabulary specific
attributes, such as
| |
| startEntity | back to summary |
|---|---|
| public void startEntity(final String name) throws SAXException Implements org. Doc from org. Report the beginning of some internal and external XML entities. The reporting of parameter entities (including
the external DTD subset) is optional, and SAX2 drivers that
report LexicalHandler events may not implement it; you can use the
General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]". When a SAX2 driver is providing these events, all other
events must be properly nested within start/end entity
events. There is no additional requirement that events from
Note that skipped entities will be reported through the
Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:
These will be silently expanded, with no indication of where the original entity boundaries were. Note also that the boundaries of character references (which are not really entities anyway) are not reported. All start/endEntity events must be properly nested.
| |
| startPrefixMapping | back to summary |
|---|---|
| public void startPrefixMapping(final String prefix, final String uri) throws SAXException Overrides org. Implements org. This will add the prefix mapping to the JDOM
| |
| transferNamespaces | back to summary |
|---|---|
| private void transferNamespaces(final Element element) This will take the supplied
| |
| unparsedEntityDecl | back to summary |
|---|---|
| public void unparsedEntityDecl(final String name, final String publicID, final String systemID, final String notationName) Overrides org. Implements org. Handler for unparsed entity declarations in the DTD | |