Practical uP25 XML Changes

As of uPortal 2.5, uPortal requires the modern JAXP 1.3 XML libraries. Not coincidentally, these APIs are built right into JRE 1.5. uPortal 2.5 does not, however, require JRE 1.5, and is committed to also running under JRE 1.4.

This page aspires to explain exactly what you'll neeed to do to make uPortal 2.5 run under JRE 1.4.x.

Stepwise instructions

Acquire the JAXP 1.3 jars

The JAXP 1.3 jars are now distributed with uPortal itself in the /lib/jaxp/ directory.

Install those JAXP 1.3 jars in the /lib/endorsed/ directory of your JDK JRE

You'll need these .jars to be installed into the /jre/lib/endorsed/ directory of the JDK under which you will be running your ANT builds or otherwise compiling the uPortal source to build your local uPortal for deployment.

Into /jre/lib/endorsed/ go:

• dom.jar
• jaxp-api.jar
• sax.jar
• xalan.jar
• xercesImpl.jar

Install those JAXP 1.3 jars in the /common/endorsed/ directory of your Tomcat.

Into your Tomcat's /common/endorsed/ directory go:

• dom.jar
• jaxp-api.jar
• sax.jar
• xalan.jar
• xercesImpl.jar

If you're using Eclipse

You'll need to configure your IDE such that you can compile the project using these JAXP jars.

Configuring the classpath

Here's the .classpath file I'm using locally. Notice that it does not declare the following .jars that are distributed in the /lib/ directory of uPortal:

• xalan-2-6-0.jar
• xercesImpl.jar
• xml-apis.jar

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
	<classpathentry kind="src" path="source"/>
	<classpathentry kind="src" path="tests"/>
	<classpathentry kind="lib" path="lib/activation.jar"/>
	<classpathentry kind="lib" path="lib/commons-logging.jar"/>
	<classpathentry kind="lib" path="lib/cos.jar"/>
	<classpathentry kind="lib" path="lib/hsqldb.jar"/>
	<classpathentry kind="lib" path="lib/jakarta-oro-2.0.8.jar"/>
	<classpathentry kind="lib" path="lib/junit.jar"/>
	<classpathentry kind="lib" path="lib/log4j-1.2.8.jar"/>
	<classpathentry kind="lib" path="lib/portlet-api-1.0.jar"/>
	<classpathentry kind="lib" path="lib/proxyportlet.jar"/>
	<classpathentry kind="lib" path="lib/servlet.jar"/>
	<classpathentry kind="lib" path="lib/tyrex-1.0.1.jar"/>
	<classpathentry kind="lib" path="lib/wsrp4j-consumer-0.3.jar"/>
	<classpathentry kind="lib" path="lib/wsrp4j-shared-0.3.jar"/>
	<classpathentry kind="lib" path="lib/commons-collections-3.1.jar"/>
	<classpathentry kind="lib" path="lib/commons-dbcp-1.2.1.jar"/>
	<classpathentry kind="lib" path="lib/commons-pool-1.2.jar"/>
	<classpathentry kind="lib" path="lib/spring.jar"/>
	<classpathentry kind="lib" path="lib/pluto-1.0.1-rc1.jar"/>
<!-- I've inserted a linebreak in the following entry to make it look nice in the Wiki -- you need to
  remove the linebreak between internal. and debug.ui... -->
	<classpathentry kind="con"
path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.
debug.ui.launcher.StandardVMType/jaxp13_1_4_2_04"/>
	<classpathentry kind="lib" path="lib/tidy.jar"/>
	<classpathentry kind="output" path="bin"/>
</classpath>

When you right-click on your project's root directory and click "Properties" in the resulting contextual menu, you'll get the "Properties for ProjectName" dialog. Click "Java Build Path" in the left navigation pane and then click the "Libraries" tab. You can remove the entries for "xalan.jar" or "xalan-2-6-0.jar" and "xercesImpl.jar" and "xml-apis.jar" from your build path. On the "Order and Export" tab, ensure that the JRE comes before tidy.jar (as in the order described in the XML above.)

Configuring the JRE under which you build the project

The JRE under which you build the project needs to have the JAXP 1.3 jars installed and it needs to actually be using them.

Let's create a new JRE entry in Eclipse, so that we can continue to use a non-JAXP 1.3 JRE for other projects. We'll give this project its own JRE configuration.

In Window -> Preferences -> Java -> Installed JREs

Create a new JRE. Give it a name evocative of its use of JAXP 1.3, e.g. "jaxp13_1_4_2_04". The JRE home directory should be the directory of the JDK you've installed the JAXP 1.3 jars into, e.g. "C:\Copy of j2sdk1.4.2_04".

Uncheck "Use default system libraries". Click the now-activated "Add External Jars...". Navigate to the endorsed directory of the lib directory of the jre directory of that JDK. E.g,

"C:\Copy of j2sdk1.4.2_04\jre\lib\endorsed\"

Select the five .jars there: dom.jar, jaxp-api.jar, sax.jar, xalan.jar, and xercesImpl.jar, and add all of these.

Ensure that these five jars appear before rt.jar in the order of jars in this JRE definition. Use the "Up" and "Down" buttons to float these jars to the top of the list if they aren't already before "rt.jar".

Click "Ok" to exit "Edit JRE" and then click "Ok" to exit "Preferences".

Edit your project properties for the uPortal project (right click the project root folder and select "properties" from the contextual menu. Select "Java Build Path" from the left hand navigation pane. Click the "Libraries" tab. Select the JRE System Library and click the "Edit..." button. Choose from the alternate JRE pulldown the name of the alternate JRE you created above.

You still need xalan-2-6-0

The Xalan 2.6.0 jar, previously distributed as /lib/xalan.jar, has been renamed to /lib/xalan-2-6-0.jar so as not to collide with the JAXP xalan.jar. You still need to endorse it (the xalan-2-6-0.jar) so that it will override the org.apache.xml APIs in JDK 1.4's rt.jar. You endorse xalan-2-6-0.jar typically by placing it into the /lib/endorsed/ directory of your JRE and the /common/endorsed/ directory of your Tomcat.

What to do if these instructions are insufficient