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

Creation Date: December 7, 2004
Status: Production
Version: PDK Release 9.0.4.1.0

Contents

Introduction
Contents of pdk.zip
Contents of the jpdk/v2 Directory
Installing or Upgrading to This Version of PDK-Java
Manually Installing to a Stand-Alone OC4J Instance
Testing the Deployment
Registering the Sample Providers
Migrating PDK-Java Applications
Deploying Your Own Providers

Introduction

Note: Starting with PDK 9.0.4.1.0, the PDK download is intended to be installed and deployed in a standalone OC4J instance only. If you plan to use PDK in an Oracle Application Server instance, you must get and install the corresponding Oracle Application Server releases or patchsets.

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

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

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

Note: If your upgraded portlets had previously been invoked in Edit Defaults mode by users logged in with multiple Portal session languages, you may have to use the Preference Store Migration Utility to ensure that the appropriate locale specific portlet preferences data is visible to your upgraded portlets. See the release notes for more information on the Preference Store Migration Utility.

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:

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

where:

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:

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:

The service names of the URL Services sample providers are:

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.
  4. Click on the next button to enter the Web Provider specific information
  5. Enter the Web Provider location and Service Name
  6. Scroll down to the User/Session Information section and specify the login frequency
  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
1.2 December 7, 2004

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