What is this page?
This page documents why these JAXP 1.3 jars are included with the distribution and what you should do with them.
What are these jars?
These are the JAXP 1.3 jars. They implement an endorsed extension to the JDK 1.4.x environment. They provide a way to bridge from the JDK 1.4 world to the JDK 1.5 world. These jars include support for standardized XML parsing, transformations, and DOM Level 3 Documents.
Under what licenses are these .jars distributed?
See /docs/licenses/acknowledgements.txt. See also the Java.net site where these .jars are distributed.
The short version:
If compiling and deploying under JDK 1.4.x, drop these .jar files into your /lib/endorsed/ directory of your JDK's JRE and into the /commmon/endorsed/ directory of your Tomcat. The 'JAXP-Install' target in the uPortal build.xml will do this for you.
You also need to copy /lib/xalan-2-6-0.jar to the /lib/endorsed/ directory of your JDK's JRE and into the /common/endorsed/ directory of your Tomcat. xalan-2-6-0.jar overrides the org.apache.xml APIs that were included in JDK 1.4.
The long version:
uPortal 2.5+ and 2.4.4+ releases include support for being compiled and running under JDK 1.4 or 1.5. For those not familiar, JDK 1.4 includes support for JAXP 1.2 and JDK 1.5 supports JAXP 1.3.
JAXP is an API that allows an application to process an XML document independent of the underlying XML processing engine (see FAQ). The support for DOM Level 3 was a main driver for introducing the JAXP 1.3 release. Unfortunately, the JAXP 1.3 API is not backward compatible with JAXP 1.2.
This means that an application programmed to use the JAXP 1.3 API will compile/run with no problems under JDK 1.5, but fails under an out-of-the-box JDK 1.4 install. To remedy this problem (JAXP 1.3 with JDK 1.4), Sun makes available the JAXP 1.3 libraries, which must be referenced by the JDK 1.4 Java Compiler or Application before the JAXP 1.2 libraries that ship with the JDK.
For compilation in uPortal, this is done by installing the JAXP 1.3 libraries (/portal/lib/jaxp/*.jar) into the $JDK_HOME/jre/lib/endorsed directory. For running Tomcat, this is done by copying these libraries into the $TOMCAT_HOME/common/endorsed directory as specified in the Java endorsed standards override mechanism. Both of these actions are performed by the ant JAXP-Install target. Technically, the JAXP 1.3 JAR files are being added to the Java bootclasspath, which tells Java to look there for a class before looking in the runtime JAR ($JAVA_HOME/jre/lib/rt.jar).
Note that all generated .class file compatibility is 1.4.
The following table should prevent common JAXP configuration errors:
|
JDK 1.4 |
JDK 1.5 |
|---|---|---|
Compile |
|
|
Run under Tomcat 5.0.x |
|
|
Run under Tomcat 5.5.x |
|
|
Common problems
An incorrectly configured JDK/JRE or Tomcat for JAXP version is common. Some common exceptions are listed below. This can usually be resolved by following the build/tomcat config steps listed in the above table.
ERROR [main] checks.Dom3Check.[] Jul/21 16:19:06 - DOM3 check failing
because DOM3 method not found:
java.lang.NoSuchMethodError: org.w3c.dom.Document.normalizeDocument()V
at org.jasig.portal.tools.checks.Dom3Check.doCheck(Dom3Check.java:40)
java.lang.reflect.InvocationTargetException
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
...
Caused by: javax.xml.parsers.FactoryConfigurationError: Provider org.apache.xerces.jaxp.SAXParserFactoryImpl not found
at javax.xml.parsers.SAXParserFactory.newInstance(Unknown Source)
If using JDK 1.5:
You don't need this folder at all if you're running JDK 1.5 as both your development environment and your Tomcat environment.
You will still need to make /lib/xalan-2-6-0.jar available to provide the org.apache.xml APIs.
Where can I read more?
What JDK should I be using?
While the uPortal 2.5 release is committed to continuing to support JDK 1.4, you might still want to go ahead and use JDK 1.5 if at all possible.