|
GXPARSE hosted by | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Listener<T extends Parser>
Combined listener interface for XML processing applications that are driven
by an XML push Parser
.
This interface borrows ideas from, and has considerable similarity to,
David Megginson's
SAX interface, as
embodied in class org.xml.sax.ext.DefaultHandler2
and the interfaces
org.xml.sax.ContentHandler
org.xml.sax.DTDHandler
org.xml.sax.EntityResolver
org.xml.sax.ErrorHandler
org.xml.sax.ext.DeclHandler
org.xml.sax.ext.LexicalHandler
The principal differences from event based parser interfaces like SAX are:
doDocument(Parser, CurrentDocument)
that
instead of two methods that separately notify the start and the end
of a document. The method does not exit until all content
of the document has been parsed. Document content is parsed by
invoking a parser callback
from within the method.
doDocument(Parser, CurrentDtd)
that
instead of two methods that separately notify the start and the end
of a DTD. The method does not exit until all content
of the DTD has been parsed. DTD content is parsed by
invoking a parser callback
from within the method.
doElement(Parser, CurrentElement)
instead of in two methods that separately notify the start and the
end of an element. Information from the start tag remains available
until the method exits. The method does not exit until all content
of the element, including any child elements, has been parsed.
Element content is is parsed by invoking a
parser callback
from within
the method.
doEntity(Parser, CurrentEntity)
instead of two methods that separately notify the start and the end
of an entity. The method does not exit until all content of the
entity has been parsed. Entity content is parsed by invoking a
parser callback
from within
the method. Entity and Element notifications can be nested inside
each other.
CharSequence
by
two different methods.
instead of being presented as a subarray of an array of characters.
This has two advantages, (1) presenting only the characters of
interest, and (2) presenting the characters in the most convenient way
for stream processing..
cdata
instead of in two methods
that mark the beginning and end. This simplifies state management
(like handling CDATA differently from PCDATA) by bringing all of the
management into the scope of a single method.
Most Listener methods receive String parameters, usually the same as the parameters received by corresponding SAX methods, because the String parameters correspond exactly to data in the XML imput file. This creates a bit more work in the application, but it also gives more flexibility in processing because there is no need to undo a transformation that would otherwise hide some characteristics of the input data from the application. David Megginson may have had a similar reason for returning String parameters in the SAX interface.
A number of Listener
methods are inherited from sperclasses to
support delegation of the methods from a subclass of Listener
.
More of the methods may be moved to new superclasses in the future.
Method Summary | |
---|---|
void |
cdata(T parser,
CurrentMarkedSection cdata)
Receive a CDATA marked section. |
void |
comment(T parser,
CharSequence charSequence)
Report an XML comment anywhere in the document. |
void |
doDocument(T parser,
CurrentDocument document)
Receive a request to handle a document that is being
parsed. |
Input |
getExternalSubset(T parser,
String name,
String baseURI)
Allows applications to replace a missing external subset. |
void |
processingInstruction(T parser,
String target,
String data)
Receive notification of a processing instruction. |
Input |
resolveEntity(T parser,
String name,
String publicId,
String baseURI,
String systemId)
Allow the application to resolve external entities. |
Methods inherited from interface ca.gorman.xml.parse.CharacterListener |
---|
characters, ignorableWhitespace |
Methods inherited from interface ca.gorman.xml.parse.DtdListener |
---|
attributeDecl, doDtd, elementDecl, externalEntityDecl, internalEntityDecl, notationDecl, unparsedEntityDecl |
Methods inherited from interface ca.gorman.xml.parse.ElementListener |
---|
doElement |
Methods inherited from interface ca.gorman.xml.parse.EntityListener |
---|
doEntity |
Methods inherited from interface ca.gorman.xml.parse.MessageListener |
---|
error, fatalError, warning |
Methods inherited from interface ca.gorman.xml.parse.PrefixListener |
---|
endPrefixMapping, startPrefixMapping |
Methods inherited from interface ca.gorman.xml.parse.SkippedEntityListener |
---|
skippedEntity |
Method Detail |
---|
void cdata(T parser, CurrentMarkedSection cdata) throws ListenerException, IOException
Receive a CDATA marked section.
The method is invoked at the beginning of the CDATA section. The method
must invoke
content handler
exactly once to parse the CDATA section. Consequently, this
method has control only before and after the parser reads the CDATA
section
parser
- The Parser
that invoked this methodcdata
- CurrentMarkedSection
instance with a
content handler
to parse the centent of the entity.
ListenerRuntimeException
- if this method does not invoke the
content handler
exactly once before returning.
ListenerException
IOException
void doDocument(T parser, CurrentDocument document) throws ListenerException, IOException
Receive a request to handle a document
that is being
parsed. The method is invoked just before the parser begins parsing.
The method must invoke
content handler
exactly once to parse the content of the document. Consequently, this
method has control only before and after the actual parsing operation.
parser
- The Parser
that invoked this methoddocument
- CurrentDocument
instance
with a content handler
to parse the centent of the
document.
ListenerRuntimeException
- if this method does not invoke the
content handler
exactly once before returning.
ListenerException
IOException
Input getExternalSubset(T parser, String name, String baseURI) throws ListenerException, IOException
Allows applications to replace a missing external subset.
This method is invoked when there is a DOCTYPE declaration that does not
define an external subset. Returning an Input
that
provides wan external subset has the same effect as if the document text
had originally included the external subset.
This method is also invoked when the root element has been encountered,
but no DOCTYPE declaration has been seen. Returning an
Input
that provides an external subset has the same effect
as if a DOCTYPE declaration with an external subset had preceded the
root element.
Warning: Returning an external subset modifies the input document. By providing definitions for general entities, it can make a malformed document appear to be well formed.
parser
- The Parser
that invoked this methodname
- Identifies the document root element. This name comes
from a DOCTYPE declaration (where available) or from
the actual root elementbaseURI
- The absolute URI of the document, or null if the URI
was not given to the parser
ListenerException
IOException
void processingInstruction(T parser, String target, String data) throws ListenerException, IOException
Receive notification of a processing instruction.
parser
- The Parser
that invoked this methodtarget
- The processing instruction target.data
- The processing instruction data, or null if
none was supplied. The data does not include any
whitespace separating it from the target.
ListenerException
IOException
Input resolveEntity(T parser, String name, String publicId, String baseURI, String systemId) throws ListenerException, IOException
Allow the application to resolve external entities.
parser
- The Parser
that invoked this methodname
- Either "[dtd]" for the external subset, or a name
starting with "%" to indicate a parameter entity, or
else the name of a general entitypublicId
- The public identifier of the external entity being
referenced, or null if none was suppliedbaseURI
- The absolute URI against which a relative systemID
would be resolved, or null if none was suppliedsystemId
- The absolute or relative URI that identifies the
external entity being referenced.
ListenerException
IOException
void comment(T parser, CharSequence charSequence) throws ListenerException, IOException
Report an XML comment anywhere in the document.
In some implementations, charSequence
may reference data
that is not resident in memory. In such cases, the amount of data may
be large enough to cause the CharSequence.toString()
method
to throw OutOfMemoryError
.
parser
- The Parser
that invoked this methodcharSequence
- A CharSequence containing the characters in the
comment.
ListenerException
IOException
|
GXPARSE download | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |