Oracle9iAS Portal Developer Kit (PDK)
Using JNDI with PDK Java

Introduction

When writing Java portlets you may have some deployment specific properties you want to set so that their values may be retrieved somewhere inside your provider code. The most efficient way of doing this is to utilize the JNDI service provided buy your J2EE container. This way, any property can be specified in a provider deployment and then easily accessed anywhere in your provider code. The PDK-Java provides utilities to enable the retrieval of both provider specific and non-provider specific JNDI variables within a J2EE container. This document explains how to use JNDI in conjunction with these utilities when building Java portlets.

Declaring JNDI Variables

JNDI variables are declared in the web.xml file for your provider. The format for declaring a JNDI variable is as follows:

<env-entry>
    <env-entry-name>variableName</env-entry-name>
    <env-entry-type>variableType</env-entry-type>
    <env-entry-value>variableValue</env-entry-value>
</env-entry>

The env-entry-name element contains the name by which you want the variable to be identified, env-entry-type contains the fully qualified Java type of the variable (see the section Variable Types, below) and the env-entry-value element will contain the variable's default value.

Variable Types

In the env-entry-type element you should supply the fully-qualified Java type of the variable you are declaring and that will be expected by your Java code. The Java types you may use in your JNDI variables are as follows:

• java.lang.Boolean
• java.lang.String
• java.lang.Integer
• java.lang.Double
• java.lang.Float

The J2EE container uses these type declarations to automatically construct an object of the specified type and gives it the specified value when you retrieve that variable in your code.

Variable Naming Conventions

The PDK-Java defines a number of environment variables that can be set at the individual provider service level or at the web application level. To avoid naming conflicts between different provider services or different application components packaged in the same web application, we recommend that you use the following naming conventions

Provider Service specific names should be of the form:

{company}/{component name}/{provider name}/{variable name}

Shared names should be of the form:

{company}/{component name}/{variable name}

where

• {company} is the name of the company owning the application
• {component name} is the name of the application or component the provider is associated with
• {provider service name} is the service name of the provider
• {variable name} is the name of the variable itself

As you can see, these naming conventions are similar to those used for Java packages. This approach minimizes the chance of name collisions between applications or application components.

The PDK-Java provides utilities (described below) that allow you to retrieve variables in this form without needing to hard-code the service name of the provider into your Servlets or JSPs. The Service name only has to be defined in the provider's WAR file.

Some provider specific variable name examples

oracle/portal/myProvider/myDeploymentProperty

oracle/portal/myprovider/myProperties/myProperty

A provider non-specific example

oracle/portal/myOtherProperty

Setting JNDI Variable Values

In your provider deployment you may want to set a new value for some or all of your JNDI variables. How you do this will depend on whether you are using Oracle Enterprise Manager (OEM), dcmctl, or a standalone OC4J install to deploy your provider

Through OEM

1. In OEM click on the instance where you have deployed the PDK-Java.
2. Click on the name representing this deployment.
3. Under the web modules heading, jpdk will be listed. Click on this.
4. In the administration section at the bottom of the screen, click on the Environment link.
5. Under the environment entries section, all of the environment variables are listed. If it has a default value, this is listed under the value heading. To update a value for a particular variable, enter the new value in the text box in that variable's row.
6. When you have updated all of the variable's values that you want, click on the Apply button at the bottom of the screen.

Manually

This method should be used wherever OEM is not available. Changes to JNDI variable values at deployment should be declared in the PDK-Java's orion-web.xml file. This file can be found in the following location:

For a full IAS install:

{{Oracle Home}}\j2ee\{{OC4J instance}}\application-deployments\jpdk\jpdk

For a standalone OC4J install:

{{Oracle Home}}\j2ee\home\application-deployments\jpdk\jpdk

If the file does not exist then you should create it.

For each deployment property that you want to set a value for, add the following:

<env-entry-mapping name="{{JNDI Variable name}}">{{deployment value}}</env-entry-mapping>

For example, your orion-web.xml might look like this:

<?xml version = '1.0'?>
<!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd">
    <orion-web-app deployment-version="9.0.3.0.0" jsp-cache-directory="./persistence" temporary-directory="./temp" servlet-webdir="/servlet/">
        <env-entry-mapping name="oracle/portal/sample/rootDirectory">D:\prefs</env-entry-mapping>
        <env-entry-mapping name="oracle/portal/sample/definition">D:\definitions\def.xml</env-entry-mapping>
    </orion-web-app>

Retrieving JNDI Variables

JNDI is a standard J2EE technology. As such, you can use standard J2EE APIs to access your environment variables. To access a JNDI environment variable using J2EE APIs, you would use something like this:

String myVarName = "oracle/portal/myProvider/myVar"
String myVar = null;
try
{
   InitialContext ic = new InitialContext();
   myVar = (String)ic.lookup("java:env/" + myVarName);
}
catch(NamingException ne)
{
   ...exception handling logic...
}

PDK Java APIs

In addition to the basic APIs, the PDK Java provides a simple utility class for retrieving the values of variables defined and used by the PDK itself. These variables all conform to the naming convention described above and are of the form:

• oracle/portal/{provider service name}/{variable name}
• oracle/portal/{variable name}

To use these APIs, you only need to provide the information in the braces (the service name and the variable name). The utilities will construct the full JNDI variable name based on the information you provide, lookup the variable using code similar to that included above and return the value of the variable.

The EnvLookup class (oracle.portal.utils.EnvLookup) provides two lookup() methods, one to retrieve provider specific variables and the other for non-provider specific variables. Both methods return a java.lang.Object, which can be cast to the Java type you are expecting.

To retrieve a provider specific variable you can use the following code example. myProviderName represents the service name for your provider that makes up part of the the variable name and the myVariableName parameter represents the portion of the variable name that would come after the provider's service name. The following example assumes the variable being retrieved is of type java.lang.String.

EnvLookup el = new EnvLookup();
String s = (String)el.lookup(myProviderName, myVariableName);

EnvLookup el = new EnvLookup();
Object o = el.lookup(myVariableName);

The PDK-Java will use the following JNDI environment variables if they have been declared. If they have not been declared for a specific provider, the PDK-Java will look for the values in their original locations (web.xml file, deployment properties file etc).

Non-Provider Specific Variables

• oracle/portal/log/logLevel - This is the logging level to be used by the JPDK, and has a default value of 4

Provider Specific Variables

• oracle/portal/sample/showTestPage - Boolean flag that determines if a provider's test page is accessible,defaults to true
• oracle/portal/sample/maxTimeDifference - Provider's HMAC time difference.
• oracle/portal/sample/definition - Location of provider's definition file, provider.xml
• oracle/portal/sample/autoReload - Boolean auto reload flag, defaults to true.
• oracle/portal/sample/sharedKey - HMAC shared key, no default value.
• oracle/portal/sample/rootDirectory - Location for provider customizations, no default value.