D 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 WebLogic Server or another J2EE application server. It then explains how to deploy the resulting EAR file in an Oracle WebLogic Server environment and subsequently register it with one or more Oracle Portal instances.

Note:

In general, we recommend that you package and deploy your providers using 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.

D.1 Introduction

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

D.1.1 WAR and EAR files

WAR and EAR files are used to deploy applications on a J2EE application server, such as Oracle WebLogic 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 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 Oracle 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.

D.2 Packaging and Deploying Your Providers

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

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

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

  7. Copy the _default.properties file to service_name.properties and edit it to reflect your provider'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 provider definition file in the subdirectory you just created.

  10. 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 D.2.1.2, "Specifying Your Default Service" for more information on this step.

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

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

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 Using Fusion Middleware Control

You can deploy your EAR file to your WebLogic Managed Server (WLS_PORTAL) using Fusion Middleware Control. To deploy the EAR file:

  1. Start the Oracle Fusion Middleware Control and navigate to the home page of the Portal instance in which you configured PDK-Java (for example, WLS_PORTAL).

  2. From the WebLogic Server menu, choose Application Deployment, and then Deploy.

    The Select Archive page is displayed.

  3. In the Archive or Exploded Directory section, you can select one of the following:

    • Archive is on the machine where this browser is running. Then, enter the location of the archive or click Browse to find the archive file.

    • Archive or exploded directory is on the server where Enterprise Manager is running. Then, enter the location of the archive or click Browse to find the archive file.

  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. In the Deployment Plan section, you can select one of the following:

    • Automatically create a new deployment plan.

    • Deployment plan is on the machine where this web browser is running. If you select this option, enter the path to the plan.

    • Deployment plan is on the server where Enterprise Manager is running. I If you select this option, enter the path to the plan.

  6. Click Next.

    The Select Target page is displayed.

  7. Select the target to which you want to deploy the application. The Administration Server, Managed Servers, and clusters are listed. You can select a cluster, one or more Managed Server in the cluster, or a Managed Server that is not in a cluster. Although the Administration Server is shown in the list of targets, you should not deploy an application to it. The Administration Server is intended only for administrative applications such as the Oracle WebLogic Server Administration Console.

  8. Click Next.

    The Application Attributes page is displayed.

  9. In the Application Attributes section, for Application Name, enter the application name.

  10. In the Context Root of Web Modules section, if the web module does not have the context root configured in the application.xml file, you can specify the context root for your application. The context root is the URI for the web module. Each web module or EJB module that contains web services may have a context root.

  11. If the application's adf-config.xml file archive contains MDS configuration, the Target Metadata Repository section is displayed. It allows you to choose the repository and partition for this application:

    • To change the repository, click the icon next to the Repository Name. In the Metadata Repositories dialog box, select the repository and click OK.

    • To change the partition, enter the partition name in Partition Name.

  12. In the Distribution section, you can select one of the following:

    • Distribute and start application (servicing all requests)

    • Distribute and start application in admin mode (servicing only admin requests)

    • Distribute only

  13. Click Next.

    The Deployment Wizard, Deployment Settings page is displayed.

  14. On this page, you can perform common tasks before deploying your application or you can edit the deployment plan or save it to a disk. You can:

    • Configure Web modules

    • Configure application security

  15. Expand Deployment Plan.

    You can edit and save the deployment plan, if you choose.

  16. Click Deploy.

    Application Server Control displays processing messages.

  17. When the deployment is completed, click Close.

D.2.3 Testing Deployment

To test your provider deployment, you access the provider 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 Oracle WebLogic Server instance. In an Oracle Application Server installation with Oracle Web Cache installed, port should be the Oracle Web Cache listener port (for example, 8090). In the Oracle WebLogic Server 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:8090/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:8090/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-2 provides a list of these variables with descriptions.

Table D-2 JNDI Variables for Provider Deployment

Variable Description
oracle/portal/provider/global/log/logLevel

Is the logging level (0-8) 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.


Setting the Variables

You can set the values of the variables in Table D-2 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.

D.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.2.7, "Implementing Portlet Security" and the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

D.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.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet" for more information about registering your provider.