Oracle Application Server Portal Developer Kit (PDK)
Packaging and Deploying Your Providers

Contents

1. Introduction
2. WAR and EAR files
3. Service Names or Identifiers
4. Specifying the Contents of Your WAR file
5. Specifying Your Default Service
6. Creating Your WAR file
7. Creating Your EAR file
8. Deploying Using OracleAS Enterprise Manager (OEM)
9. Manually Deploying to an OracleAS Instance Using dcmctl
10. Manually Deploying to a Stand-Alone OC4J Instance
11. Setting Deployment Properties
12. Securing Your Provider
13. Registering Your Provider

Introduction

This article explains how to package up your PDK-Java provider implementation into a portable format suitable for deployment on OracleAS or other J2EE Appplication server. It goes on to explain how to deploy the resulting EAR file in an OracleAS environment and subsequently register it with one or more OracleAS Portal instances.

WAR and EAR files

WAR and EAR files are used to deploy applications in a J2EE application server, such as OracleAS. 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 allows you to deploy multiple providers under a single adapter servlet. The providers are identified by a service name or 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 OracleAS Portal to ensure that requests are sent to the correct provider. For 3.0.x releases of OracleAS 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, but the following manual steps should also suffice.

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 $service_name.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 OracleAS 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 .war

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. change the value of the <context-root> element to the URI path prefix you would like to be mapped to your application by default (e.g. /myapp).
5. save application.xml back to the same location. Do not change the name of this file
6. copy the WAR file you created earlier into your working directory. Put it in the working directory itself, not a subdirectory
7. zip up the contents of your working directory. Be careful to include the subdirectory paths (but not the working directory itself)
8. 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 Using OracleAS Enterprise Manager (OEM)

This section assumes:

• PDK-Java is installed in your target OC4J instance (if not, please refer to the document Installing the PDK-Java Framework)
• You have OracleAS installed with OEM (if not, follow the manual installation instructions for OracleAS or Standalone OC4J)

1. In OEM, navigate to the home page of the OC4J instance in which you configured PDK-Java (e.g. OC4J_Portal).
2. On the Applications tab, click Deploy EAR file
3. Enter the following Information:
   • J2EE Application: browse to the location of your EAR file on your local filesystem.
   • Application Name: enter the unique name you want to associate with your provider application.
   • Parent Application: default
4. Click Continue. The URL mapping for Web Modules displays. The mappings will default to the context-roots specified in application.xml (e.g. /myapp) but you can change them if you want to, to avoid clashing with the context roots of other deployed applications.
5. Click Finish. The Last step contains a summary of all information you entered.
6. Click Deploy and then OK on the confirmation screen.

Your provider application is now deployed to your OracleAS instance. You should see the newly deployed application in the list of applications for the OC4J instance you selected. Please proceed to Testing the Deployment

Manually Deploying to an OracleAS Instance Using dcmctl

This section assumes:

• PDK-Java is installed in your target OC4J instance (if not, please refer to the document Installing the PDK-Java Framework)
• You have OracleAS installed (if not, follow the manual installation instructions for Standalone OC4J

Warning: Before using dcmctl to manage an OracleAS instance, make sure there are no OEM processes managing that same instance. If multiple processes are managing the same instance, there is a risk of inconsistencies or corruption of the data used to manage the instance.

1. Deploy your EAR file using the command-line deployment utility dcmctl

   $IAS_HOME/dcm/bin/dcmctl deployApplication -v -a $application_name -co $oc4j_instance -f $ear_file_path

   where:
• $application_name is the unique name that should be given to the application for administrative purposes.
• $oc4j_instance is the name of the target OC4J instance with PDK-Java installed that the application should be deployed into (e.g. OC4J_Portal).
• $ear_file_path is the full path to your EAR file on the filesystem

Your provider application is now deployed to your OracleAS instance. Please proceed to Testing the Deployment

Manually Deploying to a Stand-Alone OC4J Instance

This section assumes:

• You have a compatible version of OC4J Standalone installed (check the Release Notes for a compatible version)
• PDK-Java is installed in this OC4J instance (if not, please refer to the document Installing the PDK-Java Framework)

1. If OC4J is not already running, start it as a background process with the following commands
   
   • In Windows Command Prompt:
     cd $oc4j_home\j2ee\home
     start java -server -Xmx256m -jar oc4j.jar
   • In Unix/Linux Bourne Shell (sh):
     cd $oc4j_home/j2ee/home
     java -server -Xmx256m -jar oc4j.jar &

   where:

   • $oc4j_home is your OC4J installation root directory (e.g. D:\oc4j904)

   Note: the -Xmx256m option specifies a 'maximum heap size' of 256 Megabytes for the OC4J process, which is the recommended setting. However, you may raise or lower this setting to suit your application. If you encounter java.lang.OutOfMemoryError exceptions, you should raise this setting.

2. Deploy your EAR file using the following command

   java -jar admin.jar ormi://localhost admin $admin_password -deploy -deploymentName $application_name -file $ear_file_path

   where:

• $admin_password is the OC4J administration password you set on installation
• $application_name is the unique name that should be given to the application for administrative purposes.
• $ear_file_path is the full path to your EAR file on the filesystem
3. For each of the WAR files in your EAR file (as listed in $oc4j_home/j2ee/home/applications/$application_name/application.xml), bind the corresponding web applications to a URI path on your website with the following command:

   java -jar admin.jar ormi://localhost admin $admin_password -bindWebApp $application_name $web_app_name file:$oc4j_home/j2ee/home/config/http-web-site.xml $context_root

where:

• $web_app_name is WAR file name without the ".war" extension (e.g. jpdk)
• $context_root is the URI path prefix you would like to be mapped to that web application (e.g. /myapp).

Your provider application is now deployed. Please proceed to Testing the Deployment

Testing the Deployment

Access the provider test page using the following URL:

http://$host:$port$context_root/providers

where:

• $host and $port are the host name and port number of the HTTP listener for your target OC4J instance. In an OracleAS installation with webcache installed, $port should be the Web Cache listener port (e.g. 7777). In a standalone OC4J installation, the default HTTP port number is 8888.
• $context_root is the URI path prefix you mapped to the provider web application on deployment (e.g. /myapp), or the default one specified in application.xml in the case of a manual deployment with dcmctl.

An example URL is

http://my.host.com:7777/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. For example:

http://my.host.com:7777/newProvider/providers/myService

Setting Deployment Properties

In the PDK-Java there are a number of deployment properties that are specified as JNDI variables. You may wish to alter the values of these properties for your particular deployment. The level of logging to be used is one such variable and is global to all providers in the PDK-Java war file. Other variables are defined (see list below) but are provider-specific, therefore each provider will have its own variable for each of the properties declared as JNDI variables.

Non-Provider Specific Deployment Properties

• oracle/portal/log/logLevel - This is the logging level to be used by the JPDK

Service Specific Deployment Properties

These properties can be used to control each deployed provider service individually, and hence require you to specify a $service_name in the corresponding JNDI path. If you want to set one of these properties for all services at once, you can use the special keyword global as the $service_name.

• oracle/portal/$service_name/showTestPage - Boolean flag that determines if a provider's test page is accessible,defaults to true
• oracle/portal/$service_name/maxTimeDifference - Provider's HMAC time difference.
• oracle/portal/$service_name/definition - Location of provider's definition file, provider.xml
• oracle/portal/$service_name/autoReload - Boolean auto reload flag, defaults to true.
• oracle/portal/$service_name/sharedKey - HMAC shared key, no default value.
• oracle/portal/$service_name/rootDirectory - Location for provider customizations, no default value.

Note: For more information about HMAC authentication, see the article "Securing Your Web Provider".

Controlling the Properties

Through OEM

1. In OEM click on the instance where you have installed the PDK-Java.
2. Click on the name representing the sample J2EE application.
3. Under the web modules heading, jpdk will be listed. Click on this.
4. In the administration section at the bottom of the screen, click on the Environment link.
5. Under the environment entries section, all of the environment variables are listed. If it has a default value, this is listed under the value heading. To update a value for a particular variable, enter the new value in the text box in that variable's row.
6. When you have updated all of the variable's values that you want, click on the Apply button at the bottom of the screen.

Manually

This method should be used wherever OEM is not available. Changes to JNDI variable values at deployment should be declared in the PDK-Java's orion-web.xml file. This file can be found in the following location:

For a full OracleAS install:

$ias_home\j2ee\$oc4j_instance\application-deployments\$application_name\$web_app_name

For a standalone OC4J install:

$oc4j_home\j2ee\home\application-deployments\$application_name\$web_app_name

If the file does not exist then you should create it.

For each deployment property that you want to set a value for, add the following:

<env-entry-mapping name="$jndi_variable_name">$deployment-value</env-entry-mapping>

For example, your orion-web.xml might look like this:

<?xml version = '1.0'?>
<!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd">
    <orion-web-app deployment-version="9.0.4.0.0" jsp-cache-directory="./persistence" temporary-directory="./temp" servlet-webdir="/servlet/">
        <env-entry-mapping name="oracle/portal/sample/rootDirectory">D:\prefs</env-entry-mapping>
        <env-entry-mapping name="oracle/portal/sample/definition">D:\definitions\def.xml</env-entry-mapping>
    </orion-web-app>

Securing Your Provider

When using the PDK-Java framework in a production environment, it is recommended to secure access to your Provider machine or more specifically, your Provider.  There are a number of different ways you can secure a Web Provider. For more information please review An Overview of Portlet Security

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 OracleAS Portal, the registration process is slightly different.

Registering on OracleAS Portal 9.x

When registering your web provider on OracleAS Portal, 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 OracleAS Portal 3.0.9.x

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

For example:

service name: myService

servlet URL: http://my.host.com:7777/newProvider/providers

registration URL: http://my.host.com:7777/newProvider/providers/myService

If you omit the service name 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 2.0 November 28, 2003