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)

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.