# OracleAS Portal Developer Kit (PDK)
Installing the Portal Tools

Last Updated: | December 7, 2004
Status: | Production
Version: | PDK Release 2 (9.0.4.1.0 and later)

### Contents

> Introduction
> Contents of pdksoftware.zip
> Contents of the portalTools Directory
> Contents of the libcommon Directory
> Deploying the Portal Tools Application
> Manually Deploying to a Stand-Alone OC4J Instance
> Configuring and Registering the Providers under Portal Tools
> Troubleshooting
> Advanced Portal Tools Configurations

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

Portal Tools is a collection of deployable OracleAS Portal tools built on Oracle's PDK-Java technology. By using Portal Tools, OracleAS Portal page designers can easily combine any Web content and publish data from a variety of data sources to a portal page.
This download includes the following Portal Tools:

- Web Clipping is an OracleAS Portal technology that enables content reuse and aggregation. Using Web Clipping, Portal page designers can clip page content from an existing Web site and deliver it as a portlet to a Portal page.

- OmniPortlet takes advantage of Portal's parameters and events. It provides wizards that enable Portal page designers to publish SQL, XML, Web Service, Spreadsheet, and existing Web page data directly to a Portal page.

This document contains installation and configuration information on the Portal Tools, and explains how to:

- Install and configure the standalone OC4J Server needed to run the Portal Tools. (OC4J stands for "OracleAS Containers for J2EE". For more information about OC4J, refer to the Oracle Technology Network.)

- Register the Portal Tools' providers with an OracleAS Portal instance.

- Use the portlets contained within the pre-configured providers under the Portal Tools.

If you are upgrading from a previous version of Portal Tools, please see the upgrading.portaltools.html article in the portalTools directory.

Please consult the release notes for up-to-date list of new features, known issues as well as the minimum requirements to deploy the current release of Portal Tools.

## Contents of pdksoftware.zip

Portal Tools is part of the OracleAS Portal Developer Kit (PDK). To install it, first unzip the pdksoftware.zip file into a directory located on the same machine where OC4J is installed. (These instructions will from now on refer to this directory as $unzip_directory.) Unzipping pdksoftware.zip to the $unzip_directory creates the following directory structure:

- $unzip_directory
  - pdk
    - jpdk
    - portalTools
    - libcommon

### Contents of portalTools Directory

The portalTools directory is created under $unzip_directory/pdk and contains all the files required by the Portal Tools. The following files are included in this directory:

- portalTools.ear: The enterprise archive file for Portal Tools providers.
- installing.portaltools.html: Instructions for installing the Portal Tools (this document).
- release.notes.html: Release notes describing known issues in the current release.
- upgrading.portaltools.html: Instructions for upgrading to the current release.
- doc directory: Contains documentation about the Portal Tools and the providers included in it.

- install: Contains installation and configuration documentation about the providers:

- configuring.webclipping.html: Installation and configuration document about the Web Clipping provider.
- configuring.omniportlet.html: Installation and configuration document about the OmniPortlet provider.
- configuring.sample.html: Installation and configuration document about sample providers.
- securing.providerui.html : Document describing how to secure the UI for configuring the providers.

- src directory: Contains source or sample files used in the sample or demo.
- conf directory: Contains configuration files for essential components of the Portal Tools. The configuration files are for the following features:

- HTTPS Communication using HTTP Client

- portal/conf/ca-bundle.crt: Contains trusted certificates that enable the Web Clipping Provider and the OmniPortlet Provider to communicate using HTTPS with secure HTTP Servers. It is the exported version of the trusted server certificate file from Oracle Wallet Manager (OWM).

- Using Web Cache to Cache Portlet Content
  - portal/conf/cache.xml: This is a template for the Web Cache configuration file that defines the invalidation port. Please see the individual provider configuration document for more information.

- lib directory: Contains libraries for the essential components of the Portal Tools. The components and the included libraries are shown below. Some of these libraries may already exist in your OC4J standalone instance installation. If so, you need to selectively copy them into your installation directory by ensuring you only update them if the supplied libraries are newer than your current installation. The library path is the relative path to your OC4J instance installation directory.

  > Component | Library | Version | How to Get Version Information
  > Bali | jlib/jewt4.jar | 4_2_18 | Jar file contains a file with a version number, e.g., "4_2_18"
  > BI Graph | jlib/bigraphbean.jar | 2.7.5.29 | Jar file contains a file with a version number, e.g., "2.7.5.29"
  > | jlib/LW_PfjBean.jar | 2.7.5.29 | Jar file contains a file with a version number, e.g., "2.7.5.29"
  > Oracle Help for the Web | jlib/ohw.jar | 1_1_7 | Jar file contains a file with a version number, e.g., "1_1_7"
  > Oracle Search API | ultrasearch/lib/searchlet.jar | n/a | Compare timestamp in jar file
  > Web Clipping | portal/jlib/wce.jar | 9.0.4.1.0 | Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  > | wireless/lib/wcptg.jar | 9.0.4.1.0 | Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  > | portal/jlib/wcwebdb.jar | 9.0.4.1.0 | Look for an Implementation-Version entry in the Manifest.mf file in the jar file

### Contents of the libcommon Directory

The libcommon directory is created under $unzip_directory/pdk and contains libraries shared by different components contained in pdksoftware.zip. Some of these libraries may already exist in your OC4J standalone instance installation. If so, you need to selectively copy them into your installation directory by ensuring you only update them if the supplied libraries are newer than your current installation. The library path is the relative path to your OC4J instance installation directory.

> Component | Library | Version | How to Get Version Information
> PDK-Java | portal/jlib/pdkjava.jar | 9.0.4.1.0 | Jar file contains a file with a version number, e.g., "version_9.0.4.1.0"
> | portal/jlib/ptlshare.jar | 9.0.4.1.0 | Jar file contains a file with a version number, e.g., "version_9.0.4.1.0"
> | portal/jlib/portaltools.jar | 9.0.4.1.0 | Jar file contains a file with a version number, e.g., "version_9.0.4.1.0"
> URL Services | portal/jlib/tidy.jar | n/a | Compare timestamp in jar file
> UIX | jlib/uix2.jar | 2_1_21 | Jar file contains a file with a version number, e.g., "2_1_21"
> | jlib/share.jar | 1_1_18 | Jar file contains a file with a version number, e.g., "1_1_18"
> | jlib/regexp.jar | n/a | Compare timestamp in jar file
> Web Cache | webcache/jlib/jawc.jar | n/a | Compare timestamp in jar file
> Oracle Net | jlib/netcfg.jar | n/a | Compare timestamp in jar file
> Oracle Internet Directory (OID) | jlib/ldapjclnt9.jar | n/a | Compare timestamp in jar file
> Encryption Library | jlib/ojmisc.jar | n/a | Compare timestamp in jar file

## Deploying the Portal Tools Application

### Copying the Required Files

Before deploying the Portal Tools application, you need to copy all the required library files to the OracleAS installation home.

> copy $unzip_directory/pdk/portalTools/lib/jlib/* to $INSTALL_HOME/jlib/
> copy $unzip_directory/pdk/portalTools/lib/portal/jlib/* to $INSTALL_HOME/portal/jlib/
> copy $unzip_directory/pdk/portalTools/lib/ultrasearch/lib/* to $INSTALL_HOME/ultrasearch/lib/
> copy $unzip_directory/pdk/portalTools/lib/wireless/lib/* to $INSTALL_HOME/wireless/lib/
> copy $unzip_directory/pdk/libcommon/portal/jlib/* to $INSTALL_HOME/portal/jlib/
> copy $unzip_directory/pdk/libcommon/webcache/jlib/* to $INSTALL_HOME/webcache/jlib/
> copy $unzip_directory/pdk/libcommon/jlib/* to $INSTALL_HOME/jlib/

You only need to copy the following configuration files if they do not already exist in the $INSTALL_HOME.

> copy $unzip_directory/pdk/portalTools/conf/portal/conf/* to $INSTALL_HOME/portal/conf/

> Notes:

> - $unzip_directory denotes the directory where you have unzipped the pdksoftware.zip. The libraries and the components to which they belong are described above.
> - Create the target directories if they do not already exist.
> - If installing on a standalone OC4J instance, $INSTALL_HOME is $OC4J_HOME (the root directory of your OC4J installation). You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory.
> - Only copy the above files if the supplied libraries are newer than your current installation. It is always good practice to back up existing files in your current installation prior to copying.
> - The portaltools.jar file (in $INSTALL_HOME/portal/jlib/portaltools.jar) includes all the required jar files in its Manifest.MF file. This file is already referenced in the deployment library path of the portalTools.ear's orion-application.xml file so you need not include it again in your global application.xml or application specific orion-application.xml file.

### Deploying the Application

### Manually Deploying to a Standalone OC4J Instance

This section assumes that you already have a standalone 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. Shut down the OC4J instance.
   To shut down OC4J, you can use the following command from $OC4J_HOME/j2ee/home directory:
   java -jar admin.jar ormi://<host>:<port>/ admin <admin_password> -shutdown
2. Performed the steps in Copying the Required Files.
3. Copy $unzip_directory/pdk/portalTools/portalTools.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:
   <application name="portalTools" path="../applications/portalTools.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="portalTools" name="portalTools" load-on-startup="true" root="/portalTools" />
   <web-app application="portalTools" name="webClipping" load-on-startup="true" root="/portalTools/webClipping" />
   <web-app application="portalTools" name="omniPortlet" load-on-startup="true" root="/portalTools/omniPortlet" />
   <web-app application="portalTools" name="providerBuilder" load-on-startup="true" root="/portalTools/builder" />
   <web-app application="portalTools" name="sample" load-on-startup="true" root="/portalTools/sample" />
6. Start up the OC4J instance again by executing the following command from $OC4J_HOME/j2ee/home directory:
   java -jar oc4j.jar

Portal Tools is now deployed. Please proceed to Configuring and Registering.

## Configuring and Registering the Providers under Portal Tools

Now that Portal Tools is deployed, you should proceed to configure the individual providers before registering them with an OracleAS Portal instance. This can be done from the Portal Tools home page at the following URL:

> http://<server>:<port>/portalTools

The home page lists the providers under Portal Tools. Click on each link to display the provider's test page and configure the provider.

The following links let you view a document describing how to configure the provider and register it with OracleAS Portal:

1. Web Clipping Provider

2. OmniPortlet Provider

3. Sample Provider

## Troubleshooting

Error you are most likely to encounter and possible solutions for them are listed below.

- `java.lang.OutOfMemoryError` or other "out of memory" errors.
  - You need to increase the maximum heap size for the JVM your <OC4J_instance> runs in. The solution differs depending on your OC4J instance:
    - Standalone OC4J instance:
      java -Xmx512M -jar oc4j.jar...

## Advanced Portal Tools Configurations

This section discusses the configurations that need to be performed to accommodate some of these more advanced topics.

### Shutting down Web Cache completely

This section is only applicable if you installed Portal Tools in an OracleAS installation. If you want to shut down OracleAS Web Cache completely, you must perform the following steps for Portal Tools to function properly:

1. Open the $IAS_HOME/Apache/Apache/conf/httpd.conf file and update the Listen directive to the port on which OracleAS Web Cache was listening.
2. Restart the Oracle HTTP Server.

For more information, refer to the Shutting down OracleAS Web Cache completely section of the OracleAS Portal Configuration Guide.

### Securing the UI Used to Configure the Providers

This section is only applicable if you installed Portal Tools in an OracleAS installation. While configuring a provider, you will come across steps where you need to edit the provider. The UI displayed when you click on the "Edit" link, in default installation, is not secured. This UI can be secured only for OC4J instance deployment in OracleAS. To secure the UI, follow the steps described in the Securing the Edit Provider UI article.

Revision History: |
Revision No | Last Update
1.0 | October 21, 2002
2.0 | June 30, 2003
2.1 | September 15, 2003
2.2 | November 17, 2003
2.4 | December 07, 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