Working with JSR 168 Portlets

This chapter provides overviews of JSR 168 and PeopleSoft compliance with JSR 168, and discusses how to:

Configure the portlet container.
Create portlet applications for Oracle application server deployment.
Describe the portlet entity registry.

Understanding JSR 168

JSR 168 is an emerging standard for portals running in a Java 2 Platform, Enterprise Edition (J2EE) architecture. It specifies content definitions much like pagelets, called portlets, that present portal content defined according to the JSR 168 standard. Portlets are Java-based web components that you can register in the PeopleSoft portal just as you register pagelets. Both HTML templates and frame templates support portlet content.

Portlets generate fragments of markup (such as HTML, Extensible HyperText Markup Language, and Wireless Markup Language). The PeopleSoft portlet engine manages and invokes portlets by using Java programs. This combines markup fragments that are generated by different portlets into a portal page.

You develop your own Java-based JSR 168 compliant portlets, and then register them by using the PeopleSoft portal registration components.

You expose your locally installed portlets to remote WSRP consumers by creating entries in the portal entity registry.

See Describing the Portlet Entity Registry.

Understanding PeopleSoft Compliance with JSR 168

This section discusses:

Java Portlet API
Window states.
Content caching.
Portlet modes.

Java Portlet API

Portlets obtain their context via the Portlet API- functions like access to user profile information for the current user, participation in the portal window and action event model, access to web client information, sharing of information with other portlets and a standard way of storing and retrieving per-user/per-instance portlet data persistently. PeopleTools portlet container supports the Java Portlet API 1.0. The Java Portlet API provides a URL-rewriting mechanism for creating links to trigger actions within a portlet without requiring knowledge on how URLs are structured in the particular web application. Portlets are grouped in a Portal Application by bundling them in a single web application archive file (WAR) with a Portlet deployment descriptor file. In addition, the API provides a mean for sharing data among portlets of the same Portal Application.

Window States

The PeopleSoft JSR 168 engine accepts all of the required as well as any custom window states. However, although we allow any window state, PeopleSoft does not react to them. Portlets always appear to have a Normal amount of screen real-estate.

Content Caching

In the current release, the PeopleSoft JSR 168 engine doesn't support the caching of portlet content based on caching elements that are embedded in the portlet; any caching tags in the portlet are ignored. However, the engine does support caching by using the PSCACHECONTROL content reference attribute.

See Implementing Pagelet Caching.

Portlet Modes

The PeopleSoft JSR 168 engine supports all of the required portlet modes, which are:

VIEW
EDIT
HELP

Configuring the Portlet Container

If the logClientIPOnMalformedRequest initialization parameter is set to true, it will log the address of clients making failed attempts to access the Java portlets (due to malformed URLs).

If the AccessJavaPortletsFromPeopleSoftPortalOnly initialization parameter is set to true, only clients who have their REMOTE_USER setting will be allowed access. By default, all accesses from the users homepage supply the REMOTE_USER setting.

Note. You can secure all of the Java portlets on your system using J2EE security and role based permissions within your portlet logic.

The parameter can be found in the PortletContainerServlet definition in the web.xml of the /pspc application

The following is the relevant section from the /pspc/WEB-INF/web.xml within the domain:

<servlet>
   <servlet-name>PortletContainerServlet</servlet-name>
   <display-name>PeopleSoft PortletContainer Servlet</display-name>
   <servlet-class>com.peoplesoft.pt.portlet.container.ContainerServlet</servlet-class> 
       <!-- <load-on-startup>0</load-on-startup> -->
   <init-param>
       <param-name>logClientIPOnMalformedRequest</param-name>
       <param-value>true</param-value>
   </init-param>
	  <init-param>
		    <param-name>AccessJavaPortletsFromPeopleSoftPortalOnly</param-name>
		    <param-value>false</param-value>
	  </init-param>
</servlet>

Creating Portlet Applications For Oracle Application Server Deployment

PeopleSoft delivers a sample portlet application named helloportletapp for use as a model when creating your own portlet applications. This example applies to OAS, but applies generally to other web servers.

Go to your Peoplesoft Application home in OAS. For example, %OAS_HOME%\j2ee\<your Peoplesoft OC4J instance>.

During the execution of the following procedures you will be adding and updating the following files from your Peoplesoft Application home in OAS:

\application-deployments\<your Peoplesoft OC4J instance>\orion-application.xml
\application-deployments\<your Peoplesoft OC4J instance>\<your portlet module>\orion-web.xml
\applications\<your Peoplesoft OC4J instance>\<your portlet module>\WEB-INF\web.xml
\applications\<your Peoplesoft OC4J instance>\<your portlet module>\WEB-INF\portlet.xml

Values entered in one xml file will be used in other xml files so it is important that you follow these instructions carefully. For example, the Module Name value entered in the application.xml file will become the first part of the servlet's portlet-guid information that you enter in the web.xml file.

To create a portlet application for deployment:

Insert a portlet application into the PeopleSoft domain. (helloportalapp is a minimal example).

Note. Portlet applications are directories in the PeopleSoft domain, and therefore must have unique names with respect to all other web and portlet applications within the domain. Each one is essentially your expanded WAR file.
Add a module definition to <web-module id="helloportletapp" path="helloportletapp.war"/>:
Add a web.xml file. Use the helloportletapp’s web.xml as an example. The critical values are: servlet-name, servlet-class, and the two initialization parameters —portlet-guid and portlet-class. These must be aligned correctly.

Note. The value of the portlet-class must be your portlet-class, which is available in either your WEB-INF/classes or WEB-INF/lib folders.

The servlet-class must be org.apache.pluto.core.PortletServet

The following is the relevant section from the helloportletapp web.xml file:
```
<servlet>
<servlet-name>HelloPortlet</servlet-name>
<display-name>HelloPortlet Wrapper</display-name>
<description>Automated generated Portlet Wrapper</description>
<servlet-class>org.apache.pluto.core.PortletServet</servlet-class>
<init-param>
<param-name>portlet-guid</param-name>
<param-value>helloportletapp.HelloPortlet</init-param>
<init-param>
<param-name>portlet-class</param-name>
<param-value>com.peoplesoft.pt.portlet.hello.HelloPortlet</param-value>
</init-param>
</servlet>
```
Add a WEB-INF/portlet.xml file, which must conform to the Java Portlet 1.0 specification. Use the portlet.xml for helloportletapp as a guide.

Each portlet that is defined in the portlet.xml must have unique <portlet-name> as per the specification. Use the value entered for the url-pattern in the web.xml file.

Note. The portlet-name in portlet.xml must be the same as the servlet-name and the second part of the portlet-guid in web.xml.

View the helloportletapp portlet.xml to see how to define a custom preferences validator.
Add an orion-web.xml file with the context path. Use helloportletapp’s orion-web.xml as an example.
Write and compile your portlets, and then add them to the WEB-INF/classes folder of your portlet application or, Jar them and add them to your WEB-INF/lib folder.
Add any Java Server Pages (JSPs), images, and static content that you require. Use the JSPs in helloportletapp/jsp as an example. If you use the tag library for portlets, include it in your WEB-INF/tlb folder.

Note. The tag library for portlets is included in the helloportletapp WEB-INF/tlb folder.
Add a custom Preference Validator by editing the portlet.xml of your portal application, as defined in the Java Portlet 1.0 specification.
Restart the web server and define your content references (CREFs) to

/pspc/portlet/<your entity portlet application ID>/<your entity portlet ID>

See Describing the Portlet Entity Registry.

Defining Portlet Content References

You define a content reference for a JSR 168 portlet with many of the same settings as a PeopleSoft pagelet. The key properties are:

Usage Type

Select Pagelet.

URL Type

SelectNon-PeopleSoft URL.

Portal URL

Enter a value that points to the portlet. Use this syntax:

/pspc/portlet/<your entity portlet application ID>/<your entity portlet ID>

You can treat the portlet content reference like any pagelet, such as including applying security.

Note. The entity portlet application ID and the entity portlet ID mentioned above, are referring to the entities you created in the portletentityregistry.xml file described below.

Note. When you define a JSR 168 portlet as a PeopleSoft pagelet, the Help and Edit icons will always be displayed, regardless of the settings in the portlet.xml file.

Describing the Portlet Entity Registry

The portlet entity registry is the source for both the PeopleSoft portlet content references and the portlets produced through WSRP.

Choosing Portlets to Produce For WSRP

You can choose which portlets to produce for WSRP by including them as <portlet> elements in portletentityregistry.xml.

To produce portlets for WSRP:

Edit portletcontainer/WEB-INF/data/portletentityregistry.xml to add an <application> element for your new portlet application.

The following is the portletentityregistry.xml file as delivered, showing the production of four portlets for WSRP consumption, WSRPTestPortlet of the wsrptest portlet application, TestPortlet1 and TestPortlet2 of the testsuite portlet application, and the HelloPortlet of the helloportletapp portlet application.
```
<?xml version="1.0" encoding="UTF-8"?>
<portlet-entity-registry>
    <application>
        <definition-id>helloportletapp</definition-id>
        <portlet>
            <definition-id>helloportletapp.HelloPortlet</definition-id>
        </portlet>
    </application>
    <application>
        <definition-id>wsrptest</definition-id>
        <portlet>
            <definition-id>wsrptest.WSRPTestPortlet</definition-id>
        </portlet>
        <portlet>
            <definition-id>wsrptest.WSRPTestPortlet</definition-id>
        </portlet>
    </application>
    <application>
        <definition-id>testsuite</definition-id>
        <portlet>
            <definition-id>testsuite.TestPortlet2</definition-id>
        </portlet>
        <portlet>
            <definition-id>testsuite.TestPortlet1</definition-id>
        </portlet>
    </application>
</portlet-entity-registry>
```
The portletentityregistry.xml requires the following:
- Your portlet application must have a new <application> element in which the <definition-id> is the name of your portlet application directory and the id is unique within the file.
- Any portlets you wish to produce from your portlet application must have their own <portlet> elements within your new <application> element. Use the delivered portletentityregistry.xml as a guide.
  
  Note. Each portlet must have a unique id within the <application>. For example, refer to the same definition multiple times —each having different preferences and its own unique entity ID.
- The <definition-id> of each portlet is a period-separated fully qualified name for the portlet of the form: “<porletApplicationName>.<portletName>” as shown. The portletApplicationName portion must match the <definition-id> of the <application>. The portletName portion must match the <portlet-name> element for the <portlet> definition in your portlet.xml file.
Restart your web server. Your Java portlets are now produced via WSRP technology. All WSRP Consumers you may choose to use will need to retrieve the new service description, which will include the new Java portlets.