C Manually Packaging and Deploying PDK-Java Providers

This appendix explains how to manually package your PDK-Java provider implementation into a portable format suitable for deployment on the Oracle Application Server or another J2EE application server. It then explains how to deploy the resulting EAR file in an Oracle Application Server environment and subsequently register it with one or more OracleAS Portal instances.

Note: In general, we recommend that you package and deploy your providers via the tools available in Oracle JDeveloper. However, if you find that you must package and deploy your providers manually for some reason, we provide the information in this appendix for your reference.

• Introduction

• Packaging and Deploying Your Providers

Note: Throughout this chapter, you will see references to ORACLE_HOME. ORACLE_HOME represents the full path of the Oracle home, and is used in cases where it is easy to determine which Oracle home is referenced. The following conventions are used in procedures where it is necessary to distinguish between the middle tier, OracleAS Infrastructure, or Oracle Application Server Metadata Repository Oracle home: MID_TIER_ORACLE_HOME, represents the full path of the middle-tier Oracle home. INFRA_ORACLE_HOME, represents the full path of the Oracle Application Server Infrastructure Oracle home. METADATA_REP_ORACLE_HOME, represents the full path of the OracleAS Infrastructure home containing the Oracle Application Server Metadata Repository.

C.1 Introduction

Before preceding with packaging and deploying your provider, you must understand a couple of basic concepts.

• WAR and EAR files

• Service Identifiers

C.1.1 WAR and EAR files

WAR and EAR files are used to deploy applications on a J2EE application server, such as Oracle Application Server. The WAR and EAR files encapsulate all of the components necessary to run an application in a single file. These files make the deployment of an application very easy and consistent, reducing the possibility of errors when moving an application from development to test, and test to production.

• 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 required resources.

• EAR files represent an enterprise application.

C.1.2 Service Identifiers

PDK-Java enables you to deploy multiple providers under a single adapter servlet. The providers are identified by a service identifier. When you deploy a new provider, you must assign a service identifier to the provider and use that service identifier when creating your provider WAR file. The service name is used to look up a file called service_id.properties, which defines the characteristics of the provider, such as whether to display its test page.

For example, you can register the PDK-Java samples provider using the following URL and a service identifier of urn:sample:

http://mycompany.com/jpdk/providers

Alternatively, you can use a URL of the form:

http://mycompany.com/jpdk/providers/sample

where the provider name (sample) is appended to the URL of the PDK-Java samples provider. In this case, you should leave the Service Id field blank when registering the provider.

You can specify the service identifier separately in cases where multiple portals are sharing the same provider. By registering each portal with a different service identifier, you can specify the provider properties for each consumer independently.

Once your provider has been deployed, you must use the correct service identifier to register your provider with OracleAS Portal, which ensures that requests are routed to the correct provider. If the adapter servlet receives a request without a service identifier, the request goes to the default provider.

Note: If you do not know the service identifier, check the provider test page or contact the administrator of the provider. If you are using the Federated Portal Adapter, the URL points to the adapter, not the provider, thus you must enter a value for this field. In this case, the service identifier would be urn: followed by the name of the database provider.

C.2 Packaging and Deploying Your Providers

The following sections show the steps you must perform to package and deploy a provider manually:

• Packaging Your Provider

• Deploying Your EAR File

• Testing Deployment

• Setting Deployment Properties

• Securing Your Provider

• Registering Your Provider

C.2.1 Packaging Your Provider

The steps in this section explain how to manually package a WAR file. If you are familiar with one of the various utilities for assembling WAR files, you are free to assemble your WAR file that way.

• Preparing Your Directories

• Specifying Your Default Service

• Creating Your WAR File

• Creating Your EAR File

C.2.1.1 Preparing Your Directories

In preparation for creating your WAR file, you need to perform the following steps:

1. Create a working directory where you can collect the necessary files.

2. Extract the template.war file from /pdk/jpdk/v2/template.war into your working directory. Make sure that you extract the file paths, too.

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 classes not contained in a JAR file, add them to the WEB-INF/classes directory. Make sure that you save the class file in a directory structure that corresponds to their Java package names.

5. Add any static HTML files, JSPs and images to your working directory. Create subdirectories as needed to organize the files. Note that the subdirectories will become part of the path necessary to access the HTML or JSP files.

6. Create a subdirectory for your provider under the providers directory. The name of the subdirectory is the service identifier (name) of 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. Edit _default.properties to reflect the configuration settings of your default provider. The default provider is accessed if a service identifier is not specified in a request. Refer to Section C.2.1.2, "Specifying Your Default Service" for more information on this step.

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 required by PDK-Java.

C.2.1.2 Specifying Your Default Service

The default service is the provider that receives any request without a service name. You specify a default provider by editing the _default.properties file in the deployment directory of your WAR file.

Edit the definition entry to point to the provider definition file that represents your default provider. Paths should be relative to the WEB-INF directory within your WAR file, not the physical location of the file in the file system.

The _default.properties file looks similar to the following:

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

C.2.1.3 Creating Your 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 the contents of the working directory you created in Section C.2.1.1, "Preparing Your Directories", including the subdirectory paths but not the working directory path itself.

2. Rename the resulting file to give it a meaningful name and change the extension to .war.

C.2.1.4 Creating Your EAR File

The steps below represent manual configuration of an EAR file. To create the EAR file:

1. Create another working directory for the creation of your EAR file.

2. Extract the template.ear file from /pdk/jpdk/v2/template.ear into your working directory. Make sure that you extract the file paths, too.

3. Open the META-INF/application.xml file that was contained in the template EAR file. It should look something like the following:

   <?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>Display Name of the Application</display-name>
       <description>Description of the application</description>
       <module>
           <web>
               <web-uri>yourwarfile.war</web-uri>
               <context-root>/</context-root>
           </web>
       </module>
   </application>
   
   

   Table C-1 describes the elements of application.xml.

   Table C-1 Elements of application.xml

   Element	Description
   <display-name>	Is the name of the application.
   <description>	Is a description of the application and its functions.
   <web-uri>	Is the name of your WAR file.
   <context-root>	Is the prefix you would like to map to your application by default (for example, /myapp).

   
   

4. Save application.xml back to the same location without changing the name of the 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 the contents of the working directory, including the subdirectory paths but not the working directory path itself.

7. Rename the resulting file to give it a meaningful name and change the extension to .ear.

C.2.2 Deploying Your EAR File

You can deploy your EAR file in any one the following ways depending upon your requirements:

• Deploying with the Grid Control Console

• Deploying Manually with dcmctl

• Deploying Manually to Standalone OC4J

C.2.2.1 Deploying with the Grid Control Console

To deploy your EAR file via the Grid Control Console, you must have PDK-Java installed in your target OC4J.

1. Start the Grid Control Console and navigate to the home page of the OC4J instance in which you configured PDK-Java (for example, OC4J_Portal).

2. On the Applications tab, click Deploy EAR file.

3. Enter the information in Table C-2.

   Table C-2 Application Tab Settings

   Setting	Value
   J2EE Application	Browse to the location of your EAR file in your local file system
   Application Name	Enter the unique name you want to associate with your provider application.
   Parent Application	Use default.

   
   

4. Click Continue. The URL mapping for Web Modules displays. The mappings will default to the context roots specified in application.xml (for example, /myapp), but you can change them to avoid clashing with the context roots of other deployed applications.

5. Click Finish. A summary appears with all of the information you entered.

6. Click Deploy.

7. Click OK.

   Your provider application is now deployed to your Oracle Application Server instance. You should see the newly deployed application in the list of applications for the selected OC4J instance. Once you have successfully deployed your EAR file, you need to test the deployment. Refer to Section C.2.3, "Testing Deployment".

C.2.2.2 Deploying Manually with dcmctl

To deploy your EAR file via dcmctl, you must have PDK-Java installed in your target OC4J.

Note: Before using dcmctl to manage an Oracle Application Server instance, make sure you have no Grid Control Console processes managing that same instance. If multiple processes manage the same instance, you run the risk of inconsistencies or corruption in the data used to manage the instance.

You deploy your EAR file using the command-line deployment utility dcmctl: (Arguments in brackets are optional.)

cd MID_TIER_ORACLE_HOME/dcm/bin/
./dcmctl deployApplication -f file -a app_name 
   [-co comp_name] [-enableIIOP] [-rc rootcontext] [-pa parent_name]

where:

file is the name of the EAR or WAR file you want to deploy.

app_name is the name of the application specified by the user in the original deployment.

comp_name is the name of the OC4J instance to which the application will be deployed. The default is the home instance. (Optional)

enable IIOP enables the Internet Inter-Orb Protocol. (Optional)

rootcontext is the base path used in the URL to access the Web module (for example, http://hostname:port/context root). This option applies only to the deployment of WAR files. (Optional)

parent_name is the parent application name. The parent application contains common classes used by child applications. (Optional)

Your provider application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you need to test the deployment. Refer to Section C.2.3, "Testing Deployment".

C.2.2.3 Deploying Manually to Standalone OC4J

To deploy your EAR file to a standalone instance of OC4J, it must be a compatible version and have PDK-Java installed.

1. If OC4J is not already running, start it as a background process with the following commands:

   On Microsoft Windows:

   cd OC4j_HOME\j2ee\home
   start java -server -Xmx256m -jar oc4j.jar
   
   

   On UNIX/Linux (Bourne shell):

   cd OC4J_HOME/j2ee/home
   java -server -Xmx256m -jar oc4j.jar &
   
   

   where:

   OC4J_HOME is your OC4J installation root directory (for example, D:\oc4j904).

   
   

   Note: The -Xmx256m option specifies a maximum heap size of 256 Mb for the OC4J process, which is the recommended setting. 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 given to the application for administrative purposes.

   ear_file_path is the full path to your EAR file on the file system.

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 Web site 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 (for example, jpdk).

   context_root is the URI path prefix you would like to be mapped to that Web application (for example, /myapp).

   Your provider application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you need to test the deployment. Refer to Section C.2.3, "Testing Deployment".

C.2.3 Testing Deployment

To test your provider deployment, you access the provider test page with a URL of the following form:

http://host:portcontext_root/providers

where:

host and port are the host name and port number of the HTTP listener for your target OC4J instance. In an Oracle Application Server installation with OracleAS Web Cache installed, port should be the OracleAS Web Cache listener port (for example, 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 (for example, /myapp) or the default one specified in application.xml in the case of a manual deployment with dcmctl.

For example:

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

If your .properties file specifies showTestPage=true, you should see the familiar test page for your default provider. To view the test page for a specific provider service, you can append the service name to the URL. For example:

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

C.2.4 Setting Deployment Properties

In PDK-Java, you can specify a number of deployment properties via JNDI variables. Table C-3 provides a list of these variables with descriptions.

Table C-3 JNDI Variables for Provider Deployment

Variable	Description
oracle/portal/log/logLevel	Is the logging level used by PDK-Java and applies to all providers.
oracle/portal/service_name/showTestPage	Is a Boolean flag that specifies whether a provider's test page is accessible. The default value is true.
oracle/portal/service_name/maxTimeDifference	Is the provider's HMAC time difference.
oracle/portal/service_name/definition	Is the location of the provider's definition file, provider.xml.
oracle/portal/service_name/autoReload	Is a Boolean auto reload flag. The default value is true.
oracle/portal/service_name/sharedKey	Is the HMAC shared key. It has no default value.
oracle/portal/service_name/rootDirectory	Is the location for provider customizations. It has no default value.

C.2.4.1 Setting the Variables

You can set the values of the variables in Table C-3 as you would any other JNDI variables. Refer to Section 7.1.4.2, "Setting JNDI Variable Values" for information on how to set JNDI variables.

C.2.5 Securing Your Provider

When using the PDK-Java framework in a production environment, you should secure your providers. For more information on securing providers, refer to Section 7.1.6, "Implementing Portlet Security" and the Oracle Application Server Portal Configuration Guide.

C.2.6 Registering Your Provider

Once you have successfully deployed and verified your provider, you can register it as you would any other provider. Refer to Section 6.3.2.5, "Registering and Viewing Your Portlet" for more information about registering your provider.