XML in a Nutshell, Third Edition

SAX uses properties and features to control parser behavior. Each feature and property has a name that's an absolute URI. Like namespace URIs, absolute URIs are only used to name things and do not necessarily point to a real page you can load into a web browser. Features are either true or false; that is, they're Booleans. Properties have values of an appropriate Object type. Different parsers support different groups of features and properties, although there are a few standard ones most parsers support.

The http://xml.org/sax/features/validation feature controls whether a parser validates . If this feature is true, then the parser will report validity errors in the document to the registered ErrorHandler ; otherwise , it won't. This feature is turned off by default. To turn a feature on, pass the feature's name and value to the XMLReader 's setFeature( ) method:

try { parser.setFeature("http://xml.org/sax/features/validation", true); } catch (SAXNotSupportedException ex) { System.out.println("Cannot turn on validation right now."); } catch (SAXNotRecognizedException ex) { System.out.println("This is not a validating parser."); }

Not all parsers can validate. If you try to turn on validation in a parser that doesn't validate or set any other feature the parser doesn't provide, setFeature( ) throws a SAXNotRecognizedException . If you try to set a feature the parser does recognize but cannot change at the current timee.g., you try to turn on validation when the parser has already read half of the document setFeature( ) throws a SAXNotSupportedException . Both are subclasses of SAXException .

You can check a feature's current value using XMLReader 's getFeature( ) method. This method returns a boolean and throws the same exceptions for the same reasons as setFeature( ) . If you want to know whether the parser validates, you can ask in the following manner:

try { boolean isValidating = parser.getFeature("http://xml.org/sax/features/validation"); } catch (SAXException ex) { System.out.println("This is not a validating parser"); }

Properties are similar to features, but they allow a broader choice than a simple Boolean on/off, true/false dichotomy . Each property value is an object of unspecified type. For example, to determine the version of XML (1.0 or 1.1) used by the document, read the http://xml.org/sax/properties/document-xml-version property with the getProperty( ) method:

try { String version = (String) parser.getProperty( "http://xml.org/sax/properties/document-xml-version"); if ("1.0".equals(version) { System.out.println("A good conservative document"); } else if ("1.1".equals(version) { System.out.println("A dangerously radical document"); } else { System.out.println("A very strange document: " + version); } } catch (SAXNotSupportedException ex) { System.out.println( "Cannot provide the version of XML used by the document right now."); } catch (SAXNotRecognizedException ex) { System.out.println("Parser does not recognize the " + "http://xml.org/sax/properties/document-xml-version property"); }

You can change a property value by invoking the setProperty( ) method with two arguments. The first is the URI of the property to set. The second is the object specifying the value for the property. For example, this code fragment attempts to set the http://xml.org/sax/properties/LexicalHandler property to a new instance of the MyLexicalHandlerClass . The parser reports lexical events (comments, CDATA sections, and entity references) to the org.xml.sax.ext.LexicalHandler implementation object named by this property:

try { parser.setProperty( "http://xml.org/sax/properties/LexicalHandler", new MyLexicalHandlerClass( ) ); } catch (SAXException ex) { System.out.println("This parser does not provide lexical events."); }

If you pass in the wrong kind of object for a property (e.g., an object that does not implement the LexicalHandler interface for the http://xml.org/sax/properties/LexicalHandler property), then setProperty( ) throws a SAXNotSupportedException .

Not all features and properties can be set. Some features such as http://xml.org/sax/properties/document-xml-version are read-only. Others can be set at some times but not others. For example, you cannot turn on validation when the parser is already halfway through a document. An attempt to do so will fail and throw a SAXNotSupportedException . However, you can change a parser's features after parsing one document, but before parsing the next . You can read most feature and property values at any time, although a few (such as http://xml.org/sax/properties/document-xml-version ) can only be read when the parser is reading a document.