SAX Features and Properties (XML in a Nutshell, 2nd Edition)

19.2. SAX Features and Properties

SAX uses properties and features to control parser behavior. Each feature and property has a name that's an absolute URI. Like namespace URIs, these 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.

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 e) {
  System.out.println("Cannot turn on validation right now.");
}
catch (SAXNotRecognizedException e) {
  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 time--e.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 e) {
  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, if you want to know the literal string of data parsed to produce the current SAX event, you can ask by reading the http://xml.org/sax/properties/xml-string property with the getProperty( ) method:

try {
  String tag = (String) parser.getProperty(
   "http://xml.org/sax/properties/xml-string");
}
catch (SAXNotSupportedException e) {
  System.out.println("This parser does not provide the original data");
}
catch (SAXNotRecognizedException e) {
  System.out.println("Parser does not recognize the " +
   "http://xml.org/sax/properties/xml-string 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 e) {
  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 at all times. For example, you cannot suddenly decide to start validating 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 in between documents -- after parsing one document, but before parsing the next. You can read most feature and property values at any time.


19. Simple API for XML		19.3. Filters