The Xerces Native Interface core contains a series of interfaces and classes designed to communicate a document's "streaming" information set. This page documents the API available for receiving this information in the following sections:
A few examples are also included to illustrate the use of the streaming information set:
For information regarding the parser configuration framework, refer to the Parser Configuration documentation.
The document information is communicated using the
XMLDocumentHandler
interface. In addition, the
XMLDocumentFragmentHandler
interface is included
to get information regarding document fragments. Programmers
already familiar with the SAX programming interfaces should
be immediately comfortable programming to the Xerces Native
Interface. However, XNI does not depend on the SAX interfaces
and classes.
org.apache.xerces.xni
package.
Communicates document structure and content information. This is the most important handler interface in the Xerces Native Interface.
Methods |
---|
public void startDocument(
XMLLocator locator,
String encoding
) throws XNIException;
|
public void xmlDecl(
String version,
String encoding,
String standalone
) throws XNIException;
|
public void doctypeDecl(
String rootElement,
String publicId,
String systemId
) throws XNIException;
|
public void comment(
XMLString text
) throws XNIException;
|
public void processingInstruction(
String target,
XMLString data
) throws XNIException;
|
public void startPrefixMapping(
String prefix,
String uri
) throws XNIException;
|
public void endPrefixMapping(
String prefix
) throws XNIException;
|
public void startElement(
QName element,
XMLAttributes attributes
) throws XNIException;
|
public void emptyElement(
QName element,
XMLAttributes attributes
) throws XNIException;
|
public void endElement(
QName element
) throws XNIException;
|
public void startEntity(
String name,
String publicId,
String systemId,
String baseSystemId,
String encoding
) throws XNIException;
|
public void textDecl(
String version,
String encoding
) throws XNIException;
|
public void endEntity(
String name
) throws XNIException;
|
public void characters(
XMLString text
) throws XNIException;
|
public void ignorableWhitespace(
XMLString text
) throws XNIException;
|
public void startCDATA()
throws XNIException;
|
public void endCDATA()
throws XNIException;
|
public void endDocument()
throws XNIException;
|
Communicates information about a document fragment. This interface is provided for convenience in defining a document fragment but is not required to be used by a compliant XNI parser component or configuration.
Methods |
---|
public void startDocumentFragment(
XMLLocator locator,
NamespaceContext
) throws XNIException;
|
public void startEntity(
String name,
String publicId,
String systemId,
String baseSystemId,
String encoding
) throws XNIException;
|
public void textDecl(
String version,
String encoding
) throws XNIException;
|
public void endEntity(
String name
) throws XNIException;
|
public void comment(
XMLString text
) throws XNIException;
|
public void processingInstruction(
String target,
XMLString data
) throws XNIException;
|
public void startPrefixMapping(
String prefix,
String uri
) throws XNIException;
|
public void endPrefixMapping(
String prefix
) throws XNIException;
|
public void startElement(
QName element,
XMLAttributes attributes
) throws XNIException;
|
public void emptyElement(
QName element,
XMLAttributes attributes
) throws XNIException;
|
public void endElement(
QName element
) throws XNIException;
|
public void characters(
XMLString text
) throws XNIException;
|
public void ignorableWhitespace(
XMLString text
) throws XNIException;
|
public void startCDATA()
throws XNIException;
|
public void endCDATA()
throws XNIException;
|
public void endDocumentFragment()
throws XNIException;
|
Besides the handler interfaces there are several related interfaces and classes. All of these are described below.
Represents a generic Xerces Native Interface exception.
Note:
This exception extends java.lang.RuntimeException
.
Therefore, even though all of the handler interface methods can
throw this type of exception, it is not explicitly required to
be caught. Since XNI is intended to be an internal set of
interfaces, it is expected that XNI implementations will provide
a catch block for this exception at the top level so that XNI
exceptions do not "leak" out to the application code.
Constructors |
---|
public XNIException(String message); |
public XNIException(Exception exception); |
public XNIException(String message, Exception exception);
|
Methods |
public Exception getException(); |
This interface is used to communicate the document location to the various handler interfaces. The application can use the methods on this interface to query the public, system, and base system identifier as well as the line and column number.
A locator is passed as a parameter in the first method called
by the XMLDocumentHandler
,
XMLDocumentFragmentHandler
, and
XMLDTDHandler
interfaces.
Note: Parser components that emit document information are not required to provide a locator object. However, the Xerces2 reference implementation does provide a locator to registered handlers.
Methods |
---|
public String getPublicId(); |
public String getSystemId(); |
public String getBaseSystemId(); |
public int getLineNumber(); |
public int getColumnNumber(); |
The QName object is a structure of qualified name information.
Note: The fields of this object have public visibility but should be considered to be read-only to all methods that are passed this object. The caller that creates and passes the QName object "owns" the data. Therefore, callees should not retain a reference to the passed object and are required to copy the references contained in the object if the data is to be used beyond the scope of the method call.
Fields |
---|
public String prefix; |
public String localpart; |
public String rawname; |
public String uri; |
Constructors |
public QName(); |
public QName(String prefix, String localpart,
String rawname, String uri);
|
public QName(QName qname);
|
Convenience Methods |
public void setValues(String prefix, String localpart,
String rawname, String uri);
|
public void setValues(QName qname);
|
public void clear(); |
This interface represents the collection of attributes that is
passed to the startElement
and emptyElement
methods of the XMLDocumentHandler
and
XMLDocumentFragmentHandler
interfaces. This
collection of attributes contains all of the information about
the attributes of an element (except order) and is editable.
This interface is also capable of storing information about entities appearing in the attribute value. However, it should be noted that if entity information is set for an attribute, then the non-normalized value of the attribute must also be stored because the offsets and lengths of entities in the attribute have no meaning for the normalized value.
Methods |
---|
public void addAttribute(
QName attrName,
String attrType,
String attrValue
);
|
public void removeAllAttributes(); |
public void removeAttributeAt(int attrIndex); |
public void addAttributeEntity(
int attrIndex,
String entityName,
int entityOffset,
int entityLength
);
|
public void removeAllEntitiesFor(int attrIndex);
|
public void removeEntityAt(int attrIndex, int entityIndex);
|
public int getLength(); |
public int getIndex(String qName); |
public int getIndex(String uri, String localName);
|
public void setName(
int attrIndex,
QName attrName
);
|
public void getName(
int attrIndex,
QName attrName
);
|
public String getURI(int attrIndex); |
public String getLocalName(int attrIndex); |
public String getQName(int attrIndex); |
public void setType(int attrIndex, String attrType);
|
public String getType(int attrIndex); |
public String getType(String qName); |
public String getType(String uri, String localName);
|
public void setValue(int attrIndex, String attrValue);
|
public String getValue(int attrIndex); |
public String getValue(String qName); |
public String getValue(String uri, String localName);
|
public void setNonNormalizedValue(int attrIndex, String attrValue);
|
public String getNonNormalizedValue(int attrIndex);
|
public void setSpecified(int attrIndex, boolean specified);
|
public boolean isSpecified(int attrIndex); |
public int getEntityCount(int attrIndex); |
public void setEntityName(
int attrIndex,
int entityIndex,
String entityName
);
|
public String getEntityName(
int attrIndex,
int entityIndex
);
|
public void setEntityOffset(
int attrIndex,
int entityIndex,
int entityOffset
);
|
public int getEntityOffset(
int attrIndex,
int entityIndex
);
|
public void setEntityLength(
int attrIndex,
int entityIndex,
int entityLength
);
|
public int getEntityLength(
int attrIndex,
int entityIndex
);
|
The XMLString object is a structure for holding text information. This object allows the underlying implementation to pass text information by using its own internal character buffer without creating new String objects or copying the data.
Note: The fields of this object have public visibility but should be considered to be read-only to all methods that are passed this object. The caller that creates and passes the XMLString object "owns" the data. Therefore, callees should not retain a reference to the passed object and are required to copy the information contained in the object if the data is to be used beyond the scope of the method call. Also, callees should never modify the contents of the character array directly as that could adversely affect the operation of the caller.
Fields |
---|
public char[] ch; |
public int offset; |
public int length; |
Constructors |
public XMLString(); |
public XMLString(char[] ch, int offset, int length);
|
public XMLString(XMLString string);
|
Convenience Methods |
public void setValues(char[] ch, int offset, int length);
|
public void setValues(XMLString string);
|
public void clear(); |
Namespace context information for document fragments. This
object is passed to the first method of the
XMLDocumentFragmentHandler
interface.
Constants |
---|
public static final String XMLNS; |
public String getURI(String prefix); |
public int getDeclaredPrefixCount(); |
public String getDeclaredPrefixAt(int index); |
public NamespaceContext
getParentContext();
|
The DTD information is communicated through two interfaces:
XMLDTDHandler
and XMLDTDContentModelHandler
.
The first handler interface passes the basic DTD information
whereas the second handler interface breaks down each element
declaration content model into separate callbacks.
Communicates basic DTD information such as element and attribute declarations. The implementor of this interface can also be informed of characters within an ignored conditional section.
Constants |
---|
public static final short CONDITIONAL_INCLUDE; |
public static final short CONDITIONAL_IGNORE; |
Methods |
public void startDTD(
XMLLocator locator
) throws XNIException;
|
public void startEntity(
String name,
String publicId,
String systemId,
String baseSystemId,
String encoding
) throws XNIException;
|
public void textDecl(
String version,
String encoding
) throws XNIException;
|
public void endEntity(
String name
) throws XNIException;
|
public void comment(
XMLString text
) throws XNIException;
|
public void processingInstruction(
String target,
XMLString data
) throws XNIException;
|
public void elementDecl(
String name,
String contentModel
) throws XNIException;
|
public void startAttlist(
String elementName
) throws XNIException;
|
public void attributeDecl(
String elementName,
String attributeName,
String type,
String[] enumeration,
String defaultType,
XMLString defaultValue
) throws XNIException;
|
public void endAttlist() throws XNIException;
|
public void internalEntityDecl(
String name,
XMLString text
) throws XNIException;
|
public void externalEntityDecl(
String name,
String publicId,
String systemId,
String baseSystemId
) throws XNIException;
|
public void unparsedEntityDecl(
String name,
String publicId,
String systemId,
String notation
) throws XNIException;
|
public void notationDecl(
String name,
String publicId,
String systemId
) throws XNIException;
|
public void startConditional(
short type
) throws XNIException;
|
public void characters(
XMLString text
) throws XNIException;
|
public void endConditional() throws XNIException;
|
public void endDTD() throws XNIException;
|
Breaks down each element declaration's content model into
a set of separate methods so that handlers don't have to
reparse the content model string given in the
XMLDTDHandler#elementDecl(String,String)
method.
This separation also helps those applications that want to
know boundaries of entities when used as part of an element's
content model.
Constants |
---|
public static final short SEPARATOR_CHOICE;
|
public static final short SEPARATOR_SEQUENCE;
|
public static final short OCCURS_ZERO_OR_ONE;
|
public static final short OCCURS_ZERO_OR_MORE;
|
public static final short OCCURS_ONE_OR_MORE;
|
Methods |
public void startContentModel()
throws XNIException;
|
public void any()
throws XNIException;
|
public void empty()
throws XNIException;
|
public void startGroup()
throws XNIException;
|
public void pcdata()
throws XNIException;
|
public void element(String elementName)
throws XNIException;
|
public void separator(short type)
throws XNIException;
|
public void occurrence(short type)
throws XNIException;
|
public void endGroup()
throws XNIException;
|
public void endContentModel()
throws XNIException;
|
The following examples demonstrate the basic use of the various XNI handler interfaces.
The following example demonstrates a basic pass-through document handler filter. This filter receives document handler events and passes them through to the next document handler.
The following code extends the pass-through document handler filter to upper-case all of the element names.