How Do I Deploy BC4J JSP Applications to iPlanet?

An Oracle9i JDeveloper How To Document
Version 1
July 8, 2002

Content

• Introduction
• Stopping iPlanet
• Installing the iPlanet patch for bc4jhtml.jar
• Installing the BC4J Runtime in iPlanet
  • Updating iPlanet's CLASSPATH setting
  • Manual installation webapp.war and cabo.war
• Creating a BC4J Project.
• Deploying Your BC4J Application as a Web Module
• Creating a BC4J JSP Application
• Modifying the location of the Tag Library Descriptor
• Starting iPlanet
• Deploying the BC4J JSP Application.
• References

Introduction

This document describes in detail the requirements and steps to deploy the BC4J runtime components as well as a BC4J Application as a Web Module to iPlanet.

This document was written for Oracle9i JDeveloper 9.0.2 and Sun iPlanet Application Server 6.5 Enterprise Edition on Windows 2000, although other versions of Oracle9i JDeveloper and/or iPlanet Application Server should behave the same.

Stopping iPlanet

Before we deploy the BC4J libraries to iPlanet, we need to stop the Application Server. The Application Server should remain stopped until after we are finished updating the CLASSPATH of the Application Server.

On windows this is done with the Services Control Panel Applet inside of the Administrative Tools for Windows. On UNIX, please consult the iPlanet Administration Documentation.

Installing the iPlanet patch for bc4jhtml.jar

On iPlanet, the results of ServletRequest.getParameter(String) are not decoded, therefore certain information passed as parameters with the BC4J Web Application do not behave properly. We have created a patch for the oracle.jbo.html.HtmlServices class. The source code of this class is also shipped with Oracle9i JDeveloper at the location %ORACLE_HOME%\bc4j\src\bc4jhtmlsrc.zip.

This patch contains a file bc4jhtml-patched.jar containing a built version of this class, as well as the source of this file. This patch must be on the CLASSPATH before the bc4jhtml.jar file.

The patch is available here.

Deploying the BC4J Runtime to iPlanet

Two steps need to be taken to install the BC4J runtime libraries to iPlanet. First the Java CLASSPATH needs to be set to contain the shared BC4J framework classes. Second, the bc4j.ear file must be manually installed under the document root.

Updating iPlanet's CLASSPATH setting

To deploy the BC4J runtime to iPlanet, add the following JAR files to the CLASSPATH for the iPlanet Application Server so they can be used by multiple web applications. (see the instructions below for modifying iPlanet's CLASSPATH).

The CLASSPATH for iPlanet is set using the iPlanet Registry editor (kregedit). This is a java based application which allows you to customize the iPlanet LDAP registry. Since this updates the LDAP server and not the Application Server, this may be performed while the Application Server is stopped.

Here is the path to the Java CLASSPATH key:

You will need to add the location of the preceding Java archives to the end of this CLASSPATH setting. I recommend creating the list of paths in a text editor then pasting it into the CLASSPATH text input area.

Manual installation of webapp.war and cabo.war

The BC4J web application framework requires some resources to be accessible from a shared absolute URL within the application server. These absolute URL's are /webapp and /cabo. Since a web application (bc4j.ear) cannot be installed under the root context (/) on iPlanet, these resources must be installed manually.

In the directory %JDEV_HOME%\BC4J\redist there are two archives called cabo.war and webapp.war. Decompress both of these WAR files under the document root of your web server. The default location for the iPlanet Web Server 6.0 is \iPlanet\Servers\docs.

Here is the command line used on Windows, this example uses F: as the drive with iPlanet installed, and F:\jdev902 as the home directory where Oracle9i JDeveloper is installed.

F:\iPlanet\Servers\docs>unzip F:\jdev902\BC4J\redist\webapp.war -d webapp
F:\iPlanet\Servers\docs>unzip F:\jdev902\BC4J\redist\cabo.war -d cabo

Once your server is running, you can test that the webapp.war file has been extracted properly by checking the following URL: http://localhost/webapp/admin/bc4jadmin.jpg.

Note: You may need to substitute your hostname for localhost, and add the port number if your iPlanet Web Server is not active on port 80.

This is what should be displayed:

Creating a BC4J Project

Our BC4J Project will be created on the DEPT and EMP tables in the SCOTT sample schema which is part of the Oracle database.

Create Entity Objects, with default View Objects and a default Application Module in the Business Components Wizard. Once created, your project should look similar to the following:

Deploying Your BC4J Application as a Web Module

We will invoke the Business Components for Java Deployment Wizard to deploy our BC4J Application. Here are the steps:

1. In the Navigator, Select the Project Node.
2. Right-click this node, and choose Deploy Business Components...
3. In the wizard, click Next
4. From the Profiles Page of the wizard, shuttle Simple Archive Files from the Available to the Selected list.
5. Click Next
6. Check Deploy and click Next
7. Click Finish
8. Look in the Deployment Log (in the JDeveloper message window) and note the location of the two JAR files which are created. Add these two files to the CLASSPATH of iPlanet.

Due to an issue with the Java Class Loader in iPlanet, these two JAR files will need to be added to the System CLASSPATH of iPlanet. The restriction is that the ContextClassLoader for the Thread executing the code will not see any JAR files deployed within the Web Archive. This is why they can not simply be included in the WAR file that will be deployed to the Application Server.

Follow the steps from the section Updating iPlanet's CLASSPATH setting to add these two JAR files to the System CLASSPATH.

Creating a BC4J JSP Application

In order to test our BC4J business components, we will create a JSP application which will use them.

1. In the navigator, select the Workspace node which contains the BC4J Project.
2. Create a New Empty Project in this workspace.
3. Using the Business Components JSP Application wizard, create a default JSP Application for the BC4J objects just created.
4. On each of the "edit" pages (these are the ones named <ViewObjectName>_Edit.jsp, change the releasemode attribute on the ApplicationModule tag from Reserved to Stateful. This is due to timing differences in the Servlet container from other Application Servers, in the next release of BC4J this will not be required.
5. From the main menu, Choose File > Save All.

Modifying the location of the Tag Library Descriptor

Due to how iPlanet handles deployment, the JSP Tag Library Descriptor can not be referenced by a JAR file which contains an entry for META-INF/taglib.tld. We will need to extract the TLD file from the datatags.jar archive and rename it, and then modify the web.xml document to reference the new location.

Perform the following steps outside of Oracle9i JDeveloper.

Note: You do not need to exit JDeveloper, just perform these steps from outside of JDeveloper.

1. Extract the file taglib.tld from %JDEV_HOME%\BC4J\lib\datatags.jar.
2. Copy this file to the directory public_html\WEB-INF which is under your project root directory.
3. Rename this file to DataTags.tld so it will not conflict with any other tag library which may be included with your WAR file.

Perform the following steps inside of Oracle9i JDeveloper.

1. Add the file public_html\WEB-INF\DataTags.tld to your BC4J JSP project.
2. In the navigator, select web.xml.
3. Right-click and choose Settings.
4. From the Web Application 2.2 Deployment Descriptor dialog, select Tag Libraries.
5. Select the only Tag Library from the list.
6. Modify the Taglib location to /WEB-INF/DataTags.tld
7. Click OK.
8. From the main menu, Choose File > Save All.

Starting iPlanet

Now that we are finished modifying the CLASSPATH of iPlanet, we can start the Application Server.

On windows start iPlanet using the Services control panel applet inside of the Administrative Tools. On UNIX, please consult the iPlanet Administration Documentation.

Deploying the BC4J JSP Application.

When you create a default BC4J JSP Application, a default deployment profile will be created automatically. The name of this profile is myappwar.deploy.

Here are the steps to deploy our WAR file:

1. In the Navigator, right-click myappwar.deploy, and choose Deploy to EAR file.
2. On the Message window, under the Deployment tab, a message shows the location of the newly created EAR file. Use the iPlanet Deployment tool to deploy this EAR file to your iPlanet Application Server. You may use either the GUI iPlanet Deployment Tool (on Windows this tool is available under the iPlanet Application Server 6.5 program group), or you may use the command-line tool iasdeploy. The command line to invoke iasdeploy is: iasdeploy deployapp <My EAR file name>.

You now have a fully functional BC4J JSP Application deployed as a Web Module. You may invoke the Application in your web browser with the URL http://localhost/NASApp/<context root>, where <context root> is the J2EE Context Root for your project containing the BC4J JSP Application (for example: Workspace1-Project2-context-root/)

References

• Sun ONE Middleware Developer Web Site