Oracle9iAS Portal Developer Kit
Upgrading to PDK-Java v2

This document describes how to upgrade your PDK-Java v3.0.9 provider to PDK-Java v9.0.x. The jump in version numbers reflects the synchronization of version numbers with Oracle9iAS v9.0.2, of which the PDK-Java is a component.

Please review the Release Notes for a detailed description of the changes since release 3.0.9.

Contents

1. Migration Options
2. Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1)
3. Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)
4. Migrating from PDK-Java 9.0.x (v1) to PDK-Java 9.0.x (v2)

Migration Options

PDK-Java 9.0.x includes two versions of the PDK-Java framework known as version 1 (v1) and version 2 (v2). 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 must run in the JServ servlet container. Version 2 lets you create web providers that run in the new, J2EE compliant, OC4J servlet container. In addition to J2EE support, version 2 of the PDK-Java framework has been modified to make the framework more object-oriented and easier to extend in future releases without impacting web providers that were built using earlier releases. 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 version 2 of the framework.

Since there are now two versions of the framework, there are 3 migration options. The options are:

1. Migrate from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1)
2. Migrate from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)
3. Migrate from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1) and then migrate to PDK-Java 9.0.x (v2)

Option 1 is the easiest because it does not require any changes to your existing web providers. However, you must configure the JServ servlet container in Oracle9iAS. This approach allows you to migrate to Oracle9iAS 9.0.x and get your existing web providers up and running in the shortest time. However, you will not be able to use any of the features of OC4J or version 2 of the PDK-Java framework.

Option 2 requires a little more work, because your web providers need to be modified to use the new framework. For most web providers, the changes you need to make are relatively straightforward, involving modifying the import statements in your Java classes and changing the classes used for some method calls. Generally, all the methods that existed in version 1 of the framework are still there and their function has not changed but the class they are contained in may have changed. Even though option 2 requires a little extra work, once you have completed the conversion you will be able to take advantage of the features of the OC4J servlet container and the new features/functionality included in version 2 of the framework. In the future, new features will only be added to version 2 of the framework.

Option 3 combines both options 1 and 2. Using this migration approach, you can quickly get your web providers up and running on Oracle9iAS 9.0.x and then migrate indiviual providers to version 2 of the framework at your convenience.

The remainder of this document describes each of the migration options in detail.

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

This section outlines the changes you will need to migrate a PDK-Java 3.0.9 provider to PDK-Java 9.0 (v1). 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 your web provider.

> 1. configure Oracle9iAS to use JServ. Refer to the Oracle9iAS Configuration Guide for details.
> 2. install the dependent products your 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

> > For installation instructions, Refer to the Installation Guide for each component

> 3. install PDK-Java 9.0.x version 1. This is shipped as a zip file in a similar format to PDK-Java 3.0.9. The zip file is located in $ORACLE_HOME/portal/pdkjava/v1/jpdkv1.zip . You can unzip this file in any location. For the purposes of this document, it is assumed that you will unzip the file into $ORACLE_HOME/portal/pdkjava/v1
> 4. add $ORACLE_HOME/portal/pdkjava/v1/jpdk/v1/lib/provider.jar to the wrapper.classpath in jserv.properties .
> 5. declare the servlet entries for your providers in your zone.properties file. You should be able to cut & paste the servlet entries from your existing zone.properties file to the new one.

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

This section outlines the changes you will need to make to an existing (PDK-Java 3.0.9) provider.

### Update Java classes, Servlets and JSPs

For this section you will most likely need to refer to the JavaDoc for the new framework. The JavaDoc is installed with the PDK-Java sample providers and should be accessible at the following URL: http://<host>:<port>/jpdk/apidoc where <host> is the name of the computer on which Oracle9iAS 9.0.x is installed and <port> is the port number the HTTP listener has been configured to listen on. The PDK-Java (v2) samples are installed automatically when you install Oracle Portal.

> 1. change import statements in Java classes and JSPs to reflect 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 you are calling.
> 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 you are calling.
> 4. 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.

> Update 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/file) within your provider’s WAR file. Review Packaging Your Provider for Deployment for a description of the provider WAR file and how it is used to deploy your provider.
> 5. 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 can read files in any character set and after reading the file it caches it in memory, rendering subsequent requests from memory.
> 6. replace v1 personalization managers with the equivalent v2 personalization managers.

>    Version 2 of the PDK-Java framework includes two personalization managers oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager and oracle.portal.provider.v2.personalize.DBPersonalizationManager. PrefStorePersonalizationManager replaces both FilePersonalizationManager and DBPersonalizationManager2, utilizing 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 the personalization managers included in PDK-Java 3.0.9

>    If you previously used:

>    - FilePersonalizationManager, use PrefStorePersonalizationManager in conjunction with a file-based preference store
>    - DBPersonalizationManager2 use PrefStorePersonalizationManager in conjunction with a database preference store
>    - DBPersonalizationManager use oracle.portal.provider.v2.personalize.DBPersonalizationManager

> > To declare a file based preference, use the following XML.

> > > <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> > > <name>prefStore1</name>
> > > <rootDirectory>d:\root\directory</rootDirectory>
> > > <useHashing>true</useHashing>
> > > </preferenceStore>

> > The <rootDirectory> should be the same as the <rootDirectory> you 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, simply zip or tar up the contents of the original root directory (including all the subdirectories) and unzip or untar into the new location. The new value for <rootDirectory> will the the path of the directory into which the data was unzipped/untarred.

> > To declare a database-based preference store, use the following XML.

> > <preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">
> > <name>prefStore2</name>
> > <connection>oc4jDataSourceName</connection>
> > <table>databaseTableName</table>
> > </preferenceStore>

> > 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 it should use for the preference store
> > Preference stores must be declared inside the <provider> element at the same level as <portlet> elements.

> Provider Definition Files Before and After Upgrading

> > The Following section shows two provider definition files, the first from PDK-Java 3.0.9 and the second from PDK-Java 9.0.2 version 2. The highlighted areas show where there are differences between the 2 files.
> > Areas that are bold indicate that a value has changed. Most of these values are class names.

> > Areas that bold/italic indicate that the structure of the file has changed. The highlighted section may represent removal, addition or modification.

> > Sample Provider Definition File from PDK-Java 3.0.9

> > <?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 ">
> > <session>true</session>
> > <containerRenderer class="oracle.portal.provider.v1.DefaultContainerRenderer " />
> > <portlet class="oracle.portal.provider.v1.http.DefaultPortlet ">
> > <id>1</id>
> > <name>samplePortlet</name>
> > <title>Sample Portlet</title>
> > <shortTitle>Sample</shortTitle>
> > <description>PDK-Java version 1 portlet definition</description>
> > <timeout>10</timeout>
> > <timeoutMessage>Sample Portlet timed out</timeoutMessage>
> > <hasHelp>true</hasHelp>
> > <hasAbout>true</hasAbout>
> > <showDetails>true</showDetails>
> > <showEdit>true</showEdit>
> > <showEditDefault>true</showEditDefault>
> > <acceptContentType>text/html</acceptContentType>
> > <renderer class="oracle.portal.provider.v1.RenderManager ">
> > <appPath>&virtualRoot;samplePortlet</appPath>
> > <appRoot>&physicalRoot;samplePortlet</appRoot>
> > <contentType>text/html</contentType>
> > <showPage class="oracle.portal.provider.v1.http.JspRenderer">
> > <name>showPage.jsp</name>
> > </showPage>
> > <helpPage class="oracle.portal.provider.v1.http.FileRenderer">
> > <name>help.html</name>
> > </helpPage>
> > <editPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
> > <servletClass>your.package.EditServlet</servletClass>
> > </editPage>
> > <editDefaultsPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
> > <servletClass>your.package.EditServlet</servletClass>
> > </editDefaultsPage>
> > <aboutPage class="oracle.portal.provider.v1.http.FileRenderer">
> > <name>about.html</name>
> > </aboutPage>
> > <showDetailsPage class="oracle.portal.provider.v1.http.JspRenderer">
> > <name>details.jsp</name>
> > </showDetailsPage>
> > </renderer>
> > <personalizationManager class=" oracle.portal.provider.v1.FilePersonalizationManager">
> > <dataClass>your.package.DataClass</dataClass>
> > <useHashing>true</useHashing>
> > </personalizationManager>
> > <securityManager class="oracle.portal.provider.v2.security.DefaultSecurityManager ">
> > <authLevel>STRONG</authLevel>
> > </securityManager>
> > </portlet>
> > </provider>

> > Sample Provider Definition File after following above steps

> > <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
> > <?providerDefinition version="3.1"?>
> > <provider class="oracle.portal.provider.v2.DefaultProviderDefinition ">
> > <session>false</session>
> > <containerRenderer class="oracle.portal.provider.v2.render.DefaultContainerRenderer" />
> > <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> > <name>prefStore1</name>
> > <rootDirectory>d:\root\directory</rootDirectory>
> > <useHashing>true</useHashing>
> > </preferenceStore>

> > <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition ">
> > <id>1</id>
> > <name>samplePortlet</name>
> > <title>Sample Portlet</title>
> > <shortTitle>Sample</shortTitle>
> > <description>PDK-Java version 2 portlet definition</description>
> > <timeout>10</timeout>
> > <timeoutMessage>Sample timed out</timeoutMessage>
> > <hasHelp>true</hasHelp>
> > <hasAbout>true</hasAbout>
> > <showDetails>true</showDetails>
> > <showEdit>true</showEdit>
> > <showEditDefault>true</showEditDefault>
> > <acceptContentType>text/html</acceptContentType>
> > <renderer class="oracle.portal.provider.v2.render.RenderManager ">
> > <contentType>text/html</contentType>
> > <showPage class=" oracle.portal.provider.v2.render.ResourceRenderer">
> > <resourcePath>/jsps/showPage.jsp</resourcePath>
> > </showPage>
> > <helpPage class="oracle.portal.provider.v2.render.http.FileRenderer">
> > <appRoot>d:\this\is\the\file\path</appRoot>
> > <name>help.html</name>
> > </helpPage>
> > <editPage>/servlet/editServlet</editPage>
> > <editDefaultsPage>/servlet/editServlet</editDefaultsPage>
> > <aboutPage>/htdocs/submitServlet/about.html</aboutPage>
> > <showDetailsPage>/jsps/showDetails.jsp</showDetailsPage>
> > </renderer>
> > <personalizationManager class=" oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager " >
> > <dataClass>your.package.DataClass</dataClass>
> > </personalizationManager>
> > <securityManager class="oracle.portal.provider.v2.security.AuthLevelSecurityManager ">
> > <authLevel>STRONG</authLevel>
> > </securityManager>
> > </portlet>

> > </provider>

> > Package and Deploy Your Provider

> > The final step in the migration process is to package and deploy your provider. Please refer to Packaging Your Provider for Deployment for detailed instructions regarding packaging and deploying your provider on the OC4J platform.

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

Migrating from PDK-Java 9.0.x (v1) to PDK-Java 9.0.x (v2) requires that you follow the steps described in the section Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)

Revision History:

- August 24, 2001 Created
- March 18, 2002 Updated