Oracle9iAS Portal Developer Kit (PDK)
Packaging and Deploying Your Providers

This document describes the steps necessary to package your provider for deployment.

Contents

1. Service Names or Indentifiers
2. WAR and EAR files
3. Specifying the Contents of Your WAR file
4. Specifying Your Default Service
5. Creating Your WAR file
6. Creating Your EAR file
7. Registering Your Provider

Introduction

One of the biggest differences between PDK-Java v1 and PDK-Java v2 is the packaging and deployment process. In PDK-Java v1, a Web Provider was essentially just a Servlet and it was registered in JServ's zone.properties along with any Servlets you referenced in your provider definition file. You also had to make sure all the other components of your provider were in the correct place so they could be referenced. This was not too difficult when you had a small number of providers on a single machine, but it became a real headache when you had to deal with a large number of providers in a load-balanced environment - everything had to be replicated correctly. J2EE introduces the concepts of Enterprise Applications and Web Applications and their associated EAR and WAR files.

WAR and EAR files

WAR and EAR files are used to deploy applications in a J2EE application server, such as OC4J. The purpose of the WAR and EAR files is to encapsulate all the components necessary to run an application in a single file. This makes the deployment of an application packaged this way very easy and very consistent, reducing the possibility of errors due when an application needs to be moved from development to test, to production. However, this does require a little more work from developers to create the files.

WAR files represent a web application and include all the components of that web application including java libraries or classes, servlet definitions and parameter settings, JSP files, static HTML files and any other resources the application might need.

EAR files represent an "enterprise application". This is primarily an EJB concept, but also provides a grouping mechanism for web applications.

Service Names or Identifiers

The PDK-Java now allows you to deploy multiple providers under a single adapter servlet. The providers are identified by a service name or service identifier. For those of you who are familiar with the SOAP standard, this is similar to the SOAP service identifier. When you deploy a new provider you must assign a service name to the provider and use that service name when creating your provider WAR file.

Once your provider has been deployed, the correct service name must be used when registering your provider in Oracle Portal to ensure that requests are sent to the correct provider. For older releases of Oracle Portal that do not understand the concept of a service name, you can choose one of your providers to be the default. If the adapter servlet receives a request that does not specify a service name, the request will be forwarded to the default provider.

Packaging Your Provider

The first step in deploying your provider is to create the WAR file that contains the provider and all the resources it needs to execute. The steps below represent manual configuration of a WAR file. If you are familiar with one of the various utilities for assembling WAR files, you are free to use it.

1. create a working directory
2. extract the template war file into your working directory ensuring that file paths are also extracted
3. if your provider needs any additional jar files, add them to the WEB-INF/lib directory
4. if your provider needs any additional java class that are not contained in a jar file, add them to the WEB-INF/classes directory. Make the class files are saved in a directory structure that corresponds to their Java package names
5. add any static HTML files, JSPs and images to the to your working directory. If you need to create subdirectories to organize the files do so. Note that the subdirectories will become part of the path necessary to access the HTML or JSP files
6. create a subdirectory under the providers directory for your provider. The name of the subdirectory is important because that will be the service identifier or name for your provider
7. place your provider definition file in the subdirectory you just created.
8. copy the _default.properties file to <serviceid>.properties and edit it to reflect your provider's configuration.
9. If you have only one provider in your WAR file, edit _default.properties so the configuration settings reflect your default provider. The default provider is the provider that will be accessed if a service id is not specified in a request from a portal. Release 3.0.9 and earlier portals cannot specify a service id so requests will always be directed to the default provider.
10. if you use servlets to render content, edit WEB-INF/web.xml to add your servlets to the list of pre-defined servlets. Be careful not to remove the entries for servlets that are required by the PDK-Java

Specifying Your Default Service

The default service is the provider that should receive any request that does not specify a service name. This feature is provided to allow you to register your provider on release 3.0.9 of Oracle Portal.

The default provider is specified by editing the _default.properties file in the deployment directory of your WAR file. The _default.properties file looks something like this:

serviceClass=oracle.webdb.provider.v2.adapter.soapV1.ProviderAdapter
loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader
showTestPage=true
definition=providers/sample/provider.xml
autoReload=true

Edit the "definition" entry so it points to the provider definition file that represents your default provider. The directory path should be based on the contents of you WAR file, not the physical location of the file on the filesystem.

If you are not using a provider definition file to define your provider, you need to create an implementation of the ProviderLoader interface and edit the "loaderClass" entry.

Creating You WAR File

Once you have specified the contents of your WAR file, you are ready to create the WAR file itself. To create the WAR file:

1. zip up the contents of your working directory. Be careful to include the subdirectory paths (but not the working directory itself)
2. rename the resulting file (the name is not important as long as it is meaningful to you) and change the file extension to .ear

Creating Your EAR File

The steps below represent manual configuration of an EAR file. If you are familiar with one of the various utilities for assembling EAR files, you are free to use it.

1. create another working directory for the creation of your EAR file
2. extract the template EAR file into your working directory ensuring that file paths are also extracted
3. open the META-INF/application.xml file that was contained in the template EAR file. It should look something like this:

<?xml version "1.0">
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
          "http://java.sun.com/j2ee/dtds/application_1_3.dtd">
<application>
    <display-name>this is the display name of the application</display-name>
    <description>this is a description of the application</description>
    <module>
        <web>
            <web-uri>yourwarfile.war</web-uri>
            <context-root>/</context-root>
        </web>
    </module>
</application>

1. change the value of the <display-name> element so it reflects the display name for your application
2. change the value of the <description> element so it describes your application
3. change the value of the <web-uri> element to the name of your WAR file
4. save application.xml back to the same location. Do not change the name of this file
5. copy the WAR file you created earlier into your working directory. Put it in the working directory itself, not a subdirectory
6. zip up the contents of your working directory. Be careful to include the subdirectory paths (but not the working directory itself)
7. rename the resulting file (the name is not important as long as it is meaningful to you) and change the file extension to .ear

Deploying Your Provider on OC4J

1. Copy the .ear file into your oc4j applications subdirectory. Usually, this directory is:

   $IAS_HOME/oc4j/j2ee/home/applications

2. Add the following to $IAS_HOME/oc4j/j2ee/home/config/server.xml:

   <application name="{application name}"
                path="../applications/{ear file name}" />

   Replace the substitution strings with appropriate values.

   {application name} - the name of the application

   {ear file name} - the name of the .ear file containing the provider

   eg </application name="Application Name" path="../application/upgradedProvider.ear" />

3. Bind the web-app to the default site by adding the following to $IAS_HOME/oc4j/j2ee/home/config/http-web-site.xml:

   <web-app application="{application name}"
            name="{deployment name}"
            root="/{application path}" />

   Replace the substitution strings with appropriate values.
   {application name} - the name of the application as specified in server.xml
   {deployment name} - the name associated with this deployment of the application
   {application path} - the relative URI for the application

   e.g. <web-app application="Global Application Name"
                 name="Local Application Name"
                 root="/newProvider" />

4. Start up OC4J. This will automatically deploy the application based on the information specified in step 3
5. Access the provider using the following URL:

   http://{server}:{port}/{application path}/providers/

   Replace the substitution strings with appropriate values.

   {server} - the name of the server hosting the 9iAS listener
   {port} - the port for the 9iAS listener
   {application path} - the relative URI for the application defined in step 3

   e.g. http://iashost:80/newProvider/providers/

   Verify that the provider has been deployed and is accessible. You should see the familiar test page for your default provider (assuming your .properties file specifies showTestPage=true). To view the test page for specific provider service, append the service name to the above URL

   e.g. http://iashost:80/newProvider/providers/myService

Registering Your Provider

As mentioned earlier in this document, web providers now have service names or identifiers as well as a URL. The URL represents the location of the adapter servlet and the service name identifies a provider deployed on that adapter. Since service names did not exist in release 3.0.9 of Oracle Portal, the registration process is slightly different.

Registering on Oracle Portal 3.1

When registering your web provider on Oracle Portal 3.1, the registration wizard now includes fields for both the provider URL and service name. The URL is the URL of the adapter servlet and the service name is the name of the provider service you want to register. You should specify both the URL and the service name. If you omit the service name, you will, in effect, be registering the default provider. You are encouraged to always use the service name so you are sure which provider you are registering.

Registering on Oracle Portal 3.0.9

When registering on Oracle Portal 3.0.9, the service name is specified by appending it to the adapter URL

For example:

service name: sample

servlet URL: http://iashost:80/newProvider/providers/

registration URL: http://iashost:80/newProvider/providers/sample

If you omit the "sample" from the registration URL then any requests will be forwarded to the provider specified in _default.properties (see Specifying Your Default Service). This feature is provided so you can upgrade existing providers to the new version of PDK-Java and deploy them using the original URL, without impacting any portals that were using the provider.

Revision History:

Revision No Last Update 1.1 October 25, 2002