Welcome to the PDK Services for Java. The PDK Services for Java include the tools and documentation to build Web portlets. This download includes the PDK Services for Java and Web Provider samples to help you get started. Included in the PDK Services for Java is the provider framework. Your portlets will use this framework and build upon it. For more information on the Web Provider framework, refer to the PDK documentation on Web Providers.

This document is an installation and configuration guide to install the JPDK samples. This document explains:

• How to setup and configure the Oracle HTTP Server to run the JPDK.
• How to setup the Oracle HTTP Server to run the samples included in this download.
• How to setup and configure the Oracle HTTP Server to run your own portlets.

Contents

This section describes the contents of the JPDK download. There are five main folders and two important documentation files and each is described below.

Folders

• doc: Contains Java documentation for all the class files in the download. The file to view is index.html.

• htdocs: Contains the jsp files, images, and html needed for the portlet samples.

• lib : Contains jar files: provider.jar and samples.jar. The provider.jar file contains the class files of the provider framework. The samples.jar file contains the class files used by the sample.

• provider : Home directory of the providers. provider.xml is stored in the directory called 'sample', located below provider.

• src: Source code for the provider runtime and the samples.

Documentation

• releasenotes.html: Requirements and pre-installation notes.

• installing.jpdk.html: This document.

Preparation

JPDK requires the use of Oracle XML and Oracle JSP. Normally, both of these are configured during the installation of iAS. If you are using a version of Apache/iAS where Oracle XML and JSP are not already configured, you can download them from Oracle Technology Network  and configure them by following the instructions.

IMPORTANT: If you are using the version of the Oracle HTTP Server that came with Oracle9iAS Portal 3.0.6.3.3 (Early Adopters Release), you MUST install the files located in the patches directory for these samples to work. If you are using a production version of Oracle9iAS Portal (3.0.6.6.5, 3.0.7.6.2), disregard the instructions below.

These instructions assume you installed Oracle9iAS Portal in D:\oracle\iSuites\. The patches are as follows:

1. ojsp.jar . Version ojsp1.1 comes standard with Oracle9iAS Portal production. Make sure that you have at least ojsp1.1 installed with your Oracle HTTP Server. If you have an older version, you may download the newest OJSP from Oracle Technology Network.

2. Parallel.jar. If you see 302 errors in the samples provided (specifically when applying end-user customizations), make a backup copy of and replace D:\oracle\iSuites\Apache\Jserv\servlets\Parallel.jar with the version of Parallel.jar in the patches directory. Note : If the listener used for the JPDK is different from the Oracle9iAS Portal listener, please place the Parallel.jar within the listener where Oracle9iAS Portal is installed.

This article is based on the Oracle HTTP Server powered by Apache and assumes the following:

1. You have already configured the Oracle HTTP Server to use the Oracle XML Parser (version 2). Most often, the Oracle HTTP Server is already configured for this. Verify that the XML parser has been added to the Jserv classpath in the jserv.properties (in D:\oracle\iSuites\Apache\Jserv\conf) file.

   For example: wrapper.classpath=D:\oracle\iSuites\xdk\lib\xmlparserv2.jar

2. You have already configured the Oracle HTTP Server to use JSP (Java Server Pages). You have also tested JSPs by calling a JSP page using Oracle9iAS. Verify that ojsp.jar has been added to the Jserv classpath in the jserv.properties file.

   For example: wrapper.classpath=D:\oracle\iSuites\jsp\lib\ojsp.jar

3. You have extracted the JPDK download to D:\jpdk. This D:\jpdk directory should contain this file as well as the subdirectories listed above. The steps within this article will reference these directories. Please adjust if you have extracted to UNIX or to different directories.

Setup

Backing up Files

This section will update two Oracle HTTP Server configuration files. The jserv.properties is located at: %ORACLE_HOME%\Apache\Jserv\conf on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX. The zone.properties is located at %ORACLE_HOME%\Apache\Jserv\servlets on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX.

Note: We recommend that you back up both these files prior to making changes

Configuring the Web Provider Framework

1. Stop your Web listener, i.e. Oracle HTTP Server.

2. In jserv.properties, add the following to the section containing the wrapper.classpath statements.

   wrapper.classpath=D:\jpdk\lib\provider.jar

Configuring the Web Provider Sample

1. In jserv.properties, add the following to the section containing the wrapper.classpath statements.

   wrapper.classpath=D:\jpdk\lib\samples.jar

2. Save and close jserv.properties.

3. Open zone.properties. This document uses the root zone which has a virtual path of "/servlets". For manageability, you may choose to use a different zone.

4. Under the Servlet Aliases section, add the alias that points to the Provider Adapter:

   servlet.sample.code=oracle.portal.provider.v1.http.HttpProvider

5. Under the Aliased Servlet Init Parameters section, add the initial arguments needed by the sample. This points the Adapter (sample) to the location of the provider.xml file. Make sure you modify the directory section to point to the correct location of the provider.xml file.

   servlet.sample.initArgs=provider_root=D:\jpdk\provider\sample, sessiontimeout=1800000

   Note : Sessiontimeout must match the session.timeout setting located in the zone.properties of your Apache listener. Both settings are specified in milliseconds. Please review the release notes of the JPDK download for more information on these arguments.

6. Save and close zone.properties.

7. Create a JPDK directory in the default JSP directory for your listener. For example, if your default directory is D:\oracle\iSuites\Apache\Apache\htdocs, create a directory D:\oracle\iSuites\Apache\Apache\htdocs\jpdk.

8. There are a number of JSP directories located within the jpdk. Copy all the folders beneath the D:\jpdk\htdocs directory to the directory you just created.

9. Modify the following entry which is located at the top of the provider.xml to point to the correct location of your JSP directories.

<!DOCTYPE provider [

<!ENTITY virtualRoot "/jpdk/">

<!ENTITY physicalRoot "E:\9iAS\Apache\Apache\htdocs\jpdk\">

]>

For example if you placed your JSP directories in: D:\oracle\iSuites\Apache\Apache\htdocs\jpdk\, then the entry would be as follows:

<!DOCTYPE provider [

<!ENTITY virtualRoot "/jpdk/">

<!ENTITY physicalRoot "D:\oracle\iSuites\Apache\Apache\htdocs\jpdk\">

]>

10. Save and close the provider.xml file.

Testing the sample

You can test that you have properly setup the sample by using Oracle 9iAS.

1. Start your Oracle 9iAS listener.

2. Execute the sample from the Oracle 9iAS listener. This refers to the listener where you configured your sample.

   For example: http://myserver.mydomain.com:port/servlets/sample

3. You should receive a test page informing you that the sample worked. If you did not receive the test page, verify that you can execute standard servlets using Oracle 9iAS. Then, verify all the steps within the SETUP section.

Registering the Provider

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

1. Under the Administer tab (on Oracle Portal home page), click on Add a Portlet Provider within the portlet called Provider.

2. Fill out Provider information for the Sample.

   1. Name: SampleWebProvider

   2. Display Name: Sample Web Provider

   3. Timeout: 100

   4. Timeout Message: Application Timed Out

   5. Implementation Style: Web

   6. Provider Login Frequency: Once per User Session

   7. Register on Remote Nodes: No

   8. URL: http://myserver.mydomain.com:port/servlets/sample (replace this with your URL)

   9. Check the following radio button: The user has the same identity in the HTTP providers application as in the Single Sign-On identity.

   10. Proxy: No (As long as no proxy is required to contact the Provider Adapter).

3. Click OK.

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

Adding the Portlet to a Page

1. Add any of the sample portlets listed under the Provider called "SampleWebProvider" to the portal page. Please refer to Oracle9iAS Portal online documentation for more information on adding portlets to a page.

You have now successfully installed and setup the Web provider samples. The next section is optional and describes how to easily configure your own sample.

Configuring Your Web Provider and Portlets

Configuring your own Web provider is easy.

1. Create your own portlet. For example, create a JSP sample and test the execution using Oracle9iAS.

2. Place that sample in a directory under the default directory for Oracle9iAS.

3. Create a new provider.xml to point to your new portlet.

4. Create a new directory to store your provider.xml.

5. Create a new alias to point to the same Provider Adapter in the Servlet Aliases section of zone.properties.

6. Create a new entry in the Aliased Servlet Init Parameters section of zone.properties to point the "provider_root" to this new directory.

7. Create a new alias to point to the same Provider Adapter in the Servlet Aliases section of zone.properties.

8. Test your sample with the new alias name.

9. Register your new provider with Oracle9iAS Portal.

For detailed information on building your own Web portlet, please review How to Build a Web Portlet. Also, the PDK Services for Java include a separate Subscriber ID Provider sample. This sample demonstrates portal-based subscription billing. For detailed information on installing and configuring this sample, please review Installing the Subscriber ID Sample.

Web Provider Configuration Options

There are a number of configuration options available for you to use with any web provider. These options are specified as initArgs to your provider servlet in your zone.properties file. The available options are:

• provider_root
• provider_definition
• debuglevel
• show_test_page
• sessiontimeout
• auto_reload
• reload_interval

provider_root

This specifies the location, in the form of a directory path, of your provider definition file and is the default root directory for storing any file based customization data.

provider_definition

This specifies the name of your provider definition file. The default name is "provider.xml"

debuglevel

debuglevel controls the logging that the PDK-Java performs. The valid values are:

• less than zero or not specified - logging is disabled
• 0 (zero) - performance logging is enabled. Performance logging will result in 1 log message per portlet request that includes performance statistics for that request
• 1 - debug logging enabled. Provider test page is also enabled
• 2 - fine-grained debug logging enabled. This is the most detailed level of logging that is availble. The main difference between this and level 1 is that the contents of SOAP messages are dumped to the logs

show_test_page

Controls the display of the provider's test. The valid values are:

• < 1 - test page is disabled. Attempting to access the test page will result in a 403 Forbidden message
• 1 - test page is enabled
• 2 - test page is enabled. If an error is encountered while loading a provider definition, a stack trace will be included after the error message

sessiontimeout

sessiontimeout specifies the timeout period for HTTP Sessions. This value should be the same as the servlet session timeout specified in the zone.properties file.

auto_reload

Controls whether auto-reload of provider definitions is enabled. When disabled, the default, provider definitions are loaded once, when the provider starts up. Any changes to the provider definition require the server to be bounced before they are "seen". If auto-reload is enabled, the provider will periodically compare the last modified date of the provider definition file it has in memory with that of the file on disk. If the definition has been modified since it was last loaded, the new definition will be automatically loaded.

This feature used to be controlled by performing a portlet repository refresh, but this mechanism did not work well in load balanced environments so a timer based approach in now used (since 3.0.9.8.5A)

reload_interval

Specifies the time interval (in milliseconds) between comparing the definition in memory with that on disk. The default interval is 5 minutes (300000ms)

Revision History:

• April, 2001

• April, 2003 - added configuration options