C Manually Packaging and Deploying PDK-Java Providers

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

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.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.2.4.2, "Setting JNDI Variable Values" for information on how to set JNDI variables.