26.3 SAX Features and Properties


Absolute URIs are used to name a SAX parser's properties and features. Features have a Boolean value; that is, for each parser, a recognized feature is either true or false. Properties have object values. SAX 2.0 defines six core features and two core properties that parsers should recognize. SAX 2.0.2 adds nine more. In addition, most parsers add features and properties to this list.

SAX Core Features

All SAX parsers should recognize six core features. Of these six, two ( http://xml.org/sax/features/namespaces and http://xml.org/sax/features/namespace-prefixes ) must be implemented by all conformant processors. The other four are optional and may not be implemented by all parsers:


When true, this feature indicates that the startElement( ) and endElement( ) methods provide namespace URIs and local names for elements and attributes. When false, the parser provides prefixed element and attribute names to the startElement( ) and endElement( ) methods. If a parser does not provide something it is not required to provide, then that value will be set to the empty string. However, most parsers provide all three (URI, local name, and prefixed name), regardless of the value of this feature. This feature is true by default.


When true, this feature indicates that xmlns and xmlns : prefix attributes will be included in the attributes list passed to startElement( ) . When false, these attributes are omitted. Furthermore, if this feature is true, then the parser will provide the prefixed names for elements and attributes. The default is false unless http://xml.org/sax/features/namespaces is false, in which case this feature defaults to true. You can set both http://xml.org/sax/features/namespaces and http://xml.org/sax/features/namespace-prefixes to true to guarantee that local names, namespace URIs, and prefixed names are all available.


When this feature is true, all element names, prefixes, attribute names, namespace URIs, and local names are internalized using the intern( ) method of java.lang.String ; that is, equal names compare equally when using = = .


When true, the parser validates the documents against its DTD. When false, it doesn't. The default is false for most parsers. If you turn on this feature, you'll probably also want to register an ErrorHandler with the XMLReader to receive notice of any validity errors.


When true, the parser resolves external parsed general entities. When false, it doesn't. The default is true for most parsers that can resolve external entities. Turning on validation automatically activates this feature because validation requires resolving external entities.


When true, the parser resolves external parameter entities. When false, it doesn't. Turning on validation automatically activates this feature because validation requires resolving external entities.

SAX 2.0.2 adds eight more standard features, although as with the SAX 2.0 features, parsers are not required to support any of these:


When true, the parser reports parameter entity boundaries to the LexicalHandler using the startEntity( ) and endEntity( ) methods. The default behavior is implementation-dependent.


Indicates whether the document's XML declaration specified standalone="yes ". This feature is read-only and can be inspected only after startDocument( ) has returned and before the parser has finished reading the document.


When true, relative URIs found in notation declarations, unparsed entity declarations, and external entity declarations will be converted to absolute URIs before being reported to the methods of DTDHandler and DeclHandler . When false, relative URIs are not absolutized. The default is true. Relative URIs are never absolutized before being passed to the methods of LexicalHandler or EntityResolver .


When true, the parser checks that text content is in Unicode Normalization Form C, as recommended by the XML 1.1 specification. Any normalization problems found are reported to the registered ErrorHandler using the nonfatal error( ) method. The default is false, do not check for normalization.


When true, the Attributes object passed to startElement( ) can be cast to Attributes2 , a subclass of Attributes with extra methods to determine whether an attribute was declared in the DTD, specified in the instance document, or both.


When true, the parser will use the extra methods defined in EntityResolver2 if you pass an EntityResolver2 object to setEntityResolver( ) .


When true, the Locator object passed to setLocator( ) can be cast to Locator2 , with extra methods to determine the character encoding and XML version of the entity or document.


When true, this feature indicates that the parser adheres to a backward incompatible revision of the namespaces specification that binds the xmlns prefix to the namespace URI http://www.w3.org/2000/xmlns/ . The default is false, do not bind the xmlns prefix to any namespace URI.

SAX Core Properties

SAX defines four core properties, although implementations are not required to support them:


This property's value is an org.xml.sax.ext.DeclHandler object to which the parser will report ELEMENT , ATTLIST , and parsed ENTITY declarations found in the document's DTD.


This property's value is an org.xml.sax.ext.LexicalHandler object to which the parser reports comments, CDATA section boundaries, and entity boundaries.


This property's value is an org.w3c.dom.Node object that represents the current node the parser is visiting.


This property's value is a java.lang.String object containing the characters that were the source for the current event. As of mid-2004, no parsers are known to implement this property.

SAX 2.0.2 adds one more standard property:


This property's value is a java.lang.String containing the version of the XML document. It would normally be either 1.0 or 1.1. This is a read-only property.

XML in a Nutshell
XML in a Nutshell, Third Edition
ISBN: 0596007647
EAN: 2147483647
Year: 2003
Pages: 232

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net