Chapter 8 Integrating with Sun Java Portal Environment 7.1

The WDK environment package contains APIs that enable WDK to operate on J2EE application servers, JSR-168 compliant portal servers, or non-JSR-168 compliant portal servers. Environments are provided for J2EE standalone Web applications and for several JSR-168 compliant portal servers.

For certified J2EE application servers, refer to Web Development Kit Release Notes. For certified portal servers, refer to WDK for Portlets Release Notes.

The following topics describe the configurable and customizable environments in WDK:

Where to Integrate WDK into a Portal

If you are using a portal that is listed in the certification table of the WDK for Portlets release notes, your portal environment is provided by the installer and you can simply use Documentum portlets and components in your application after running the installer.

If you are using a JSR-168 compliant portal that does not have an environment provided by Documentum, you must extend the Jsr168Environment class and provide methods that write user preferences using the portal-specific APIs. For an example, refer to Writing user-level preferences. If you are using a portal that is not JSR-168 compliant, you must extend the PortalEnvironment class and provide methods that both read and write user preferences. For examples, refer to Writing user-level preferences and Reading user-level preferences

Environment Classes

The environment layer is a set of classes in the com.documentum.web.env package that comprise base implementations, hooks and interfaces. The Environment class encapsulates an environment's specific behavior and functionality. WDK instantiates and uses the registered environment class whenever it requires information from its environment.

A portal-specific environment is implemented as a single Java class that extends the abstract Environment class and implements one or more of the com.documentum.web.env interfaces. WDK environments are packaged in com.documentum.web.env.xxx where xxx is the name of the environment; for example, com.documentum.web.env.sun.

WDK instantiates an environment as a singleton object, and all threads call into the single instance. All methods implemented for a custom environment must be thread-safe. If you need to store state, the base Environment class provides instance methods to store and retrieve your attributes in the environment implementation.

The environment layer of WDK consists of a set of classes that provide a number of starting places for your integration depending on the type of portal server you have. The environment APIs are shown in the diagram below.

Figure 8–1 Environment APIs

The environment classes are the following:

AbstractEnvironment class

The AbstractEnvironment class is abstract and provides default implementations of environment APIs.

Environment class

The Environment class is also abstract. It extends AbstractEnvironment and adds default implementations for session and request access, dispatching, encryption, and portal API access.

---

Note –

Many of these APIs must be overridden for specific portals.

---

AppServerEnvironment class

The AppServerEnvironment Class provides a configured environment for integrating with J2EE Application Servers.

PortalEnvironment class

The PortalEnvironment class provides a configured environment for non-JSR-168 compliant portal servers. If you are integrating with a non-JSR-168 compliant Portal Server then you should extend the PortalEnvironment class.

Jsr168Environment class

The Jsr168Environment class provides a configured environment for integrating with JSR-168 compliant portal servers.

SunPortalEnvironment class

The SunPortalEnvironment Class integrates with the Sun Portal Server. (For specific versions, refer to the release notes.)

AbstractEnvironment Class

The AbstractEnvironment class provides a set of methods that return the environment interface contracts. The AbstractEnvironment class returns whether the environment is a Portal environment using the isPortalEnvironment() method. The current HttpServletRequest, HttpServletResponse, and HttpSession are returned from the getRequest(), getResponse(), and getSession() methods.

Environment Class

The Environment class is also an abstract class and cannot be instantiated directly. The Environment class provides default implementations for the lifecycle events, security, error handling, page dispatching, action processing, content transfer, branding, environment properties, and attribute storage. These implementations should be sufficient for most environments:

Lifecycle

The lifecycle methods store the request, response and session objects in thread safe storage. If you are overriding any of these methods and you need to continue to store the objects in the thread safe storage, then you must call the superclass implementation.

Security

The security methods encode and decode passwords and encrypt and decrypt the trusted authenticator password using a Caesar cipher. For details on trusted authentication, refer to User principal authentication. Methods also get the user name, password, and domain.

Error Handling

The error methods get the error URL and handle errors.

Page Dispatching

Page dispatching methods include forward and inline dispatch and access to the object. By default, pages are included and actions are processed before the page is rendered.

Action Processing

The queryExecute() method is provided to test action preconditions

Content Transfer Mechanism

The content transfer method returns the content transfer mechanism, which is UCF-based by default in portal environments.

Branding

The Environment class looks for mapping of WDK CSS classes to portal styles. For details on this mapping, refer to Portal styles

Environment Properties

The getResourceBundle() method returns the properties file that configures the environment.

Attribute Storage

Attribute storage methods get, set, and remove attributes from the environment's thread-safe local store. A log() method is also provided.

AppServerEnvironment Class

The AppServerEnvironment class inherits from Environment. The AppServerEnvironment class is used by WDK for non-portal J2EE applications such as Webtop. This class includes all of the implementations for running on a J2EE environment.

For backwards compatibility with previous versions of WDK, the following implementations are in the AppServerEnvironment class:

• The encodeUrl() method returns the full path to the JSP page that is to receive the next post-server event.

• The implementations of the IPreference interface hook into the WDK HTTP cookie store used in previous versions of WDK.

PortalEnvironment Class

The PortalEnvironment class inherits from Environment and serves as the superclass for all portal environment implementations. You can extend this class to support WDK portlets on a non-JSR-168 compliant portal server.

The following methods are implemented:

preprocess()

Turns on pre-processing.

encodeUrl()

Removes the action URL in order to force all server events to be posted through the component dispatcher.

handleError() and errorAcknowledged()

Report errors to the WDK's error message service and handles the user event that is generated when the user acknowledges an error dialog.

postProcess()

Turns on post-processing.

Jsr168Environment Class

The Jsr168Environment class inherits from PortalEnvironment. You can extend Jsr168Environment to integrate WDK portlets into a JSR-168 compliant portal server that does not have an environment supplied by Documentum. The following methods are implemented:

Lifecycle events

The onRequestStart() and onRequestFinish() methods provide access to the request events

Session access

The getUsername(), getUserPassword(), getDomain(), getDocbaseName(), getUserPrincipal(), and getLocale() methods provide access to the user's portal session.

Pre-processing

The preProcess() method turns on pre-processing.

URL encoding

The encodeUrl() method returns a JSR-168 action URL.

JavaScript rewriting

The namespaceJsMethodName() method changes the supplied JavaScript function name to a name unique within the generated web page by prefixing that function with the portlet ID. The rewriteScriptTag() method prefixes the portlet ID to a supplied JavaScript function name.

Link rewriting methods

The rewriteATag() method rewrites the href and onclick attributes in a JavaScript call to prefix the call with the portlet ID. This gives the JavaScript call a unique name in the scope of the whole web page that is generated.

Preferences methods

Several methods enumerate preferences and look up or write preference values (user-level or portlet-level, or application-level). The Jsr168Environment class handles the writing of Portlet level preferences through the writePortletLevelPreference() method. The writing of user level preferences is not covered by the JSR-168 specification: They are written by vendor-specific environment classes.

Error methods

The getErrorUrl() method handles errors in a JSR-168 environment, passing the error to the stack trace.

SunPortalEnvironment Class

The SunPortalEnvironment class inherits from Jsr168Environment. The SunPortalEnvironment integrates with the Sun portal server. (For specific versions refer to the release notes.) This class implements the following methods:

getUserPrincipal()

Looks up the user principal for trusted authentication mode using classes in the com.iplanet.sso package.

getWriteModePreferenceScopes()

Returns an enumeration of the preference types that can be written.

getNamespace()

Uniquely identifies the HTML for two portlets on the same page in a Sun portal environment.

writeUserLevelPreference()

Writes preferences using APIs in the com.iplanet.am.sdk package.