JBoss uses the JAXP 1.1 optional package to JAXP to parse and transform XML documents using a pure Java API that is independent of a particular XML processor implementation. This allows the flexibility to swap between XML processors without making application code changes. Version 1.1 includes an XSLT framework based on TrAX (Transformation API for XML) plus some updates to the parsing API to support DOM Level 2 and SAX version 2.0 and an improved scheme to locate pluggable implementations.
This section covers how one configures which xml parser and transformers the JBoss uses. It is based largely on the current Java API for XML Processing (JAXP) 1.1 specification. The types of configurable objects include DOM parsers, SAX parsers and XSLT transformers. First we'll describe the configuration options for the various objects per the JAXP spec and then show how JBoss uses the configuration properties and how you can change them.
The SAX Plugability classes allow an application programmer to provide an implementation of the org.xml.sax.DefaultHandler API to a SAXParser implementation and parse XML documents. In order to obtain a SAXParser instance, an application programmer first obtains an instance of a SAXParserFactory. The SAXParserFactory instance is obtained via the static newInstance method of the SAXParserFactory class. This method uses the following ordered lookup procedure to determine the SAXParserFactory implementation class to load:
Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for the classname in the file META-INF/services/javax.xml.parsers.SAXParserFactory in jars available to the runtime.
The DOM plugability classes allow a programmer to parse an XML document and obtain an org.w3c.dom.Document object from a DocumentBuilder implementation which wraps an underlying DOM implementation. In order to obtain a DocumentBuilder instance, an application programmer first obtains an instance of a Document-BuilderFactory. The DocumentBuilderFactory instance is obtained via the static newInstance method of the DocumentBuilderFactory class. This method uses the following ordered lookup procedure to determine the DocumentBuilderFactory implementation class to load:
Use the javax.xml.parsers.DocumentBuilderFactory system property
Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for the classname in the file META-INF/services/javax.xml.parsers.DocumentBuilderFactory in jars available to the runtime.
The XSLT Plugability classes allow an application programmer to obtain a Transformer object that is based on a specific XSLT stylesheet from a TransformerFactory implementation. In order to obtain a Transformer object, a programmer first obtains an instance of the TransformerFactory. The TransformerFactory instance is obtained via the static newInstance method of the TransformerFactory class. This method uses the following ordered lookup procedure to determine the TransformerFactory implementation class to load:
Use the javax.xml.transform.TransformerFactory system property
Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for the classname in the file META-INF/services/javax.xml.transform.TransformerFactory in jars available to the runtime.
JBoss uses a DOM DocumentBuilder to parse the jboss.jcml configuration file. The run.bat and run.sh startup scripts sets the javax.xml.parsers.DocumentBuilderFactory and javax.xml.parsers.SAXParserFactory system properties to the bundled Crimson 1.1 DOM and SAX parsers contained in lib/crimson.jar. Figure 13.30 shows the setup.
Figure 13.30. The run.sh setup for the Crimson xml parsers
# Add the XML parser jars and set the JAXP factory names # Crimson parser JAXP setup(default) CLASSPATH=$CLASSPATH:../lib/crimson.jar JAXP=-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.crimson.jaxp.DocumentBuilderFactoryImpl JAXP="$JAXP -Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp.SAXParserFactoryImpl"
To change JBoss to use the Xerces parser, you would need change the setup to that shown in Figure 13.31 assuming you copied the xerces.jar into the JBoss lib directory.
Figure 13.31. The run.sh setup for the Xerces xml parsers
# Add the XML parser jars and set the JAXP factory names # Xerces parser JAXP setup CLASSPATH=$CLASSPATH:../lib/xerces.jar JAXP=-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl JAXP="$JAXP -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"
JBoss does not currently use any XSLT transformers and so does not set a default value for the javax.xml.transform.TransformerFactory system property. To setup the desired transformer you are free to use any of the approaches described in the section called “XSLT Transformer Configuration”.
To aide in porting your xml parser creation to use the JAXP package, this section gives some small code fragments showing the use of each type of factory. See the JAXP spec or JavaDoc for the full usage details.
Figure 13.32. Example SAX Parser Creation
import javax.xml.parsers.FactoryConfigurationError; import javax.xml.parsers.ParserConfigurationException; import javax.xml.parsers.SAXParser; import javax.xml.parsers.SAXParserFactory import org.xml.sax.SAXException; import org.xml.sax.helpers.DefaultHandler; SAXParser parser = null; DefaultHandler handler = new DefaultHandler() { ... } try { SAXParserFactory factory = SAXParserFactory.newInstance(); parser = factory.newSAXParser(); String docURI = ...; parser.parse(docURI); } catch(SAXException e) { ... } catch(java.io.IOException e) { ... } catch(ParserConfigurationException e) { ... } catch(FactoryConfigurationError e) { ... }
Figure 13.33. Example DOM Parser Creation
import javax.xml.parsers.FactoryConfigurationError; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.parsers.FactoryConfigurationError; import javax.xml.parsers.ParserConfigurationException; import org.xml.sax.SAXException; DocumentBuilder parser = null; try { DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); String docURI = ...; parser.parse(docURI); } catch(SAXException e) { ... } catch(java.io.IOException e) { ... } catch(ParserConfigurationException e) { ... } catch(FactoryConfigurationError e) { ... }
Figure 13.34. Example XSLT Transformer Creation
import javax.xml.transform.Transformer; import javax.xml.transform.TransformerConfigurationException; import javax.xml.transform.TransformerException; import javax.xml.transform.TransformerFactory; import javax.xml.transform.TransformerFactoryConfigurationError; import javax.xml.transform.stream.StreamResult; import javax.xml.transform.stream.StreamSource; Transformer transformer = null; try { TransformerFactory factory = TransformerFactory.newInstance(); String stylesheet = "file:///ssheet.xsl"; String xmldoc = "file:///application.xml"; StreamSource style = new StreamSource(stylesheet); StreamSource src = new StreamSource(xmldoc); StreamResult result = new StreamResult(System.out); transformer = factory.newTransformer(style); transformer.transform(src, dest); } catch(TransformerFactoryConfigurationError e) { ... } catch(TransformerConfigurationException e) { ... } catch(TransformerException e) { ... }