OracleAS Portal Developer Kit (PDK)
Installing the Portal Tools

Contents

Introduction
Contents of pdksoftware.zip
Contents of the portalTools Directory
Contents of the libcommon Directory
Deploying the Portal Tools Application
Deploying Using Oracle Enterprise Manager (OEM)
Manually Deploying to an OracleAS Instance Using dcmctl
Manually Deploying to a Stand-Alone OC4J Instance
Configuring and Registering the Providers under Portal Tools
Troubleshooting
Advanced Portal Tools Configurations

Introduction

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:

• WebClipping is an OracleAS Portal technology that enables content reuse and aggregation. Using WebClipping, 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 OracleAS/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.to.<current_version>.html article in the portalTools directory. 

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.to.<current_version>.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 or OracleAS 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 or OracleAS 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.28	Jar file contains a file with a version number, e.g., "2.7.5.28"
  	jlib/LW_PfjBean.jar	2.7.5.28	Jar file contains a file with a version number, e.g., "2.7.5.28"
  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	portal/jlib/searchlet.jar	n/a	Compare timestamp in jar file
  Web Clipping	portal/jlib/wce.jar	9.0.4.0.2	Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  	wireless/lib/wcptg.jar	9.0.4.0.2	Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  	portal/jlib/wcwebdb.jar	9.0.4.0.2	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 or OracleAS 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 or OracleAS instance installation directory.

Component	Library	Version	How to Get Version Information
PDK-Java	portal/jlib/pdkjava.jar	9.0.4.0.2	Jar file contains a file with a version number, e.g., "version_9.0.4.0.2"
	portal/jlib/ptlshare.jar	9.0.4.0.0	Jar file contains a file with a version number, e.g., "version_9.0.4.0.0"
	portal/jlib/portaltools.jar	9.0.4.0.2	Jar file contains a file with a version number, e.g., "version_9.0.4.0.2"
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

Deploying the Portal Tools Application

Copying the Required Files

Before deploying the Portal Tools application, you need to copy all the required configuration and library files to the OracleAS installation home (if installing on an OC4J instance in OracleAS, $IAS_HOME) or to the root directory of your OC4J installation (if installing on a standalone OC4J instance, $OC4J_HOME).  Collectively, we call this directory the $INSTALL_HOME.

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

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

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 an OC4J instance in OracleAS, $INSTALL_HOME is $IAS_HOME (your OracleAS installation home).
• 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

The next step for deploying the Portal Tools Application differs depending on where you want to deploy it.

• If you are deploying into an OracleAS instance with OEM or a standalone OC4J instance and you have installed OEM separately to manage to your standalone 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 OracleAS instance and you do not have OEM installed or you want to do the configuration manually, follow the steps under Manually Deploying to an OracleAS Instance Using dcmctl.
• If you are installing on a standalone OC4J instance and you don't have Oracle Enterprise Manager (OEM) installed and configured, follow the steps in the section, Manually Deploying to a Standalone OC4J Instance. 

Note:

If you are installing into an OracleAS 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 OracleAS with Portal installed, the preferred OC4J instance is the "OC4J_Portal" instance. 

Deploying Using Oracle 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 deployment instructions for OracleAS or standalone OC4J.

Before deploying the Portal Tools application, 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.)

1. Shut down the OC4J instance.
   To shut down OC4J, you can use the following command from $IAS_HOME/opmn/bin directory:
   opmnctl stopproc gid="<OC4J_Instance>"
2. Performed the steps in Copying the Required Files.
3. Start up the OC4J instance.
   opmnctl startproc gid="<OC4J_Instance>"
4. Go to your OEM interface and log in. You can usually access OEM at http://<server>:1810/
5. Click on the OracleAS middle tier where you want to deploy the Portal Tools. You will see a list of all your system components in your middle tier.
6. Click on the OC4J instance where you want to deploy the Portal Tools. If you are deploying on the OracleAS middle tier that is being used for Oracle Portal, there will normally be an OC4J instance named "OC4J_Portal". You should normally deploy the Portal Tools in this instance.
7. Click Deploy EAR file.

8. Click Next.

9. Enter the following Information:
   • J2EE Application: $unzip_directory/pdk/portalTools/portalTools.ear
   • Application Name: portalTools

10. Click Next. The URL mapping for Web Modules displays. Do not change the default mappings that are there. If you already have Portal Tools application deployed in another OC4J instance on the same Application Server, you need to follow the steps described in the upgrading.to.<current_version>.html article in the portalTools directory. Alternatively, you need to deploy Portal Tools on a different Application Server instance.
11. Click Finish. The last step contains a summary of all information you entered.
12. Click Deploy. The Portal Tools will be deployed to your OracleAS instance. You should see the portalTools application in the list of applications for the OC4J instance you selected.

13. Click portalTools in the list of applications to view a page displaying properties of the application.

14. Click General under the Administration : Properties section.

15. Click Apply.

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

Manually Deploying to an OracleAS Instance Using dcmctl

This section assumes:

• You have OracleAS installed but you do not have OEM installed or
• You wish to deploy the provider manually without using OEM

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

Before deploying the Portal Tools application, 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.)

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. You may shut down OEM using the following command: $IAS_HOME/bin/emctl stop

To deploy the application manually:

1. Shut down the OC4J instance.
   To shut down OC4J, you can use the following command from $IAS_HOME/opmn/bin directory:
   opmnctl stopproc gid="<OC4J_Instance>"
2. Performed the steps in Copying the Required Files.
3. Start up the OC4J instance:
   opmnctl startproc gid="<OC4J_Instance>"
4. Deploy portalTools.ear using the command-line deployment utility dcmctl:
   $IAS_HOME/dcm/bin/dcmctl deployApplication -v -f <earFilePath> -a <applicationName> -co <OC4J_Instance>
   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 into which the application should be deployed.

   For example,
   dcmctl deployApplication -v -f $unzip_directory/pdk/portalTools/portalTools.ear -a portalTools -co OC4J_Portal
   
   You can also use dcmctl to redeploy or undeploy an application or perform a variety of other OracleAS administrative tasks.

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

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...
      
    • An OC4J Instance in an OracleAS Instance:
      Update $IAS_HOME/opmn/conf/opmn.xml (Changes shown in bold):

      <process-type id="OC4J_Portal" module-id="OC4J">
        <environment>
          <variable id="LD_LIBRARY_PATH" value="/usr/local/ohome/lib"/>
        </environment>
        <module-data>
          <category id="start-parameters">
            <data id="java-options" value="... -Djava.awt.headless=true -Xmx512M"/>
            <data id="oc4j-options" value="-properties"/>
          </category>
          ...
        </module-data>
        ...

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.