Oracle9iAS Portal Developer Kit (PDK)
Installing the PDK-Java Framework and Sample Providers

Contents

Introduction
Contents of PDK.zip
Contents of the jpdk Directory
Contents of the libcommon Directory
Deploying the PDK-Java Sample Providers
Deploying Using Oracle Enterprise Manager (OEM)
Manually Deploying to an Oracle9iAS Instance Using dcmctl
Manually Deploying to a Stand-Alone OC4J Instance
Testing the Deployment
Setting Deployment Properties
Registering the Sample Providers
Deploying Your Own Providers

Introduction

Welcome to the PDK-Java. The PDK-Java Framework includes the tools and documentation to build Web portlets. This download includes the PDK-Java Framework and Web Provider Samples to help you get started. You can use the PDK-Java framework to develop your own web providers and portlets. Please refer to the PDK documentation on Web Providers for more information.

This document is an installation and configuration guide for the PDK-Java Framework and samples. It explains how to

• setup and configure Oracle9iAS Application Server or a standalone OC4J (Oracle Containers for J2EE) instance to run the PDK-Java Framework.
• install and register the sample providers included in this download.
• setup and configure the Oracle HTTP Server to run your own web providers.

Contents of pdk.zip 

The PDK-Java and sample providers are part of the Portal Developers Kit (PDK). To begin the installation process you first need to unzip the file called pdk.zip into a directory located on the same machine as your Oracle9iAS Application Server or OC4J instance. (The remainder of the instructions contained in this document will refer to this directory to as $unzip_directory.) Unzipping pdk.zip in the $unzip_directory creates the following directory structure: 

• pdk

  • jpdk (see Contents of the "jpdk" Directory for more information)
• portalTools
• libcommon (see Contents of "libcommon" Directory for more information)
• articles
• plsql
• urlservices
• index.html
• pdk.release.notes.html
• PDKHome.html
  
• pdkpages

• index.html

Contents of the "jpdk" Directory

The jpdk directory is created under $unzip_directory/pdk and contains all the files required by the PDK-Java sample providers. The following files are included in this directory:

• installing.pdkjava.v2.html: Instructions for installing the PDK-Java sample providers (i.e., the document you are currently reading).
• upgrading.to.pdkjava.v2.html: Instructions for migrating existing web providers from PDK-Java v1 to PDK-Java v2.
• deploying.pdkjava.v2.providers.html: Instructions for packaging and deploying your own PDK-Java v2 web providers.
• pdkjava.v2.release.notes.html: Release notes describing changes since the last release and known issues with
• jpdk.ear: The enterprise archive (EAR) file for the PDK-Java Sample Providers
• template.ear: A sample EAR file you can use when packaging your own web providers. See Packaging and Deploying Your Provider for more information
• doc directory: Contains provider specific installation instructions. Many of the providers require additional configuration before they can be registered with a portal. There is a subdirectory for each provider requiring additional configuration. The subdirectories contain the provider specific configuration instructions and, in some cases, scripts or templates you will need to complete the configuration.
• src.zip: a zip file containing the public classes and interfaces you may need during the development process - either for debugging your own provider or understanding more about the PDK-Java framework when creating your own implementations of abstract classes or extending the default implementations.

Contents of the "libcommon" directory

The libcommon directory is created under  $unzip_directory/pdk and contains libraries shared by different components contained in in pdk.zip. The following files (with path information) are included in this directory:

• JPDK (Component Version 9.0.2.6.1 or later)
  • portal/jlib/pdkjava.jar
• portal/jlib/ptlshare.jar
• WebCache (Component Version 9.0.2 or later)
• webcache/jlib/jawc.jar
• Oracle Internet Directory (OID) (Component version 9.0.2 or later)
  • jlib/ldapjclnt9.jar

Deploying the PDK-Java Sample Providers

The steps for deploying the PDK-Java Sample Providers differ depending on where you want to deploy the PDK-Java Samples.

• If you are deploying into an Oracle9iAS instance with OEM or a standalone OC4J instance and you have installed OEM separately to manage to your stand-alone OC4J server, follow the steps in the section, Deploying Using Oracle Enterprise Manager. This is the recommended way to deploy web applications.
• If you are deploying into an Oracle9iAS instance and you do not have OEM installed or you want to do the configuration manually, follow the steps under Manually Deploying to an Oracle9iAS Instance Using dcmctl.
• If you are installing on a stand-alone OC4J instance and you don't have Oracle Enterprise Manager (OEM) installed and configured, follow the steps in the section, Manually Deploying to a Stand-Alone OC4J Instance. 

If you are installing into an Oracle9iAS instance there may be more than one OC4J instance configured. You must choose the OC4J instance you want to use for this application.

If you have Oracle9iAS with Portal installed, the PDK-Java Sample Providers are already installed in the "OC4J_Portal" instance. You can update these providers by deploying the new jpdk.ear on top of the existing one.

If Oracle Portal is not installed, you should use the "OC4J_HOME" instance. You should also use this instance (or another instance you have created) when deploying your own web providers.

Deploying Using Oracle Enterprise Manager (OEM)

This section assumes:

• you have Oracle9iAS installed with OEM or
• you have a stand-alone OC4J instance with OEM installed and configured to manage that instance.

If you do not have one of these configurations, either install and configure them according to their respective installation instructions or follow the appropriate manual deployment instructions for Oracle9iAS or standalone OC4J.

1. create the following directories (if they do not already exist)

   $OC4J_HOME/portal/jlib
   $OC4J_HOME/webcache/jlib

   Notes:
   This step should only be required if you are using a standalone OC4J instance. $OC4J_HOME is the root directory of your OC4J installation. You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory.

2. Copy the latest PDK-Java jar files to your Oracle9iAS or OC4J home. The jar files are included in $unzip_directory/pdk/libcommon/portal/jlib. The other jar files included in the libcommon directory are included for installation in a standalone OC4J instance. Oracle9iAS installations already include all the jar files needed by the PDK-Java
   
   copy $unzip_directory/pdk/libcommon/portal/jlib/* to $IAS_HOME/portal/jlib/
   
   Notes
   $unzip_directory denotes the directory where you have unzipped the pdk.zip. The libraries and the components to which they belong are described above.
   
3. Copy the required support files to your OC4J home. Skip this step if you are using an Oracle9iAS instance.
   
   copy $unzip_directory/pdk/libcommon/webcache/jlib/* to $IAS_HOME/webcache/jlib/
   copy $unzip_directory/pdk/libcommon/jlib/* to $IAS_HOME/jlib/
   
4. Go to your OEM interface and login. You can usually access OEM at http://{server}:1810/
5. Click on the Oracle9iAS mid-tier where you want to deploy the PDK-Java Sample Providers application. You will see a list of all your system components in your mid-tier.
6. Click on the OC4J instance where you want to deploy the PDK-Java Sample Providers. If you are deploying on the Oracle9iAS mid-tier that is being used for Oracle Portal, there will normally be an OC4J instance named "OC4J_Portal". You should normally deploy the PDK-Java Sample Providers in this instance, but that is not required
7. Click Deploy EAR file.
8. Click Next.
9. Enter the following Information:
   • J2EE Application: $unzip_directory/pdk/jpdk/v2/jpdk.ear (this is the full path to the jpdk.ear file)
   • Application Name: enter the name you want to associate with the PDK-Java sample providers. Typically this is "jpdk"
10. Click Next. The URL mapping for Web Modules displays. The mapping will default to /jpdk but you can change it if you want to. The rest of this document is written assuming you used the default of /jpdk
11. Click Finish. The Last step contains a summary of all information you entered.
12. Click Deploy. The PDK-Java Sample Providers will be deployed into your Oracle9iAS instance. You should see the newly deployed application in the list of applications for the OC4J instance you selected.
13. Click on your newly deployed application to view a page displaying properties of the application.
14. Click General under the Administration : Properties section.
15. In the Library Paths section, you can add a library. To add a library path, click Add Another Row. Add the following jar files :

../../../../portal/jlib/pdkjava.jar
../../../../portal/jlib/ptlshare.jar
../../../../webcache/jlib/jawc.jar
../../jazn.jar
../jlib/ldapjclnt9.jar

1. Click Apply.

The PDK-Java v2 Sample Providers are now deployed. Please proceed to Testing the Deployment

Manually Deploying to an Oracle9iAS Instance Using dcmctl

This section assumes that you already have Oracle9iAS installed but you do not have OEM installed (or you wish to deploy the provider manually without using OEM). Before deploying the PDK-Java Sample Providers you must decide which OC4J instance in your Oracle9iAS installation you want to use. This instance will be referred to as <OC4J_instance> from here on).

If you do not have an Oracle9iAS installation, either install and configure Oracle9iAS according to the installation instructions or choose one of the OC4J standalone deployment methods.

Warning: Before using dcmctl to manage an Oracle9iAS 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.

To deploy the application manually:

1. Copy all the latest PDK-Java jar files to your Oracle9iAS home. The jar files are included in $unzip_directory/pdk/libcommon/portal/jlib. The other jar files included in the libcommon directory are included for installation in a standalone OC4J instance. Oracle9iAS installations already include all the jar files needed by the PDK-Java
   
   copy $unzip_directory/pdk/libcommon/portal/jlib/* to $IAS_HOME/portal/jlib/
   
   Notes
   $unzip_directory denotes the directory where you have unzipped the pdk.zip. The libraries and the components to which they belong are described above.

2. Deploy jpdk.ear using the command-line deployment utility dcmctl

   $IAS_HOME/dcm/bin/dcmctl deployApplication -v -f {earFilePath} -a {applicationName} -co {OC4JInstanceName}

   where:
• {earFilePath} is the location of the EAR file to be deployed
• {applicationName} is the name that should be given to the application for administrative purposes
• {OC4JInstanceName} is the name of the OC4J instance the application should be deployed into.

eg dcmctl deployApplication -v -f $unzip_directory/jpdk/v2/jpdk.ear -a jpdk -co OC4J_Portal

You can also use dcmctl to redeploy or undeploy an application or perform a variety of other Oracle9iAS administrative tasks.

4. Stop the Oracle9iAS instance by executing the following command:

   $IAS_HOME/opmn/bin/opmnctl stopall

5. Add the following dependent library references to the orion-application.xml file. This file is found at the following location:

   $IAS_HOME/<OC4J_instance>/application-deployments/jpdk/orion-application.xml

Dependent library references:

<library path="../../../../portal/jlib/pdkjava.jar"/>
<library path="../../../../portal/jlib/ptlshare.jar"/>
<library path="../../../../webcache/jlib/jawc.jar"/>
<library path="../../jazn.jar"/>
<library path="../jlib/ldapjclnt9.jar"/>

6. Start up the Oracle9iAS instance again by executing the following command:

   $IAS_HOME/opmn/bin/opmnctl startall

The PDK-Java v2 Sample Providers are now deployed. Please proceed to Testing the Deployment

Manually Deploying to a Stand-Alone OC4J Instance

This section assumes that you already have a stand-alone OC4J server installed and configured. If you do not have an OC4J installation, please install and configure it according to its installation instructions. 

To deploy the application manually:

1. create the following directories (if they do not already exist)

   $OC4J_HOME/portal/jlib
   $OC4J_HOME/webcache/jlib

   Notes:
   $OC4J_HOME is the root directory of your OC4J installation. You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory.

2. Copy all the latest PDK-Java jar files to your Oracle9iAS home. The jar files are included in $unzip_directory/pdk/libcommon/.

   copy $unzip_directory/pdk/libcommon/portal/jlib/* to $OC4J_HOME/portal/jlib/
   copy $unzip_directory/pdk/libcommon/webcache/jlib/* to $OC4J_HOME/webcache/jlib/
   copy $unzip_directory/pdk/libcommon/jlib/* to $OC4J_HOME/jlib/
   
   Notes:
   $unzip_directory denotes the directory where you have unzipped the pdk.zip. The libraries and the components to which they belong are described above.

3. Copy $unzip_directory/jpdk/v2/jpdk.ear into your OC4J applications subdirectory. Usually, this directory is $OC4J_HOME/j2ee/home/applications

4. Add the following to $OC4J_HOME/j2ee/home/config/server.xml: (You should put it after the following line in your file <default-web-app application="default" name="defaultWebApp" root="/j2ee"/>)
   
   <application name="jpdk" path="../applications/jpdk.ear" auto_start="true"/>

5. Add the following to your OC4J web site configuration file. Check the entry "<web-site path=......>" in $OC4J_HOME/j2ee/home/config/server.xml. This specifies the name and location of the web site configuration file. For example, if it is pointing to "http-web-site.xml" file, you need to add the following entries in your $OC4J_HOME/j2ee/home/config/http-web-site.xml file:
   

   <web-app application="jpdk" name="jpdk" root="/jpdk" />

4. Start OC4J and then stop your OC4J instance using the following commands. This will deploy the application

   java -jar admin.jar ormi://<host>:<port>/ admin <admin_password> -shutdown 
   java -jar admin.jar ormi://<host>:<port>/ admin <admin_password> -startup

5. Add the following dependent library references to the orion-application.xml file. This file is found at the following location:

   $OC4J_HOME/j2ee/<OC4J_instance>/application-deployments/jpdk/orion-application.xml

Dependent library references:

<library path="../../../../portal/jlib/pdkjava.jar"/>
<library path="../../../../portal/jlib/ptlshare.jar"/>
<library path="../../../../webcache/jlib/jawc.jar"/>
<library path="../../jazn.jar"/>
<library path="../lib/ldapjclnt9.jar"/>

6. Start up the OC4J instance again by executing the following command:

   java -jar admin.jar ormi://<host>:<port>/ admin <admin_password> -startup

The PDK-Java v2 Sample Providers are now deployed. Please proceed to Testing the Deployment

Testing the Deployment

The PDK-Java v2 Sample Providers application is now deployed. To test the application, access the "sample" provider's test page at the following URL:

http://{server}:{port}/jpdk/providers/sample

This page lists the portlets that are included with the provider that has a service name of "sample". The test pages of other providers can be accessed using a similar URL. Simply replace "sample" with the service name of the provider.

The service names of the other providers included with the PDK-Java v2 Sample Providers application are:

• sample - demonstrates many of the basic capabilities of the PDK-Java v2
  • portlet pages implemented as static HTML files
  • portlet pages implemented as JSPs
  • portlet pages implemented as Servlets
  • portlet pages implemented as Java classes
  • all portlet render modes
  • stateful or session-based portlets
  • portlets containing images
  • expires based caching
  • validation based caching
  • portlet personalization
  • parameters and events
  • private event submission
  • mobile enabled portlets
• dbPreferenceStore - demonstrates how to use a database-based Preference Store for storing personalization data
• event - demonstrates how to build portlets using parameters and events
• externalApp - demonstrates how to build a web provider associated with an External Application
• feedback - demonstrates how to build a portlet that submits data to itself without that data being "seen" by other portlets
• partnerApp - demonstrates how to build a web provider associated with a Partner Application
• prefStore - includes portlets demonstrating the use of the Preference Store API for storing generic data (not just personalization data). Requires configuration of a datasource and database table
• subscriber - demonstrates how to build a web provider that allows portals to subscribe to its services
• webcache - demonstrates invalidation based caching and the ESI portlets (requires Oracle9iAS)
• webservices - demonstrates how to build portlets that utilize the Web Services renderers

The service names of the URL Services sample providers are:

• urlsample - demonstrates the basic capabilities of URL Services
• urlparams - demonstrates how to build a parameter driven URL Services provider
• urlnls - demonstrates how to build a URL Services provider that performs character set conversion to correctly display multibyte characters (Chinese, Japanese, Korean, Arabic etc)
• urlbasicauth - demonstrates how to build a URL Services provider that display data from a source that is secured using Basic Auth
• urlexternalauth - demonstrates how to build a URL Services provider that displays data from a password protected External Application

The majority of the providers require additional configuration of some kind. For each of these providers there is an installation document detailing the additional configuration steps and instructions for using the provider. The installation documents can be found in $unzip_directory/pdk/jpdk/v2/doc/{service name}

Setting Deployment Properties

In the PDK-Java there are a number of deployment properties that area 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

Provider Specific Deployment Properties.

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

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

Through OEM

1. In OEM click on the instance where you have deployed the PDK-Java.
2. Click on the name representing this deployment.
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 IAS install:

$IAS_HOME\j2ee\{OC4J instance}\application-deployments\jpdk\jpdk

For a standalone OC4J install:

$OC4J_HOME\j2ee\home\application-deployments\jpdk\jpdk

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

Registering the Sample Providers

After deploying the PDK-Java Sample Providers, you must register the provider with Oracle9iAS Portal before adding the sample portlet(s) to a page.

1. Login to Oracle Portal using an account that has build privileges. If your home page is not the "build/administer" page, click on the Builder link in the top right corner of the screen. Click on the Build tab if that is not the active tab.
2. Under the Build tab (on Oracle Portal Home Page), click on Register Portlet Provider within the portlet called Providers.
3. Fill out provider information for the sample.
   • Name: SampleWebProvider
   • Display Name: Sample Web Provider
   • Timeout: 100
   • Timeout Message: Application Timed Out
   • Implementation Style: Web
4. Click on the next button to enter the Web Provider specific information
5. Enter the Web Provider location and Service Name
• URL: http://{host}:{port}/jpdk/providers/
• Service Name: urn:sample
6. Scroll down to the User/Session Information section and specify the login frequency
   • Login Frequency: Once Per User Session
7. Click on the Finish button to complete the registration

Note: When registering a new provider with Oracle Portal, only the user who registered the provider has privileges to see the provider/portlets. If necessary, go to the Folder with the name of the provider within the Portlet Repository content area and update the provider privileges as required.

Adding Sample Portlets to a Page

1. Display the contents of the Portlet Repository and review the sample portlets.

2. Add any of the sample portlets listed under the Provider called "SampleWebProvider" to a Portal page.

   Please refer to Oracle9iAS Portal online documentation for more information on adding portlets to a page.

You have now successfully installed and setup the Web Provider Samples.

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

Deploying Your Own Web Providers

Review the article Packaging and Deploying Your Provider for detailed instructions on how to package and deploy your own providers

For detailed information regarding creating new providers, review the article How to Build a Java Portlet.

 

Revision History:

Revision No Last Update Comments 1.0 October 29, 2002 Created 1.1 June 14, 2003 Added ldapjclnt9.jar for OID support