Option 1 is the easiest because it does not require any changes to your existing web providers, since the PDK-Java 9.0.4 API is completely backward compatible with PDK-Java 9.0.2.x (v2).

Options 2 and 3 require 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 the 9.0.4 version of the framework.

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

Migrating from PDK-Java 9.0.2.x (v2) to PDK-Java 9.0.4 and later

Because the PDK-Java 9.0.4 API is completely backward compatible with PDK-Java 9.0.2.x (v2), this should be the most straightforward of the migration paths. However, because PDK-Java 9.0.4 requires Oracle AS 9.0.4, the main task is to migrate enterprise applications from the older application server to the newer one.

If you have the original .ear file for the provider application you want to migrate, migration may be a simple matter of deploying the .ear file on your new OracleAS mid tier. However, in some cases the original .ear file alone is not enough, as there are certain types of Provider that add extra meta data to their web applications after deployment. Examples of such providers are:

• Web Providers built through the Portal UI
• Customizable Providers configured with the default settings for FilePreferenceStore, where customization data is written under the WEB-INF directory of the provider itself.
• Providers customized by the user after deployment, e.g where edits have been made to .jsp files inline.

To get around this problem, PDK-Java provides the Transporter utility, which can be used to repackage a deployed application back into EAR file format, complete with any web app content and meta data that has been added or changed since deployment. To use it, enter the following command:

java -classpath $dest_oracle_home/portal/jlib/pdkjava.jar oracle.webdb.provider.v2.tools.Transporter $source_oracle_home/j2ee/$oc4j_instance/applications/$application_name $destination_ear_file

where:

• $dest_oracle_home is the root directory of the Oracle AS installation to which you want to migrate the application
• $source_oracle_home is the root directory of the Oracle AS installation containing the application to be migrated
• $application_name is the name of the application to be migrated
• $oc4j_instance is the name of the target OC4J instance with PDK-Java installed that the application should be deployed into (e.g. OC4J_Portal).
• $destination_ear_file is the full path to your EAR file on the filesystem

This should result in a new EAR file being written to $destination_ear_file, complete with any extra data added to the application since deployment.

For example:

java -classpath D:\as904\portal\jlib\pdkjava.jar oracle.webdb.provider.v2.tools.Transporter D:\ora9ias\j2ee\OC4J_Portal\applications\jpdk D:\jpdk-rezipped.ear

To complete the migration, you simply need to take the following steps

Migrating from PDK-Java 9.0.2.x (v1) to PDK-Java 9.0.4 and later

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)

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 OracleAS 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 OracleAS 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. replace references to oracle.portal.provider.v1.DefaultSecurityManager with oracle.portal.provider.v2.security.AuthLevelSecurityManager
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.

Update Provider Definition Files (provider.xml):

1. replace references to oracle.portal.provider.v1.http.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.http.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 and Deploying Your Providers 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
• 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 the equivalent v2 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.

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