D Manually Packaging and Deploying PDK Portlet Producers

This appendix explains how to manually package your portlet producer 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. The sections in this appendix are as follows:

Note:

In general, Oracle recommends that you package and deploy your producers using the tools available in Oracle JDeveloper. However, if you find that you must package and deploy your producers manually for some reason, then refer to the tasks in this appendix.

• Introduction

• Packaging and Deploying Your Producers

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.

D.1 Introduction

Before preceding with packaging and deploying your producer, you must understand the following basic concepts:

• WAR and EAR files

• Service Identifiers

D.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.

D.1.2 Service Identifiers

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

For example, you can register the PDK-Java samples producer 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 producer name (sample) is appended to the URL of the PDK-Java samples producer. In this case, you should leave the Service Id field blank when registering the producer.

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

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

Note:

If you do not know the service identifier, then check the producer test page or contact the administrator of the producer. If you are using the Federated Portal Adapter, then the URL points to the adapter, not the producer, 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.

D.2 Packaging and Deploying Your Producers

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

• Packaging Your Producer

• Deploying Your EAR File

• Testing Deployment

• Setting Deployment Properties

• Securing Your Producer

• Registering Your Producer

D.2.1 Packaging Your Producer

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, then 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

D.2.1.1 Preparing Your Directories

In preparation for creating your WAR file, you must 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 producer needs any additional JAR files, then add them to the WEB-INF/lib directory.

4. If your producer needs any additional Java classes not contained in a JAR file, then 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 producer under the producers directory.

7. Copy the _default.properties file to service_name.properties and edit it to reflect your producer's configuration.

8. Set the definition value in the provider_name.properties file that is available in the WEB-INF/deployment folder, as follows:

   definition=providers/provider_dir_you_created/provider.xml
   

9. Place your producer definition file in the subdirectory you just created.

10. Edit _default.properties to reflect the configuration settings of your default producer. The default producer is accessed if a service identifier is not specified in a request. See Section D.2.1.2, "Specifying Your Default Service" for more information about this step.

11. If you use servlets to render content, then edit WEB-INF/web.xml to add your servlets to the list of predefined servlets. Be careful not to remove the entries for servlets required by PDK-Java.

D.2.1.2 Specifying Your Default Service

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

Edit the definition entry to point to the producer definition file that represents your default producer. 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

D.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, perform the following steps:

1. Zip the contents of the working directory you created in Section D.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.

D.2.1.4 Creating Your EAR File

To create the EAR file manually, perform the following steps:

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 D-1 describes the elements of application.xml.

   Table D-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.

D.2.2 Deploying Your EAR File

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

• Deploying with the Grid Control Console

• Deploying Manually with dcmctl

• Deploying Manually to Standalone OC4J

D.2.2.1 Deploying with the Grid Control Console

To deploy your EAR file using the Grid Control Console, you must have PDK-Java installed in your target OC4J. To deploy your EAR file using this method, perform the following steps:

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 D-2.

   Table D-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 producer application.
   Parent Application	Use default.

   
   

4. Click Continue. The URL mapping for Web Modules appears. 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 producer 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 must test the deployment. See Section D.2.3, "Testing Deployment".

D.2.2.2 Deploying Manually with dcmctl

To deploy your EAR file using 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, then 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 producer application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you must test the deployment. See Section D.2.3, "Testing Deployment".

D.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. To deploy your EAR file in this method, perform the following steps:

1. If OC4J is not already running, then 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 can raise or lower this setting to suit your application. If you encounter java.lang.OutOfMemoryError exceptions, then 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/default-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 producer application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you must test the deployment. See Section D.2.3, "Testing Deployment".

D.2.3 Testing Deployment

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

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 Oracle Application Server installation with Oracle Web Cache installed, port should be the Oracle 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 producer Web application on deployment (for example, /myapp) or the default one specified in application.xml in a manual deployment with dcmctl.

For example:

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

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

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

D.2.4 Setting Deployment Properties

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

Table D-3 JNDI Variables for Producer Deployment

Variable	Description
oracle/portal/provider/global/log/logLevel	Is the logging level (0-8) used by PDK-Java and applies to all producers.
oracle/portal/service_name/showTestPage	Is a Boolean flag that specifies whether a producer's test page is accessible. The default value is true.
oracle/portal/service_name/maxTimeDifference	Is the producer's HMAC time difference.
oracle/portal/service_name/definition	Is the location of the producer'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 producer customizations. It has no default value.

Setting the Variables

You can set the values of the variables in Table D-3 as you would any other JNDI variables. See Section 19.2.3.2, "Setting JNDI Variable Values" for information about how to set JNDI variables.

D.2.5 Securing Your Producer

When using the PDK-Java framework in a production environment, you should secure your producers. See Chapter 10, "Securing Your WebCenter Application" for more information about securing producers.

D.2.6 Registering Your Producer

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