• Introduction
  
• What are the Prerequisites?
  • What Should You Know?
  • What are the Software Requirements?
  • What are the Notations?
• How to Build the Application?
  • Examining the Distribution
  • Setting up the Application
  • Starting OC4J
  • Building and Deploying the Application
• How to Run the Application?
  • Determining the XML Parser Details
  • Running the Application
  • Creating a New a Shared Library
  • Consuming a Shared Library
  • Re-executing the Application
• Summary

Change Tracking

Introduction

This how-to demonstrates how the shared library mechanism -- introduced in OC4J 10g (10.1.3) -- can be used to define which XML parser implementation is loaded and used by a deployed application.

Note: See the OC4J Configuration and Administration Guide for a detailed discussion on the shared libraries functionality available in OC4J.

By default, the XML v2 parser supplied with the Oracle XDK is made available and used by applications when they are deployed to OC4J.

To demonstrate the shared-library capabilities, the Xerces XML parser and Xalan XSL translator class libraries are installed and published as shared-library and the application is then re-deployed and configured to consume the new shared-library. When the application is re-executed, it will show that the Xerces and Xalan libraries are loaded.

Like many other application servers, OC4J is configured to load a pre-defined set of libraries. For instance, all of the J2EE libraries supported and implemented by a specific release are loaded when OC4J starts. Additionally, the Oracle XDK (XML Developer Kit) which provides the XML parser and other artifacts which OC4j itself uses is loaded and made available to applications by default. Typically this is a handy situation for users of OC4J, eliminating the need to track down a set of XML libraries and include them for use with an application.

However, situations do arise whereby an application running on OC4J has a dependency, or has been explicitly certified for use with another XML parser implementation and needs to have that implementation loaded in preference to the Oracle XML parser. Up until the 10.1.3 release, this has proven to be a non trivial problem for users of OC4J.

The main problem has been that Oracle XDK libraries have been hard-coded into the classpath of the container using the referential JAR file Class-Path mechanism. Altering this has required the use of the JRE extension library mechanism, or altering the boot classpath of the JVM when it is launched to load the alternative XML parser implementation instead. While this works, it has been an unsupported operation since the effect of this change is not limited to a specific application – it’s effect are felt across the entire container and this may lead to unpredictable results at runtime.

But a solution is now at hand with the introduction of the shared-library mechanism with OC4J 10g (10.1.3). Using the shared library mechanism, classes can now exist within a parallel class loading space, enabling a clean separation to be made between the libraries used by OC4J itself and the libraries used by applications that are deployed to OC4J.

With this shared library implementation, it is possible to specifically override and replace any of the default class libraries which are loaded and made available by default. This can be done on an individual application-by-application basis or rolled up to a set of defaults inherited by each application.

A shared library consists of a set of code-sources from which Java classes can be loaded by a class loader. A shared library has a name and a version.

By default, an application deployed to OC4J inherits a number of pre-defined shared-libraries. The definitions for these shared libraries are shown below.

 <imported-shared-libraries>
 <import-shared-library name="oracle.dms"/>
 <import-shared-library name="oracle.jdbc"/>
 <import-shared-library name="oracle.xml"/>
<import-shared-library name="soap"/>
<import-shared-library name="global.libraries"/>
<import-shared-library name="global.tag.libraries" />
</imported-shared-libraries>

The definitions for the default set of shared-libraries are specified in an internal OC4J file which can't be changed. However, it's possible to install and publish additional shared libraries, then configure applications to load them and even replace any of the inherited libraries as needed.

This how-to demonstrates exactly how to perform this task.

What are the Prerequisites?

What Should You Know?

• Be generally familiar with J2EE applications and related XML parsing concepts
• Have an appreciation what class libraries are and how they are used in conjunction with J2EE containers.

What are the Software Requirements?

• OracleAS or OC4J 10g (10.1.3) installed. Available from OTN.
• Sun JDK 1.4_02 or above. Available from the Sun Web site.
• Xerces and Xalan Apache XML distributions. Available from the XML Apache Web site.

What are the Notations?

• %ORACLE_HOME% : the directory in which OC4J has been installed.
• %J2EE_HOME% : the directory where the oc4j.jar file exists within OC4J.
  This is typically 2 directories under %ORACLE_HOME%. For example, if you installed OC4J to c:\ then %J2EE_HOME% would be c:\j2ee\home
• %JAVA_HOME% : the directory where the JDK is installed on your machine.

How to Build the Application?

This how-to needs to be built and deployed before it can be accessed.

Examining the How to Distribution

First off, let's examine the contents of the how-to distribution.

• how-to-swapxmlparser/src - contains all Java source code for the example.
  • web/
    • index.jsp - the page used by the container to display the XML parser related classes
    • css/
      • blaf.css - the style-sheet.
• how-to-swapxmlparser/etc/
  • web.xml - the standard J2EE Web module deployment descriptor
  • application.xml - the standard J2EE application module descriptor
• how-to-swapxmlparser/doc/
  • how-to-swapxmlparser.html - this document.
  • images/ - contains the images for this document
• how-to-swapxmlparser/
  • build.xml - the Ant build file to build, package and deploy the application
  • oracle-ant.xml - sets correct environment up for Ant to to build and deploy the application
  • oracle-ant.properties - defines the properties of the OC4J instance which the application is deployed to

Setting Up the Application

Make sure the following properties are configured correctly in the oracle-ant.properties file located in the root directory of this how-to distribution.

NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file.  If necessary, modify these variables to the proper values for you environment:

• oracle.home - the root directory of oracle installation.  Defaults to the ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas..host - the hostname of the platform on which the target OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas..admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to "oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to "welcome1".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to "http-web-site"
• oracleas.deployer.uri - identifies the target for deployment operations -- enables OC4J standalone, OracleAS single instance or an OracleAS group to be deployed to using the same set of Ant tasks

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).

The instructions from herein this document assume the use of the OC4J zip distribution. If OracleAS is being used, the appropriate commands required to start/stop the server should be used.

Start OC4J

• %ORACLE_HOME%/bin/oc4j start

Note that the oc4j.cmd script expects the JAVA_HOME environment variable to point to a full JDK installation.

Deploying the Application

>ant

Executing the default "all" target of the supplied build.xml file performs the following steps:

• Compiles all the source files
• Packages the Web module into a WAR file and produces a J2EE application module (ear file) that contains the various files required for the deployment of the application.
• Deploys the application module.  The .ear file generated in the previous step is now deployed to the server using the ant deploy ant task:

<oracle:deploy
  deployerUri="${oracleas.deployer.uri}"
  userId="${oracleas.admin.user}"
  password="${oracleas.admin.password}"
  file="${lib.dir}/${app.name}.ear"
  deploymentName="${app.name}"
  bindAllWebApps="${oracleas.binding.module}"/>      

How to Run this How-To

In this how-to you will perform a number of tasks to observe how shared-libraries can be used with OC4J.

The tasks you will now perform are:

• Execute the deployed how-to-swapxmlparser application to view the XML parser classes that are loaded
• Install and publish a new shared-library with a different XML parser implementation.
• Reconfigure the deployed application to override the default oracle.xml shared-library and load the new shared-library.
• Re-execute the application and view the XML library that is now in use.

Determining the XML Parser Details

The how-to uses a simple JSP application to view the various XML factories and class instances loaded by the application.

The application uses the JAXP (Java API for XML parsing) API to create instances of the SAX parser artifacts (SAXParserFactory and SAXParser), DOM parser artifacts (DocumentBuilderFactory and DocumentBuilder) and the XSL artifacts (TransformerFactory and Transformer). It then displays the full qualified class names of these objects to display which classes have been loaded.

 public static String getDOMDetails () 
 {
 DocumentBuilder builder=null;
 DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();

 try 
 {
 builder = factory.newDocumentBuilder();
return "<BR><B>DocumentBuilderFactory Instance:</B> " + factory.getClass().getName() +
"<BR><B>DocumentBuilder Instance:</B> " + builder.getClass().getName() +"<BR>"; }
catch (Exception e)
{
return "Error processing DOM -- " + e.getMessage();
}
}

A similar approach is used to obtain the details of the SAX and XSL loaded classes.

The JSP page then displays the the results of calling these methods, which in turn identifies the XML library in use.

Running the Application

Once the application has been deployed, you can determine what XML library has been loaded by executing the application.

Open a browser window and enter the URL:

http://localhost:8888/how-to-swapxmlparser

This will display the fully qualified class names of the XML related classes the application loaded.

On a default OC4J configuration this should show::

DOM Parser

DocumentBuilderFactory Instance: oracle.xml.jaxp.JXDocumentBuilderFactory
DocumentBuilder Instance: oracle.xml.jaxp.JXDocumentBuilder

SAX Parser

SAXParserFactory Instance: oracle.xml.jaxp.JXSAXParserFactory
SAXParser Instance: oracle.xml.jaxp.JXSAXParser

XSL Transformer

TransformerFactory Instance: oracle.xml.jaxp.JXSAXTransformerFactory
Transformer Instance: oracle.xml.jaxp.JXTransformer

The HTML page in the browser should look like the below:

Creating a Shared Library

You will now replace the Oracle XML Parser with another XML parser implementation.

To start with, you need to have a different XML parser and XSL translator implementation available to use. The popular open source implementations from Apache, Xerces and Xalan, can be downloaded from http://xml.apache.org/ and used as an alternative XML implementation.

For the rest of this document, it will be assumed that you have downloaded and have available the following distributions:

• Xerces2 Java Parser 2.7

This will mean you have the following JAR files at your disposal:

• xercesImpl.jar
• xml-apis.jar

If you are using different versions of Xerces, then it doesn't really make any difference to this how-to. There may be some slight filename changes across the different versions to be aware of.

Using Application Server Control to Create a Shared Library

A shared-library can be created and configured using Application Server Control Console (ASC) supplied with OC4J. The Shared Library task located on the Administration page of ASC enables shared libraries to be created, edited and deleted. When creating new shared libraries, ASC allows JAR files from a client to be uploaded directly to the OC4J instance being managed and configured as code-sources for the library.

Note: the OracleAS 10.1.3 production also supports the additional ability to install and publish shared libraries using both the command line and Oracle Ant tasks. See the documentation for more information.

The format of a shared-library is name/version, where name is the unique name you wish to give to the shared library, and the version is any arbitrary (or meaningful) version string you wish to use. It is possible to install more than one version of a shared-library so the version identifier can be of significance.

When new shared libraries are created and populated with archives, by default they will reside in the following directory structure:

 %ORACLE_HOME%
 \j2ee
   \home
     \shared-lib
       \name
         \version
           archive1.jar
           archive2.jar

For the purposes of this how-to, you will create a shared-library as apache.xml:2.7. The 2.7 used here is arbitrary but helps to identify the version of the Apache libraries being used.

The results of the creating the shared library with ASC are visible in the %ORACLE_HOME%\j2ee\home\config\server.xml file. Each shared library is defined with the <shared-library> tag, and each JAR file to be used as a code-source is declared using the <code-source> tag.

1.	Access Application Server Control Console from a browser. URL: http://host:8888/em Logon: oc4jadmin/<password> where <password> is the password set when the OC4J instance was first started.
2.	Select the Administration page.
3.	Click the Create button.
4.	Specify the name and version of the new library and click the Next button. Name: apache.xml Version: 2.7
5.	Click the Add button to add an archive to the shared library. The provided archives will use as code-sources by the shared library.
6.	Using the File Upload dialog that appears locate the xercesImpl.jar from the Xerces 2.7 distribution on the client. Press the Open to upload the JAR file to the server.
7.	The xercesImpl.jar file will be added as an archive on the server. Click the Add button again to add another archive.
8.	Using the File Upload dialog that appears locate the xml-apis.jar from the Xerces 2.7 distribution on the client. Press the Open to upload the JAR file to the server.
9	Click the Finish button to finish the creation process

The %ORACLE_HOME%\j2ee\home\config\server.xml file will now contain a new shared library element with defined code-source tags for each archive that was uploaded.

<shared-library name="apache.xml" version="2.7" >
 <code-source path="xercesImpl.jar"/>
 <code-source path="xml-apis.jar"/>
</shared-library>

Consuming a Published Shared Library

Once the apache.xml:2.7shared library has been installed and published, it can then be consumed by any of the applications which are deployed to OC4J.

The shared-library set which is available to an application is determined by two factors.

The first defining factor is the parent application. Since OC4J supports a parent application concept for deployed applications, a newly deployed application will inherit the shared-libraries set from it’s specified parent.

In most cases new applications are deployed with the ‘default’ application being specified as the parent application. This results in the shared-library set which is specified for the default application being inherited by the child application.

The second defining factor is the application’s own specific configuration which is defined in the application’s own orion-application.xml file. This file allows settings to be applied specifically for the one application, including the supplementing and overriding of inherited properties from it’s parent.

Thus configuring a specific shared-library set for an application can be performed by adding shared-library related tags to the applications’s orion-application.xml.

 <imported-shared-libraries>
 <import-shared-library name="library.name" version="library.version"/>
 </imported-shared-libraries>

Class loading behaviour can also be prescribed using ASC during an application's deployment phase. The class loading settings are configurable on the Deployment Tasks page as the final step before performing the deployment via ASC. This ultimately results in the imported-shared-library tags being added to the orion-application.xml file of the application being deployed.

Since we have an existing application that has been deployed via the Ant tasks, we will now use ASC to redeploy the how-to-swapxmlparser application and specify the required XML parser library to use. This will require the removal of the default oracle.xml library import setting and the setting of the import flag for the new apache.xml shared library.

1.	Open the browser to the Application Server Control Console page. Select the Applications page. Select the how-to-swapxmlparser application and click the Redeploy button.
2.	Click the Browse button and select the how-to-swapxmlparser.ear file from the directory of this how-to.
3.	Observe the details shown for the how-to-swapxmlparser application and click the Next button to proceed.
4.	Select the Configure Class Loading task on the Deployment Tasks page.
5.	Select the "Show all n" option in the Select box to see all the shared libraries installed on the server.
6.	Check the Import setting for the apache.xml shared library. Uncheck the Import setting for the oracle.xml shared library. Click the OK button to proceed.
7.	Click the Redeploy button to proceed with the redeployment.
8	Click Return to exit the redeployment operation.

The additional class loading configuration task modifies the the %ORACLE_HOME%\j2ee\home\application-deployments\howtoswapxmlparser\orion-application.xml and adds the following tags to change the XML parser implementation.

 <imported-shared-libraries>
 <import-shared-library name="apache.xml"/>
 <remove-inherited name="oracle.xml"/>
</imported-shared-libraries>

These tag entries will remove the default oracle.xml library being loaded by the application and will import the apache.xml shared-library containing the different XML parser implementation.

Re-Executing the Application

The how-to application is now configured to use the Apache XML libraries as defined in the apache.xml:2.7shared-library.

To observe the results of the shared-library change, re-execute the application to view the different XML parser classes loaded.

http://localhost:8888/how-to-swapxmlparser

A correctly configured server will show:

DOM Parser

DocumentBuilderFactory Instance: org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
DocumentBuilder Instance: org.apache.xerces.jaxp.DocumentBuilderImpl

SAX Parser

SAXParserFactory Instance: org.apache.xerces.jaxp.SAXParserFactoryImpl
SAXParser Instance: org.apache.xerces.jaxp.SAXParserImpl

XSL Transformer

TransformerFactory Instance: org.apache.xalan.processor.TransformerFactoryImpl
Transformer Instance: org.apache.xalan.transformer.TransformerIdentityImpl

The HTML page in the browser should look like the below:

Summary

This how-to has demonstrated the ability to provide an alternative XML parser and configure applications to use of it.

The choice of which libraries an application uses is now entirely yours.