# OracleAS Portal Developer Kit (PDK)
Configuring the OmniPortlet Provider

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

### Contents

> Introduction
> OmniPortlet Provider Dependencies
> OmniPortlet Provider Test Page
> Registering the OmniPortlet Provider
> Troubleshooting

## Introduction

Before you configure the OmniPortlet Provider, you must install the PDK-Portal Tools. This is described in the installing.portaltools.html document, which can be found under the pdk/portalTools directory when you unzip pdksoftware.zip.

This document describes how to configure the OmniPortlet Web provider that is included in the PDK-Portal Tools download.

### Features

The OmniPortlet Web Provider provides portlets whose default settings page designers can modify to:

- display data from multiple sources (CSV, SQL, XML, Web Services, Web Page)
- access secured data
- format data using a variety of layouts (chart, form, reports, etc.)
- accept page parameters
- pass parameters
- raise events
- expose customizable settings to page viewers.

## OmniPortlet Provider Dependencies

The OracleAS components shown in the table below are required for the OmniPortlet Provider to function properly. These are installed as part of the OracleAS installation. For more information, see installing.portaltools.html (located under the pdk/portalTools directory when you unzip pdksoftware.zip).

Component | Description | Required? | Degradation Policy if Not Installed or Configured
UIX | Used to render the Edit Defaults and Customize pages, as well as the Test Page. | Yes | None. UIX must be installed. On UNIX, if X Display Server is not configured, these pages may not render properly.
Web Cache | Used for invalidation-based caching of portlet content. | No | If not configured, portlet content will not be cached.
BI Graph Bean | Used to generate chart outputs. | No | If not installed, the portlet cannot produce chart layouts. Same behavior on UNIX if X Display Server is not configured.
Secured Data Repository | Used for storing credential for secured data access as well as Web Clipping info. | No | If repository is not configured, Web Page data source cannot be used. Also, the SQL and other data sources using HTTP protected URLs will not work.

You can configure all of the above components using the OmniPortlet Provider Test Page.

## OmniPortlet Provider Test Page

The OmniPortlet Provider Test Page indicates whether the OmniPortlet provider is functioning properly. You can access the Test Page by clicking the OmniPortlet Provider link on the Portal Tools Welcome Page, located at http://<server>:<host>/portalTools. The Test Page displays:

- The portlets included in the OmniPortlet provider:
  - OmniPortlet
  - Simple Parameter Form Portlet
- Provider initialization parameters and values.
- The status of each of the above components, with links to configuration instructions.

### Required Configuration

UIX is required in order for the OmniPortlet provider to function properly. UIX is installed when you install the Portal Tools. No additional configuration is necessary.

### Optional Configurations

The following are optional configurations for the OmniPortlet provider. If not available, the provider will degrade gracefully, or specific functionality may become unavailable. On the OmniPortlet provider Test Page, click the links in the Actions column next to a Setting to configure it.

#### HTTP Proxy

If a proxy server is required for the provider to make URL connection to a server outside the firewall, you must set up the HTTP Proxy. To do this, click Edit next to HTTP Proxy on the OmniPortlet provider Test Page. An Edit Provider page displays, on which you can specify the HTTP Proxy Host and Proxy Port. You do not need to restart OC4J for the new settings to take effect.

#### Web Cache

If you want your portlet content cached using invalidation-based caching, an Oracle Web Cache instance must be configured in front of your provider. For more information on how to set this up, see Setting up the Invalidation Caching Sample.

After you set up and start the Web Cache instance, register the OmniPortlet provider as usual, but set the URL host name and port number to point to the Web Cache instance instead. For example,

http://<cache_instance_name>:<cache_port>/portalTools/omniPortlet/providers/omniPortlet

When an OmniPortlet definition is altered either through the Edit Defaults or Customize page, the provider generates a request that invalidates and removes the portlet content from the cache. The invalidation request is sent to the invalidation port of the Web Cache instance.

The invalidation port is defined by the cache.xml configuration file (a template copy can be found under pdk/portalTools/conf/portal/conf directory). To specify the port, modify the configuration file as indicated by italicized entries shown in the following example:

    <?xml version="1.0"?>
    <webcache>
        <invalidation
            host="cache.us.oracle.com"
            port="4001"
            authorization="0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11"/>
    </webcache>

The provider locates the cache.xml file using one of the following methods:

- First, it looks in $IAS_HOME/portal/conf/cache.xml.
  - The $IAS_HOME location is derived as follows:
    - Checking the system property oracle.home
    - Derived from the relative position of the portal/jlib/wce.jar file.
- Then, it looks in the default location as defined by the system property oracle.http.configfile.

If the Web Cache Invalidation setting is not configured properly, Web Cache will continue to return stale content that no longer reflects the portlet definition. To fix this, check the application.log file for these errors:

- CONFIGURATION: Encountered a Cache Invalidation Exception.
  oracle.net.http.HttpConfigurationException: Bad "port" value in configuration element "invalidation"
  - The "port" value is not specified properly in the cache.xml file
- CONFIGURATION: Encountered a Cache Invalidation Exception.
  oracle.net.http.HttpConfigurationException: Bad "authorization" value in configuration element "invalidation." String un-obfuscation error
  - Starting with OracleAS 10g (version 9.0.4), the "authorization" value (if present) needs to be encrypted - see Setting up the Invalidation Caching Sample for how this is done. If omitted, the value defaults to the default of "invalidator:invalidator".
- Error: CONFIGURATION: Provider Test Page: Web Cache component not installed properly.
  java.lang.NoClassDefFoundError: oracle/webcache/invalidation/invalidators/InvalidatorElement
  - Reason: webcache/jlib/jawc.jar is not installed.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file not defined by "oracle.http.configfile"
  - Reason: The "oracle.http.configfile" system property is not defined when you start OC4J.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file defined by "oracle.http.configfile" does not exist.
  - Reason: The configuration file defined by "oracle.http.configfile" system property does not exist.

See the Troubleshooting section below for the location of the application.log file. For additional Web Cache troubleshooting tips, see Setting up the Invalidation Caching Sample.

#### BIGraph Bean

If BIGraph Bean is not installed properly, the portlet cannot produce graphical output such as charts. To fix this, check the application.log file for these errors:

- Error: CONFIGURATION: Provider Test Page: BIGraphBean component not installed properly
  java.lang.ClassNotFoundException: tdg/Perspective
  - Reason: jlib/LW_PfjBean.jar is not installed.
- Error: CONFIGURATION: Provider Test Page: BIGraphBean component not installed properly
  java.lang.ClassNotFoundException: oracle/dss/dataView/Model
  - Reason: jlib/bigraphbean.jar is not installed.

See the Troubleshooting section below for the location of the application log.

#### DISPLAY Environment Variable (UNIX only)

If the middle tier where you are hosting this provider is a UNIX system, you must have a valid DISPLAY setting. Without a valid DISPLAY setting, the portlet still renders, but the Edit Defaults and Customize pages, as well as the Provider Test Page may not display buttons and tabs properly. In addition, the portlet will not produce any graphical output.

To set a valid DISPLAY setting, you can:

- set the DISPLAY environment variable to an X server that you can access. If the middle tier machine lacks frame buffer hardware, you can install the X Virtual Frame Buffer (XVFB) utility, downloadable from the Oracle Technology Network.
- Alternatively, with JDK 1.4 or above, you can specify a "headless" display when starting your JVM.

#### Setting up the DISPLAY in Standalone OC4J Installation

You can set the DISPLAY environment variable prior to starting your OC4J instance. For example:

> setenv DISPLAY localhost:0.0
> java -jar oc4j.jar

or:

> java -Djava.awt.headless=true -jar oc4j.jar

#### Setting up the DISPLAY in OracleAS Installation

Follow these steps:

1. Shut down Oracle Enterprise Manager (OEM) using the following command: $IAS_HOME/bin/emctl stop
2. Set the DISPLAY environment variable by updating $IAS_HOME/opmn/conf/opmn.xml (Changes shown in bold):

   <process-type id="OC4J_Portal" module-id="OC4J">
   <environment>
   <variable id="DISPLAY" value="localhost:0.0"/>
   </environment>
   ...
   or:

   <process-type id="OC4J_Portal" module-id="OC4J">
   ...
   <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>
   ...

3. The changes you made will take effect only after you update the DCM repository using: $IAS_HOME/dcm/bin/dcmctl updateConfig
4. Shut down DCM using: $IAS_HOME/dcm/bin/dcmctl shutdown
5. Restart DCM using: $IAS_HOME/dcm/bin/dcmctl start
6. Restart OEM using: $IAS_HOME/bin/emctl start

#### Secured Data Repository Setting

OmniPortlet leverages the Web Clipping Repository to store credentials needed to access secured data. This is a required configuration if you intend to use the Web Page data type or work with secured data (e.g., SQL database server or data source URL with HTTP Basic Authentication). To configure the Repository, click Edit next to Secured Data Repository on the OmniPortlet provider Test Page. An Edit Provider page displays, on which you can enter the Repository information.

#### Library For HTTPS Access in Standalone OC4J Installation

OmniPortlet can access data through HTTPS URLs. To access these URLs, OmniPortlet needs access to njssl9.dll (for Windows®) or libnjssl9.so (for Unix). For providers running on Windows®, njssl9.dll must be present in a folder defined in the PATH environment variable. For Unix systems, libnjssl9.so file must be found in the folder defined in LD_LIBRARY_PATH environment variable.

You can typically find this library and copy it from the $IAS_HOME/bin directory (for Windows®) or $IAS_HOME/lib directory (for Unix) in an OracleAS installation. After copying, you must restart OC4J.

## Registering the OmniPortlet Provider

After you've successfully configured the OmniPortlet Provider, you'll need to register it as a portlet provider in an OracleAS Portal instance before you can add its portlets to a portal page. The registration steps may vary depending on your version of OracleAS Portal.

If you are running Oracle9iAS Portal:

1. Log on to Portal.
2. Navigate to the Build tab (located on the OracleAS Portal Home Page). By the default, you should see the Providers portlet on this page. If not, use the Portal Search feature to locate it.
3. In the Providers portlet, click Register a Portlet Provider.
4. In the wizard steps, provide information for the OmniPortlet provider as follows:

   Field | Value
   Name | OmniPortlet
   Display Name | OmniPortlet Provider
   Timeout | 200 seconds
   Timeout Message | OmniPortlet provider timed out.
   Implementation Style | Web
   URL | http://<server>:<port>/portalTools/omniPortlet/providers/omniPortlet
   The user has the same identity in the Web providers application as in the Single Sign-On identity. | (Select this radio button)
   Select User, to send user specific information to the provider. | (Select this radio button)
   Login Frequency | Never
   Require Proxy | No (as long as no proxy is required to contact the Provider Adapter)

5. Click Finish when you are done.

Note:

- When registering a new provider with OracleAS Portal, only the user who registered the provider has privileges to see the provider and its 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.
- The above registration steps may vary slightly depending on the version of your OracleAS Portal.

## Troubleshooting

You can view errors that occur when bringing up the OmniPortlet Provider Test Page:

- In the Web server file, $OC4J_HOME/j2ee/home/application-deployments/portalTools/application.log, or $IAS_HOME/j2ee/<OC4J_instance>/application-deployments/portalTools/<OC4J_instance>_default_island_1/application.log

You can view errors that occur during the execution of the OmniPortlet:

- In the Web server file, $OC4J_HOME/j2ee/home/application-deployments/portalTools/application.log, or $IAS_HOME/j2ee/<OC4J_instance>/application-deployments/portalTools/<OC4J_instance>_default_island_1/application.log
- Embedded in the output HTML as comment. You can view this by viewing the HTML source (e.g., on Microsoft Internet Explorer, do View->Source).

You may alter the logging level of the OmniPortlet Provider by accessing the web.xml file and modifying the context-param value of oracle.portal.log.LogLevel to the possible values ranging from 1 to 7 with 7 meaning debug. The web.xml file is located at:

- In the web server file, $OC4J_HOME/j2ee/home/applications/portalTools/omniPortlet/WEB-INF/web.xml, or $IAS_HOME/j2ee/<OC4J_instance>/applications/portalTools/omniPortlet/WEB-INF/web.xml

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

- Error: Chart is not rendered on UNIX
  - DISPLAY environment variable is not set up.
- CONFIGURATION: Encountered a Cache Invalidation Exception.
  oracle.net.http.HttpConfigurationException: Bad "port" value in configuration element "invalidation"
  - The "port" value is not specified properly in the cache.xml file
- CONFIGURATION: Encountered a Cache Invalidation Exception.
  oracle.net.http.HttpConfigurationException: Bad "authorization" value in configuration element "invalidation." String un-obfuscation error
  - Starting with OracleAS 10g (version 9.0.4), the "authorization" value (if present) needs to be encrypted - see Setting up the Invalidation Caching Sample for how this is done. If omitted, the value defaults to the default of "invalidator:invalidator".
- Error: CONFIGURATION: Provider Test Page: Web Cache component not installed properly.
  java.lang.NoClassDefFoundError: oracle/webcache/invalidation/invalidators/InvalidatorElement
  - Reason: webcache/jlib/jawc.jar is not installed.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file not defined by "oracle.http.configfile"
  - Reason: The "oracle.http.configfile" system property is not defined when you start OC4J.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file defined by "oracle.http.configfile" does not exist.
  - Reason: The configuration file defined by "oracle.http.configfile" system property does not exist.
- Error: CONFIGURATION: Provider Test Page: BIGraphBean component not installed properly
  java.lang.ClassNotFoundException: tdg/Perspective
  - Reason: jlib/LW_PfjBean.jar is not installed.
- java.lang.NoClassDefFoundError: oracle/cabo/share/config/Configuration
  - Reason: jlib/uix2.jar is not installed.
- java.lang.NoClassDefFoundError: oracle/bali/ewt/pivot/PagingComponent
  - Reason: jlib/jewt4.jar is not installed.
- java.lang.ClassNotFoundException: oracle.cabo.tags.ColumnTEI
  - Reason: BC4J/lib/uixtags.jar is not installed.
- java.lang.NoClassDefFoundError: oracle/bali/share/collection/ArrayMap
  - Reason: jlib/share.jar is not installed.
- java.lang.NoClassDefFoundError: at oracle.security.ssl.OracleSSLCipherSuite.isSSLLibDomestic when accessing HTTPS site with certificate
  - Reason: The required SSL library is not in the library path. Click here for more info
- java.lang.ClassNotFoundException: oracle.security.misc.Checksum
  - Reason: jlib/ojmisc.jar is not installed

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