55.1 Introduction to Java Portlets

55.1.1 Introduction to Standards-Based Java Portlets

Organizations engaged in WebCenter Portal application projects have found application integration to be a major issue. Until now, users developed portlets using proprietary APIs for a single portal platform and often faced a shortage of available portlets from a particular portal vendor. All this changed with the introduction of the following standards:

Web Services for Remote Portlets (WSRP)

Java Specification Request (JSR) 286

These two standards enable the development of portlets that interoperate with different portal products, and therefore widen the availability of portlets within an organization. This wider availability can, in turn, dramatically increase an organization's productivity when building WebCenter Portal applications.

WSRP is a web services standard that enables the plug-and-play of visual, user-facing web services with portals or other intermediary web applications. Being a standard, WSRP enables interoperability between a standards-enabled container and any WSRP portal. WSRP defines the following:

JSR 286 is a specification that defines a set of APIs to enable interoperability between portlets and portals, addressing the areas of aggregation, personalization, presentation, and security. JSR 286 defines container services which provide the following:

A portlet API for coding portlet functionality

The URL-rewriting mechanism for creating user interaction within a portlet container

The security and personalization of portlets

Inter-portlet communication using portlet events and public render parameters

Oracle actively participates in portlet standards including those produced by the OASIS (WSRP) and JCP (JSR 168, 286, 301, 329, and so on) standards organizations.

Note:

HTML forms can be submitted using either the get or post method, but the WSRP standard only requires the consumer (WebCenter Portal application) to use the post method. Support of the get method is optional according to the standard. Since application consumers are not required to support the get method, Oracle recommends that you use the post method when developing your portlets.

The Relationship Between WSRP and JSR 286

WSRP is a communication protocol between a portlet client, for example, a WebCenter Portal application, and a portlet container running on a remote server. JSR 286 describes the Java Portlet API for running portlet applications. Combining these standards enables developers to integrate their applications from any internal or external source as portlets with WSRP portals. Building pages becomes as simple as selecting portlets from the JDeveloper Resource Palette or Application Resources pane of the Application Navigator.

55.1.2 Introduction to PDK-Java Portlets

PDK-Java gives you a framework to simplify the development of Java portlets by providing commonly required utilities and enabling you to leverage existing development skills and application components such as JSPs, servlets, and static HTML pages. PDK-Java also enables you to create portlets without having to deal directly with the complexity of communications between Oracle WebCenter Framework and producers.

The PDK-Java framework is divided into the following areas:

The Producer Adapter insulates the developer from the HTTP syntax defined by Oracle WebCenter Framework for communication with web producers. It translates the information passed between Oracle WebCenter Framework and your Java web producer. Without an adapter, your producer would not only manage portlets, but it would also have to communicate this information directly to Oracle WebCenter Framework in the expected language. The adapter eliminates the need for your web producer to understand the portal language and vice-versa.

The Producer Interface defines the APIs (functions) required by your Java implementation to integrate with the Producer Adapter. The Producer Adapter receives messages from the WebCenter Portal application, translates them into calls to the Producer Interface, and translates the producer's response into a format that the application can understand. The Producer Interface contains a set of Java classes that define the methods your producer implements and, in often, provides a standard implementation. Some of the primary classes are as follows:

ProviderDefinition (oracle.portal.provider.v2.ProviderDefinition)

ProviderInstance (oracle.portal.provider.v2.ProviderInstance)

PortletDefinition (oracle.portal.provider.v2.PortletDefinition)

PortletInstance (oracle.portal.provider.v2.PortletInstance)

ParameterDefinition (oracle.portal.provider.v2.ParameterDefinition)

EventDefinition (oracle.portal.provider.v2.EventDefinition)

The Producer Runtime provides a base implementation that follows the specification of the Producer Interface. The Producer Runtime includes a set of default classes that implement each of the Producer Interfaces and enables you to leverage the rendering, personalization, and security frameworks provided with PDK-Java. These classes and the associated frameworks simplify the development of a producer by implementing common functions for Oracle WebCenter Framework requests and providing a declarative mechanism for configuring the producer. Using the Producer Runtime, you can focus your development efforts on the portlets themselves rather than the infrastructure needed to communicate with the WebCenter Portal application. If the standard behavior of the Producer Runtime does not meet your requirements, then you can easily extend or override specific behaviors. Some of the primary classes are as follows:

The Producer Utilities provide methods for simplifying the rendering of portlets. The utilities include methods for constructing valid links (hrefs), rendering the portlet's container (including the header), rendering HTML forms that work within a page, and supporting portlet caching.

55.2 Creating Java Portlets

You are familiar with Oracle JDeveloper and know how to build and deploy Java components using it.

The application in which you are going to create your JSR 286 and PDK-Java portlets is either a Portlet Producer Application or any application scoped for portlet creation (any application except for WebCenter Portal Application).

Note:

The figures in this section were taken with the default Look and Feel (Oracle) and Theme (Fusion Blue) settings in JDeveloper. If you have changed these settings, then what you see on your screen may vary slightly, but the content and functionality remains the same. To change the Look and Feel and Theme settings, select Preferences from the Tools menu, and then select Environment.

55.2.1 How to Create a JSR 286 Java Portlet

Using the Create JSR 286 Java Portlet wizard in JDeveloper you can expose your portlet over WSRP 2.0 quickly and easily. This wizard supports both WSRP 1.0 and WSRP 2.0.

In the Create JSR 286 Java Portlet wizard, you can choose which portlet modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML) to use for each mode. The wizard then creates a simple implementation for each of the selected modes.

To create a JSR 286 Java portlet using the JDeveloper wizard:

In the JDeveloper Application Navigator, open the application under which you want to create your portlet.

The application must be scoped for portlet creation. An easy way to achieve this is to use the Portlet Producer Application template.

Note:

WebCenter Portal Applications are not scoped for portlet creation.

Right-click the project under which you want to create your portlet (for example Portlets), and choose New.

In the New Gallery, expand Web Tier, select Portlets and then Standards-based Java Portlet (JSR 286), and click OK.

Note:

If the project already contains JSR 286 portlets, you can also create a new portlet by:

Right-clicking portlet.xml and choosing Add Portlet.

Opening portlet.xml, clicking the Design tab, and clicking the Add icon on the Portlets tab.

On the General Portlet Information page of the Create JSR 286 Java Portlet wizard (Figure 55-3), replace the default name provided in the Name field with one that better describes the purpose of the portlet.

If you select this option, you can specify implementation details for the portlet's Edit mode later on in the wizard.

Click Next.

On the Additional Portlet Information page (Figure 55-4), in the Portlet Title field, enter a descriptive title for your portlet.

The portlet title is displayed in the Resource Palette or Application Resources panel, so make the title something to help users decide whether the portlet is useful to them. The portlet title is also displayed on the portlet header when the portlet appears on a page.

The Display Name, Short Title, Description, and Keyword attributes are not implemented in WebCenter Portal applications. You do not need to enter any values for these fields unless your portlet is likely to be consumed by other applications.

For example, Oracle Portal uses the portlet display name in the Portlet Repository.

At this point in the wizard, you can click Finish to create the portlet immediately, using the default values for all remaining settings.

To provide additional details for your portlet, click Next and follow the remaining steps.

On the Content Types and Portlet Modes page (Figure 55-5), in the Content Types and Portlet Modes list, select view.

In the Implementation Method section, select how you want to implement View mode for your portlet (for more information about View mode, see Section 53.1.3.1, "View Mode"):

Select Generate JSP to generate a skeleton JSP file for the portlet mode. Enter a name for the JSP in the corresponding field, or accept the default.

When you complete the wizard, the generated JSP displays in the Application Navigator where you can select it for further development. This is the default selection for all portlet display modes.

Select Generate ADF-Faces JSPX to generate a page to which you can add ADF-Faces components. Enter a name for the JSPX in the corresponding field, or accept the default.

Note:

If you choose this option, the portlet implementation class is created as a subclass of oracle.portlet.bridge.adf.application.ADFBridgePortlet, instead of as a subclass of javax.portlet.GenericPortlet. That is, the wizard generates a portlet application which uses the Oracle JSF Portlet Bridge. For more information about the Oracle JSF Portlet Bridge, see Chapter 54, "Creating Portlets with the Oracle JSF Portlet Bridge."

Select Map to Path to map the portlet mode to a web resource in the portlet application, such as a page. The resource is not generated by the wizard. Enter the name and path in the corresponding field. You can create this resource after completing the wizard if necessary.

With this selection, you must write the targeted resource or file yourself. The target could be, for example, a JSP, a servlet, or an HTML file. This selection enters code in the generated portlet Java class that routes requests for the given mode to the specified target.

Select Custom Code to implement the portlet mode through a custom coded object. You must create this object later. This selection generates a skeleton method to render content (private void doMODE_NAMECONTENT_TYPE) in the generated portlet java class. You must update this code to render useful content.

Note:

If you want this portlet mode to support a different content type, for example text/xml, see Step 17.

If you selected Enable users to edit portlet content on the first page of the wizard, select edit and then select the implementation method for Edit mode (for information about Edit mode, see Section 53.1.3.2, "Edit Mode").

In the Content Types dialog, move the required content types to the Selected list and click OK.

Click Next.

If you selected Enable users to edit portlet content on the General Portlet Information page earlier in the wizard, then you can create customization preferences to enable users of the portlet to specify values for the portlet at runtime. Go to step 19.

In the Add New Preference dialog, in the Name field, enter a name for the new preference.

The name must be unique in the portlet. Use only letters, numbers, and the underscore character.

In the Default Values field, enter one or more default values for the new preference. Separate multiple values with commas.

To make the preferences translatable, select the Translate Preference checkbox and then click OK.

JDeveloper generates a resource bundle class for translatable preferences, with strings for which you can obtain translations. At runtime, the portlet references the resource bundle entries.

Note:

The preference name is always translated, but there is not always a requirement to translate the default values. For example, if the value is an integer, then no translation is needed.

Repeat the preceding steps to add more preferences. When you are done click Next.

On the Security Roles page (Figure 55-7), to add an existing security role to your portlet, select the security role and move it to the Selected list.

Security roles enable you to set tiered levels of access to the portlet. For example, a View user can view the portlet but cannot edit it; a Customize user can customize portlet settings; a Manage user can perform all available functions associated with the portlet.

The Available list displays the security roles defined for the application in which you are creating the portlet. Moving a security role to the Selected list creates a reference of the security role in the application's portlet deployment file (portlet.xml) that refers to the security role in the application's web deployment file (web.xml).

You can create new security roles for the application by editing web.xml. For more information, see the JDeveloper online help.

Selecting this option indicates that portlet caching is managed by the portlet container. The portlet itself may choose to cache content for any given response. The settings on this page apply only when the portlet itself does not specify a caching condition for a response.

If you do not want any default caching for this portlet, choose Do Not Cache By Default. In this case, the wizard actually sets a cache duration of 0 seconds. As stated earlier, this cache setting only comes into play when the portlet itself does not specify a caching condition for a response.

If you choose no caching here and you later decide to implement default caching for the portlet, then you can change the cache duration value in the portlet.xml file, which is generated by the wizard, to a number greater than zero.

If you chose to cache the portlet, in the Default Expiry Conditions section, select:

Cache Content Expires After [ ] seconds to expire the cached portlet content after a certain amount of time. Specify the time limit in the corresponding field.

Cache Content Never Expires to never expire the cached portlet content. You may want to select this option if the portlet contains static content that is unlikely to change.

Click Next.

On the Initialization Parameters page (Figure 55-9), you can add initialization parameters to your portlet.

Initialization parameters provide the application developer, who decides what goes into the .war file, an alternative to JNDI variables for configuring the behavior of all of the different components of the application (for example, servlets and portlets) in a compatible way. These initialization parameters are added to the portlet.xml file.

Click New to add a new initialization parameter to the portlet.

In the newly added row, double-click each field to provide a Name, default Value, and Description for the parameter.

55.2.2 What Happens When You Create a JSR 286 Java Portlet Using the JDeveloper Wizard

When you use the JDeveloper wizard to create a JSR 286 Java portlet, JDeveloper generates a default implementation of the portlet. Specifically, the following files are created:

Two Java classes:

portletName.java is invoked by the portlet container and contains all the methods required by the portlet standards.

portletnameBundle.java contains all the translation strings for the portlet.

portlet.xml is the portlet deployment descriptor file for the application.

web.xml is the web deployment descriptor file for the application.

Files for each portlet mode you selected for the portlet:

If you selected Generate JSP for the portlet mode, a JSP page is created for the mode, for example, view.jsp.

If you selected Generate ADF-Faces JSPX, a JSPX page is created for the mode, for example, view.jspx. You can add Faces components to this page.

If you selected Map to Path, no additional files are created as the code for the portlet mode resides in an existing resource. Code is added to the portlet's Java class to route requests to the specified target.

If you selected Custom Code, no additional files are created, but the code for the portlet mode resides in the portlet's Java class.

You can see all these files in the Application Navigator, as shown in Figure 55-10.

55.2.4 How to Create a PDK-Java Portlet

Using the Create Oracle PDK-Java Portlet wizard in JDeveloper you can quickly and easily create PDK-Java portlets. You can choose which portlet modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML) to use for each mode. The wizard then creates a simple implementation for each of the selected modes.

To create a PDK-Java portlet using the JDeveloper wizard:

In the JDeveloper Application Navigator, open the application under which you want to create your portlet.

The application must be scoped for portlet creation. An easy way to achieve this is to use a Portlet Producer Application. WebCenter Portal Applications are not scoped for portlet creation.

Right-click the project under which you want to create your portlet, and choose New.

Note:

To create the portlet in an existing producer, right-click the producer's provider.xml file and choose Add Portlet. This takes you directly to the General Portlet Information page of the Create Oracle PDK-Java Portlet wizard (step 8).

In the New Gallery, expand Web Tier, select Portlets and then Oracle PDK-Java Portlet, and click OK.

serviceID.properties defines properties for a producer with that service ID. The service ID has the same value as the producer name.

_default.properties is a default properties file. A producer application may have multiple producers, each with its own service ID. On registration, if no service ID is defined, then the default properties file is used.

Select Generate XML Entries.

This automatically generates a producer definition file (provider.xml) for the producer that contains details of the portlets belonging to the producer, including those generated by the wizard.

Select Generate Index JSP and then click Next.

This automatically generates an index.jsp file that lists all the producers that reside in the application with hyperlinks that enable easy access to producer test pages.

On the General Portlet Information page (Figure 55-12), enter a name and display name for your portlet.

The name is used internally and is not exposed to users. The display name is displayed to users in portlet selection lists, such as the Component Palette.

The description is not implemented in WebCenter Portal applications so you do not need to enter a value in this field unless your portlet is likely to be consumed by other applications, such as Oracle Portal.

In the Timeout Interval (Seconds) field, enter the number of seconds to allow for rendering the portlet.

In the Timeout Message field, enter a message to display if the rendering of the portlet exceeds the timeout interval specified and then click Next.

On the View Modes page (Figure 55-13), under Show Page, from the Implementation Style dropdown list, select the implementation style to use for the portlet's Shared Screen mode.

Select JSP to implement the portlet's Shared Screen mode as a JavaServer Page. In the File Name field, enter the name of the file to be generated by the wizard.

Select HTTP Servlet to implement the portlet's Shared Screen mode as an HTTP servlet. In the Package Name field, enter the name of the package that contains the HTTP servlet. In the Class Name field, enter the Java class to be referenced with the portlet's Shared Screen mode.

Select HTML File to implement the portlet's Shared Screen mode as an HTML file. In the File Name field, enter the name of the file to be generated by the wizard. Note that, when you choose HTML File, the following code is added inside the <renderer> element of your provider.xml file:

charSet indicates the character set that the producer must use to encode the HTML page. The default character set is determined by JDeveloper preferences. If you require a different character set, you must update this element of provider.xml accordingly.

Select Java Class to implement the portlet's Shared Screen mode as a Java class. In the Package Name field, enter the name of the package that contains the Java class. In the Class Name field, enter the name of the Java class.

At this point in the wizard, you can click Finish to create the portlet immediately, using the default values for all remaining settings.

To provide additional details for your portlet, click Next and follow the remaining steps.

On the Customize Modes page (Figure 55-14), Edit Page is selected by default. To implement Edit mode for your portlet, select an implementation style as described for Shared Screen mode in step 11. If you do not want to implement Edit mode, then deselect Edit Page.