# Oracle Application Server Portal Developer Kit (PDK)
Installing the PDK-Java Framework and Sample Providers

Creation Date: | November 5, 2003
Status: | Production
Version: | PDK Release 9.0.4

### Contents

> Introduction
> Contents of pdk.zip
> Contents of the jpdk/v2 Directory
> Installing or Upgrading to This Version of PDK-Java
> Installing Using OracleAS Enterprise Manager (OEM)
> Manually Installing to an OracleAS Instance Using dcmctl
> Manually Installing to a Stand-Alone OC4J Instance
> Testing the Deployment
> Registering the Sample Providers
> Migrating PDK-Java Applications
> 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 OracleAS 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 OracleAS 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 Oracle 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/v2 (see Contents of the "jpdk/v2" Directory for more information)

- portalTools
- libcommon
- articles
- plsql
- urlservices
- index.html
- pdk.release.notes.html
- PDKHome.html

- index.html

## Contents of the "jpdk/v2" Directory

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

- installing.pdkjava.v2.html: Instructions for installing the PDK-Java (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 source code for 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.

## Installing or Upgrading to This Version of PDK-Java

Before proceeding, note the minimum supported application server versions stated in the release notes. If you want to upgrade PDK-Java applications currently deployed on older application server versions, you will need to install PDK-Java on one of the supported application server versions first, and then proceed to migrate the applications from the older application server. See the document Migrating Applications to PDK-Java Release 9.0.4 and later for details on how to do this.

The steps for installing or upgrading PDK-Java on a supported application server differ depending on what kind of OracleAS installation you are installing to.

- If you are installing into an OracleAS 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, Installing Using OracleAS Enterprise Manager. This is the recommended way to deploy web applications.
- If you are installing into an OracleAS instance and you do not have OEM installed or you want to do the configuration manually, follow the steps under Manually Installing to an OracleAS Instance Using dcmctl.
- If you are installing on a stand-alone OC4J instance and you don't have OracleAS Enterprise Manager (OEM) installed and configured, follow the steps in the section, Manually Installing to a Stand-Alone OC4J Instance.

Note: If your portlets previously relied on default customization data being stored per portal session locale, you may need to specify an alternative locale personalization setting. If you appear to loose default customizations, this is the likely cause. In this case, set the locale personalization level to locale. For more information on the locale personalization level, see the release notes.

## Installing Using OracleAS Enterprise Manager (OEM)

#### This section assumes:

- you have OracleAS 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 installation instructions for OracleAS or Standalone OC4J.

### Installing or Upgrading the PDK-Java Framework

1. Within your OracleAS home directory, create the following directory if it doesn't exist, or make a backup copy of the directory if it already exists

- $IAS_HOME/portal/jlib

2. Copy all the latest PDK-Java jar files to your OracleAS 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. OracleAS 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.
3. Go to your OEM interface and log in. You can usually access OEM at http://{server}:1810/
4. Click on the OracleAS mid-tier where you want to install the PDK-Java. You will see a list of all your system components in your mid-tier.
5. Click on the OC4J instance where you want to install the PDK-Java. If you are installing on the OracleAS mid-tier that is being used for OracleAS Portal, there will normally be an OC4J instance named "OC4J_Portal". You should normally install the PDK-Java in this instance, but that is not required
6. To configure PDK-Java in this OC4J instance, first select the Applications tab and select the default application, next to the "Default Application Name" prompt. This is the global J2EE application whose properties are inherited by all other applications deployed on this OC4J instance.
7. Click General under the Administration : Properties section.
8. In the Library Paths section, make sure each of the following jar files are included (you may see absolute paths rather than relative ones), and if necessary add any missing ones by clicking Add Another Row.

> ../../../portal/jlib/pdkjava.jar
> ../../../portal/jlib/portaltools.jar
> ../../../portal/jlib/ptlshare.jar
> ../../../portal/jlib/tidy.jar
> ../../../jlib/ldapjclnt9.jar
> ../../../jlib/netcfg.jar
> ../../../jlib/regexp.jar
> ../../../jlib/share.jar
> ../../../jlib/uix2.jar
> ../../../webcache/jlib/jawc.jar
> ../../home/jazn.jar

9. Click Apply and then OK on the confirmation screen. PDK-Java is now installed and available to all J2EE applications deployed in this OC4J instance.

### Installing the Sample Providers

Note: if the PDK-Java sample application (typically called "jpdk") is already installed in your target OC4J instance or you are not interested in running any of the sample portlets, you may skip this section. If you want to replace an existing PDK-Java enterprise application in your target OC4J instance, you should proceed with extreme caution, as there may be important meta data and user customization data stored under the $IAS_HOME/j2ee/<OC4J_Instance>/applications/jpdk/jpdk/WEB-INF directory. In particular, if the target OC4J instance is OC4J_Portal, this directory may contain meta data for user-built portlets. For this reason, it is recommended that you avoid taking this step in a production environment and you always deploy to a new J2EE application with a unique name (e.g. "jpdk1") rather than redeploying on top of an existing application. You should only undeploy an old jpdk enterprise application when you are sure that all meta data has been safely transported to the new one.

1. In OEM, navigate to the home page of the OC4J instance in which you configured PDK-Java.
2. On the Applications tab, click Deploy EAR file
3. 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 unique name you want to associate with the PDK-Java sample providers. Typically this is "jpdk", but see the above note.
   - Parent Application: default
4. Click Continue. 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
5. Click Finish. The Last step contains a summary of all information you entered.
6. Click Deploy and then OK on the confirmation screen. The PDK-Java Sample Providers are now deployed to your OracleAS instance. You should see the newly deployed application in the list of applications for the OC4J instance you selected.

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

## Manually Installing to an OracleAS Instance Using dcmctl

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

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

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

### Installing or Upgrading the PDK-Java Framework

1. Stop the OracleAS instance by executing the following command:

   $IAS_HOME/opmn/bin/opmnctl stopall

2. Within your OracleAS home directory, create the following directory if it doesn't exist, or make a backup copy of the directory if it already exists

- $IAS_HOME/portal/jlib

3. Copy all the latest PDK-Java jar files to your OracleAS 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. OracleAS 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.
4. Make sure the following dependent library references are present in the global application.xml file. This file is found at the following location:

   $IAS_HOME/j2ee/<OC4J_instance>/config/application.xml

   Dependent library references:

   <library path="../../../portal/jlib/pdkjava.jar"/>
   <library path="../../../portal/jlib/portaltools.jar"/>
   <library path="../../../portal/jlib/ptlshare.jar"/>
   <library path="../../../portal/jlib/tidy.jar"/>
   <library path="../../../jlib/ldapjclnt9.jar"/>
   <library path="../../../jlib/netcfg.jar"/>
   <library path="../../../jlib/regexp.jar"/>
   <library path="../../../jlib/share.jar"/>
   <library path="../../../jlib/uix2.jar"/>
   <library path="../../../webcache/jlib/jawc.jar"/>
   <library path="../../home/jazn.jar"/>

5. Bring the configuration repository up to date with the following command:

$IAS_HOME/dcm/bin/dcmctl updateConfig -v -co {OC4JInstanceName}

6. PDK-Java is now installed and available to all J2EE applications deployed in this OC4J instance. Start up the OracleAS instance again by executing the following command:

   $IAS_HOME/opmn/bin/opmnctl startall

### Installing the Sample Providers

Note: if the PDK-Java sample application (typically called "jpdk") is already installed in your target OC4J instance or you are not interested in running any of the sample portlets, you may skip this section. If you want to replace an existing PDK-Java enterprise application in your target OC4J instance, you should proceed with extreme caution, as there may be important meta data and user customization data stored under the $IAS_HOME/j2ee/<OC4J_Instance>/applications/jpdk/jpdk/WEB-INF directory. In particular, if the target OC4J instance is OC4J_Portal, this directory may contain meta data for user-built portlets. For this reason, it is recommended that you avoid taking this step in a production environment and you always deploy to a new J2EE application with a unique name (e.g. "jpdk1") rather than redeploying on top of an existing application. You should only undeploy an old jpdk enterprise application when you are sure that all meta data has been safely transported to the new one.

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

   $IAS_HOME/dcm/bin/dcmctl deployApplication -v -f $unzip_directory/jpdk/v2/jpdk.ear -a $application_name -co $oc4j_instance_name

   where:

- $application_name is the unique name that should be given to the application for administrative purposes. Typically this is "jpdk", but see the above note.
- $oc4j_instance_name is the name of the OC4J instance the application should be deployed into (e.g. OC4J_Portal).

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

## Manually Installing 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.

### Installing or Upgrading the PDK-Java Framework

1. Stop your OC4J instance, if it is running, using the following command:

   java -jar admin.jar ormi://localhost admin $admin_password -shutdown

2. Within your OC4J home directory, create the following directories if they don't exist, or make backup copies if they do exist:

- $OC4J_HOME/jlib
- $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.

3. Copy all the latest PDK-Java jar files to your OracleAS 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.
4. Add the following dependent library references to the global application.xml file. This file is found at the following location:

   $OC4J_HOME/j2ee/home/config/application.xml

   Dependent library references:

   <library path="../../../portal/jlib/pdkjava.jar"/>
   <library path="../../../portal/jlib/portaltools.jar"/>
   <library path="../../../portal/jlib/ptlshare.jar"/>
   <library path="../../../portal/jlib/tidy.jar"/>
   <library path="../../../jlib/ldapjclnt9.jar"/>
   <library path="../../../jlib/regexp.jar"/>
   <library path="../../../jlib/share.jar"/>
   <library path="../../../jlib/uix2.jar"/>
   <library path="../../../webcache/jlib/jawc.jar"/>
   <library path="../../home/jazn.jar"/>

5. PDK-Java is now installed and available to all J2EE applications deployed in this OC4J instance. Start up the OC4J server again as a background process with the following commands
   - In Windows Command Prompt:
     cd %OC4J_HOME%\j2ee\home
     start java -server -Xmx256m -jar oc4j.jar
   - In Unix/Linux Bourne Shell (sh):
     cd $OC4J_HOME/j2ee/home
     java -server -Xmx256m -jar oc4j.jar &
   Note: the -Xmx256m option specifies a 'maximum heap size' of 256 Megabytes for the OC4J process, which is the recommended setting. However, you may raise or lower this setting to suit your application. If you encounter java.lang.OutOfMemoryError exceptions, you should raise this setting.

### Installing the Sample Providers

Note: if the PDK-Java sample application (typically called "jpdk") is already installed in your target OC4J instance or you are not interested in running any of the sample portlets, you may skip this section. If you want to replace an existing PDK-Java enterprise application in your target OC4J instance, you should proceed with extreme caution, as there may be important meta data and user customization data stored under the $OC4J_HOME/j2ee/home/applications/jpdk/jpdk/WEB-INF directory. For this reason, it is recommended that you avoid taking this step in a production environment and you always deploy to a new J2EE application with a unique name (e.g. "jpdk1") rather than redeploying on top of an existing application. You should only undeploy an old jpdk enterprise application when you are sure that all meta data has been safely transported to the new one.

1. Ensure OC4J is running (use the command in the previous section to start it if it is not)
2. Deploy the sample enterprise application in jpdk.ear using the following commands:
   - java -jar admin.jar ormi://localhost admin $admin_password -deploy -deploymentName $application_name -file $unzip_directory/jpdk/v2/jpdk.ear
   - java -jar admin.jar ormi://localhost admin $admin_password -bindWebApp $application_name jpdk file:$OC4J_HOME/j2ee/home/config/http-web-site.xml /jpdk
   - java -jar admin.jar ormi://localhost admin $admin_password -bindWebApp $application_name pdkstruts file:$OC4J_HOME/j2ee/home/config/http-web-site.xml /pdkstruts

> where:

> - $admin_password is the OC4J administration password you set on installation
> - $application_name is the unique name that should be given to the application for administrative purposes. Typically this is "jpdk", but see the above note.

The PDK-Java v2 and 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:

Access the provider test page using the following URL:

> http://$host:$port/jpdk/providers/sample

where:

- $host and $port are the host name and port number of the HTTP listener for your target OC4J instance. In an OracleAS installation with webcache installed, $port should be the Web Cache listener port (e.g. 7777). In a standalone OC4J installation, the default HTTP port number is 8888.

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 OracleAS)
- 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}

## Registering the Sample Providers

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

1. Login to OracleAS 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 OracleAS 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 OracleAS 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 OracleAS Portal online documentation for more information on adding portlets to a page.

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

## Migrating PDK-Java Applications

To migrate PDK-Java applications from OracleAS releases prior to 9.0.4, please follow the instructions detailed in the document Migrating Applications to PDK-Java Release 9.0.4 and later

## 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
1.0 | October 29, 2002
1.1 | November 5, 2003

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info