Skip Headers

Oracle9i Application Server Migrating from Oracle9iAS Release 1 ( to Release 2 (9.0.2)
Release 2 (9.0.2) for Sun SPARC Solaris

Part Number A96157-03
Go To Documentation Library
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Migrating Portals Components

This chapter explains how to change the necessary configuration files and application deployment files necessary to migrate Portals components. It contains these major sections:

Migrating Oracle9iAS Portal

Migrating Oracle Ultra Search

Migrating Oracle9iAS Portal

This section explains how to migrate Oracle9iAS Portal. It is divided into the following sub-sections:

Migrating the Mid-Tier

This section describes the process of migrating the Portal mid-tier from Portal 3.0.9 to 9.0.2. It contains the following topics:

Architectural Changes in Portal Release 9.0.2

Oracle Portal 9.0.2 is based on Oracle9iAS Release 2 (9.0.2), which contains a new J2EE-compliant servlet container (OC4J), replacing the old servlet container (JServ). Manual steps are necessary to migrate the mid-tier from the old architecture to the new architecture.

Migrating from JServ Zones to OC4J Applications

  1. Configure mod_oc4j to forward requests of type /servlet/page/* to the OC4J Portal instance:

    1. Edit ORACLE_HOME_2/Apache/Apache/conf/mod_oc4j.conf and add the following line:

      OC4JMount /servlet/page OC4J_Portal 


      Place this directive next to the other OC4JMount directives in this file. The added entry must be inside the <IfModule mod_oc4j.c> block.

    2. Edit ORACLE_HOME_2/Apache/Jserv/etc/jserv.conf and modify the ApJServMount directive so that JServ does not also use the /servlet mount point. The default servlet zone uses the /servlet mount point.

      Change this directive:

      ApJServMount /servlet /root

      to specify a different mount point for JServ, for example:

      ApJServMount /anotherMountPoint /root

  2. Configue OC4J to use a Portal application to run all /servlet/page requests:

    1. Edit ORACLE_HOME_2/j2ee/OC4J_Portal/config/default-web-site.xml and add the following line:

      <web-app application="portal" name="portal" root="/" />


      Place this directive next to the other <web-app application> directives in this file. The added entry must be inside the <web-site> block.

Migrating the Parallel Page Engine

The Parallel Page Engine (PPE), which ships with the Oracle Portal 9.0.2, is backward-compatible and works with Oracle Portal 3.0.9 (Oracle9iAS Release 1 ( All the new settings that are required for Oracle Portal 9.0.2 are configured automatically. Manual steps are required to migrate custom settings to the new environment. Table 4-1 lists parameters in Oracle Portal 3.0.9 that can be modified in the PPE:

Table 4-1 Parallel Page Engine Parameters
Parameter Description


Total size of the memory buffer used to retrieved a cached page. This number should be set to a value matching approximately the total size of the system's completed pages. The buffer is used to read the file from the disk and write it to the browser. If the value is too small, then multiple disk reads occur, which hampers performance. The larger the value, the fewer reads, however, this requires more resources. The default is 32768.


A list of ports that are running SSL/HTTPS. The port numbers are delimited by a : (colon) and resembles the following:


If Portal is running in SSL/HTTPS mode, then the port on which it is running must be specified here. The default is null.


This setting can be set to debug. If this value is set, then the PPE runs in a debug mode. If this value is not set, then the PPE runs normally with minimal writing of warnings and errors when needed.


The absolute path to which PPE logs are written. This setting may be set to any existing path. The default is the default JServ log path.


Number of seconds the portlet waits for an outbound HTTP request to execute. Any timeout value given by the portlet that is less than this value is increased to this value. If this parameter is not specified in initArgs, it defaults to 5 seconds.


If for some reason Portal needs to be off line, then this setting allows the servlet to return a pre-determined file to let the client know that Portal is off line. When this value is set, the PPE can operate in off line mode. The default is null.


Total number of threads to use for parallel processing. The higher the number, the more requests that can be processed, however this also means that more resources will be used. The lower the number, the fewer requests which can be processed, and the fewer resources are needed. The default is 25.


The prefix used to point to modplsql. The default is /pls.


Host to use for proxy requests when needed. The default is null.


A list of domains to ignore when using a proxy server. The domain must follow the HTTP 1.1 standard, which means that it must start with a ".", and end in a character. The default is null.


Port to use for proxy requests when needed. The default is null.


Number of seconds a request waits in the queue before timing out and being removed from the queue. The default is 10 seconds if it is not specified in initArgs.


Number of seconds a request is allowed to execute before it times out, if no timeout parameter is specified by the metadata. This parameter is bounded by minTimeout and maxTimeout. The default is 15 seconds if it is not specified in initArgs.


Specifies whether to display PPE errors like time-out, and portlet flaws to the user. If set to true then users will see errors, if set to false then users will not see error messages. The default is true.


Number of seconds a connection remains open for an outbound HTTP request. Any timeout value given by the portlet that is greater than this will be decreased to this value. The default is 65 seconds if it is not specified in initArgs.

To migrate the parameters above, copy the parameter names and values to the ORACLE_HOME_2/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/web.xml file. The examples below show the location and format of the names and values in version 3.0.9 and version 9.0.2:

Example 4-1 initArgs Parameter in 3.0.9 Format

The 3.0.9 parameter syntax is:

To configure the httpsports parameter with a value of 443:

Example 4-2 initArgs Parameter in 9.0.2 Format

The 9.0.2 parameter syntax is:


To configure the httpsports parameter with a value of 443:


mod_plsql Parameter Changes in Release 2

mod_plsql DADs now use the Oracle HTTP Server Location directive for configuration. In this syntax, parameter names and values are separated by white space instead of the equal sign. Table 4-2 lists the Release 1 parameters and their Release 2 equivalents. Values are also compared for selected parameters.

See Also:

Oracle HTTP Server Administration Guide. for complete documentation of all DAD parameters.

Table 4-2 DAD Parameters
Release 1 Parameter Release 2 Parameter Release 1 Value Release 2 Value



all, debug ,info notice, warn, alert crit

Off, On (All other levels besides debug/all are controlled by LogLevel in httpd.conf.)

























Yes, No

1000 (default), 1











Not Set






















One per line



One per line













One per line



One per line

DAD Parameter Usage Notes

This section provides details about using the Release 2 parameters.

Migrated DAD Example

An example of the DAD in the Release 1 configuration file ORACLE_HOME_1/Apache/modplsql/cfg/ is shown below:

username = portal30 
password = portal30 
connect_string = 
default_page = portal30.home 
document_table = portal30.wwdoc_document 
document_path = docs 
document_proc = portal30.wwdoc_process.process_download 
upload_as_long_raw = txt, gif 
upload_as_blob = * 
;name_prefix = 
always_describe = No 
;before_proc = 
;after_proc = 
reuse = Yes 
pathalias = url 
pathaliasproc = portal30.wwpth_api_alias.process_download 
enablesso = Yes 
;sncookiename = 
;stateful = 
;custom_auth = 
;response_array_size = 
;exclusion_list = 
;cgi_env_list = 
;error_style = 
;nls_lang = 

The migration process converts it to the following arguments in a Location directive:

<Location /pls/portal30> 
   SetHandler pls_handler 
   Order allow, deny 
   Allow from All 
   AllowOverride None 
   PlsqlDatabaseUsername portal30 
   PlsqlDatabasePassword portal30 
   PlsqlDefaultPage portal30.home 
   PlsqlDocumentTable portal30.wwdoc_document 
   PlsqlDocumentPath docs 
   PlsqlDocumentProc portal30.wwdoc_process.process_download 
   PlsqlUploadAsLongRaw txt 
   PlsqlUploadAsLongRaw gif 
   PlsqlMaxRequestsPerSession 1000 
   PlsqlAuthenticationMode SingleSignOn 
   PlsqlPathAlias url 
   PlsqlPathAliasProcedure portal30.wwpth_alias.process_download 

Migrating Database Access Descriptors

The Portal and Login Server DADs have changed significantly between releases, and there is a migration tool for migrating the DADs. This section explains how to use the migration tool to migrate DADs, and describes the differences between the mod_plsql parameters.

Running the dadMigration Script

This section explains how to migrate Database Access Descriptors (DADs) from Oracle9iAS Release 1 ( to Oracle9iAS Release 2 (9.0.2). The information in the DAD configuration file in Oracle9iAS Release 1 (,, must be migrated to the Oracle9iAS Release 2 (9.0.2) configuration file, dads.conf. As a result of this operation, Web DAV entries are created in oradav.conf.

The migration is performed using the Portal Configuration Interface (PCI) via the dadMigration script. The full path and file name of the script is shown below.

ORACLE_HOME_2/bin/dadMigration.csh (UNIX)

ORACLE_HOME_2/bin/dadMigration.cmd (Windows)

The migration script reads in the old format DADs, and creates new DADs and corresponding Web DAV entries. It takes two parameters, targetOracleHome (-t) and migrationSource (-s). Follow the steps below to run the script.

  1. On UNIX:

    dadMigration.csh -t ORACLE_HOME_2 -s ORACLE_HOME_1/Apache/modplsql/cfg/ 

    On Windows:

    dadMigration.cmd -t ORACLE_HOME_2 -s ORACLE_HOME_1/Apache/modplsql/cfg/ 

    where ORACLE_HOME_2 specifies the target Oracle home (the default is the value of the ORACLE_HOME environment variable)

    and ORACLE_HOME_1 specifies the location of the v.3.0.9 DAD format file to be migrated (the default is

  2. Restart the EMD to pick up the changes.

  3. Verify that the DAD was migrated. You can do this using the administration and monitoring user interface to navigate to the mod_plsql services page, which contains the DAD status section. Successfully migrated DADs appear there.


    Migration changes may be lost if another migration action or a Portal configuration action is performed before the EMD is restarted.


    If the middle tier hostname and port are not the same in Release 2 as in Release 1, you must use the ssodatan script to re-register Portal. See the Oracle9iAS Portal Configuration Guide for more information.

Migrating the Mid-Tier Cache Configuration

The cache configuration migration process is manual, and requires that you change the value of parameters based on their configured values in the Oracle9iAS Release 1 ( Oracle home.

Table 4-3 Mid-TIer Cache Parameters
Release 1 Parameter Release 2 Parameter Release 1 Value Release 2 Value



Yes, No

On, Off



Directory of cache

Directory of cache







User-specified value in seconds

User-specified value in minutes


The Release 1 session cache settings and PL/SQL cache settings have been collapsed into one single setting for cache. See the examples below.

Example 4-3 Oracle9iAS Release 1 Cache Configuration File

The ORACLE_HOME_1/Apache/modplsql/cfg/cache.cfg file is shown below:

enabled = yes 
cache_dir = /u01/app/oracleproduct/IAS1022/Apache/modplsql/cache/plsql 
total_size = 25600000 
cleanup_size = 10240000 
cleanup_interval = 43200 
max_size = 1024000 
[Cookie Cache] 
enabled = yes 
cache_dir = /u01/app/oracleproduct/IAS1022/Apache/modplsql/cache/session 
total_size = 25600000 
cleanup_size = 10240000 
cleanup_interval = 43200 
max_size = 1024000

Example 4-4 Oracle9iAS Release 2 Cache Configuration File

The Release 1 file will get converted to ORACLE_HOME_2/Apache/modplsql/conf/cache.conf as follows:

PlsqlCacheEnable On 
PlsqlCacheDirectory /u01/app/oracle/product/IAS1022/Apache/modplsql/cache 
PlsqlCacheTotalSize 25600000 
PlsqlCacheCleanupSize 10240000 
PlsqlCacheCleanupInterval 720 
PlsqlCacheMaxSize 1024000

Migrating Portal Development Kit (PDK) Java Web Providers

This section describes how to upgrade your PDK-Java v3.0.9 provider to PDK-Java (9.0.x). The increase in version numbers reflects the synchronization of version numbers withOracle9iAS Release 2 (9.0.2), of which the PDK-Java is a component. This section contains the following topics:

Installing the PDK-Java Framework and Samples

Migration Options

Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1)

Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)

Packaging and Deploying Your Provider

Installing the PDK-Java Framework and Samples

The PDK-Java Framework (included with Oracle9iAS in ORACLE_HOME/portal/pdkjava/v2/) includes the tools and documentation necessary to build Web portlets. The PDK-Java Framework and Web Provider Samples will help you get started. Included in the PDK-Java Framework is the provider framework; portlets will use this framework and build upon it.

This section provides installation and configuration information for the PDK-Java Framework and samples. It explains how to configure the Oracle HTTP Server to run the PDK-Java Framework, the samples, and your own portlets.

The PDK-Java Framework includes these application files:

Configuration Requirements for the PDK-Java Framework

You must have Oracle9iAS with Oracle9iAS Containers for J2EE (OC4J) installed and configured in order to run the framework and samples.

Deploying The Sample Providers

Follow these steps to deploy the sample providers:

  1. Copy jpdk.ear into your OC4J applications subdirectory (typically, ORACLE_HOME_2/j2ee/OC4J_Portal/applications).

  2. Add the following line to the
    ORACLE_HOME_2/j2ee/OC4J_Portal/config/server.xml file:

    <application name="jpdk" path="../applications/jpdk.ear" />
  3. Bind the application to the default site by adding the following line to the
    ORACLE_HOME_2/j2ee/OC4J_Portal/config/default-web-site.xml file:

    <web-app application="jpdk" name="jpdk" path="/jpdk/" /> 
  4. Start OC4J, or restart the listener.

    The application will be automatically deployed based on the information specified in Step 3.

  5. Access the provider using the following URL:

    http://server:port/jpdk/providers/sample/provider name

There are several sample providers included with the PDK-Java. They are described in Table 4-4.

Table 4-4 PDK-Java Sample Providers
Provider Name Description


Includes a variety of portlets demonstrating different rendering techniques, customization and caching


Portlets that demonstrate the use of the dbPersonalizationManager


Demonstrates external application integration


A sample portlet that allows you to capture feedback from users of your portal


Sample portlets that demonstrate invalidation-based caching using Oracle9iAS Web Cache


Demonstrates partner application integration


Demonstrates the use of subscription keys to identify the source of requests

Registering the Sample Providers

After setting up the Web Provider Sample with the Oracle HTTP Server, you must register the provider with Oracle9iAS Portal before adding the sample portlet(s) to a page.

  1. Under the Build tab (on Oracle Portal Home Page), click on Add a Portlet Provider within the portlet called Provider.

  2. Complete the provider information fields for the sample as follows:

    Name - SampleWebProvider

    Display Name - Sample Web Provider

    Timeout - 100

    Timeout Message - Application Timed Out

    Implementation Style - Web

    Register on Remote Nodes - No

    Provider Login Frequency - Once per User Session


    (Replace this with your provider URL.)

    Click the radio button for this selection:

    The user has the same identity in the Web providers application as in the Single Sign-On identity.

    Require Proxy - No (If no proxy is required to contact the Provider Adapter).

  3. Click OK.

    Once registered, all the sample portlets are displayed in the Portlet Repository.


    When registering a new provider with Oracle Portal, only the user who registered the provider has privileges to see the provider and portlets. If necessary, go to the folder within the Portlet Repository content area with the name of the provider and update the provider privileges as required.

Adding Sample Portlets to a Page

Follow these steps to add sample portlets to a page:

  1. Create a page.

  2. Add the portlets from SampleWebProvider to the page.

  3. View the page you just added.

    You can preview the portlets in the Portlet Repository.

Securing Your Provider

Oracle recommends that you secure access to providers when using the PDK-Java framework in a production environment. Oracle9iAS (via the Oracle HTTP Server configuration file httpd.conf) has the capability to deny access by IP address or hostname, as shown in the examples below:

Accepting Requests only from Portal

To make your provider accept requests only from Oracle Portal, you can allow access only from the Portal IP addresses in a Location directive for the provider path. Include the following in your httpd.conf file:

<Location provider path>
  order deny, allow 
  deny from all 
  allow from ip address 1 
  allow from ip address 2 

where IP address 1 and IP address 2 are the IP addresses of the computer on which Portal resides.

Securing a Path

You may also want to secure the /servlet or other paths. To do this, add similar directives for those paths.

<Location /servlet > 
  order deny, allow 
  deny from all 
  allow from ip address 1 
  allow from ip address 2 

Securing a Servlet on a Path

To restrict access for a single servlet called "provider", so that it can only be accessed from or, use a directive similar to the following:

<Location /servlet/provider > 
  order deny, allow 
  deny from all 
  allow from 
  allow from 

See Also:

Oracle HTTP Server Administration Guide.

Overview of PDK-Java 9.0.2

PDK-Java 9.0.x includes two versions of the PDK-Java framework:

Version 1 extends the framework that was included in PDK-Java 3.0.9, adding more complete support for mobile or wireless content providers and portlets. This version of the framework runs in the JServ servlet container.

Version 2 enables you to create web providers that run in the J2EE-compliant, OC4J servlet container. In addition to J2EE support, version 2 has been modified to make the framework more object-oriented and easier to extend without breaking existing web providers.These changes required the addition of some new classes, and some API changes, so any existing web providers will have to be modified before they can use the new framework.

Summary of Changes Between PDK-Java Versions

PDK-Java v9.0.2 includes several changes that are designed to increase the overall stability of the framework and make it easier to introduce new features with minimal impact on existing code. These changes include:

Abstract Classes Replace Interfaces

During the development of earlier releases of the PDK-Java, it became evident that the use of Java interfaces to define top level APIs made adding new features difficult. This was because new features often required API changes and those API changes had to be reflected in changes to the Java interfaces.

For developers using the default implementations, these changes were not invasive. However, for developers writing more complex providers, any interface change could cause their code to break, because their implementations no longer matched the interface definitions.

To resolve this issue, most of the Java interfaces have been replaced with abstract classes. The switch to abstract classes allows new features to be added without breaking any existing code. While this change does reduce flexibility (due to the lack of support for multiple inheritance in Java) and requires code changes to adopt the new release of PDK-Java, the long term gains in stability are worth the cost.

Package Reorganization

In addition to replacing Java interfaces with abstract classes, the package structure of the JPDK has been modified to include a new version number and to organize the classes based on functionality.

All packages now include "v2" in the package name to indicate that the package belongs to version 2 of the PDK-Java. The inclusion of a version number in the package name allows different versions of the PDK-Java to be included in the same classpath without causing collisions.

In addition to the version number change, the classes have been re-organized into a more logical structure. The new structure groups classes based on functionality. This makes it easier to find existing classes, and organize new classes as new functionality is added.

Object-Oriented Framework

To make the code more understandable for developers and create a clean separation between the provider APIs that developers implement and the underlying code that communicates with Oracle Portal, the provider and portlet interfaces have been modified.

Previously, the provider and portlet APIs were not very object-oriented, and API calls from the communication layer of the framework sometimes bypassed these objects and accessed the "controller" objects directly. In the new API, several changes have been made: the Provider interface has been split into 2 abstract classes: ProviderInstance and ProviderDefinition.

The old Provider interface represented:

Splitting the information in this way makes the usage of the classes clearer for developers and allows a single set of metadata to be shared by many registered instances. It creates a platform for supporting provider instance-specific behavior (for example, provider configuration settings that are specific to a registered instance of that provider).

The Portlet interface has been split into 2 abstract classes: PortletInstance and PortletDefinition. The old Portlet interface really represented only the portlet metadata. All API calls that affected a portlet were actually routed directly to the appropriate controller. This architecture did not create a clean interface with the communication layer of the framework and made it difficult for developers working with more complex portlets to understand the flow of control within the framework.

To solve this problem, the PortletInstance and PortletDefinition were created. The PortletDefinition represents the sharable definition of the portlet and the PortletInstance represents a specific instance of that portlet being accessed by, or on behalf of, a specific user. The result of this split is that all APIs that affect an instance of a portlet (rendering, copying, security etc.) have been brought together in the PortletInstance class.

This change in architecture also allows developers more freedom because they are not forced to use the rendering, personalization and security frameworks provided by the PDK-Java. The default implementation of PortletInstance continues to use the familiar rendering, personalization and security controllers introduced in earlier versions of the PDK-Java. All calls from the communication layer are now made via the ProviderInstance and (if necessary) the PortletInstance.

With cleanly defined classes that represent instances of a provider and portlet, all the API calls from the communication layer of the PDK-Java can be neatly funneled through the ProviderInstance and PortletInstance interfaces, making the framework easier to understand for new developers.

Migration Options

Since there are two versions of the framework, there are three migration options:

Option 1 is the simplest, because it does not require any changes to existing web providers. However, you must configure the JServ servlet container in Oracle9iAS. This approach allows you to migrate to Oracle9iAS Release 2 (9.0.2) and implement existing web providers quickly. However, you will not be able to use any of the features of OC4J.

Option 2 is slightly more involved, since you must modify web providers to use the new framework. For most web providers, the necessary changes are straightforward (i.e., modifying the import statements in Java classes, and changing the classes used for some method calls). In general, the methods that existed in version 1 of the framework are still there, and their function has not changed--but the class in which they are contained may have changed. Option 2 enables you to take advantage of the features of the OC4J servlet container and the new functionality in version 2 of the framework. Most new features will only be added to version 2 of the framework.

Option 3 combines Options 1 and 2. Using this migration approach, you can quickly get web providers running on Oracle9iAS Release 2 (9.0.2), and then migrate them to version 2 of the framework at your convenience.

Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1)

This section explains how to migrate a PDK-Java 3.0.9 provider to PDK-Java 9.0 version 1. This migration path does not require any changes to the provider code or provider definition file. The migration primarily involves configuring JServ and declaring the servlet that represents the web provider.

  1. Uncomment the Include directive for the jserv.conf file in ORACLE_HOME_2/Apache/Apache/conf/httpd.conf.

    #include "/ORACLE_HOME_2/Apache/Jserv/etc/jserv.conf"
  2. Edit jserv.conf to set directives as appropriate for how you want to use JServ. (jserv.conf contains Include directives for mod_jserv and mod_oprocmgr, an Oracle module that provides process management and load balancing services.)

    See Also:

    Oracle HTTP Server Administration Guide in the Oracle9i Application Server documentation library.

  3. Edit the ORACLE_HOME_2/Apache/Jserv/etc/ file, if needed.

  4. Edit the ORACLE_HOME_2/Apache/Jserv/etc/ file, if needed.

  5. Perform the following configuration steps to enable JServ and Oracle9iAS Containers for J2EE (OC4J) to coexist.

    You can specify that some applications execute on JServ and some on OC4J. Suppose you have these URLs:

    /application1/file1.jsp to execute on JServ, and

    /application2/file2.jsp to execute on OC4J.

    You must rewrite the URL for application1.

    1. Edit ORACLE_HOME_2/Apache/Apache/conf/httpd.conf and ensure that the following directives are active (uncommented) and present:

      LoadModule rewrite_module libexec/
      RewriteEngine on
    2. Edit ORACLE_HOME_2/Apache/jsp/conf/ojsp.conf to add these directives:

      RewriteRule /application1/(.*)/(.*)\.jsp$ /application1/$1/$2.jsp1
      ApJServAction .jsp1 /servlets/oracle.jsp.JspServlet
    3. Remove this directive:

      ApJServAction .jsp /servlets/oracle.jsp.JspServlet
    4. Edit ORACLE_HOME_2/Apache/Jserv/etc/jserv.conf and mount /servlets to the JVM that will service the JSP requests. Use the ApJServMount or ApJServGroupMount directive (depending on how the JServ processes are started).

  6. Install the products the provider needs.

    • Oracle XML Parser v2 (required)

    • Oracle JSP (required if your provider uses JSPs)

    • Oracle JDBC (required if you use either of the database personalization managers or if your provider needs to access a database)

  7. Install PDK-Java 9.0.x version 1. This is shipped in a zip file located in ORACLE_HOME_2/portal/pdkjava/v1/ You can unzip this file in any location, but this document will assume ORACLE_HOME_2/portal/pdkjava/v1.

  8. Add ORACLE_HOME_2/portal/pdkjava/v1/jpdk/v1/lib/provider.jar to the wrapper.classpath in the ORACLE_HOME_2/Apache/Jserv/etc/ file.

  9. Declare the servlet entries for your providers in your ORACLE_HOME_2/Apache/Jserv/etc/ file. (Copy and paste the servlet entries from ORACLE_HOME_1/Apache/Jserv/etc/ file.)

    The file now resembles that shown in Example 4-5. The following typographical conventions are used in the example:

    • Bold text indicates that a value has changed. Most of the changed values are class names.

    • Bold italics indicate that the structure of the file has changed.The highlighted section may represent removal, addition or modification.

Example 4-5 Sample Provider Definition File After Upgrade to v1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<?providerDefinition version="2.0"?> 
<!DOCTYPE provider [ 
<!ENTITY virtualRoot "/jpdk/"> 
<!ENTITY physicalRoot "E:\9iAS\Apache\Apache\htdocs\jpdk\"> 
<provider class="oracle.portal.provider.v1.http.DefaultProvider"> 
<containerRenderer class="oracle.portal.provider.v1.DefaultContainerRenderer" /> 

<portlet class="oracle.portal.provider.v1.http.DefaultPortlet"> 
<title>Sample Portlet</title> 
<description>PDK-Java version 1 portlet definition</description> 
<timeoutMessage>Sample Portlet timed out</timeoutMessage> 
<renderer class="oracle.portal.provider.v1.RenderManager"> 
<showPage class="oracle.portal.provider.v1.http.JspRenderer"> 
<helpPage class="oracle.portal.provider.v1.http.FileRenderer"> 
<editPage class="oracle.portal.provider.v1.http.Servlet20Renderer"> 
<editDefaultsPage class="oracle.portal.provider.v1.http.Servlet20Renderer"> 
<aboutPage class="oracle.portal.provider.v1.http.FileRenderer"> 
<showDetailsPage class="oracle.portal.provider.v1.http.JspRenderer"> 

Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)

This section outlines the necessary changes to an existing (PDK-Java 3.0.9) provider.

Updating Java classes, Servlets or JSPs

For this section, refer to the JavaDoc for the new framework. The JavaDoc is installed with the PDK-Java sample providers and is accessible at


where host is the name of the computer on which Oracle9iAS Release 2 (9.0.2) is installed and port is the port on which the Oracle HTTP Server is listening.

  1. Change import statements in Java classes and JSPs to reflect the new package organization. The package hierarchy is now more structured with packages organized based on functional areas such as rendering, security, personalization etc.

  2. Replace references to oracle.portal.provider.v1.Provider with oracle.portal.provider.v2.ProviderInstance or oracle.portal.provider.v2.ProviderDefinition, depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method being called.

  3. Replace references to oracle.portal.provider.v1.Portlet with oracle.portal.provider.v2.PortletInstance or oracle.portal.provider.v2.PortletDefinition, depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method being called.

  4. Replace references to oracle.portal.provider.v1.DefaultSecurityManager with

  5. Change the type of variables storing providerId from long to java.lang.String. (The datatype was changed to allow more flexibility in future releases of the API.)

Updating Provider Definition Files (provider.xml)

  1. Replace references to oracle.portal.provider.v1.DefaultProvider with oracle.portal.provider.v2.DefaultProviderDefinition (or your own class that extends oracle.portal.provider.v2.ProviderDefinition).

  2. Replace references to oracle.portal.provider.v1.DefaultPortlet with oracle.portal.provider.v2.DefaultPortletDefinition (or your own class that extends oracle.portal.provider.v2.PortletDefinition).

  3. Replace references to oracle.portal.provider.v1.http.JspRenderer and oracle.portal.provider.v1.http.Servlet20Renderer with oracle.portal.provider.v2.render.http.ResourceRenderer.

  4. Replace JSP/Servlet file references with relative URIs based on the location of the resource (JSP, servlet, or file) within your provider WAR file. See "Packaging and Deploying Your Provider" for a description of the provider WAR file and how it is used to deploy your provider.

  5. (Optional) Replace references to oracle.portal.provider.v1.render.FileRenderer with oracle.portal.provider.v2.render.FileRenderer or oracle.portal.provider.v2.render.http.ResourceRenderer. ResourceRenderer can be used for JSPs, Servlets and static files. However, FileRenderer is recommended for static files because it caches the content of the specified file in memory instead of accessing the file system each time the file needs to be rendered.

  6. Replace v1 personalization managers with the equivalent v2 personalization managers.

    Version 2 of the PDK-Java framework includes two personalization managers:




    PrefStorePersonalizationManager replaces both FilePersonalizationManager and DBPersonalizationManager2, using the new Preference Store functionality. To use the PrefStorePersonalizationManager, you must declare one or more preference stores in your provider definition file. The preference stores can be either file based or database-based. File or database preference stores are compatible with the personalization managers included in PDK-Java 3.0.9.

    If you previously used... Use...


    PrefStorePersonalizationManager in conjunction with a file-based preference store


    PrefStorePersonalizationManager in conjunction with a database preference store



    Declaring a File-based Preference Store

    To declare a file-based preference, use XML similar to that shown below. The rootDirectory should be the same as the that used with the FilePersonalizationManager. If you did not specify a root directory when you declared your FilePersonalizationManager, then rootDirectory should be the same as the provider_root argument passed to the provider servlet. If you want to move your personalization data to a new location, zip or tar the contents of the original root directory (including all the subdirectories) and the unzip or untar into the new location. (The new value for rootDirectory will be the path of the directory into which the data was unzipped or untarred.)


    Declaring a Database-based Preference Store

    To declare a database-based preference store, use XML similar to that shown below. If you are using the DBPreferenceStore, you must declare a datasource in the j2ee/home/config/datasources.xml of the OC4J instance in which your provider will be deployed. The DBPreferenceStore will use JNDI to locate the datasource to use for the preference store.



    Preference stores must be declared inside of the <provider> element at the same level as <portlet> elements.

  7. Replace references to



    The file now resembles the file shown in Example 4-6. The following typographical conventions are used in the example:

    • Bold text indicates that a value has changed. Most of the changed values are class names.

    • Bold italics indicate that the structure of the file has changed.The highlighted section may represent removal, addition or modification.

Example 4-6 Provider Definition File after Upgrade to v2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?providerDefinition version="3.1"?> 
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition"> 
class="oracle.portal.provider.v2.render.DefaultContainerRenderer" /> 
<portlet class="oracle.portal.provider.v2.DefaultPortletDefinition"> 
<title>Sample Portlet</title> 
<description>PDK-Java version 2 portlet definition</description> 
<timeoutMessage>Sample timed out</timeoutMessage> 
<renderer class="oracle.portal.provider.v2.render.RenderManager"> 
<showPage class="oracle.portal.provider.v2.render.ResourceRenderer"> 
<helpPage class="oracle.portal.provider.v2.render.http.FileRenderer"> 
<appRoot>file path</appRoot> 
class="oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager" > 

Packaging and Deploying Your Provider

This section describes the steps necessary to package your provider for deployment. It contains the following topics:

Service Names or Identifiers

With the PDK-Java, you can deploy multiple providers under a single adapter servlet. The providers are identified by a service name or service identifier (equivalent to the SOAP service identifier). When you deploy a new provider, you must assign a service name to the provider and use that service name when creating the provider WAR file.

After deployment, the correct service name must be used when registering your provider in Oracle Portal to ensure that requests are sent to the correct provider. For older releases of Oracle Portal that do not include a service name, you can choose one of your providers to be the default. If the adapter servlet receives a request that does not specify a service name, the request will be forwarded to the default provider.

WAR and EAR Files

WAR (Web Application Archive) and EAR (Enterprise Application Archive) files are standardized mechanisms used to deploy applications in a J2EE application server such as OC4J. The purpose of the WAR and EAR files is to encapsulate all the components necessary to run an application in a single file. This makes deployment simple and consistent across applications, and reduces errors when applications are moved from development to test to production environments.

WAR files include all the components of a web application, including Java libraries or classes, servlet definitions and parameter settings, JSP files, static HTML files and any other resources the application might need.

An EAR file represents an enterprise application. EAR files provide a grouping mechanism for web applications.

Prepare Working Directories

Follow these steps to prepare directories for your WAR and EAR files:

  1. Create a directory named deploy.

  2. Create subdirectories named deploy/ear and deploy/war.

  3. Change directories to deploy/ear.

  4. Unzip the template EAR file into deploy/ear with the command:

    jar -xvf ORACLE_HOME_2/portal/pdkjava/v2/lib/template.ear
  5. Move deploy/ear/template.ear to the deploy directory.

  6. Move deploy/ear/template.war to deploy/war.

  7. Change directories to deploy/war.

  8. Unzip the template WAR file into deploy/war with the command:

    jar -xvf deploy/war/template.war
  9. Move deploy/war/template.war to the deploy directory.

    Two working directories now exist with the structure and files needed to create your own WAR and EAR files.

Specifying the Contents of Your WAR File

To deploy your provider, you first create the WAR file that contains the provider and all the resources it needs to execute. The steps below explain how to do this manually; you can also use a software utility.

  1. Copy any jar files that your provider needs into the deploy/war/WEB-INF/lib directory. This directory already contains the PDK-Java jar files.

  2. If your provider needs any additional Java classes not contained in a .jar file, add them to the deploy/war/WEB-INF/classes directory. Ensure that the class files are saved in a directory structure that corresponds to their Java package names.

  3. Add static HTML files, JSPs and images to deploy/war.


    You can create subdirectories to organize the files. Note that the subdirectories will become part of the URI necessary to access the files. For example, you might create a subdirectory, html, and put all of your static HTML files there. To access a file in that directory called help.html, you would use the URI html/help.html to reference the file in your provider definition file. There is no restriction on the number or depth of these subdirectories.

  4. Create a subdirectory under the providers directory for your provider. The name of the subdirectory will also be the service identifier or name for your provider.

  5. Place your provider definition file in the subdirectory created in the previous step.

  6. Copy the file to and edit it to reflect the provider's configuration.

  7. If you have only one provider in your WAR file, edit so that the configuration settings reflect the default provider (the provider that will be accessed if a service id is not specified in a request from a portal).


    Release 3.0.9 and earlier portals cannot specify a service id, so requests will always be directed to the default provider.

  8. If you use servlets to render content, edit WEB-INF/web.xml to add your servlets to the list of pre-defined servlets. Be careful not to remove the entries for servlets that are required by the PDK-Java.

Specifying Your Default Service

The default service is the provider that should receive any request that does not specify a service name. This feature is provided to allow you to register your provider on release 3.0.9 of Oracle Portal.

The default provider is specified in the file in the deployment directory of your WAR file. The file looks something like this:


  1. Edit the definition= entry so that it points to the provider definition file that for the default provider. The directory path should be based on the contents of the WAR file, not the physical location of the file on the filesystem.

  2. If you are not using a provider definition file to define your provider, you must create an implementation of the ProviderLoader interface and edit the "loaderClass" entry.

Creating a WAR File

Once you have specified the contents of your WAR file, you are ready to create the WAR file itself. Follow these steps to create the WAR file:

  1. Change directories to deploy/war.

  2. Use the following command to create the WAR file:

    jar -cvf warfilename.war

    where warfilename is the name of your WAR file.

Creating an EAR File

Follow the steps below to manually configure an EAR file. You can also use a software utility to create the EAR file.

  1. Change directories to deploy/ear.

  2. Open the META-INF/application.xml file (extracted from the EAR file template into the working directory). The file resembles that shown below:

    <?xml version "1.0"> 
    <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE 
        <display-name>this is the display name of the application</display-name> 
        <description>this is a description of the application</description> 
  3. Change the value of the <display-name> element to the display name for your application.

  4. Change the value of the <description> element so that it describes your application.

  5. Change the value of the <web-uri> element to the name of your WAR file.

  6. Save the application.xml file to its original name and location.

  7. Copy the WAR file created earlier into the deploy/ear directory.

  8. Change directories to deploy/war.

  9. Use the following command to create the EAR file:

    jar -cvf earfilename.ear

    where earfilename is the name of your EAR file.

Deploying the Provider on OC4J

Follow these steps to deploy the provider to OC4J:

  1. Copy the .ear file into your oc4j applications subdirectory (usually ORACLE_HOME/oc4j/j2ee/home/applications).

  2. Add the following to

    <application name="application name" 
     path="../applications/ear file name" /> 

    where application name is the name of the application and ear file name is the name of the .ear file containing the provider.

  3. Bind the web-app to the default site by adding the following to ORACLE_HOME/oc4j/j2ee/home/config/default-web-site.xml:

    <web-app application="application name" 
             name="deployment name" 
             path="/{application path}/" /> 

where application name is the name of the application as specified in server.xml and deployment name is the name associated with this deployment of the application.

  1. Start OC4J.

    The application is automatically deployed based on the information specified in Step 3.

  2. Access the provider using the following URL:

    http://host:port/application path/servlet/soaprouter 

where host is the name of the server hosting the Oracle9iAS listener, port is the port for the Oracle9iAS listener, and application path is the relative URI for the application defined in Step 3. For example:


  • Verify that the provider has been deployed and is accessible. You should see the test page for your default provider (assuming your .properties file specifies debug=1). To view the test page for specific provider service, append the service name to the above URL, for example:

    Registering Your Provider

    Web providers have service names or identifiers as well as a URL. The URL represents the location of the adapter servlet and the service name identifies a provider deployed on that adapter.

    Since service names did not exist in release 3.0.9 of Oracle Portal, the registration process is slightly different.

    Web Cache Cacheability Rules after Mid-Tier Upgrade

    Other than the cache setting changes described here, Oracle9iAS Release 2 (9.0.2) installs Web Cache by default, and Oracle Portal 9.0.2 uses the features of Web Cache.

    When you upgrade a version 3.0.x Portal to Oracle9iAS Release 2 (9.0.2) Portal, or when the middle tier is upgraded before the Portal Repository is upgraded to Oracle9iAS Release 2 (9.0.2), you must set certain cacheability rules in Web Cache to prevent caching of Portal content. When it is cached, the content is no longer secure. This section explains why you must set the cacheability rules, and explains how to do it.


    Migration instructions for the Portal Repository are not included in this document.

    Understanding Web Cache Caching Behavior

    The default cacheability rules for Web Cache in Oracle9iAS Release 2 (9.0.2) include:

    Understanding Portal 3.0.9 Caching Behavior

    Portal version 3.0.9 uses standard HTTP headers to cache "Full Page", images and documents from the database and images from the middle tier in the browser for a predetermined length of time.

    Caching Behavior Using a Release 2 Mid-Tier with Web Cache and Portal 3.0.9 Repository

    When a Release 2 middle tier with Web Cache is used as a front end for a Portal 3.0.9 repository, Web Cache caching rules override Portal caching rules.

    Setting the Cacheabillty Rules

    Two cacheability rules must be set in order to prevent caching of Portal content in Web Cache. These rules prevent caching of any request to:

    Follow these steps to add these cacheability rules:

    1. Go to the Web Cache Administrator page.

    2. Enter administrator for the user name, and the password given by the Web Cache administrator. (The default password is adminstrator.)

    3. Click OK.

      The Web Cache Administration page appears.

    4. In the Navigation frame, General Configuration section, click the Cacheability Rules link.

    5. Click the radio button for the first row of the Site Specific table.

    6. Click the Insert Above button (located at the bottom of the table).

      The Create Cacheability Rule window appears.

    7. Enter /pls/portal30 in the URL expression field. (If the DAD name is other than portal30, enter the DAD name.)

    8. Enter .*(dot asterisk) in the POST Body Expression field.

    9. Ensure that the Don't Cache radio button is selected.

    10. Ensure that Compress is off.

    11. Enter "This ensures that the Portal contents are not cached in Web Cache. Remove this comment as soon as the Portal Repository is upgraded to Release 2. " in the Comment field.

    12. Click Submit.

      The window closes. The first row of the table contains the values you entered.

    13. Click the radio button next to the rule you just added.

    14. Click the Insert Below button (located at the bottom of the table).

      The Create Cacheability Rule window appears.

    15. Enter /servlet/page in the URL expression field.

    16. In the Method field, click the checkboxes for GET and GET with query string.

    17. Ensure that the Don't Cache radio button is selected.

    18. Enter "This ensures that the Portal contents are not cached in Web Cache. Remove this comment as soon as the Portal Repository is upgraded to Release 2. " in the Comment field.

    19. Click Submit.

      The window closes. The second row of the table contains the values you entered.

    20. Repeat the steps above for pls/portal30_sso.

    Migrating the SSL Configuration

    Migrating the SSL configuration is a manual process, consisting of configuring the SSL connections on the Portal page rendering route. Oracle9iAS Portal contains combinations of clients and servers, each of which is secured by an SSL connection. For example, Web Cache and the Parallel Page Engine act as both clients and servers, while the Application Server acts simply as a server.

    Migrating (or re-configuring) the SSL connection in Oracle9iAS Release 2 (9.0.2) involves the steps listed below. The SSL certificate and wallet for the Oracle HTTP Server were prepared by the Oracle9iAS Migration Assistant (see "Migration of SSL Settings"). You can use the certificate from the previous release, unless it is a Global Site ID (which is not supported in Release 2).

    1. Configure Oracle9iAS Web Cache to use the wallet.

      See Also:

      Oracle9iAS Web Cache Administration and Deployment Guide

    2. Configure the Parallel Page Engine (PPE) using the new format for initArgs.

      See Also:

      Example 4-2, "initArgs Parameter in 9.0.2 Format".

    Figure 4-1 SSL Connections in Oracle9iAS Portal

    Text description of portlssl.gif follows

    Text description of the illustration portlssl.gif

    Figure 4-1 shows the communication routes involved in any Portal page rendering. Each SSL connection point is described below:

    Browser to Web Cache SSL Connection

    Web Cache to Oracle9iAS Middle Tier Connection

    Parallel Page Engine (PPE) to Web Cache Connection

    Securing Ports to Use Certificates and HTTPS

    With HTTPS, you use certificates for ports to increase security. To set this up, edit the ORACLE_HOME_2/j2ee/OC4J/applications/portal/portal/WEB_INF/web.xmlweb.xml file.

    You must set up HTTPS such that it is used by all ports at all times. The Parallel Page Engine must be aware of which port(s) are operating under HTTPS.

    Add the following to the web.xml file:


    where the port numbers 433 and 444 are replaced by your HTTPS port configuration. Your server need only have one port, but two are shown here to show the syntax used for multiple entries. Each port in this list operates using the HTTPS protocol, and must have a certificate created on the Oracle HTTP Server on that port.

    Troubleshooting Tips for Portal Migration

    This section describes configuration settings and files that must be present in order for the migrated Portal to work correctly. If you have problems, ensure that the conditions described in this section have been met.

    Configuring Oracle9iAS Release 2 (9.0.2) to Serve Release 1 Image Files

    In order for Oracle9iAS Release 2 (9.0.2) to serve all the static Oracle Portal image files used in your Oracle9iAS Release 1 ( install, you will need to make the following changes to ORACLE_HOME/Apache/Apache/conf/httpd.conf:

    # Configuration information added for Oracle Portal 3.0.9 
    Alias /help/ "/physical/location/of/your/3.0.9/help/files" 
    Alias /images/ "/physical/location/of/your/3.0.9/image/files " 
    <Directory "/physical/location/of/your/3.0.9/image/files" > 
    AllowOverride None 
    Order allow,deny 
    Allow from all 
    ExpiresActive on 
    ExpiresDefault A28800 
    <Files *> 
    Header set Surrogate-Control 'max-age=2592000' 
    <Directory "/physical/location/of/your/3.0.9/help/files" > 
    AllowOverride None 
    Order allow,deny 
    Allow from all 
    ExpiresActive on 
    ExpiresDefault A28800 
    <Files *> 
    Header set Surrogate-Control 'max-age=2592000' 

    Ensuring the Portal EAR File is Present

    Ensure that the portal.ear file exists under ORACLE_HOME_2/j2ee/OC4J_Portal/applications. If it does not, then an incorrect install type was selected to install Oracle9iAS. If you have access to this file, you can just move or copy it to this location; it is not necessary to re-install Oracle9iAS.

    Ensuring JNI Cache Library is Accessibility

    Ensure that the JNI cache library wwjni.jar exists in ORACLE_HOME_2/portal/jlib, and that OC4J is configured to use it. Specifically, verify that ORACLE_HOME_2/j2ee/home/config/application.xml has the line

    "<library_path="../../../lib" /> 

    where the path resolves to the path on which wwjni.jar resides. If it does not, then an incorrect install type was selected to install Oracle9iAS. If you have access to this file, you can just move or copy it to this location; it is not necessary to re-install Oracle9iAS.

    Migrating Oracle Ultra Search

    To migrate from Oracle Ultra Search Release 9.0.1 to Oracle Ultra Search Release 9.0.2, you must run the migration script and perform some manual steps.

    The Ultra Search migration script first verifies the version of the current system, then migrates user data. User data includes all dictionary and table data, such as metadata, data sources, mappings, crawler schedules, authentication, and query statistics.

    All crawler schedules and jobs created in the 9.0.1 system are disabled before data and system migration. When migration is complete, you should re-activate the crawling schedule to re-index the document. You do not need to reconfigure the system or re-enter any data. Users can still query documents that were crawled and indexed by the previous version.

    Migration Approaches for UltraSearch

    There are two approaches to migrate UltraSearch user data: the in-place approach and the ETL (extract-transform-load) approach.

    In-Place Migration

    To migrate using the in-place approach, perform the following steps:

    1. Back up the database, since there is no rollback capability in case of a hardware failure during migration.

    2. Run the SQL script ULTRASEARCH_HOME/admin/wk0upgrade.sql. It takes the following input parameters:

      • SYSPW - password of the user SYS

      • WKSYSPW - password of the user WKSYS

      • HOST - database host machine

      • PORT - database port number

      • ORACLE_SID - database SID

      • WK_TABLESPACE - tablespace for Ultra Search

      • WK_TEMPTABLESPACE - temporary tablespace

      • CONN_STRING - database connect string

      • ORACLE_HOME - path of the Oracle home

      • JAVA_EXE_PATH - Java executable file path

      • PATH_SEPARATOR - Java classpath separator; use : (colon) for UNIX or ; (semicolon) for Windows.

      The script performs the following functions:

      1. Backs up user data.

      2. Uninstalls 9.0.1 database objects.

      3. Installs 9.0.2 database objects.

      4. Recreates user instances.

      5. Restores the data.

    3. Rebuild the index, using the Ultra Search administration tool to re-activate all crawling schedules.

    Extract-Transform-Load Migration

    To migrate using the ETL approach, perform the following steps:

    1. Install the 9.0.2 system in a new Oracle home, either on the same computer or a different computer.


      If the new system is on the same computer, then you must configure the database listener port to be different from that in the 9.0.1 database, so that the new and old database can listen simultaneously.

    2. Recreate user instance schemas and related database objects in the new Oracle home. For each table data source created in 9.0.1, if the base table is located in the local database, then you must copy the base table to the new 9.0.2 database. If the table data source base table is set to a remote database table, then you must recreate the database link from the new 9.0.2 database to the remote database.

    3. Run the SQL script ULTRASEARCH_HOME/admin/wk0migrate.sql. It requires the following input parameters:

      • WKSYSPW - password of the user WKSYS

      • CONN_STRING - database connection string

      • SRC_WKSYSPW - password of the 9.0.1 database user WKSYS

      • SRC_CONN_STRING - source database connection string

      The script performs the following functions:

      1. Recreates user instances.

      2. Restores the data.

    4. Rebuild the index, using the Ultra Search administration tool to re-activate all crawling schedules.

    Migration Logs

    The wk0upgrade.sql and wk0migrate.sql migration scripts for in-place and ETL migration log the actions the migration script has taken. The scripts write the following actions to the log file:

    The log file name for in-place migration is:


    The log file name for ETL migration is:


  • Go to previous page Go to next page
    Copyright © 2002, 2003 Oracle Corporation.

    All Rights Reserved.
    Go To Documentation Library
    Go To Table Of Contents
    Go To Index