26.4 The org.xml.sax.ext Package | XML in a Nutshell, Third Edition

The org.xml.sax.ext package provides optional interfaces that parsers may use to provide further functionality. Not all parsers support these interfaces, although most major ones do.

The Attributes2 Interface

SAX 2.0.2 adds an Attributes2 subclass of Attributes that provides extra methods to determine whether a given attribute was declared in the DTD and/or specified in the instance document (as opposed to being defaulted in from the DTD). A parser that supports Attributes2 will pass an Attributes2 object to startElement( ) instead of a plain Attributes object. Using the extra methods requires a cast. Before casting, you may wish to check whether the cast will succeed by getting the value of the http://xml.org/sax/features/use-attributes2 feature. If this feature is true, the parser passes Attributes2 objects.

 package org.xml.sax.ext;       public interface  Attributes2  {         public boolean  isDeclared  (int  index  );   public boolean  isDeclared  (String  qualifiedName  );   public boolean  isSpecified  (String  namespaceURI  , String  localName  );   public boolean  isSpecified  (int  index  );   public boolean  isSpecified  (String  qualifiedName  );   public boolean  isSpecified  (String  namespaceURI  , String  localName  );       }

The DeclHandler Interface

DeclHandler is a callback interface that provides information about the ELEMENT , ATTLIST , and parsed ENTITY declarations in the document's DTD. To configure an XMLReader with a DeclHandler , pass the name http://xml.org/sax/properties/DeclHandler and an instance of the handler to the reader's setProperty( ) method:

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

If the parser does not provide declaration events, it throws a SAXNotRecognizedException . If the parser cannot install a DeclHandler at this moment ( generally because it's in the middle of parsing a document), then it throws a SAXNotSupportedException . If it doesn't throw one of these exceptions, it will call back to the methods in your DeclHandler as it parses the DTD:

 package org.xml.sax.ext;       public interface  DeclHandler  {         public void  elementDecl  (String  name  , String  model  ) throws SAXException;   public void  attributeDecl  (String  elementName  , String  attributeName  ,    String  type  , String  defaultValue  , String  value  ) throws SAXException;   public void  internalEntityDecl  (String  name  , String  value  )    throws SAXException;   public void  externalEntityDecl  (String  name  , String  publicID  ,    String  systemID  ) throws SAXException;       }

The EntityResolver2 Interface

SAX 2.0.2 adds an EntityResolver2 subclass of EntityResolver that provides extra methods for more flexible entity resolution. In particular, it lets a program provide an external DTD subset for a document that does not have a document type declaration. It also lets entities be resolved based on the root element name and base URL, as well as the public ID and system ID. Your code can always pass an EntityResolver2 object to setEntityResolver( ) . A parser that does not supports EntityResolver2 will simply ignore the extra methods. The http://xml.org/sax/features/use-entity-resolver2 feature tells you whether the parser will use the extra methods in EntityResolver2 .

 package org.xml.sax.ext;       public interface  EntityResolver2  {         public InputSource  getExternalSubset  (String  name  , String  baseURI  );   public InputSource  resolveEntity  (     String  name  , String  publicID  , String  baseURI  , String  systemID  );       }

The LexicalHandler Interface

LexicalHandler is a callback interface that provides information about aspects of the document that are not normally relevant, specifically :

CDATA sections
Entity boundaries
DTD boundaries
Comments

Without a LexicalHandler , the parser simply ignores comments and expands entity references and CDATA sections. By using the LexicalHandler interface, however, you can read the comments and learn which text came from regular character data, which came from a CDATA section, and which came from which entity reference.

To configure an XMLReader with a LexicalHandler , pass an instance of your handler class to the reader's setProperty( ) method with the name http://xml.org/sax/properties/LexicalHandler :

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

If the parser does not provide lexical events, it throws a SAXNotRecognizedException . If the parser cannot install a LexicalHandler at this moment (generally because it's in the middle of parsing a document), then it throws a SAXNotSupportedException . If it doesn't throw one of these exceptions, it calls back to the methods in the LexicalHandler as it encounters entity references, comments, and CDATA sections. The basic content of the resolved entities and CDATA sections are still reported through the ContentHandler interface, as normal:

 package org.xml.sax.ext;       public interface  LexicalHandler  {         public void  startDTD  (String  name  , String  publicID  , String  systemID  )    throws SAXException;   public void  endDTD  (  ) throws SAXException;   public void  startEntity  (String  name  ) throws SAXException;   public void  endEntity  (String  name  ) throws SAXException;   public void  startCDATA  (  ) throws SAXException;   public void  endCDATA  (  ) throws SAXException;   public void  comment  (char[  ]  text  , int  start  , int  length  )    throws SAXException;       }

The Locator2 Interface

SAX 2.0.2 adds a Locator2 subclass of Locator that provides extra methods to determine the character encoding and XML version used by the current entity. A parser that supports Locator2 will simply pass a Locator2 object to setLocator( ) instead of a plain Locator object. Using the extra methods requires a cast. Before casting, you may wish to check whether the cast will succeed by getting the value of the http://xml.org/sax/features/use-locator2 feature. If this feature is true, the parser passes Locator2 objects.

 package org.xml.sax.ext;       public interface  EntityResolver2  {         public String  getXMLVersion  (  );   public String  getEncoding  (  );       }

The getXMLVersion( ) method returns the version of the current entity . The http://xml.org/sax/properties/document-xml-version property returns the version of the current document . These may be but do not have to be the same.