6 Creating Java Portlets

This chapter explains how to create Java portlets based on the Java Portlet Specification (JSR 168) or the Oracle Portal Developer Kit-Java (PDK-Java) using the JSR 168 Java Portlet Wizard and Java Portlet Wizard in Oracle JDeveloper. This chapter includes the following sections:

Section 6.1, "Guidelines for Writing Java Portlets"
Section 6.2, "Introduction to Java Portlet Specification (JPS) and WSRP"
Section 6.3, "Building JPS-Compliant Portlets with Oracle JDeveloper"
Section 6.4, "Introduction to Oracle PDK-Java"
Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper"
Section 6.6, "Setting up the WSRP and JPDK Applications in Oracle Portal"

The source code for many of the examples referenced in this chapter is available as part of PDK-Java. You can download PDK-Java from the Oracle Portal Developer Kit (PDK) page on Oracle Technology Network (OTN):

http://www.oracle.com/technology/products/ias/portal/pdk.html

When you unzip PDK-Java, you will find the examples in a zip file:

../pdk/jpdk/v2/src.zip

To access the Javadoc reference for PDK-Java, extract jpdk.war from inside of:

../pdk/jpdk/v2/jpdk.ear

Then unzip jpdk.war. The Javadoc is located in a folder called apidoc.

6.1 Guidelines for Writing Java Portlets

When you write your portlets in Java for either the Java Portlet Specification (JPS) or PDK-Java, you should follow the best practices described in this section, which are as follows:

Section 6.1.1, "Guidelines for Show Modes"
Section 6.1.2, "Guidelines for Navigation within a Portlet"
Section 6.1.3, "Guidelines for JavaScript"
Section 6.1.4, "Guidelines for Mobile Portlets"

6.1.1 Guidelines for Show Modes

Show mode exhibits the runtime portlet functionality seen by users. JPS offers some modes not offered by PDK-Java and vice versa. If you are coding portlets to JPS, you can declare custom portlet modes in portlet.xml that map to the extra modes offered by PDK-Java, or to accommodate any other functionality you may want to provide. For example, the JSR 168 Java Portlet Wizard for JPS portlets includes a custom mode call print, which you can use to provide a printer friendly version of the portlet. Defining custom modes is especially useful if the portlet must interoperate with portal implementations from other vendors

The different Show modes that a portlet may have, each with its own visualization and behavior, are discussed in the following sections:

Section 6.1.1.1, "Shared Screen Mode (View Mode for JPS)"
Section 6.1.1.2, "Edit Mode (JPS and Pdk-Java)"
Section 6.1.1.3, "Edit Defaults Mode (JPS and PDK-Java)"
Section 6.1.1.4, "Preview Mode (JPS and PDK-Java)"
Section 6.1.1.5, "Full Screen Mode (PDK-Java)"
Section 6.1.1.6, "Help Mode (JPS and Oracle Portal)"
Section 6.1.1.7, "About Mode (JPS and PDK-Java)"
Section 6.1.1.8, "Link Mode (PDK-Java)"

6.1.1.1 Shared Screen Mode (View Mode for JPS)

A portlet uses Shared Screen mode (known as View mode in JPS) to appear on a page with other portlets. This is the mode most people think about when they envision a portlet. A JPS portlet must have a view mode, the rest are optional.

When developing portlets, you must consider all of the factors that may influence the portlet's appearance on the page, such as the portlet's containing object and the other portlets with which your portlet will share a page. In Oracle Portal, portlets are rendered inside HTML table cells when in Shared Screen mode. This means a portlet can display only content that can be rendered within a table cell, including, among other technologies, HTML, plug-ins, and Java applets. The actual size of the table cell is variable depending on user settings, the browser width, and the amount and style of content in the portlet.

6.1.1.1.1 HTML Guidelines for Rendering Portlets

Plain HTML is the most basic way to render portlets and provides a great deal of flexibility to portlet developers. You can use almost any standard HTML paradigm, such as links, forms, images, and tables, as long as it can display within an HTML table cell. Improperly written HTML may appear inconsistently across different browsers and, in the worst case, could cause parts of your page not to appear at all. Ensure that you adhere to the following rules:

Use standard HTML. The official HTML specification is available from the W3C (more information available at: http://www.w3.org/MarkUp).
Avoid unterminated and extraneous tags. The behavior of pages with improperly terminated tags is unpredictable because it depends on what the browser chooses to do. Tools like weblint (http://www.weblint.org) and HTML Tidy (http://www.w3.org/People/Raggett/tidy) can help detect and fix hanging and unnecessary tags.
Avoid elements that cannot be rendered properly in an HTML table cell. Some constructs cannot be used simply because they do not display correctly in a table cell. Frames, for example, do not appear when inserted in a table.
Keep portlet content concise. Do not try to take full screen content and expose it through a small portlet. You will only end up with portlet content too small or cramped for smaller monitors. Full screen content is best viewed in Full Screen mode of PDK-Java.
Do not create fixed-width HTML tables in portlets. You have no way to tell how wide a column your portlet will have on a user's page. If your portlet requires more room than given, it might overlap with another portlet in certain browsers.
Avoid long, unbroken lines of text. The result is similar to what happens with wide fixed-width tables. Your portlet might overlap other portlets in certain browsers.
Check behavior when resizing the page. Test your portlet's behavior when the browser window is resized to ensure that it works in different browser window sizes.
Check behavior when the default browser font changes. People may choose whatever font size they wish and they can change it at any time. Your portlet should handle these situations gracefully.

The HTML you use also impacts the perceived performance of your site. Users judge performance based on how long it takes for them to see the page they requested, and browsers require time to interpret and display HTML. Given that, you should consider the following:

Avoid deeply nested tables. Deeply nested tables slow performance dramatically in some older browser versions. Oracle Portal draws several levels of tables to render portlets. If your portlets use tables within tables, your users may have to wait quite a while for those pages to render.
Avoid lengthy, complex HTML. Portlets share a page with other portlets. Thus, portlet generation times can significantly effect the overall performance of the page. If portlets must render complex HTML or wait for external resources, such as third party applications, it can greatly slow the rendering of the page.

6.1.1.1.2 Cascading Style Sheet Guidelines for Rendering Portlets

The fonts and colors of every portlet on a page should match the style settings chosen by the user. To accomplish this goal, these style selections are embedded automatically using a Cascading Style Sheet (CSS) on each Oracle Portal page. The portlets access these settings for their fonts and colors, either directly or using the API.

While different browsers have implemented varying levels of the full CSS specification, Oracle Portal uses a very basic subset of this specification to allow for consistent fonts and colors. CSS implementation levels should not affect the consistency of your pages across browsers. Follow these guidelines for using CSS:

Use CSS instead of hard coding. Hard coding fonts and colors is extremely dangerous. If you hard code fonts and colors, your portlet may look out of place when the user changes the page style settings. Since you have no way of knowing the user's font and color preference choices, you might also choose to hard code a font color that turns out to be the same as the user's chosen background color, in which case your portlet appears to be invisible to that user.
Use the CSS APIs to format your text. The stylesheet definition is available at the top of Oracle Portal pages, but you should not call it directly. Instead, use the APIs provided to format your text appropriately. This method ensures that your portlets work even if the stylesheet changes in the future.
Avoid using CSS for absolute positioning. Since users can personalize their portal pages, you cannot guarantee that your portlet can appear in a particular spot.
Follow Accessibility Standards. You should ensure that you code you style sheets according to existing accessibility standards (more information available at http://www.w3.org/TR/WCAG10-CSS-TECHS/).

6.1.1.2 Edit Mode (JPS and Pdk-Java)

A portlet uses Edit mode to allow users to personalize the behavior of the portlet. Edit mode provides a list of settings that the user can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.

Portal users typically access a portlet's Edit mode by clicking Personalize on the portlet banner. When users click Personalize, a new page appears in the same browser window. The portlet typically creates a Web page representing a dialog box to choose the portlet's settings. After applying the settings, users automatically return to the original page.

6.1.1.2.1 Guidelines for Edit Mode Operations

The following guidelines should govern what you expose to users in Edit mode:

Allow users to personalize the title of the portlet. The same portlet may be added to the same portal page several times. Allowing the user to personalize the title helps alleviate confusion.
If using caching, invalidate the content. If personalizations cause a change in portlet display or content, you must ensure that the portlet content is regenerated and not returned from the cache. Otherwise, the user may see incorrect content.
Do not use Edit mode as an administrative tool. Edit mode is meant to give users a way of changing the behavior of their portlets. If you need to change provider settings or do other administrative tasks, you should create secured portlets specifically for those tasks.
Only show mobile options when applicable. The portlet can interrogate whether an Oracle Portal instance is enabled for mobile devices. If the instance is not mobile-enabled, then you need not show any mobile-specific options. Furthermore, if the page might serve both mobile and desktop users, you should consider delineating between mobile options and desktop options. Refer to Section 6.1.4.6, "Tailor Personalization Pages" for additional tips.

6.1.1.2.2 Guidelines for Buttons in Edit Mode

For consistency and user convenience, Edit mode should implement the following buttons in the following order:

OK saves the user personalizations and returns the portlet to shared screen mode.
Apply saves the user personalizations and reloads the current page.
Cancel returns the portlet to shared screen mode without saving changes.

6.1.1.2.3 Guidelines for Rendering Personalization Values

When you show the forms used to change personalization settings, you should default the values such that the user does not have to constantly re-enter settings. When rendering the personalization values, use the following sequence to provide consistent behavior:

User preference: Query and display this user's personalizations, if available.
Instance defaults: If no user personalizations are found, query and display system defaults for the portlet instance. These are set in Edit Defaults mode and apply only to this portlet instance.
Portlet defaults: If no system default personalizations are found, display general portlet defaults, which may be blank. General portlet defaults are sometimes hard coded into the portlet but should be overridden if either of the two previous conditions apply.

This logic enables the personalizations to be presented in a predictable way, consistent with the other portlets in the portal. PDK-Java makes this type of logic easy to implement.

6.1.1.3 Edit Defaults Mode (JPS and PDK-Java)

A portlet uses the Edit Defaults mode to enable page designers to customize the default behavior of a particular portlet instance. Edit Defaults mode provides a list of settings that the page designer can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.

These default personalization settings can change the appearance and content of that individual portlet for all users. Because Edit Defaults mode defines the system level defaults for what a portlet displays and how it displays it, this mode should not be used as an administrative tool or for managing other portlets.

Page designers access Edit Defaults mode, when editing a page, by clicking the Edit Defaults icon just above the portlet banner.

When users click the Edit Defaults icon, a new page appears in the same browser window. The portlet typically creates a Web page representing a dialog box to customize the portlet instance settings. After applying the settings, users are automatically returned to the original page.

6.1.1.3.1 Guidelines for Edit Defaults Mode Options

The following guidelines should govern what you expose to page designers in Edit Defaults mode:

If using caching, invalidate the cache. If customizations cause a change in portlet display or content, you must ensure that the portlet content is regenerated and not returned from the cache. Otherwise, the user may see incorrect content.
Do not use Edit Defaults mode as an administrative tool. Edit Defaults mode gives users a way of changing the behavior of their portlets. If you need to change provider settings or do other administrative tasks, you should create secured portlets specifically for those tasks.
Only show mobile options when applicable. The portlet can interrogate whether an Oracle Portal instance is enabled for mobile devices. If the instance is not mobile-enabled, then you need not show any mobile-specific options. Furthermore, if the page might serve both mobile and desktop users, you should consider delineating between mobile options and desktop options. Refer to Section 6.1.4.6, "Tailor Personalization Pages" for additional tips.

6.1.1.3.2 Guidelines for Buttons in Edit Defaults Mode

For consistency and user convenience, Edit Defaults mode should implement the following buttons in the following order:

OK saves the user customizions and returns the portlet to shared screen mode.
Apply saves the user customizations and reloads the current page.
Cancel returns the portlet to shared screen mode without saving changes.

6.1.1.3.3 Guidelines for Rendering Personalization Values

When you show the forms used to change customization settings, you should default the values so that the page designer does not have to constantly re-enter settings. When rendering customization values, use the following sequence to provide consistent behavior:

Instance preferences: Query and display system defaults for the portlet instance.
Portlet defaults: If no system default customizations are found, display general portlet defaults, which may be blank. General portlet defaults are sometimes hard coded into the portlet but should be overridden by system defaults.

This logic enables the customizations to be presented in a predictable way, consistent with the other portlets in the portal.

6.1.1.4 Preview Mode (JPS and PDK-Java)

A portlet uses Preview mode to show the user how the portlet looks before adding it to a page. Preview mode visually represents what the portlet can do.

Portal users typically access a portlet's Preview mode by clicking its Preview icon from the Add Portlet page. A window then displays the preview of the chosen portlet. The user has the option to add that portlet to the page. Portal administrators may access Preview mode from the Portlet Repository.

Guidelines for Preview Mode

The following guidelines should govern what you expose to users in Preview mode:

Provide an idea of what the portlet does. Preview mode should generate enough content for the user to get an idea of the actual content and functionality of the portlet.
Keep your portlet previews small. The amount of data produced in this mode should not exceed a few lines of HTML or a screen shot. Preview mode appears in a small area, and exceeding the window's size looks unprofessional and forces users to scroll.
Do not use live hyperlinks. Links may not behave as expected when rendered in Preview mode. Hyperlinks can be simulated using the underlined font.
Do not use active form buttons. Forms may not behave as you expect them to when rendered in Preview mode. If you decide to render form elements, do not link them to anything.

6.1.1.5 Full Screen Mode (PDK-Java)

Portlets use Full Screen mode to provide a larger version of the portlet for displaying additional details. Full Screen mode lets a portlet have the entire window to itself.

For example, if a portlet displays expense information, it could show a summary of the top ten spenders in Shared Screen mode and the spending totals for everyone in Full Screen mode. Portlets can also provide a shortcut to Web applications. If a portlet provided an interface to submitting receipts for expenses in Shared Screen mode, it could link to the entire expense application from Full Screen mode.

Portal users access a portlet's Full Screen mode by clicking the title of the portlet.

Technically, JPS portlets do not have Full Screen mode. However, you can implement the equivalent of Full Screen mode for a JPS portlet with View mode (Shared Screen mode) and a maximized state for the window.

6.1.1.6 Help Mode (JPS and Oracle Portal)

A portlet uses Help mode to display information about the functionality of the portlet and how to use it. The user should be able to find useful information about the portlet, its content, and its capabilities with this mode.

Portal users access a portlet's Help mode by clicking Help in the portlet header.

Guidelines for Help Mode

The following guidelines should govern what you expose to users in Help mode:

Describe how to use the portlet. Users may not know all the features your portlet provides just from its interface. Describe the features and how to get the most out of them.

6.1.1.7 About Mode (JPS and PDK-Java)

Users should be able to see what version of the portlet is currently running, its publication and copyright information, and how to contact the author. Portlets that require registration may link to Web-based applications or contact information from this mode, as well.

Portal users access a portlet's About mode by clicking About on the portlet header. A new page appears in the same browser window. The portlet can either generate the content for this new page or take the user to an existing page or application.

Guidelines for About Mode

The following guidelines should govern what you expose to users in About mode:

Display relevant copyright, version, and author information. Users want to know what portlet they are using and where they can get more information. The about page may become important when supporting your portlets.

6.1.1.8 Link Mode (PDK-Java)

A portlet uses Link mode to render a link to itself that displays on a mobile page. When the user clicks the link, the portlet is called in Show mode. The portlet then renders itself in the mobile View/Shared Screen mode.

For JPS portlets that declare support of the Oracle Mobile XML content type, Oracle Portal renders the link in one of two ways, as follows:

Call the portlet's View mode with the MINIMIZED window state, if the portlet declares support for it.
Otherwise, render a link using the portlet's title.

Guidelines for Link Mode

The following guidelines should govern what you expose to users in Link mode:

Limit content. The purpose of Link mode is to render a link without extraneous material. Link mode should simply render the short title and possibly some relevant summary information (usually just a word or two).

6.1.2 Guidelines for Navigation within a Portlet

In some ways, navigation between different sections or pages of a single portlet is identical to navigation between standard Web pages. Users can submit forms and click links. In the case of typical, simple Web pages, both of these actions involve sending a message directly to the server responsible for rendering the new content, which is then returned to the client. In the case of portlets, which comprise only part of a page, the form submission or link rendered within the portlet does not directly target the portlet. It passes information to the portlet through the portal. If a link or form within a portlet does not refer back to the portal, then following that link takes the user away from the portal, which is not typically the desired behavior.

The portlet developer does not need to know the detailed mechanics of how the parameters of a form or link get passed around between the user, portal, and portlet. However, they must understand that they cannot write links in a portlet the same way they do for typical, simple Web pages.

6.1.2.1 Types of Links for Portlets

A portlet may render links of four classes, as follows:

Intraportlet links require the portlet to be aware of the address of Oracle Portal because they actually refer to it in some way.
Portal links, like intraportlet links, must be aware of the address of Oracle Portal for the same reason.
External links make no reference to Oracle Portal and behave in portlets as they would do in a normal Web page.
Internal/Resource links, like external links, also make no reference to Oracle Portal.

Figure 6-1 contains a summary of these link types. The arrows indicate how the links reference the resources to which they logically refer.

Figure 6-1 Oracle Portal Link Types

Description of "Figure 6-1 Oracle Portal Link Types"

6.1.2.1.1 Intraportlet Links

Intraportlet links go to different sections or pages within a given portlet. Strictly speaking, they refer to the page containing the portlet, but they contain parameters that cause the portlet to render a different section or page within that page when it is requested by the user.

As a direct consequence, a portlet cannot expect to render links to different sections or pages of itself using relative links or absolute links based on its own server context. Intraportlet link are useful for intraportlet navigation, either as links or form submission targets.

6.1.2.1.2 Portal Links

Portal links refer to significant pages within Oracle Portal, such as the user's home page.

6.1.2.1.3 External Links

External links refer neither to the portlet (through a page) nor to any part of the portal. If selected, these links take the user away from the portal, for example, www.oracle.com.

6.1.2.1.4 Internal/Resource Links

Internal/Resource links refer to internal (to the portlet) resources. Sometimes they are exclusively used internally during portlet rendering, for example as a server side include. On other occasions, they may be used externally to reference portlet resources like images. In this latter case, you can use the PDK-Java constructResourceURL method in the UrlUtils class to retrieve images from behind a firewall using resource proxy.

For example, lottery.jsp of the lottery sample, which is available with PDK-Java, contains resource proxy requests for images.

<%@ page contentType="text/html;charset=UTF-8" %>
<%@ page session="false" import="oracle.portal.provider.v2.render.*" %>
<%@ page import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil" %>
<%@ page import="oracle.portal.provider.v2.url.UrlUtils" %>
<%@ page import="oracle.portal.sample.v2.devguide.lottery.*" %>
<%
  LottoPicker picker = new LottoPicker();
  picker.setIdentity(request.getRemoteAddr() ); %>
<% PortletRenderRequest portletRequest = (PortletRenderRequest)
request.getAttribute("oracle.portal.PortletRenderRequest"); %>
<% String name = portletRequest.getUser().getName(); %>
<P class="PortletHeading1" ALIGN="CENTER">Hi <%= name %>, Your Specially
  Picked</P><P ALIGN="CENTER"><IMG SRC="<%= UrlUtils.constructResourceURL(portletRequest,
  HttpPortletRendererUtil.absoluteLink(request, "images/winningnumbers.gif")) %>"
  WIDTH="450" HEIGHT="69" ALIGN="BOTTOM" BORDER="0"></P>
<P>
<P ALIGN="CENTER">
<TABLE ALIGN="CENTER" BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<% 
     int [] picks = picker.getPicks();
     for (int i = 0; i < picks.length; i++) { 
%>
             <TD>
    <IMG SRC="<%= UrlUtils.constructResourceURL(portletRequest,
      HttpPortletRendererUtil.absoluteLink(request, "images/ball" + picks[i])) %>
      .gif" WIDTH="68" HEIGHT="76" ALIGN="BOTTOM" BORDER="0">
     </TD>
<%
     }

These calls cause the Parallel Page Engine to make the request to the resource and return it to the browser. For session-based providers, any cookies returned from the original initSession call to the provider are sent with the request back to the provider to maintain the right session context.

6.1.3 Guidelines for JavaScript

You may find the use of JavaScript useful within a portlet, but bear in mind the following guidelines within your portlets:

You should never use JavaScript to redirect the page in which the portlet is rendered. If you need to direct users elsewhere, you should do so in your portlet action handling code or open a new window in the browser.
Ensure that identifiers in your JavaScript are qualified. By qualifying your identifiers, you ensure that they are unique and do not clash with any other JavaScript on the page.

6.1.4 Guidelines for Mobile Portlets

Oracle Portal is capable of rendering its pages for both HTML and non-HTML (mobile) devices. When rendering for a mobile device, Oracle Portal requires portlets to generate content in a universal markup language called OracleAS Wireless XML.

Many portlets, known as desktop portlets, generate only HTML responses and as such can only render themselves in standard HTML browsers. Some portlets, known as mobile portlets, generate only OracleAS Wireless XML responses. These portlets can render themselves on any device, including standard HTML browsers. Many portlets, though, take a hybrid approach that renders either HTML or OracleAS Wireless XML depending on the environment. These hybrid portlets can render themselves on any device, but they render best on standard HTML browsers. Although OracleAS Wireless XML is sufficient for HTML responses, it is not as expressive as HTML. Since portlets running in both a desktop and mobile environment are typically accessed using the desktop, developers commonly choose to create hybrid portlets that can provide the best possible rendition in the desktop environment.

When building mobile portlets, you should adhere to the following guidelines:

Section 6.1.4.1, "Declare Capabilities"
Section 6.1.4.2, "Declare a Short Title"
Section 6.1.4.3, "Implement Personalization of the Short Title"
Section 6.1.4.4, "Implement Link Mode"
Section 6.1.4.5, "Heed Device Information"
Section 6.1.4.6, "Tailor Personalization Pages"

For information on how to build mobile-enabled portlets, refer to Section 7.2.10, "Enhancing Portlets for Mobile Devices".

6.1.4.1 Declare Capabilities

To properly manage portlets, Oracle Portal must know the set of content types a portlet generates. Oracle Portal uses this information in the following ways:

To restrict the Portlet Repository view in the Add Portlet dialog. Only those portlets capable of being rendered on the targeted page will appear in the Add Portlet dialog. For example, when a user invokes the Add Portlet dialog from a mobile design page, only portlets that indicate they can generate OracleAS Wireless XML responses are displayed.
To display an icon in the Portlet Repository view in the Add Portlet dialog that identifies portlets capable of being rendered on many devices. For example, when a user invokes the Add Portlet dialog from a standard design page, those portlets that are mobile capable are listed with the icon shown in Figure 6-2 to indicate they will also render on mobile devices.

Figure 6-2 Mobile-enabled Icon

Description of "Figure 6-2 Mobile-enabled Icon"
To display only those portlets registered with the capability of generating OracleAS Wireless XML when rendering a standard page on a mobile device.
To include only those portlets registered with the capability of generating OracleAS Wireless XML when creating a new mobile page based on an existing standard page.

6.1.4.2 Declare a Short Title

The small screen size of the typical mobile device limits the number of characters it can display in a single line without scrolling. Portlet titles, which appear as the menu item label when Oracle Portal renders the mobile page in a menu structure, are often too long for mobile displays. Hence, you can define a short title for your portlet. The short title replaces the standard title where display space is limited.

6.1.4.3 Implement Personalization of the Short Title

The standard portlet title represents the default portlet instance name when rendered in the header of a portlet on a standard page. The portlet's short title represents the default portlet instance name when rendered as a menu item in a mobile page. Just as we recommend that portlets support personalizing the standard title, we also recommend that your portlets support personalizing the short title. This functionality enables the page designer or end user to give the instance a meaningful name.

6.1.4.4 Implement Link Mode

When Oracle Portal renders a standard page to the desktop, it assembles portlets on the page in the tabular layout defined by the page designer. Thus, Oracle Portal aggregates the content of many portlets on a single page. Because of their small displays, mobile devices cannot effectively display the content of multiple portlets on a single page. Instead, the page's portlets appear as links (menu items). Users view portlet content by navigating the menu one portlet at a time. The menu item links typically use the portlet's short name. Since well behaved portlets allow personalization of the short name and the portlet manages its own personalization data, the portlet must participate in rendering the menu item link. To enable this functionality, you can implement the Link mode for portlets. In response to a request to render a portlet in Link mode, a portlet generates a link to itself in the appropriate content type. For example, if the render requests HTML, the portlet returns an anchor tag. If the render requests OracleAS Wireless XML, the portlet returns a SimpleHref tag.

6.1.4.5 Heed Device Information

All requests, whether from mobile devices or the desktop, pass general device information. For example, one passed attribute identifies the device class, such as pcbrowser, pdabrowser, or microbrowser (cell phones). A portlet developer may use this attribute to adjust the response's layout or quantity of data.

6.1.4.6 Tailor Personalization Pages

A single portlet instance must maintain a single set of user personalizations spanning all devices, mobile and desktop. Therefore, the same personalization page appears even if the instance is shared between a standard and mobile page, and some fields apply only to one environment, desktop or mobile. In this situation, the portlet should identify these fields that pertain to only one environment. For example, a portlet might display a mobile-only section on its personalization page. Furthermore, because the mobile capability is configurable, a portlet could remove mobile-only references from its personalization page when it detects that the mobile functionality is disabled.

6.2 Introduction to Java Portlet Specification (JPS) and WSRP

Organizations engaged in enterprise portal 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 changes with the introduction of the following standards:

Web Services for Remote Portlets (WSRP)
Java Portlet Specification (JPS)^Foot 1 based on JSR 168

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 enterprise portals.

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:

Web Services Definition Language (WSDL) interface for the invocation of WSRP services
Markup fragment rules for markup emitted by WSRP services
The method to publish, find, and bind WSRP services and metadata

JPS 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. JPS 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

Oracle actively participates in the WSRP committee and is also a member of the expert group for JPS.

Note:

HTML forms can be submitted using either the get or post method, but the WSRP standard only requires the consumer (portal) to use the post method. Support of the get method is optional according to the standard. Since portal 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 JPS

WSRP is a communication protocol between portal servers and portlet containers, while JPS describes the Java Portlet API for building portlets. Combining these standards enables developers to integrate their applications from any internal or external source as portlets with WSRP portals. Building portal pages becomes as simple as selecting portlets from the Oracle Portal repository. Figure 6-3 shows the architecture of the WSRP specification.

Note:

Figure 6-3 illustrates the use of JPS portlets with WSRP, but it should be noted that WSRP can also work with non-JPS portlets.

Figure 6-3 WSRP Specification Architecture

Shows JPS portlet containers and WSRP portal.

Description of "Figure 6-3 WSRP Specification Architecture"

Since Oracle Portal's existing architecture is so similar to the one specified by the WSRP committee, Oracle Portal is able to support communication between our portal and both the new Java Portlet APIs as well as our existing APIs (PDK-Java). Figure 6-4 shows the architecture of the WSRP portal. Notice that the JPS-compliant portlet container uses the WSRP protocol for communication and the PDK-Java portlet container uses Oracle's proprietary SOAP protocol for communication.

Figure 6-4 Oracle Portal's WSRP Architecture

Shows PDK-Java and JPS portlets and WSRP portal.

Description of "Figure 6-4 Oracle Portal's WSRP Architecture"

6.3 Building JPS-Compliant Portlets with Oracle JDeveloper

Using the JSR 168 Portlet Wizard in Oracle JDeveloper you can expose your portlet over WSRP quickly and easily.

This section assumes the following:

You are familiar with portlet terminology such as portlet Show modes. See Chapter 1, "Understanding Portlets" and Section 6.1, "Guidelines for Writing Java Portlets."
You are already familiar with Oracle JDeveloper and know how to build and deploy Java components using it. You can download Oracle JDeveloper from OTN. Visit the Oracle JDeveloper page on OTN:
```
http://www.oracle.com/technology/products/jdev/index.html
```

This section contains the following subsections:

Section 6.3.1, "Creating a JSR 168 Portlet"
Section 6.3.2, "Adding Portlet Logic to Your JSR 168 Portlet"
Section 6.3.3, "Deploying Your JSR 168 Portlet to the Oracle WebLogic Server"
Section 6.3.4, "Registering and Viewing Your JSR 168 Portlet"
Section 6.3.5, "Registering WSRP Producers in Enterprise Configurations"

6.3.1 Creating a JSR 168 Portlet

This section walks you through the JSR 168 Java Portlet Wizard. You can choose which portlet Show modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML). The wizard then creates a simple sample implementation for each of the selected modes.

The steps to create a portlet using the JSR 168 Java Portlet Wizard are as follows:

Start Oracle JDeveloper.
In the Application Navigator, expand the application under which you want to create your portlet.
Right-click the project under which you want to create your portlet, and select New.
Note:

If you do not have a project yet, you can create one in one of the following two ways:
- Right-click an existing application in the Application Navigator and choose New Project. Select Empty Project and click OK. Fill out the Create Project dialog box and click OK.
- Right-click the Applications node and choose New Application. Fill out the Create Application dialog box and click OK. When the Create Project dialog box appears, fill it out and click OK.
In New Gallery, expand Web Tier, select Portlets and then Standards-based Java Portlet (JSR 168) (see Figure 6-5).

Selecting Standards-based Java Portlet opens the Portlet Wizard for creating JPS-compliant portlets. Selecting Oracle PDK-Java Portlet opens the Portlet Wizard for creating PDK-Java portlets.

Note:

To create standards-based Java portlets for Oracle Portal 11g, you must use Oracle JDeveloper version 11.1.1.1.0, 11.1.1.2.0, or 11.1.1.3.0 because only these versions support the creation of JSR-168 portlets.

Figure 6-5 New Gallery Dialog Box for Standards-based Java Portlet

Description of "Figure 6-5 New Gallery Dialog Box for Standards-based Java Portlet"
Click OK to display the General Portlet Information page (see Figure 6-6).

Figure 6-6 General Portlet Information Page

Description of "Figure 6-6 General Portlet Information Page"
In the Name field, enter a name for the portlet. You can accept the default name or enter your own.
In the Class field, enter a name for the class that the wizard will create for the portlet. You can accept the default name provided or enter your own. If you supply your own name, it must be a valid Java name.
From the Package list, select the package in which the class will reside. Click the Browse button to find packages within the project. If you do not select a specific package, the wizard uses the default package of the project.
From the Language list, select the default language that your portlet will support. The wizard uses English by default.
If you want your portlet to support Edit mode, select Enable users to edit portlet content. In the wizard, this option is selected by default..

If you select this option, you can specify the details for the Edit mode later on in the wizard.
If you want to create a portlet that supports Oracle WSRP 2.0 extensions, select Enable inter-portlet communication using Oracle WSRP V2 extensions and then click Next.

Note:

JSR 168 portlets built with Oracle extensions can be consumed by any consumer that supports WSRP 2.0. To leverage WSRP 2.0, the portlets must be deployed to the Oracle WebLogic Server.
In the Additional Portlet Information page (see Figure 6-7) In the Display Name field, enter a name for your portlet. This name will be displayed in the Oracle Portal catalog or repository.

Figure 6-7 The Additional Portlet Information page

Description of "Figure 6-7 The Additional Portlet Information page"
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 that will 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.
In the Portlet Title field, enter a title for your portlet. This title will be displayed on the portlet header when the portlet appears on a page.
In the Short Title field, enter a shorter title for your portlet. This short title will be displayed on the portlet header when the portlet appears on a page on a mobile device.
In the Description field, enter a description of your portlet. This description will be displayed beneath the portlet name in the Portlet Repository.
In the Keywords field, enter any additional keywords to help users find your portlet in a search.
Click Next to display the Content Types and Portlet Modes page shown in Figure 6-8.

Alternatively, you can click Finish to create the portlet immediately, using the default values for all remaining settings.

Figure 6-8 Content Types and Portlet Modes Page

Description of "Figure 6-8 Content Types and Portlet Modes Page"
By default, your portlet will display text/html as the content type. If you want to add other content types, select text/html, then click Add.

The list of available content types displays (Figure 6-9). Select the desired content types in the Available list and use the arrow buttons to move them to the Selected list. When you are finished, click OK.

Figure 6-9 Content Types Dialog Box

Description of "Figure 6-9 Content Types Dialog Box"
By default, your portlet includes view mode. If you selected Editable on the General Portlet Properties page, your portlet also includes Edit mode. If you want to include additional portlet Show modes, select an existing Show mode (for example, view), then click Add.

The list of available portlet Show modes displays (Figure 6-10). You can add Show modes by moving the desired modes from the Available list to the Selected list. When you are finished, click OK. For more information about portlet Show modes, see Section 6.1, "Guidelines for Writing Java Portlets."

Figure 6-10 Portlet Modes Dialog Box

Description of "Figure 6-10 Portlet Modes Dialog Box"
Once you have added all of the desired portlet Show modes, choose a function to be performed for each mode. For each portlet mode, click the portlet mode and select an option on the right as follows:
- Select Generate JSP if you want Oracle JDeveloper to generate a JSP for the portlet mode. Enter a name for the JSP in the corresponding field, or accept the defaults.
  
  When you complete the wizard, the generated JSP displays in the Application Navigator where it can be selected for further development. This is the default selection for all portlet display modes. This selection enters code in the generated portlet java class that routes requests for the given mode to the generated JSP.
- Select Generate ADF-Faces JSPX to generate .jspx files. The .jspx files will generate exactly the same markup as JSPs.
- Select Map to Path if you want to map the portlet to an existing Web resource, such as a page. Enter the path in the corresponding field. 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 if you want to implement the portlet mode through a custom coded object. You will create this object later. This selection generates a skeleton method to render content (private void do<MODE_NAME><CONTENT_TYPE>) in the generated portlet Java class. You must update this code to render useful content.
Click Next.

If you selected Editable on the General Portlet Properties page earlier in the wizard, then the Customization Preferences page displays(Figure 6-11). Go to step 23.

If you did not select this option, then the Security Roles page displays (Figure 6-13). Go to step 31.

Figure 6-11 Customization Preferences Page

Description of "Figure 6-11 Customization Preferences Page"
If you want to include additional customization preferences, click Add. The Add New Preferences dialog box displays.

Figure 6-12 Add New Preference Dialog Box

Description of "Figure 6-12 Add New Preference Dialog Box"
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 Value(s) field, enter one or more default values for the new customization preference. Separate multiple values with commas.
Select the Translate Preference check box if you want the customization preference value to be translated. If you select this option, Oracle JDeveloper generates a resource bundle class with strings for which you can obtain translations. At run time, the portlet references the resource bundle entries.

Note:

The Name is always translated, but there is not always a need to translate the Default Value. For example, if the value is an integer, no translation is needed
Click OK. Repeat the preceding steps if you want to add more customization preferences.
To edit details for existing customization preferences, select the preference in the Portlet Preferences list and edit the fields in the Preference Details section.
To delete an existing customization preference, select the preference in the Portlet Preferences list and click Remove.
Click Next to display the Security Roles page (Figure 6-13).

Figure 6-13 Security Roles Page

Description of "Figure 6-13 Security Roles Page"
JSR 168 portlets may use J2EE security roles that are defined in web.xml and referenced in portlet.xml. The Available list displays the security roles defined in the portlet application's Web deployment file (web.xml). Moving a security role from the Available list to the Selected list creates a reference to the security role in the application's portlet deployment file (portlet.xml) that refers to the security role in web.xml.
If you want to define a new security role, click New Security Role. The Create New Security Role dialog box displays (Figure 6-14).

Figure 6-14 Create New Security Role Dialog Box

Description of "Figure 6-14 Create New Security Role Dialog Box"
In the Name field, enter a unique name for the security role.
In the Description field, enter a description for the security role, explaining the access privileges and restrictions this role will have on the portlet.
Click OK.

The new security role is added to the Available list. You can also manually create security roles.
Click Next to display the Caching Option page (Figure 6-15).

Figure 6-15 Caching Option Page

Description of "Figure 6-15 Caching Option Page"
Select Cache Portlet if you want to enable caching for your portlet.

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.
In the Default Expiry Conditions section, select:
- Cache Content Expires After [] Seconds if you want the cached portlet content to expire after a certain amount of time. Specify the time limit in the adjacent field.
- Cache Content Never Expires if you do not want the cached portlet content to expire. You may want to select this option if the portlet contains static content that is unlikely to change.
Note:

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 that you want default caching for the portlet, you can easily go back and change the cache duration value in the portlet.xml file, which is generated by the wizard, to a number greater than zero.
Click Next to display the Initialization Parameters page (Figure 6-16).

Figure 6-16 Initialization Parameters Page

Description of "Figure 6-16 Initialization Parameters Page"
Initialization parameters provide the Web 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 Web application (for example, servlets and portlets) in a compatible way. These initialization parameters are added to the portlet.xml file.

If you want to add an initialization parameter, click New. This adds a new row to the table of parameters. You can then double click the row to edit the details.
In the Name field, enter a unique name for the initialization parameter. Use only letters, numbers, and the underscore character.
In the Value field, enter a default value for the parameter.
In the Description field, enter a description for the parameter.
To delete an initialization parameter, select it in the table and click Remove.
Click Next to display the Finish page.

Note:

If your Portal is WSRP2 enabled, then the Portal Navigation Parameters page appears. Click Next to display the Finish page.
Click Finish to generate the files for your portlet. The following files should be generated for your project node in the Application Navigator (see Figure 6-17):
- If you selected Generate JSP for the portlet modes, generated code for each mode
  
  If you selected Custom Code instead, that code will reside in the portlet's Java class.
- Two Java classes
  - <packagename>.<portletname>.java is invoked by the portlet container and contains all the methods required by the portlet standards
  - <packagename>.<portletname>Bundle.java contains all the translation strings for the portlet
- portlet.xml
- oracle-portlet.xml
- web.xml
Figure 6-17 Application Navigator

Description of "Figure 6-17 Application Navigator"

6.3.2 Adding Portlet Logic to Your JSR 168 Portlet

After you create the default implementation of your portlet, you can extend the sample code with your own business logic to implement the desired functionality and features. See the JPS or Javadoc for more information on adding functionality and features.

6.3.3 Deploying Your JSR 168 Portlet to the Oracle WebLogic Server

After you finish the wizard and successfully generate your portlet, you are ready to deploy it to the Oracle WebLogic Server. To create and deploy a WAR file, perform the following steps:

In the Application Navigator, right-click the project that contains your portlet and select New.
In the New Gallery, expand General and select Deployment Profiles.
In the Items list, select WAR File and click OK.

The Create Deployment Profile -- WAR File dialog box opens.
In the Deployment Profile Name field, enter a meaningful name for the deployment profile (for example, webapp).
Click OK.

The Edit WAR Deployment Profile Properties dialog box opens.
Under Web Application's Context Root, select Specify J2EE Web Context Root and enter the context root in the corresponding field, for example my-portlet.
Click OK.

The Project Properties dialog box opens.
Click OK.
In the Application Navigator, right-click your project and select Deploy, then select the deployment profile, next select to, and finally select the IntegratedWLSConnection.
In the Select deployment type dialog box, select Yes and click OK.
When the Deployment Finished message displays in the Deployment Log at the bottom of Oracle JDeveloper, verify that no errors occurred.
Construct the WSDL URL for your JPS-compliant portlet as follows:
```
http://host:port/context-root/portlets/wsrp2?WSDL
```
where host is the server to which your producer has been deployed.

port is the Oracle Web Cache HTTP Listener port from the Ports tab of the Application Server Control Console main page.

context-root is the Web Application's Context Root, which is found in the WAR Deployment Profile Properties under General.
In a Web browser, enter the WSDL URL from the previous step to ensure that it is working. If the WSDL definition does not appear in the browser, then the deployment of your WAR file must have failed. Refer to Appendix B, "Diagnosing Java Portlet Problems".
If you are using SSL (HTTPS), you must modify your WSDL URL before registering the producer with Oracle Portal. If you are not using SSL, you may skip to the next step now.

Note:

In order for HTTPS to work with a producer, you must have previously configured the server certificate in the infrastructure server certificate store as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

To modify your WSDL URL, perform the following steps:
1. In a Web browser, enter the HTTPS WSDL URL. For example:
```
http://host:port/context-root/portlets/WSRPBaseService?WSDL
```
  Each port in the definition should be displayed with an HTTPS location, for example:
```
<wsdl:port binding="bind:WSRP_v1_Markup_Binding_SOAP" name="WSRPBaseService">
<soap:address location="https://host:port/context-root/portlets/WSRPBaseService"/>
</wsdl:port>
```
2. If the ports are not listed with HTTPS locations, you must change them manually before proceeding. You can do this by saving the XML to a file from the browser and opening it in a text editor.
3. Save a copy of the WSDL definition to a file on your application server in a location where it can be accessed externally over HTTP. For example, the htdocs directory of your Apache installation. When you register the producer in Oracle Portal, use the location of this WSDL for your WSDL URL on the Define Connection page of the registration.
You should now register your producer and view your portlet. Refer to Section 6.3.4, "Registering and Viewing Your JSR 168 Portlet".

When you redeploy your portlets to the portlet container, all existing sessions between the producer and all of its consumers are lost. If a consumer tries to reuse an existing producer session, it may receive an error message the first time it tries to contact the producer after redeployment.
```
Error: Could not get markup. The cookie or session is invalid or there is a runtime exception. 
```
To reestablish the producer's session, refresh the portal page. You won't see this error message if you are re-accessing the portlet from a new browser session because it automatically establishes a new producer session.

6.3.4 Registering and Viewing Your JSR 168 Portlet

After you've created and deployed the provider and its portlets, you should register the provider with Oracle Portal. Registering your provider gives Oracle Portal the information it needs to locate and communicate with that provider. After you register a provider, the provider and its portlets become available in the Portlet Repository. They are also listed in the Oracle Portal Navigator.

Note:

When you build portlets and providers with built-in tools, such as the Portlet Builder, Oracle Portal automatically registers the provider for you. Once you've created your portlet, it automatically displays in the Portlet Repository. Oracle Portal also offers built-in portlets that are contained in a preconfigured provider. For example, OmniPortlet and Web Clipping are portlets that you can use out of the box, and are already registered with Oracle Portal. You can view these portlets in the Add Portlets list. However, if you build the portlets and providers programmatically, you must then register these providers to make them available to the portal user.

To register providers for your standards-based portlets:

Open Oracle Portal and log in. Note that to register your provider, you need to have Manage or Edit privileges on providers. If you do not have these privileges, you need to request them from your administrator.
If you are not already on the Portal Builder page, click Builder in the upper right corner.
Click the Administer tab.
Click the Portlets subtab.
In the Remote Providers portlet, click Register a Provider to display the Register Provider page (Figure 6-18).

Figure 6-18 Register Provider Page

Description of "Figure 6-18 Register Provider Page"
In the Name field, enter the name of the provider. This name must not be more than 200 characters or contain spaces or other special characters.
In the Display Name field, enter a name to display for the provider when it is referenced, for example in the Portlet Repository. The display name must not be more than 200 characters.
In the Timeout field, enter the number of seconds Oracle Portal should try to connect to the provider before displaying the timeout message.
In the Timeout Message field, enter the message to display when Oracle Portal cannot establish contact with the provider within the number of seconds specified in the Timeout field. The message displays within the body of the portlet. The message may not contain HTML or mobileXML.
From the Implementation Style list, select WSRP for your WSRP provider.

Note:

If a provider is unavailable for some reason, it can slow down the rendering of pages that contain portlets from that provider. By default, Oracle Portal waits until all portlets are returned before completing the page assembly. To avoid delays, you can set a time limit using the Page Assembly Timeout on the Main tab of the page properties. If Oracle Portal cannot retrieve the portlet from the provider within the specified timeout period, it will render the page without the portlet. If, at a later time, the provider becomes available, Oracle Portal refreshes the page, adding the missing portlets. In this way, page rendering is never halted due to the unavailability of a particular provider. For more information about Page Assembly Timeout, see the Oracle Fusion Middleware User's Guide for Oracle Portal.
Click Next to display the Define Connection page (Figure 6-19).
In the WSDL URL field, enter the WSDL URL for your provider. For example:
```
http://myserver.com:8888/my-portlet/portlets/WSRPBaseService?WSDL
```
Figure 6-19 Define Connection Page

Description of "Figure 6-19 Define Connection Page"

Note:

A WSRP producer can contain portlets that work within the WLDL v1 or v2 framework. WLDL v1 portlets work in pre-11gR1 Oracle Portal releases. WSDL v2 portlets work in Oracle Portal 11gR1. When a WSRP producer containing v2 portlets is registered with its v1 URL, the portlet repository displays the v1 registration name and only the v1 portlets.

So, when a WSRP producer containing only v2 portlets is registered with its v1 URL, the portlet repository displays only the registration name; it does not display any portlet.
Click Next to display the Portal Registration Property Values page (Figure 6-20).
Provide any registration properties required by the provider. If there are none, you can proceed to the next step.

Figure 6-20 Provider Registration Property Values Page

Description of "Figure 6-20 Provider Registration Property Values Page"
Click Finish. You should see a Registration Confirmation page similar to the one in Figure 6-21.

Figure 6-21 Registration Confirmation Page

Description of "Figure 6-21 Registration Confirmation Page"
Your portlet should now be available for adding to pages just as any other portlet in the Portlet Repository. To add your portlet to a page, follow the instructions in the Oracle Fusion Middleware User's Guide for Oracle Portal.

6.3.5 Registering WSRP Producers in Enterprise Configurations

When you register a WSRP producer in an Enterprise configuration, you must create a Web Seringy!!vices Definition Language (WSDL) document manually, then register the WSRP producer using that WSDL. This is because the dynamically generated WSDL creates URLs using the HTTPS protocol and the HTTPS port while WSRP producers use HTTP.

Note:

A producer for WSRP portlets is analogous to a provider for PDK-Java portlets.

To create a WSDL document manually, perform the following tasks:

View the dynamically generated WSDL through your browser (preferably Internet Explorer).

To view the WSDL for our WSRP samples, go to:
```
http://host:external http port/portletapp/portlets?WSDL
```
Save the file from the browser to any externally available location.

For our WSRP Samples, save the file from the browser into the following directory:

ORACLE_HOME/j2ee/home/applications/portletapp/wsrp-samples

Save the file as wsrpsamples.wsdl.
Edit the file, replacing https with http and correcting the ports to be the external http ports.
View the file through a browser.

For example, for our WSRP Samples use the following URL:
```
http://host:external http port/portletapp/wsrpsamples.wsdl
```
Use the URL to your *.wsdl file (such as the URL under Step 4) when you register the WSRP producer.

For more information about Enterprise configurations, see the Oracle Fusion Middleware Enterprise Architecture and Deployment Guide.

6.4 Introduction to Oracle PDK-Java

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

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

The Provider Adapter insulates the developer from the HTTP syntax defined by Oracle Portal for communication with Web providers. It translates the information passed between Oracle Portal and your Java Web provider. Without an adapter, your provider would not only manage portlets, but it would also have to communicate this information directly to Oracle Portal in the expected language. The adapter eliminates the need for your Web provider to understand the portal language and vice-versa.
The Provider Interface defines the APIs (functions) required by your Java implementation to integrate with the Provider Adapter. The Provider Adapter receives messages from the portal, translates them into calls to the Provider Interface, and translates the provider's response into a format that the portal can understand. The Provider Interface contains a set of Java classes that define the methods your provider needs to implement and, in many cases, 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 Provider Runtime provides a base implementation that follows the specification of the Provider Interface. The Provider Runtime includes a set of default classes that implement each one of the Provider 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 provider by implementing common functions for Oracle Portal requests and providing a declarative mechanism for configuring the provider. Using the Provider Runtime, you can focus your development efforts on the portlets themselves rather than the infrastructure needed to communicate with the portal. If the standard behavior of the Provider Runtime does not meet your requirements, you can easily extend or override specific behaviors. Some of the primary classes are as follows:
- DefaultProviderDefinition (oracle.portal.provider.v2.DefaultProviderDefinition)
- DefaultProviderInstance (oracle.portal.provider.v2.DefaultProviderInstance)
- DefaultPortletDefinition (oracle.portal.provider.v2.DefaultPortletDefinition)
- DefaultPortletInstance (oracle.portal.provider.v2.DefaultPortletInstance)
- PortletRenderer (oracle.portal.provider.v2.render.PortletRenderer)
- PortletPersonalizationManager (oracle.portal.provider.v2.personalize.PortletPersonalizationManager)
- PortletSecurityManager (oracle.portal.provider.v1.http.DefaultSecurityManager)
The Provider 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 portal page, and supporting portlet caching.

6.5 Building Oracle PDK-Java Portlets with Oracle JDeveloper

Using the Oracle PDK-Java Portlet Wizard in Oracle JDeveloper you can begin your portlet development quickly and easily.

This section assumes the following:

You are familiar with portlet terminology such as portlet Show modes. Refer to Chapter 1, "Understanding Portlets" and Section 6.1, "Guidelines for Writing Java Portlets".
You are already familiar with Oracle JDeveloper and know how to build and deploy Java components using it. You can download Oracle JDeveloper from OTN. Visit the Oracle JDeveloper page on OTN:
```
http://www.oracle.com/technology/products/jdev/index.html
```

This section contains the following sections:

Section 6.5.1, "Creating an Oracle PDK-Java Portlet and Provider"
Section 6.5.2, "Adding Portlet Logic to Your Oracle PDK-Java Portlet"
Section 6.5.3, "Validating Your Oracle PDK-Java Portlet and Provider"
Section 6.5.4, "Deploying Your Oracle PDK-Java Portlet to an Application Server"
Section 6.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet"

6.5.1 Creating an Oracle PDK-Java Portlet and Provider

This section walks you through the Oracle PDK-Java Portlet Wizard. You can choose which portlet Show modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML). The wizard then creates a simple sample implementation for each of the selected modes.

The steps to create a portlet and provider are as follows:

Start Oracle JDeveloper.
In the Application Navigator, expand the application under which you want to create your portlet.
Right-click the project under which you want to create your portlet, and select New.
Note:

If you do not have a project yet, you can create one in one of the following ways:
- Right-click an existing application in the Application Navigator and choose New Project. Select Empty Project and click OK. Fill out the Create Project dialog box and click OK.
- Right-click the Applications node and choose New Application. Fill out the Create Application dialog box and click OK. When the Create Project dialog box appears, fill it out and click OK.
In the New Gallery, expand the Web Tier category and select Portlets.
In the Items list, select Oracle PDK-Java Portlet (Figure 6-22).

Note:

Selecting Standards-based Java Portlet opens the Portlet Wizard for creating JPS-compliant portlets. Selecting Oracle PDK-Java Portlet opens the Portlet Wizard for creating PDK-Java portlets.

Figure 6-22 New Gallery Dialog Box for Oracle PDK-Java Portlet

Description of "Figure 6-22 New Gallery Dialog Box for Oracle PDK-Java Portlet"
Click OK to display the Provider Details Page (Figure 6-23).

Figure 6-23 Provider Details Page

Description of "Figure 6-23 Provider Details Page"
In the Provider Details page, enter a name for the new producer that will contain your portlet. This name must be unique within the project. In the PDK-Java, the term provider is used instead of producer. A provider is exactly the same thing as a producer.
Select Generate Deployment Properties File.

This automatically generates two .properties files:
- 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 more than one producer, 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.

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.
Click Next to display the General Portlet Information Page.

Figure 6-24 General Portlet Information Page

Description of "Figure 6-24 General Portlet Information Page"
In the Portlet Name field, enter a meaningful name for your portlet. This 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.
In the Display Name field, enter a display name for your portlet. This name will be displayed in portlet selection lists, such as the Portlet Repository, where users choose which portlets to add to a page.
In the Description field, enter a description for your portlet. This description will be displayed beneath the portlet name in the Portlet Repository.
In the Timeout 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 value specified.
Click Next to display the View Modes page (Figure 6-25).

Figure 6-25 View Modes Page

Description of "Figure 6-25 View Modes Page"
In the Show page section, select the implementation style for Shared Screen mode from the Implementation style list:
- 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 in conjunction 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, it results in the following being added inside the <renderer> element of your provider.xml file:
```
<showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
   <resourcePath>/hub_inside/index.html</resourcePath>
   <contentType>text/html</contentType>
   <charSet>UTF-8</charSet>
</showPage>
```
  <charSet> tells the provider what character set to use to encode the HTML page. The default character set specified by the wizard is UTF-8. If you require character set encoding other than UTF-8, 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.
For more information about Shared Screen mode, see Section 6.1.1.1, "Shared Screen Mode (View Mode for JPS)."
If you want to implement Full Screen mode for your portlet, select Show details page, then select an Implementation style as described earlier for Show page.

For more information about Full Screen mode, see Section 6.1.1.5, "Full Screen Mode (PDK-Java)."
Click Next to display the Customize Modes page (Figure 6-26)

Figure 6-26 Customize Modes Page

Description of "Figure 6-26 Customize Modes Page"
Edit page is selected by default. If you want to implement Edit mode for your portlet, select an Implementation style as described earlier for Show page. If you do not want to implement Edit mode, clear the Edit page check box.

For more information about Edit mode, see Section 6.1.1.2, "Edit Mode (JPS and Pdk-Java)."
If you want to implement Edit Defaults mode for your portlet, select Edit Defaults page, then select an Implementation style as described earlier for Show page.

For more information about Edit Defaults mode, see Section 6.1.1.3, "Edit Defaults Mode (JPS and PDK-Java)."
Click Next to display the Additional Modes page (Figure 6-27).

Figure 6-27 Additional Modes Page

Description of "Figure 6-27 Additional Modes Page"
If you want to implement Help mode for your portlet, select Help page, then select an Implementation style as described earlier for Show page.

For more information about Help mode, see Section 6.1.1.6, "Help Mode (JPS and Oracle Portal)."
If you want to implement About mode for your portlet, select About page, then select an Implementation style as described earlier for Show page.

For more information about About mode, see Section 6.1.1.7, "About Mode (JPS and PDK-Java)."
Click Next to display the Public Portlet Parameters page (Figure 6-28)

Figure 6-28 Public Portlet Parameters Page

Description of "Figure 6-28 Public Portlet Parameters Page"
If you want to add public parameters to your portlet, click Add to create a blank row. For more information about using parameters, see Section 7.2.3, "Passing Parameters and Submitting Events."
In the Name field, enter an internal name for the parameter, for example, MyParam.
In the Display Name field, enter a name to display to users, for example, My Portlet Parameter.
In the Description field, enter descriptive information about the parameter.
Click Next to display the Public Portlet Events page (Figure 6-29).

Figure 6-29 Public Portlet Events Page

Description of "Figure 6-29 Public Portlet Events Page"
On this page you can map parameters to events. For more information about using events, see Section 7.2.3, "Passing Parameters and Submitting Events."
Click Finish to generate the files for your portlet. The following files should be generated for your project in the Application Navigator (see Figure 6-30):
- Files for each portlet mode you selected
- provider.xml
- web.xml
- index.jsp
- _default.properties
- <serviceID>.properties
All these files are required to deploy and run the portlet successfully, except for index.jsp, which is used by Oracle JDeveloper for testing purposes.

Figure 6-30 Application Navigator

Description of "Figure 6-30 Application Navigator"

6.5.2 Adding Portlet Logic to Your Oracle PDK-Java Portlet

6.5.3 Validating Your Oracle PDK-Java Portlet and Provider

After you have built your portlet, you need to check the configuration to ensure that the portlet and its provider operate correctly.

Note:

This procedure is for testing purposes only. After this procedure, you still need to register your provider as described in Section 6.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet". For development and production, you should always deploy your portlet to an application server as described in Section 6.5.4, "Deploying Your Oracle PDK-Java Portlet to an Application Server".

To validate your portlet and provider:

In Oracle JDeveloper, open the project you created in the previous sections.
In the Application Navigator, right-click the index.jsp file for you portlet and select Run.

Your browser opens a page similar to the one shown in Figure 6-31.

Figure 6-31 Portlet Application Test Page

Description of "Figure 6-31 Portlet Application Test Page"
Click the link underneath Service Name.

Your browser opens with a page similar to the one shown in Figure 6-32. Note that you need the URL from this page to register your provider, which is the next task.

Figure 6-32 Provider Test Page

Description of "Figure 6-32 Provider Test Page"

6.5.4 Deploying Your Oracle PDK-Java Portlet to an Application Server

After you finish the wizard and successfully generate your portlet, you are ready to deploy it to the Oracle WebLogic Server (WLS). The following sections describe how to deploy an Oracle PDK-Java portlet to WLS.

To create and deploy the WAR file:

In the Application Navigator, right-click the project that contains your portlet and select New.
In the New Gallery, expand the General category and select Deployment Profiles.
In the Items list, select WAR File and click OK. The Create Deployment Profile -- WAR File dialog box opens.
In the Deployment Profile Name field, enter a meaningful name for the deployment profile (for example, myj2eeportlet).
Click OK. The WAR Deployment Profile Properties dialog box opens.
Under Web Application's Context Root, select Specify Java EE Web Context Root and enter the context root in the corresponding field, for example myj2eeportlet1.
Select the Contributors node under WEB-INF/lib.
Select Portlet Development.
Click OK. The Project Properties dialog opens.
Click OK.
In the Application Navigator, right-click your project and select Deploy, then select the deployment profile, next select to, and finally select the application server connection to which you want to deploy the portlet.
When the Deployment Finished message displays in the Deployment Log at the bottom of Oracle JDeveloper, verify that no errors occurred.
Construct the URL for your portlet as follows:
```
http://host:port/context-root/providers
```
where host is the server to which your provider has been deployed.

port is the Oracle Web Cache HTTP Listener port from the Ports tab of the Application Server Control Console main page.

context-root is the Web Application's Context Root, which is found in the WAR Deployment Profile Properties under General.
In a Web browser, enter the URL from the previous step to ensure that it is working. You should see a page similar to the one in Figure 6-33.

Figure 6-33 PDK - Java Test Page for Portlets

Description of "Figure 6-33 PDK - Java Test Page for Portlets"

6.5.5 Registering and Viewing Your Oracle PDK-Java Portlet

Note:

To register providers for your Oracle PDK-Java portlets:

Open Oracle Portal and log in. Note that to register your provider, you need to have Manage or Edit privileges on providers. If you do not have these privileges, you need to request them from your administrator.
If you are not already on the Portal Builder page, click the Builder link in the upper right corner.
Click the Administer tab.
Click the Portlets sub tab.
In the Remote Providers portlet, click Register a Provider to display the Register Provider page.
In the Name field, enter the name of the provider. The name must not be more than 200 characters or contain spaces or other special characters.
In the Display Name field, enter a name to display for the provider when it is referenced, for example in the Portlet Repository. The display name must not be more than 200 characters.
In the Timeout field, enter the number of seconds Oracle Portal should try to connect to the provider before displaying the timeout message.
In the Timeout Message field, enter the message to display when Oracle Portal cannot establish contact with the provider within the number of seconds specified in the Timeout field. The message displays within the body of the portlet. The message may not contain HTML or mobileXML.
From the Implementation Style list, select Web.
Click Next to display the Define Connection page (Figure 6-34)

Figure 6-34 Define Connection Page

Description of "Figure 6-34 Define Connection Page"
In the URL field, enter the URL for your provider. This URL is the one that you created at the end of Section 6.5.4, "Deploying Your Oracle PDK-Java Portlet to an Application Server."
In the Service ID field, enter the service ID for your provider.

Note:

PDK-Java enables you to deploy multiple providers under a single adapter servlet. The providers are identified by the Service ID field. When you deploy a new provider, you must assign a service identifier to the provider and use that service identifier when creating your provider WAR file. The service identifier is used to look up a file called service_id.properties, which defines the characteristics of the provider, such as whether to display its test page.

For more information about service identifiers, refer to Section D.1.2, "Service Identifiers".

To access a sample provider test page, you must use the URL and service ID. An example of a URL for a sample provider is as follows:
```
http://myserver.com:8888/myj2eeportlet1/providers/sample
```
where, http://myserver.com:8888/myj2eeportlet1/providers is the URL value, and sample is the service ID.
Click Finish. You should see a Registration Confirmation page.
Your portlet should now be available for adding to pages just as any other portlet in the Portlet Repository. To add your portlet to a page, follow the instructions in the Oracle Fusion Middleware User's Guide for Oracle Portal.

6.6 Setting up the WSRP and JPDK Applications in Oracle Portal

This section describes steps to manually configure the WSRP and JPDK application and deploying them on the Oracle WebLogic Server.

This section includes the following subsections:

Configuring and Deploying the WSRP
Configuring and Deploying the JPDK

6.6.1 Configuring and Deploying the WSRP

To configure the WSRP, complete the following steps:

Creating WSRP Managed Server
Adding the Required Libraries to the WSRP Managed Server
Starting the WSRP Managed Server
Configuring the Datasource
Extending the Existing WebLogic Domain
Adding wsm-pm to the WSRP Managed Server
Deploying the Sample EAR File
Configuring Oracle Web Cache
Registering and Viewing Your Portlet

Creating WSRP Managed Server

You can create a WebLogic Managed Server on an existing domain using the Oracle WebLogic Server Administration Console to create the managed server instance and provision the shared libraries required to run a custom Oracle Portal application. To create the WSRP Managed Server, complete the following steps:

Log on to the Oracle WebLogic Server Administration Console.
If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the Domain Structure tree, expand Environment, and then select Servers.

The Summary of Servers page is displayed.
Click New.

The Create a New Server page is displayed.
In the Create a New Server page enter the following information:
- Server Name: Enter the name of the server, for example WLS_WSRP.
- Server Listen Port: Enter the port number from which you want to access the server instance. For example, 9003.
- Select the No, this is a stand-alone server radio button.
Click Finish.
In the Summary of Servers page, click on the Server (WLS_WSRP) you have created.
Select your machine name from the Machine drop-down list and click Save.
Click Activate Changes.

Adding the Required Libraries to the WSRP Managed Server

For a portlet producer application, you must deploy the following libraries to the new Managed Server or cluster:

oracle.portlet-producer.wsrp(11.1.1,11.1.1)
oracle.portlet-producer.jpdk(11.1.1,11.1.1)
DMS Application (11.1.1.1.0)
oracle.jrf.system.filter
oracle.jsp.next(11.1.1,11.1.1)
oracle.wsm.seedpolicies(11.1.1,11.1.1)
wsil-wls

To add the libraries, complete the following steps:

Click Lock & Edit.
In the Domain Structure tree, select Deployments.

The Summary of Deployments page is displayed.
Select oracle.portlet-producer.wsrp(11.1.1,11.1.1) from the Deployments table.

The Settings for oracle.portlet-producer.wsrp(11.1.1,11.1.1) page is displayed.

Note:

If the oracle.portlet-producer.wsrp(11.1.1,11.1.1) does not appear in the Deployment table, then click Customize this table, and disable the Exclude libraries when displaying deployments check box. Click Apply.
Click the Targets tab, and select AdminServer and WLS_WSRP from the Servers section.
Click Save.
Go to your Summary of Deployments page, and for each shared library, click the Targets tab, and then check AdminServer and WLS_WSRP from the Servers section.
To add the wsil-wls library, complete the following steps:
1. Select wsil-wls from the Deployments table.
2. Click the Targets tab, and select wsil-wls from the Component table.
3. Click Change Targets, and then check AdminServer and WLS_WSRP from the Servers section.
4. Click Yes.
Click Activate Changes.

Starting the WSRP Managed Server

To start the managed server, complete the following steps:

Click Lock & Edit.
In the Domain Structure tree, expand Environment, and then select Servers.

The Summary of Servers page is displayed.
Click the Control tab, and check your created server (WLS_WSRP).
Click Start.

The Server Life Cycle Assistant page is displayed.
Click Yes, to start the managed server.

Configuring the Datasource

To map the portletPrefs datasource targets to the managed server (WLS_WSRP), do the following:

In the Domain Structure tree, expand Services, and then select and expand JDBC and click Data Sources.

The Summary of JDBC Data Sources page is displayed.
Click the Name associated with the jdbc/portletPrefs JNDI.
Click the Targets tab, and check WLS_WSRP from the Servers section.
Click Save.
Click Activate Changes.

Extending the Existing WebLogic Domain

To extend your existing Oracle WebLogic Server domain with the Oracle WSM Policy Manager, complete the following steps:

Note:

You must stop all the servers running in the Oracle Portal domain.

Select Extend an existing WebLogic Domain and click Next.

The Select a WebLogic Domain Directory screen is displayed.
Select your valid domain directory and click Next.

The Select Extension Source screen is displayed.
Select Oracle WSM Policy Manager - 11.1.1.0 [Oracle_Common] (Select the one associated with your Oracle Portal) check box from the Extend my domain automatically to support the following added products option and click Next.

The Configure JDBC Data Sources screen is displayed.
Click Next.

The Test JDBC Data Sources screen is displayed.
Click Next.

The Configure JDBC Component Schema screen is displayed.
Check the OWSM MDS Schema and enter the Host Name, Port, DBMS/ Service, Schema Password for the MDS schema. Click Next.

Note:

This is the schema created for MDS when you run the Repository Configuration Utility (RCU) at install time. If you did not created this schema already then you need to create this schema first using RCU.

The Test Component Schema screen is displayed.
Confirm the test is successful and click Next.

The Select Optional Configuration screen is displayed.
Select Deployments and Services.
Click Next.

The Target Deployments to Clusters or Servers screen is displayed.
Ensure wsrp-pm is targeted to servers including WLS_WSRP and AdminServer.
Click Next.

The Target Services to Cluster or Servers screen is displayed
Click Next.
Review your settings in the Configuration Summary screen, and click Extend.
Click Done.

Start the Oracle WebLogic Administration Server, the managed server, and the WLS_WSRP managed server.

Adding wsm-pm to the WSRP Managed Server

You must add the wsm-pm to the WLS_WSRP managed server, by completing the following steps:

If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the Domain Structure tree, select Deployments.

The Summary of Deployments page is displayed.
Select wsm-pm from the Deployments table.
Click the Targets tab, and select wsm-pm from the Component table.
Click Change Targets, and then check AdminServer and WLS_WSRP from the Servers section.
Click Yes.

Deploying the Sample EAR File

To deploy the EAR file, download the wsrp-samples.ear file, from Download the Oracle Portlet Container at http://www.oracle.com/technology/products/ias/portal/pdk.html and do the following:

Click Lock & Edit.
In the Domain Structure tree, select Deployments.

The Summary of Deployments page is displayed.
Click Install.
Select wsrp-samples.ear from your directory, click Next.
Select Install this deployment as an application, and click Next.
Check WLS_WSRP from the Servers section, and click Next.
Enter a name for the deployment, and click Finish.
Click Activate Changes.
In the Summary of Deployments page, select the application you have deployed, and then click Start.

Now that you have deployed the sample EAR file, you need to test its WSDL URL by entering it into a browser. The WSDL URL is of the form:

http://host:port/portletapp/portlets?WSDL

You should see a page similar to the one shown in Example 6-1.

Example 6-1 WSRP Producer WSDL Page

<?xml version="1.0" encoding="UTF-8" ?> 
<definitions targetNamespace="urn:oasis:names:tc:wsrp:v1:wsdl"
 xmlns="http://schemas.xmlsoap.org/wsdl/"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:bind="urn:oasis:names:tc:wsrp:v1:bind">
<import namespace="urn:oasis:names:tc:wsrp:v1:bind"
 location="http://stamf10.us.abc.com:8090/wsrp-tools/portlets/wsrp1?WSDL=wsrp_v1_bindings.wsdl" /> 
<service name="WSRP_v1_Service">
<port name="WSRPServiceDescriptionService" 
 binding="bind:WSRP_v1_ServiceDescription_Binding_SOAP">
<soap:address location="http://stamf10.us.abc.com:8090/wsrp-tools/portlets/WSRPServiceDescriptionService" /> 
</port>
<port name="WSRPBaseService" binding="bind:WSRP_v1_Markup_Binding_SOAP">
<soap:address location="http://stamf10.us.abc.com:8090/wsrp-tools/portlets/WSRPBaseService" />
</port>
<port name="WSRPPortletManagementService"
 binding="bind:WSRP_v1_PortletManagement_Binding_SOAP">
<soap:address location="http://stamf10.us.abc.com:8090/wsrp-tools/portlets/WSRPPortletManagementService" /> 
</port>
<port name="WSRPRegistrationService" binding="bind:WSRP_v1_Registration_Binding_SOAP">
<soap:address location="http://stamf10.us.abc.com:8090/wsrp-tools/portlets/WSRPRegistrationService"/> 
</port>
</service>
</definitions>

Configuring Oracle Web Cache

To view the WSDL URL using the Oracle Web Cache port, edit the portal.conf file (Located at ORACLE_INSTANCE\config\OHS\ohs1\moduleconf in Windows) as follows:

<Location /portletapp>
    SetHandler weblogic-handler
    WebLogicHost servername.domain.com
    WebLogicPort 9003
</Location>

Save your file and restart the Oracle HTTP Server. Now you can access the WSDL URL through the Oracle Portal port (The default port is 8090).

Registering and Viewing Your Portlet

After you've created and deployed the provider and its portlets, you should register the provider with Oracle Portal. For more information, see Registering and Viewing Your JSR 168 Portlet in the "Oracle Fusion Middleware Developer's Guide for Oracle Portal."

6.6.2 Configuring and Deploying the JPDK

To configure and deploying the JPDK, perform the following:

Creating the JPDK Managed Server
Adding the Required Libraries to the JPDK Managed Server
Starting the JPDK Managed Server
Configuring the Datasource
Deploying the EAR File
Configuring Oracle Web Cache
Registering and Viewing Your Portlet

Creating the JPDK Managed Server

Log on to the WebLogic Server Administration Console.
If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the Domain Structure tree, expand Environment and then select Servers.

The Summary of Servers page is displayed.
Click New.

The Create a New Server page is displayed.
In the Create a New Server page enter the following information:
- Server Name: Enter the name of the server. For this step use WLS_JPDK as an example.
- Server Listen Port: Enter the port number from which you want to access the server instance. For this step use 9004 as an example.
- Select the No, this is a stand-alone server radio button.
Click Finish.
In the Summary of Servers page, click on the Server (WLS_JPDK) you have created.
Select your machine name from the Machine drop-down list and click Save.
Click Activate Changes.

Adding the Required Libraries to the JPDK Managed Server

For a portlet producer application, you must deploy the following libraries to the new Managed Server or cluster:

oracle.portlet-producer.jpdk(11.1.1,11.1.1)
DMS Application (11.1.1.1.0)
oracle.jsp.next(11.1.1,11.1.1)

To add the libraries, do the following:

Click Lock & Edit.
In the Domain Structure tree, select Deployments.

The Summary of Deployments page is displayed.
Select oracle.portlet-producer.jpdk(11.1.1,11.1.1) from the Deployments table.

The Settings for oracle.portlet-producer.jpdk(11.1.1,11.1.1) page is displayed.

Note:

If the oracle.portlet-producer.jpdk(11.1.1,11.1.1) does not appear in the Deployment table, then click Customize this table, and disable the Exclude libraries when displaying deployments check box. Click Apply.
Click the Targets tab, and select AdminServer and WLS_JPDK from the Servers section.
Click Save.
Go to your Summary of Deployments page, and for each shared library, click the Targets tab, and then check AdminServer and WLS_JPDK from the Servers section.
Click Activate Changes.

Starting the JPDK Managed Server

To start the managed server do the following:

Click Lock & Edit.
In the Domain Structure tree, expand Environment and then select Servers.

The Summary of Servers page is displayed.
Click the Control tab, and select your created server (WLS_JPDK).
Click Start.

The Server Life Cycle Assistant page is displayed.
Click Yes, to start the managed server.

Configuring the Datasource

To map the portletPrefs datasource targets to the managed server (WLS_JPDK), do the following:

In the Domain Structure tree, expand Services, and then select and expand JDBC and click Data Sources.

The Summary of JDBC Data Sources page is displayed.
Click the Name associated with the jdbc/portletPrefs JNDI.
Click the Targets tab, and check WLS_JPDK from the Servers section.
Click Save.
Click Activate Changes.

Deploying the EAR File

To deploy the JPDk, do the following:

Click Lock & Edit.
In the Domain Structure tree, select Deployments.

The Summary of Deployments page is displayed.
Click Install.

The Install Application Assistant page is displayed.
In the Path field, enter the location of the jpdk.ear file (Located at ORACLE_HOME/archives/applications for Windows and ORACLE_HOME\archives\applications for UNIX).
Select jpdk.ear, and click Next.
Select Install this deployment as an application, and click Next.
Check WLS_JPDK from the Servers section, and click Next.
In the Name field, enter a name for the deployment.
Click Finish.
Click Activate Changes.
Click Lock & Edit.
From the Summary of Deployments page, select the application and click Start and then, Servicing all requests.
From the Start Application Assistant, click Yes.
Now that you have deployed the sample EAR file, you need to test its URL by entering it into a browser. The URL is of the form:
```
http://host:port/jpdk/providers/sample/
```

For more information, see Creating Java Portlets in the Oracle Fusion Middleware Developer's Guide for Oracle Portal.

Configuring Oracle Web Cache

To view the JPDK sample URL using the Oracle Web Cache port, edit the portal.conf file (Located at ORACLE_INSTANCE\config\OHS\ohs1\moduleconf in Windows) as follows:

<Location /jpdk>
    SetHandler weblogic-handler
    WebLogicHost servername.domain.com
    WebLogicPort 9004
</Location>

Save your file and restart the Oracle HTTP Server. Now you can access the WSDL URL through the Oracle Portal port (The default port is 8090).

Registering and Viewing Your Portlet

After you've created and deployed the provider and its portlets, you should register the provider with Oracle Portal. For more information, see "Registering and Viewing Your Oracle PDK-Java Portlet" section in the Oracle Fusion Middleware Developer's Guide for Oracle Portal.

Footnote Legend

Footnote 1: The Java Portlet Specification 1.0 arose from Java Specification Request 168 and the JSR168 Expert Group.