User: starksm
Date: 01/03/25 09:30:36
Modified: src/docs jbossdocs.xml
Added: src/docs howtojaxp.xml
Log:
Added JAXP configuration howto.
Revision Changes Path
1.7 +2 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- jbossdocs.xml 2001/03/21 08:30:20 1.6
+++ jbossdocs.xml 2001/03/25 17:30:36 1.7
@@ -21,6 +21,7 @@
<!ENTITY basicconfiguration.xml SYSTEM "basicconfiguration.xml">
<!ENTITY howtomdb.xml SYSTEM "howtomdb.xml">
<!ENTITY howto_socketfactories.xml SYSTEM "howto_socketfactories.xml">
+ <!ENTITY howtojaxp.xml SYSTEM "howtojaxp.xml">
<!ENTITY jbosssx.xml SYSTEM "jbosssx.xml">
]>
<book>
@@ -55,6 +56,7 @@
&howtojca.xml;
&howtojndi_external.xml;
&howto_socketfactories.xml;
+&howtojaxp.xml;
</chapter>
</book>
1.1 manual/src/docs/howtojaxp.xml
Index: howtojaxp.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<section>
<title>Configuring and Using JAXP 1.1 In JBoss</title>
<para>
<author>
<firstname>Scott</firstname>
<surname>Stark</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>Introduction</title>
<para>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.
</para>
</section>
<section>
<title>Configuring XML Parsers and Transformers</title>
<para>This section covers how one configures which xml parser and transformers the
JBoss uses. It is based largely on the current <ulink url =
"http://java.sun.com/xml/download.html">Java API for XML Processing (JAXP) 1.1</ulink>
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.</para>
<section id = "howto.jaxp.sax">
<title>SAX Parser Configuration</title>
<para>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:</para>
<orderedlist>
<listitem>
<para>Use the javax.xml.parsers.SAXParserFactory system property</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Platform default SAXParserFactory instance.</para>
</listitem>
</orderedlist>
</section>
<section id = "howto.jaxp.dom">
<title>DOM Parser Configuration</title>
<para>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:</para>
<orderedlist>
<listitem>
<para>Use the javax.xml.parsers.DocumentBuilderFactory system property</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Platform default SAXParserFactory instance.</para>
</listitem>
</orderedlist>
</section>
<section id = "howto.jaxp.xslt">
<title>XSLT Transformer Configuration</title>
<para>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:</para>
<orderedlist>
<listitem>
<para>Use the javax.xml.transform.TransformerFactory system property</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Platform default TransformFactory instance.</para>
</listitem>
</orderedlist>
</section>
<section id = "howto.jaxp.jboss.config">
<title>Changing the JBoss Defaults</title>
<para>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. <xref linkend = "howto.jaxp.run.sh.crimson"/> shows the setup.</para>
<figure id = "howto.jaxp.run.sh.crimson">
<title>The run.sh setup for the Crimson xml parsers</title>
<programlisting># 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"</programlisting>
</figure>
<para>To change JBoss to use the Xerces parser, you would need change the setup
to that shown in <xref linkend = "howto.jaxp.run.sh.xerces"/> assuming you copied the
xerces.jar into the JBoss lib directory.</para>
<figure id = "howto.jaxp.run.sh.xerces">
<title>The run.sh setup for the Xerces xml parsers</title>
<programlisting># 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"</programlisting>
</figure>
<para>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 <xref
linkend = "howto.jaxp.xslt"/>.</para>
</section>
</section>
<section>
<title>Using JAXP</title>
<para>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.</para>
<figure id = "jaxp.howto.sax.example">
<title>Example SAX Parser Creation</title>
<programlisting>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)
{
...
}</programlisting>
</figure>
<figure id = "jaxp.howto.dom.example">
<title>Example DOM Parser Creation</title>
<programlisting>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)
{
...
}</programlisting>
</figure>
<figure id = "jaxp.howto.xslt.example">
<title>Example XSLT Transformer Creation</title>
<programlisting>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)
{
...
}</programlisting>
</figure>
</section>
<section>
<title>Common Questions</title>
<qandaset>
<qandaentry>
<question>
<para>Do I have to use JAXP for xml parsing?</para>
</question>
<answer>
<para>Not necessarily. If you have a specific parser you want to use and you
want to uses a parser specific factory you can as long as the parser supports JAXP as
this is how JBoss is locating its xml parsers.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Can I mix different xml parsers?</para>
</question>
<answer>
<para>If they are all support the same level of the xml standards and JAXP then
you should be able to. However, if there are differences then you are likely to see a
SecurityException("sealing violation") error thrown.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What if I have to use an older parser that does not support JAXP?</para>
</question>
<answer>
<para>The you will need to use your own ClassLoader instance to isolate any
common xml parser packages to avoid the sealing violation exception.</para>
</answer>
</qandaentry>
</qandaset>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
