Oracle9iAS Portal Developer Kit (PDK)
Installing the Portal Tools

Contents

Introduction
Contents of pdk.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 Oracle9iAS 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 Oracle9iAS Portal tools built on Oracle's PDK-Java technology. By using Portal Tools, Oracle 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 Oracle 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 Oracle9iAS/standalone OC4J Server needed to run the Portal Tools. (OC4J stands for "Oracle9iAS Containers for J2EE". For more information about OC4J, refer to the Oracle Technology Network.)

• Register the Portal Tools' providers with an Oracle9iAS 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.<from>.to.<to>.html article in the portalTools directory. 

Contents of pdk.zip 

Portal Tools is part of the Oracle9iAS Portal Developer Kit (PDK). To install it, first unzip the pdk.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 pdk.zip to the $unzip_directory creates the following directory structure: 

• $unzip_directory

  • pdk

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

  • pdkpages

  • index.html

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 new features since the last release and known issues in the current release.
• upgrading.90240.to.90261.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 Oracle9iAS 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 Oracle9iAS instance installation directory.

  Component	Library	Version	How to Get Version Information
  Bali	jlib/jewt4.jar	4_2_6	Jar file contains a file with a version number, e.g., "4_2_6"
  UIX	jlib/uix2.jar	2_0_21	Jar file contains a file with a version number, e.g., "2_0_21"
  	jlib/share.jar	1_1_17	Jar file contains a file with a version number, e.g., "1_1_17"
  	jlib/regexp.jar	n/a	Compare timestamp in jar file
  BC4J	BC4J/lib/uixtags.jar	n/a	Compare timestamp in jar file
  BI Graph	jlib/bigraphbean.jar	2.7.0.11	Jar file contains a file with a version number, e.g., "2.7.0.11"
  	jlib/LW_PfjBean.jar	2.7.0.11	Jar file contains a file with a version number, e.g., "2.7.0.11"
  Oracle Help for the Web	jlib/ohw.jar	1_0_7	Jar file contains a file with a version number, e.g., "1_0_7"
  Oracle Search API	portal/jlib/searchlet.jar	1.0	Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  URL Services	portal/jlib/tidy.jar	n/a	Compare timestamp in jar file
  Web Clipping	portal/jlib/wce.jar	9.0.2.6.2	Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  	wireless/lib/wcptg.jar	9.0.2.6.2	Look for an Implementation-Version entry in the Manifest.mf file in the jar file
  	portal/jlib/wcwebdb.jar	9.0.2.6.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 pdk.zip.  Some of these libraries may already exist in your OC4J standalone or Oracle9iAS 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 Oracle9iAS instance installation directory.

Component	Library	Version	How to Get Version Information
PDK-Java	portal/jlib/pdkjava.jar	9.0.2.6.2	Jar file contains a file with a version number, e.g., "version_9.0.2.6.2"
	portal/jlib/ptlshare.jar	9.0.2.6.0	Jar file contains a file with a version number, e.g., "version_9.0.2.6.0"
Web Cache	webcache/jlib/jawc.jar	n/a	Compare timestamp in jar file
Oracle Internet Directory (OID)	jlib/ldapjclnt9.jar	1.0	Look for an Implementation-Version entry in the Manifest.mf file in the 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 and configuration files to the Oracle9iAS installation home (if installing on an OC4J instance in Oracle9iAS, $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/lib/BC4J/lib/* to $INSTALL_HOME/BC4J/lib/
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/

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

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. 
• Create the target directories if they do not already exist.
• If installing on an OC4J instance in Oracle9iAS, $INSTALL_HOME is $IAS_HOME (your Oracle9iAS 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 PDK-Java pdkjava.jar file (in $INSTALL_HOME/portal/jlib/pdkjava.jar) includes all the required jar files in its Manifest.MF file. Including this file in the deployment library path (to be done in the next step) will include all the other required files. 

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 Oracle9iAS 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 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 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 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 preferred OC4J instance is the "OC4J_Portal" instance. 

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.

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

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

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 Oracle9iAS 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 Oracle9iAS Instance Using dcmctl

This section assumes:

• You have Oracle9iAS 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 Oracle9iAS installation, either install and configure Oracle9iAS 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 Oracle9iAS installation you want to use. (This instance will be referred to as <OC4J_instance> from here on.)

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. 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 Oracle9iAS 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" root="/portalTools" />
   <web-app application="portalTools" name="webClipping" root="/portalTools/webClipping" />
   <web-app application="portalTools" name="omniPortlet" root="/portalTools/omniPortlet" />
   <web-app application="portalTools" name="providerBuilder" root="/portalTools/builder" />
   <web-app application="portalTools" name="sample" 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 Oracle9iAS 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 Oracle9iAS 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.

• Errors compiling ../<file>.java.  The compiler has run out of memory. Consider using the "-J-mx<number>" command line option to increase the maximum heap size.
  • 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 Oracle9iAS Instance:
      Update $IAS_HOME/opmn/conf/opmn.xml (Changes shown in bold):

      <oc4j instanceName="<OC4J_instance>" numProcs="1" maxRetry="3">
        <java-option value="-Xmx512M"/>
      </oc4j>

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 Oracle9iAS installation.  If you want to shut down Oracle9iAS 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 Oracle9iAS Web Cache was listening.
2. Restart the Oracle HTTP Server.

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

Securing the UI Used to Configure the Providers

This section is only applicable if you installed Portal Tools in an Oracle9iAS 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 Oracle9iAS. To secure the UI, follow the steps described in the Securing the Edit Provider UI article.