| Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
| Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
This chapter explains how to create Java portlets based on the Java Portlet Specification (JSR 168) or the Oracle Application Server 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 18.2, "Introduction to Java Portlet Specification (JPS) and WSRP"
Section 18.3, "Configuring Your Application Server or Standalone OC4J to Run Portlets"
Section 18.5, "Building JPS-Compliant Portlets with Oracle JDeveloper"
Section 18.7, "Building PDK-Java Portlets with Oracle JDeveloper"
Section 18.9, "Deploying Your Portlet to an Application Server"
The source code for many of the examples referenced in this chapter is available as part of the Portlet Developer's Kit (PDK). You can download the PDK from it's 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.
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:
Portlet mode exhibits the run time portlet functionality seen by users. JPS offers some modes not offered by PDK-Java and vice versa. If you are coding portlets to JPS, then 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 called 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.
A portlet may have the following portlet modes, each with its own visualization and behavior:
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. 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 the page. For example, suppose you choose to place your portlet inside of an HTML table cell. This would mean the portlet could display only content that can be rendered within a table cell. Furthermore, the actual size of the table cell will vary depending on user settings, the browser width, and the amount and style of content in the portlet.
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, 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.
Consider restrictions imposed by container objects. If your portlet is contained inside of an HTML element, such as a table cell, then you must ensure that your portlet can be rendered within that container. For example, if you place a portlet in a table cell, then you could not use frames in the portlet because they 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, then 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 want and they can change it at any time. Your portlet should handle these situations gracefully.
The HTML you use also affects 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 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, then it can greatly slow the rendering of the page.
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 page. The portlets access these settings for their fonts and colors, either directly or using the Application Programming Interface (API).
While different browsers have implemented varying levels of the full CSS specification, Oracle WebCenter Framework uses a very basic subset of this specification to enable 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, then 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 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 pages, you cannot guarantee that your portlet can appear in a particular spot.
Follow Accessibility Standards. You should ensure that you code your style sheets according to existing accessibility standards (more information available at http://www.w3.org/TR/WCAG10-CSS-TECHS/).
A portlet uses Edit mode to enable 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.
Users typically access a portlet's Edit mode by choosing Personalize from the portlet's dropdown list of options. When users choose 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.
The following guidelines should govern what you expose to users in Edit mode:
Enable users to personalize the title of the portlet. The same portlet may be added to the same page several times. Enabling 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, then 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 producer settings or do other administrative tasks, then you should create secured portlets specifically for those tasks.
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 view mode.
Apply saves the user personalizations and reloads the current page.
Cancel returns the portlet to view mode without saving changes.
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, then 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, then 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 WebCenter application. PDK-Java makes this type of logic easy to implement.
A portlet uses the Edit Defaults mode to enable administrators to customize the default behavior of a particular portlet instance. Edit Defaults mode provides a list of settings that the application developer 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.
Administrators access Edit Defaults mode, when editing a page, by choosing Customize from the portlet's dropdown list.
When users click the Customize icon, the portlet displays in the same browser window. The portlet typically creates a Web page representing a dialog box to personalize the portlet instance settings. After applying the settings, users are automatically returned to the original page.
The following guideline should govern what you expose to page designers in Edit Defaults mode:
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 producer settings or do other administrative tasks, then you should create secured portlets specifically for those tasks.
For consistency and user convenience, Edit Defaults mode should implement the following buttons in the following order:
OK saves the user personalizations and returns the portlet to view mode.
Apply saves the user personalizations and reloads the current page.
Cancel returns the portlet to view mode without saving changes.
When you show the forms used to change personalization settings, you should default the values so that the application developer does not have to constantly re-enter settings. When rendering personalization 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 personalizations are found, then 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 personalizations to be presented in a predictable way, consistent with the other portlets in the WebCenter application.
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. Not all portlet consumers will call this mode. For example, Oracle Application Server Portal (OracleAS Portal) makes use of this mode but Oracle WebCenter Framework does not.
OracleAS Portal calls it when the user clicks the 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.
Note:
This mode has no particular application in WebCenter applications, but used in OracleAS Portal's Portlet Repository, where it renders as a magnifying glass icon, which users click to preview a portlet.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 work as expected when rendered in Preview mode. Hyperlinks can be simulated using the underline font.
Do not use active form buttons. Forms may not work as you expect them to when rendered in Preview mode. If you decide to render form elements, then do not link them to anything.
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. Not all portlet consumers will call this mode. For example, OracleAS Portal makes use of this mode but Oracle WebCenter Framework does not. In OracleAS Portal, users access a portlet's Full Screen mode by clicking the title of the portlet.
For example, if a portlet displays expense information, then 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, then it could link to the entire expense application from Full Screen mode.
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.
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.
Users access a portlet's Help mode by choosing the Help action in the portlet.
Guideline for Help Mode
The following guideline 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.
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.
Users access a portlet's About mode by choosing About from the dropdown list in the portlet's chrome. 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.
Guideline for About Mode
The following guideline 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.
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).
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 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 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 WebCenter application. If a link or form within a portlet does not refer back to the application, then following that link takes the user away from the application, which is not typically the desired behavior.
The component developer does not need to know the detailed mechanics of how the parameters of a form or link get passed around between the user, application, and portlet. However, they must understand that they cannot write links in a portlet the same way they do for typical, simple Web pages.
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 the WebCenter application because they actually refer to it in some way.
Application links, like intraportlet links, must be aware of the address of the WebCenter application for the same reason.
External links make no reference to the WebCenter application and work in portlets as they would do in a normal Web page.
Internal/Resource links, like external links, also make no reference to the WebCenter application.
Figure 18-1 contains a summary of these link types. The arrows indicate how the links reference the resources to which they logically refer.
Figure 18-1 WebCenter Application Link Types
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.
Application links refer to significant pages within the WebCenter application, such as the user's home page.
External links refer neither to the portlet (through a page) nor to any part of the WebCenter application. If selected, these links take the user away from the application, for example, www.oracle.com.
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. Note that in order for resource proxying to work, you must first set the JNDI variable, oracle/portal/provider/sample/resourceUrlKey, for the producer. For more information about setting JNDI variables, see Section 19.2.3.2, "Setting JNDI Variable Values".
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>
<%
}
For session-based producers, any cookies returned from the original initSession call to the producer are sent with the request back to the producer to maintain the right session context.
JavaScript can often be useful within a portlet, but bear in mind the following guidelines within your portlets:
Portlets with JavaScript should be rendered in Inline Frames (IFRAMEs). You can do this by setting RenderPortletInFrame to true. For more information about the RenderPortletInFrame attribute and how to set it, see Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag".
You should never use JavaScript to redirect the page in which the portlet is rendered. If you need to direct users elsewhere, then 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 JavaScript on the page.
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 component developer may use this attribute to adjust the response's layout or quantity of data.
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.
Organizations engaged in WebCenter application projects have found application integration to be a major issue. Until now, users developed portlets using proprietary APIs for a single portal platform and often faced a shortage of available portlets from a particular portal vendor. All this 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 WebCenter applications.
WSRP is a Web services standard that enables the plug-and-play of visual, user-facing Web services with portals or other intermediary Web applications. Being a standard, WSRP enables interoperability between a standards-enabled container and any WSRP portal. WSRP defines the following:
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 theget or post method, but the WSRP standard only requires the consumer (WebCenter application) to use the post method. Support of the get method is optional according to the standard. Since application consumers are not required to support the get method, Oracle recommends that you use the post method when developing your portlets.The Relationship Between WSRP and JPS
WSRP is a communication protocol between WebCenter application 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 pages becomes as simple as selecting portlets from the Oracle JDeveloper Component Palette. Figure 18-2 shows the architecture of the WSRP specification.
Note:
Figure 18-2 illustrates the use of JPS portlets with WSRP, but it should be noted that WSRP can also work with non-JPS portlets.Figure 18-2 WSRP Specification Architecture
Oracle WebCenter Framework is able to support communication between the WebCenter application and both the new Java Portlet APIs as well as our existing APIs (PDK-Java). Figure 18-3 shows the architecture of the WSRP support. 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 18-3 Oracle WebCenter Portlet Architecture
See Section 10.10, "Securing Identity Propagation Through WSRP Producers With WS-Security" for a description of how JSR 168 security concepts are exposed through WSRP.
You can run portlets from any number of configurations, each with its own set of requirements. This section describes the configuration requirements for two of the more common portlet scenarios: configuring Oracle Containers for J2EE (OC4J) in Oracle Application Server and configuring a standalone OC4J. If you have Oracle Application Server 10.1.3.2.0, then you already have an OC4J that is preconfigured to run portlet producers (OC4J_WebCenter). If you prefer not to use OC4J_WebCenter, or if you plan to use a standalone OC4J to run your portlet producers, then follow the steps provided in this section.
Note:
Oracle JDeveloper provides a preconfigured OC4J that supports PDK-Java and WSRP portlets out of the box. For information about the preconfigured OC4J, see Chapter 3, "Preparing Your Development Environment".To configure an application server OC4J instance or a standalone OC4J to run portlets, perform the following steps:
For an OC4J that is part of Oracle Application Server, create a new OC4J instance into which you can deploy your portlets:
Log in to the Application Server Control Console as oc4jadmin at:
http://host_name:port_number/em
For example:
http://localhost:8888/em
On the Cluster Topology page, click the link to your application server.
Under System Components, click the Create OC4J Instance button.
On the Create OC4J Instance page, specify a name for the OC4J instance.
For example, to create a separate instance for WSRP producers, you might name the instance wsrp. You can use any name you prefer.
Make sure the Start this OC4J instance after creation check box is not selected.
Click Create.
For a standalone OC4J, stop the standalone OC4J in the Application Server Control Console:
Log in to Application Server Control as oc4jadmin at:
http://host_name:port_number/em
For example:
http://localhost:8888/em
On the OC4J home page, click Stop.
If required, set up a preference store.
Most portlet producers use a File preference store by default (the Web Clipping portlet is the exception; for more information, see Section 18.4.3, "What You Should Know About the Web Clipping Portlet and a Preference Store"). The File preference store is configured and ready to use out of the box. For high availability, you can configure the preference store to use a database instead. Using a database preference store requires additional configuration. For more information, see Section 18.4, "Setting Up a Preference Store".
Download and install the portlet run time and the sample portlet producers.
You will find the relevant download at the following URL:
http://www.oracle.com/technology/products/webcenter/pdk.html
The detailed steps for installation are provided in the readme files included with the download.
Start OC4J by navigating to ORACLE_HOME\bin (where ORACLE_HOME is the source location of your OC4J) and running the following command:
oc4j -start
Test the configuration to confirm it is working correctly.
You can use the sample WSRP producer, wsrp-samples.ear, for this purpose. You will find wsrp-samples.ear in your portlet container directory.
For the standalone OC4J, this file is in the file you downloaded in step 3. For the Application Server OC4J you can find this file in ORACLE_HOME\adfp\lib.
Before proceeding, you must deploy the sample portlets EAR file.
To deploy the sample portlets EAR file, perform the following steps:
Return to the Application Server Control Console.
Log in to Application Server Control as oc4jadmin at:
http://host_name:port_number/em
For example:
http://localhost:8888/em
On Oracle Application Server, click the Oracle Application Server middle-tier instance to which you plan to deploy portlets.
On Oracle Application Server, click the OC4J instance that you created earlier, wsrp.
Click the Applications tab.
Click Deploy.
The Deploy: Select Archive page is displayed.
Select Archive is present on local host. Upload the archive to the server where Application Server Control is running.
In Archive Location, enter the path to and the filename wsrp-samples.ear.
Select Automatically create a new deployment plan.
Click Next.
Wait while the system uploads the EAR file. When the file is uploaded, the Deploy: Application Attributes page is displayed.
For Application Name, enter sampleportlets.
For Context Root:
For a standalone OC4J, enter portletapp.
For the Application Server instance, enter some other name that is not already in use.
Click Next.
The Deploy: Deployment Settings page is displayed.
Click Deploy.
You can alter any deployment settings on this page, but, in this case, just click Deploy.
The Deployment Confirmation page is displayed.
Carefully check the settings to ensure that they are correct.
Click Return to dismiss the Confirmation page.
See Oracle Containers for J2EE Deployment Guide for complete information about how to deploy an EAR file.
Once the sample EAR file is deployed, test its WSDL URL by entering it into a browser.
For the WSDL URL syntax, use the following structure:
http://<host>:<port>/portletapp/info
The Web page displays content like that depicted in Figure 18-4.
Figure 18-4 Example WSRP Producer (WSDL URL) Test Page
Copy the link location of one of the portlet producers listed under WSDL URLS, and register this portlet producer by following the instructions in Section 18.10, "Registering and Viewing Your Portlet".
Further test the configuration by adding some of the sample portlets from the newly registered portlet producer to a page and displaying the page. If the registration fails for any reason or you cannot add portlets to a page, then see Appendix G, "Troubleshooting WebCenter Applications".
The portlet preference store is used for persisting consumer registration handles and portlet preference data. Portlet producers can use one of two types of preference store: File and Database. For most portlet producers, the file preference store is specified by default and is ready to use out of the box. The database preference store requires additional configuration.
In a clustered environment, Oracle recommends the use of a database preference store. If you prefer to use a file-based preference store, then you must also use a shared file system.
This section describes how to set up a database preference store and a file-based preference store. It includes the following subsections:
A database preference store is desirable in environments where high availability is key. Setting up a database preference store for a portlet producer requires a little extra configuration over what is required for a default file preference store. For example:
A schema for storing preferences must be created in the database.
Connection details must be mapped to the data source.
The preference store type must be specified using the persistentStore JNDI environment variable (WSRP) or the preferenceStore tag (PDK-Java).
This section describes how to set up a database preference store for WSRP and PDK-Java producers. It contains the following subsections:
Section 18.4.1.1, "Creating the Schema for a Database Preference Store"
Section 18.4.1.2, "Mapping Connection Details to a JDBC Data Source"
Section 18.4.1.3, "Setting Portlet Preference Store Variables in Producer Configuration Files"
Section 18.4.1.4, "Database-Related Attributes and Parameters of the preferenceStore Tag"
To use a database preference store, both WSRP and PDK-Java producers require the creation of a database schema. You can create the schema in the Oracle Application Server infrastructure database or any other Oracle database for this purpose.
The script dbprefstore.sql is available for creating database schemas for portlet producer database preference stores. In one operation, the script creates database schemas for WSRP and PDK-Java producers.
Note:
For additional information about creating a schema for a Web Clipping producer, see Section 18.4.3, "What You Should Know About the Web Clipping Portlet and a Preference Store".The script is named dbprefstore.sql, and it is located at:
ORACLE_HOME/j2ee/home/database/wsrp/
Note:
Although the directory path for this script includeswsrp, it creates database objects for both WSRP and PDK-Java preference stores.To create database schemas for WSRP and PDK-Java producer preference stores, perform the following steps:
Connect to SQL*Plus using the SYS account and SYSDBA database administrator role.
At the prompt:
Enter user-name: SYS AS SYSDBA
Enter password: SYS_password
At the SQL prompt, enter the following:
SQL> @ORACLE_HOME\j2ee\home\database\wsrp\dbprefstore.sql
When prompted, enter a user name and password for the WSRP and PDK-Java preference store database schema.
For example, your user name might be portlet_prefs.
Once the command executes, a database preference store is created and the schema is populated with the required database objects.
Note:
For information about migrating portlet preferences from one database preference store to another, or from a database preference store to a file preference store, see Appendix B, "Additional Portlet Configuration".Once the portlet preference schema is created, you must tell the producers where to find the portlet preference store. You must do this twice: once for WSRP and once for PDK-Java.
Tell producers where to find the portlet preference store by mapping connection details to the JDBC data source, using the Application Server Control Console. These details are stored in the data-sources.xml file.
This section describes how to do this mapping for both WSRP and PDK-Java portlet producers, noting where there are slight variations.
To map connection details to a JDBC data source for WSRP and PDK-Java portlet producers, perform the following steps:
Log in to the Application Server Control Console.
Typically, the URL for the Application Server Control Console is in the following format:
http://hostname:port/em/
Navigate to the home page for the OC4J you want to configure.
Click the Administration tab.
The Administration Tasks list is displayed.
Under the Services task, click the Go to Task icon for JDBC Resources.
The JDBC Resources page is displayed.
In the Connection Pools section, click Create.
The Create Connection Pool - Application page is displayed. On this page, you can specify the application to which the new connection pool is to be added. Additionally, you can specify whether you want to create a connection pool or use an existing one.
From the Application list, select default.
Click Continue.
The Create Connection Pool page is displayed. Use this page to specify the details required to create a connection pool.
Enter values as described in Table 18-1.
Table 18-1 Create Connection Pool Settings (Database Portlet Preference Store)
| Setting | Value |
|---|---|
|
Enter a name for this connection pool. For example, for a WSRP producer you might enter: OracleWSRPPool For a PDK-Java producer, you might enter: OraclePDKPool |
|
|
Accept the default value: oracle.jdbc.pool.OracleDataSource |
|
|
Enter the JDBC URL for the Oracle database that contains the schema that you created for the preference store using the following syntax: jdbc:oracle:thin:@//dbhost:dbport/service_name For example: jdbc:oracle:thin:@//shobeen:1521/sales_us |
|
|
Enter the user name for the database where you created the schema for the preference store. |
|
|
For the user specified in the Username field, enter the indirect password for the database that contains the preference store schema. For example: role/username For example: users/Scott |
Click Finish.
The JDBC Resources page is displayed.
Click the Test Connection icon for the newly created connection.
If the test fails, then review the settings for your pool to ensure that they are correct.
In the Data Sources section, click Create.
The Create Data Source - Application & Type page is displayed. Use this page to specify the application to which the new data source is to be added and the data source type.
From the Application list, select default.
Click Continue.
The Create Data Source - Managed Data Source page is displayed. Use this page to specify details for creating a managed data source.
Enter values as described in Table 18-2.
Table 18-2 Create Data Source Settings (WSRP Producer Preference Store)
| Setting | Value |
|---|---|
|
Enter a name for your data source. For example, for a WSRP producer preference store you might enter: WSRP_PREF_DS For a PDK-Java preference store, you might enter: PDK_PREF_DS |
|
|
Enter the JNDI path as follows: jdbc/portletPrefs |
|
|
Accept the default value: Global & Local Transactions |
|
|
Choose the connection pool that you created earlier. For example, for a WSRP producer preference store you might enter: OracleWSRPPool For a PDK-Java producer preference store OraclePDKPool |
|
|
Accept the default value, |
Click Finish.
After you run the script to set up the database objects for a database preference store and map connection details to the JDBC data source, both portlet producer types require a little additional adjustment in their configuration files—web.xml for WSRP producers and provider.xml for PDK-Java producers. In these files, you must specify the preference store type and, in some cases, the preference store location.
This section describes how to accomplish such tasks. It contains the following subsections:
Section 18.4.1.3.1, "Setting Preference Store-Related Variables for a WSRP Portlet Producer"
Section 18.4.1.3.2, "Setting Preference Store-Related Variables for a PDK-Java Portlet Producer"
Once your preference store database objects are created and the portlet producer knows where to find them, you must tell the portlet producer that a database preference store will be used instead of the default file preference store. You do this by setting the JNDI variable, persistentStore to the value Database.
Set JNDI preference store variables for all WSRP producers in their associated web.xml files.
Example 18-1 lists sample file locations for various WSRP producers' web.xml files:
Example 18-1 Sample File Locations for web.xml Files
Rich Text Portlet Producer: ORACLE_HOME\j2ee\OC4J_WebCenter\applications\richtextportlet\richtextportlet\WEB-INF WSRP Samples Producer: ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portletapp\wsrp-samples\WEB-INF
Table 18-3 lists and describes the JNDI variable that is relevant to a database preference store.
Table 18-3 WSRP Producer Database Preference Store-Related JNDI Variable
| Variable Name | Variable Value | Description |
|---|---|---|
|
|
Determines which data store (File or Database) is used for persisting a portlet application's consumer registration handles and portlet preferences. Permissible values: { |
Example 18-2 illustrates database preference store set-up in a producer's web.xml file. If you are moving to a database preference store from a file-based preference store, then be sure to remove the fileStoreRoot tag from the preference store set up (see Example 18-5 for an example of the fileStoreRoot tag).
Note:
Preference-store-related variables may or may not be present in a WSRP producer'sweb.xml file. Before you enter the variables, search for them. If the variables are present, then modify them as desired. If the variables are not present, then enter them as illustrated in Example 18-2.Example 18-2 Configuring web.xml to Use a Database Preference Store
<env-entry> <env-entry-name>oracle/portal/wsrp/server/persistentStore</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>Database</env-entry-value> </env-entry>
Once you have altered all relevant web.xml files, restart your OC4J instance.
Once your preference store database objects are created and the PDK-Java producer knows where to find them, you must tell the PDK-Java producer that a database preference store will be used instead of the default file preference store. You do this by setting the value for the preferenceStore tag in each PDK-Java producer's provider.xml file.
Example 18-3 lists sample file locations for various PDK-Java producers' provider.xml files:
Example 18-3 Sample File Locations for provider.xml Files
Omniportlet: ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portalTools\omniPortlet\WEB-INF\providers\omniPortlet JPDK samples: ORACLE_HOME\j2ee\OC4J_WebCenter\applications\jpdk\jpdk\WEB-INF\providers\providername
Note:
For information about configuring a repository for the Web Clipping portlet producer, see Section 18.4.3, "What You Should Know About the Web Clipping Portlet and a Preference Store".Modify the preferenceStore tag to use a database preference store (Example 18-4).
Example 18-4 Configuring provider.xml to Use a Database Preference Store
<preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">
<name>producer_name</name>
<connection>jdbc/PooledConnection</connection>
</preferenceStore>
In Example 18-4, you would substitute producer_name with the actual producer name (the name you enter here is your choice). Otherwise, use the example exactly as written.
Note:
For a list and description of database-related attributes and parameters of thepreferenceStore tag, see Section 18.4.1.4, "Database-Related Attributes and Parameters of the preferenceStore Tag".Once you have altered all relevant provider.xml files, restart your OC4J instance.
Table 18-4 lists and describes the attributes and parameters used with the preferenceStore tag when a database preference store is specified.
Table 18-4 Database-Related Attributes and Parameters of the preferenceStore Tag
A file-based preference store is the default preference store type for portlet producers and is configured out of the box.
Note:
If you choose to use a file-based preference store in a clustered environment, then each node in the cluster must use the same location.In the event you are moving from a database preference store to a file-based preference store or you want to change the location of the file-based preference store, this section describes how to set up a file-based preference store for both WSRP and PDK-Java portlet producers. It contains the following subsections:
Section 18.4.2.1, "Configuring a WSRP Producer to Use a File-Based Preference Store"
Section 18.4.2.2, "Configuring a PDK-Java Producer to Use a File-Based Preference Store"
Note:
For information about migrating portlet preferences from a database preference store to a file preference store, see Appendix B, "Additional Portlet Configuration".For a WSRP producer, all of the configuration required for a file-based preference store occurred in the producer's web.xml file. Multiple producers mean multiple web.xml files. In such an environment, be sure to configure all relevant web.xml files.
Two JNDI variables control preference store functionality for WSRP producers: persistentStore and fileStoreRoot. Both database and file preference stores require the persistentStore variable. The fileStoreRoot variable is used only in the presence of a file preference store.
Note:
For additional information about setting JNDI variables, see Section 19.2.3, "Using JNDI Variables".Table 18-5 lists and describes the WSRP producer preference store-related JNDI variables that are relevant to a file-based preference store.
Table 18-5 WSRP Producer File Preference Store-Related JNDI Variables
| Variable Name | Default Variable Value | Description |
|---|---|---|
|
|
Determines which data store (File or Database) is used for persisting a portlet application's consumer registration handles and portlet preferences. Permissible values: { |
|
|
|
Defines the path to the root directory to be used by the file preference store. Absolute paths are interpreted relative to the file system root. Relative paths are interpreted relative to the Note that all producers running within the same OC4J instance must use the same path for this variable. Otherwise, you will get a |
Example 18-5 depicts default producer preference store settings in a WSRP producer's web.xml file. Relevant settings are marked in bold:
Note:
Preference store-related variables may or may not be present in a WSRP producer'sweb.xml file. Before you enter the variables, search for them. If the variables are present, then modify them as desired. If the variables are not present, then enter them as illustrated in Example 18-5.Example 18-5 Configuring web.xml to Use a File-Based Preference Store
<env-entry> <env-entry-name>oracle/portal/wsrp/server/persistentStore</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>File</env-entry-value> </env-entry> <env-entry> <env-entry-name>oracle/portal/wsrp/server/fileStoreRoot</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>portletdata</env-entry-value> </env-entry>
Once you change all relevant web.xml files, restart your OC4J instance.
PDK-Java producers use the preferenceStore tag in their provider.xml configuration files to indicate the type of producer preference store to use. Multiple producers mean multiple provider.xml files. In such an environment, be sure to configure all relevant provider.xml files.
Note:
See Example 18-3 for some sample file locations of various PDK-Java producers'provider.xml files.Modify the preferenceStore tag to use a file-based preference store. Add the tag if necessary. In Example 18-6, you would substitute producer_name with the actual producer name (the name you enter here is your choice). Otherwise, use the example exactly as written for all PDK-Java portlets except OmniPortlet (see Example 18-7).
Example 18-6 Configuring provider.xml to Use a File-Based Preference Store
<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
<name>producer_name</name>
<useHashing>true</useHashing>
</preferenceStore>
OmniPortlet uses a different preferenceStore class from the standard class used by all other PDK-Java portlet producers. The OmniPortlet preferenceStore class extends the default class with features specific to OmniPortlet. Additionally, it makes use of the rootDirectory parameter, which specifies where portlet preferences are stored.
Note:
TherootDirectory parameter is not exclusive to OmniPortlet. Other portlets can use it as well. For example:
<rootDirectory>
ORACLE_HOME/portal/portletdata/tools/providerBuilder
</rootDirectory>
When the rootDirectory parameter is not specified, a default location is used for storing portlet preferences. This is the same location where the producer's provider definition file is stored.
In rootDirectory, the expression ${oracle.home} is unique to OmniPortlet, and must not be used with other portlet preference store configurations.
For a list and description of file-related attributes and parameters of the preferenceStore tag, see Section 18.4.2.3, "File-Related Attributes and Parameters of the preferenceStore Tag".
Example 18-7 illustrates the OmniPortlet preferenceStore class specification for a file-based preference store. When you specify a file-based preference store for OmniPortlet, use the parameters and parameter values provided in Example 18-7.
Example 18-7 Configuring OmniPortlet's provider.xml File to Use a File-Based Preference Store
<preferenceStore class="oracle.webdb.reformlet.ReformletFilePreferenceStore">
<name>omniPortletprefStore</name>
<useHashing>true</useHashing>
<rootDirectory>
${oracle.home}/portal/portletdata/tools/omniPortlet
</rootDirectory>
</preferenceStore>
Once you change all relevant provider.xml files, restart your OC4J instance.
Table 18-6 lists and describes the attributes and parameters used with the preferenceStore tag when a file-based preference store is specified.
Table 18-6 File-Related Attributes and Parameters of the preferenceStore Tag
|
This required attribute specifies the Java class that defines the location and other details of portlet preferences. For example, most PDK-Java portlet producers use the following class for a file-based preference store: <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
OmniPortlet uses its own class. For example: <preferenceStore class="oracle.webdb.reformlet.ReformletFilePreferenceStore">
For more information, see Section 18.4.2.2, "Configuring a PDK-Java Producer to Use a File-Based Preference Store". |
|
|
This required parameter provides a name for the preference store. Use any value you choose. For example: <preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">
<name>MyPDKProducerPreferenceStore</name>
</preferenceStore>
|
|
|
This optional parameter specifies the location where the file-based preference store preferences are stored. <preferenceStore class="oracle.webdb.reformlet.ReformletFilePreferenceStore"> <name>PDKProducerPreferenceStore</name> <useHashing>true</useHashing> <rootDirectory> ORACLE_HOME/portal/portletdata/tools/providerBuilder </rootDirectory> </preferenceStore> OmniPortlet has its own value for this parameter. For example: <rootDirectory> ${oracle.home}/portal/portletdata/tools/omniPortlet </rootDirectory> For more information, see Section 18.4.2.2, "Configuring a PDK-Java Producer to Use a File-Based Preference Store". When this parameter is not included with the |
|
|
This optional parameter takes the value For example: <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
<name>PDKProducerPreferenceStore</name>
<useHashing>true</useHashing>
</preferenceStore>
|
The Web Clipping portlet provides a unique case in terms of its use of a preference store. It does not use one. Rather it places Web Clipping definitions and clippings into a repository. This can be either an Oracle MetaData Services (MDS) repository (the default, out-of-the-box configuration located on a file system) or a database repository (best for high availability).
This section describes how to configure a Web Clipping portlet producer to use a database repository or an MDS repository for Web Clipping definitions and clippings. It contains the following subsections:
Section 18.4.3.1, "Configuring a Web Clipping Portlet Producer to Use a Database Repository"
Section 18.4.3.3, "Attributes and Child Tags of the repositoryInfo Tag"
To use a database repository for storing Web Clipping definitions and clippings, you must complete two tasks:
Section 18.4.3.1.1, "Creating a Database Schema for Web Clipping Portlet Definitions and Clippings"
Section 18.4.3.1.2, "Configuring the Web Clipping Portlet's provider.xml File"
To create a database schema for Web Clipping definitions and clippings, run the Java command described in Example 18-8.
Example 18-8 Java Command for Creating a Schema for Web Clipping Portlet Definitions and Clippings
ORACLE_HOME/jdk/bin/java -classpath ORACLE_HOME/lib/xmlparserv2.jar: ORACLE_HOME/jdbc/lib/ojdbc14.jar:ORACLE_HOME/portal/jlib/wce.jar oracle.portal.wcs.Installer -installSchema -username dbuser -password dbpassword -dburl jdbc:oracle:thin:@//host:port/dbid
Note:
The classpath in Example 18-8 uses different separators for UNIX and Windows. On UNIX systems, theclasspath uses a colon (:) separator. On Windows systems, the classpath uses a semicolon (;) separator.Where:
ORACLE_HOME is the path to your Oracle home directory
dbuser is the database user for the schema
Consider using the same database user you used to create the WSRP and PDK-Java preference store database schema. See Section 18.4.1.1, "Creating the Schema for a Database Preference Store". If you do not use the same user, then you must create a new user and grant it connect and resource privileges.
dbpassword is the specified user's password
dburl is the URL for the database
This is the database that contains the schema that you created for Web Clipping portlet definitions and clippings using the following syntax:
jdbc:oracle:thin:@//dbhost:dbport/service_name
For example:
jdbc:oracle:thin:@//shobeen:1521/sales_us
Set up the Web Clipping producer database repository in the producer's provider.xml file located at:
ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portalTools\webClipping\WEB-INF\providers\webClipping
To use a database repository, update the repositoryInfo tag to use the DatabaseInformation class as illustrated in Example 18-9. Tag parameters are listed and described in Section 18.4.3.3, "Attributes and Child Tags of the repositoryInfo Tag"
Example 18-9 Configuring the Web Clipping provider.xml File to Use a Database Repository for Web Clipping Definitions and Clippings
<repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation"> <useRAA>false</useRAA> <databaseHost>infradbhost</databaseHost> <databasePort>1521</databasePort> <databaseSid>iasdb</databaseSid> <databaseUsername>webclip_user</databaseUsername> <databasePassword>!AX3tR</databasePassword> <useASO>false</useASO> </repositoryInfo>
Restart your OC4J instance after making changes to the provider.xml file.
Set up the Web Clipping producer MDS repository in the producer's provider.xml file located at:
ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portalTools\webClipping\WEB-INF\providers\webClipping
To use an MDS repository, update the repositoryInfo tag to use the MdsInformation class as illustrated in Example 18-10. Tag parameters are listed and described in Section 18.4.3.3, "Attributes and Child Tags of the repositoryInfo Tag"
Example 18-10 Configuring the Web Clipping provider.xml File to Use an Oracle Metadata Services Repository for Web Clipping Definitions and Clippings
<repositoryInfo class="oracle.portal.wcs.provider.info.MdsInformation"> <mdsConfigLocation>mds-config.xml</mdsConfigLocation> </repositoryInfo>
This configuration points to the mds-config.xml file that specifies the actual MDS location. By default, the mds-config.xml file is located at:
ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portalTools\webClipping\WEB-INF
The mds-config.xml file specifies the location of the repository in a property tag (Example 18-11).
Example 18-11 Specifying the Location of the MDS Repository in the mds-config.xml File
<property name="metadata-path" value="portletdata/tools/webClipping"/>
Note:
If you manually reconfigure the value formetadata-path in mds-config.xml, then that directory must exist at the time the producer is restarted.The location specified for value is relative to ORACLE_HOME\portal. Any relative path specified will be interpreted to be relative to ORACLE_HOME\portal. If you want to use another location, for example, a location outside the Oracle home, then specify an absolute path, such as c:\mds.
Restart your OC4J instance after making the changes outlined in this section.
Table 18-7 lists and describes the attributes and child tags of the repositoryInfo tag.
Note:
The attributes and child tags of therepositoryInfo tag are also described in the comments in the Web Clipping provider.xml file.
In the comments in the provider.xml file, the example provided for Oracle9i Database or later using AS Infrastructure Database is specific to OracleAS Portal and its infrastructure database and application programming interfaces. That example should not be used for WebCenter application implementations.
Table 18-7 Attributes and Child Tags of the repositoryInfo Tag
| Attributes/Parameter | MDS/database | Description |
|---|---|---|
|
both |
The oracle.portal.wcs.provider.info.MdsInformation This value signifies that MDS is used to store the Web Clipping definitions and that MDS configuration is pushed to the oracle.portal.wcs.provider.info.DatabaseInformation This value signifies that an Oracle9i Database or later is used to store the Web Clipping definitions and that the database connection details will be included as children in the |
|
|
MDS |
Use the This configuration points to the ORACLE_HOME\j2ee\OC4J_WebCenter\applications\portalTools\webClipping\WEB-INF
For more information, see Example 18-11. |
|
|
database |
Set to
|
|
|
database |
Set to
|
|
|
database |
Specify the host name of the Oracle database. Use only version 9i or later. For example: mycompany.dbhost.com |
|
|
database |
Specify the port number of the Oracle database listener. This is usually |
|
|
database |
Specify the Oracle SID of the database that will host the Web Clipping repository. |
|
|
database |
Enter the user name used to log in to the database. |
|
|
database |
Enter a plain text password for the specified database username. Prefix the password with an exclamation point (!) to enable the Web Clipping producer to encrypt the password once the producer starts. For example: !AX3tR |
Using the JSR 168 Java Portlet Wizard in Oracle JDeveloper you can expose your portlet over WSRP 2.0 quickly and easily. Note that the wizard supports both WSRP 1.0 and WSRP 2.0. If you choose to create a WSRP 2.0 portlet, then an additional page appears in the wizard for the WSRP 2.0 enhancements.
This section assumes the following:
You are familiar with portlet terminology such as portlet modes. See Chapter 14, "Understanding Portlets" and Section 18.1, "Guidelines for Creating Java Portlets".
You have installed the preconfigured OC4J provided on OTN. See Section 3.2, "Using the Preconfigured OC4J".
You are already familiar with Oracle JDeveloper and know how to build and deploy Java components using it.
This section walks you through the JSR 168 Java Portlet Wizard. You can choose which portlet 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.
Note:
The figures in this section were taken with a Look and Feel setting of Windows in Oracle JDeveloper. If your Look and Feel is set to Oracle, then what you see on your screen will vary slightly, but the content and functionality remains the same. To change the Look and Feel setting, select Preferences from the Tools menu, and then select Environment.The steps to create a portlet using the JSR 168 Java Portlet Wizard are as follows:
Start Oracle JDeveloper.
In the Applications 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 chose the WebCenter Application Template when you created the application, then create the portlet in the Portlets project. If you do not have such an application or project yet, then see Section 3.1, "Creating a WebCenter Application".In the New Gallery, expand the Web Tier category and select Portlets.
In the Items list, select Standards-based Java Portlets (JSR 168), as shown in Figure 18-5.
Note:
Selecting Java Portlet opens the Portlet Wizard for creating JPS-compliant portlets. Clicking Oracle PDK Java Portlet opens the Portlet Wizard for creating PDK-Java portlets.If you are on the Welcome page of the wizard, then click Next to display the Web Application page (Figure 18-6).
Select the Web Application Version option for the project. Note that Servlet 2.4 is supported only in Oracle Application Server Release 10.1.3 and later.
Note:
If your project already contains any JSPs or JSF JSPs, then the Web Application Version will have already been set. If this is the case, then you will not see this page, and will instead go straight to the General Portlet Properties page.Click Next to display the General Portlet Properties page (Figure 18-7).
Figure 18-7 General Portlet Properties Page
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 supply your own.
In 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, then the wizard uses the default package of the project.
In the Default Language list, select the default language that your portlet will support. The wizard uses English by default.
Select Editable to add an edit mode. In the wizard, this option is selected by default.
Select Enable WSRP V2 inter-portlet communication using Oracle extensions to indicate that this portlet will support Oracle WSRP 2 extensions. Selecting this option creates the oracle-portlet.xml file, which is used for WSRP 2.0 features, such as navigation parameters. The WSRP 2.0 standard extends WSRP 1.0 by including support for inter-portlet communication (through navigation parameters) and export/import of portlet customizations.
Note:
JSR 168 portlets built with the 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 Application Server release 10.1.3.2.Click Next to display the Name and Attributes page (Figure 18-8).
In the Display Name field, enter a name for your portlet. This portlet attribute is not used by WebCenter application, but may be useful with portlets consumed by other applications. For example, OracleAS Portal uses this value on its portlet pick list (that is, in the Portlet Repository).
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 portlet attribute is not implemented in WebCenter applications, but may be useful with portlets consumed by other applications. For example, if you use this portlet in OracleAS Portal, and plan to provide a mobile option to your users, then enter a Short Title for the portlet, to be displayed in the portlet's header in place of the longer Portlet Title.
In the Description field, enter a description of your portlet. This portlet attribute is not used by WebCenter applications, but may be useful with portlets consumed by other applications. For example, if you use this portlet in OracleAS Portal, then the description displays beneath the portlet in the Portlet Repository.
In the Keywords field, enter any additional keywords to help users find your portlet in a search. This portlet attribute is not implemented in WebCenter applications, but may be useful with portlets consumed by other applications.
Click Next to display the Content Types and Portlet Modes page shown in Figure 18-9.
Alternatively, you can click Finish to create the portlet immediately, using the default values for all remaining settings.
Figure 18-9 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, then select text/html, then click Add.
The list of available content types displays (Figure 18-10). 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.
By default, your portlet includes View mode. If you selected Customizable on the General Portlet Properties page, then your portlet also includes Edit mode. If you want to include additional portlet modes, then select an existing portlet mode (for example, view), then click Add.
The list of available portlet modes displays (Figure 18-11). You can add portlet 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 modes, see Section 18.1, "Guidelines for Creating Java Portlets".
Once you have added all of the desired portlet modes, choose the function to be performed for each mode. For each portlet mode, click the portlet mode and select a 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 default.
When you complete the wizard, the generated JSP displays in the Applications 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 Map to Path if you want to map the portlet mode to a 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 though 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 Properties page earlier in the wizard, then the Customization Preferences page displays (Figure 18-12). Go to step 26.
If you did not select this option, then the Security Roles page displays (Figure 18-12). Go to step 34.
Figure 18-12 Customization Preferences Page
If you want to include additional customization preference, then click Add. The Add New Preferences dialog box displays (Figure 18-13).
Figure 18-13 Add New Preference Dialog Box
In the Name field, enter a name for the new customization 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 value for the new customization preference. Separate multiple values with commas.
If you want the customization preference value to be translated, then select the Translate check box. If you select this option, then 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, then 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 18-14).
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 of 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, then click New Security Role. The Create New Security Role dialog box displays (Figure 18-15).
Figure 18-15 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, as described in Section 10.2, "Setting Up Security for Your Application".
Click Next to display the Caching page (Figure 18-16).
If you want to enable caching for your portlet, then select Cache 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, then 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, then 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, shown in Figure 18-17.
Figure 18-17 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, then 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 of parameters and click Remove.
Click Next to display the Portlet Navigation Parameters page (Figure 18-18).
Figure 18-18 Portlet Navigation Parameters Page
For information about Portlet Navigation Parameters, see Section 19.1.2, "Implementing Navigational Parameters (WSRP 2.0)".
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 18-19):
If you selected Generate JSP for the portlet modes, generated code for each mode
If you selected Custom Code instead, then 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 18-19 Example of Files Generated for a JPS-Compliant Portlet
The next step is to add your own portlet logic to the portlet to implement your desired functionality. See Section 18.8, "Adding Portlet Logic".
PDK-Java gives you a framework to simplify the development of Java portlets by providing commonly required utilities and enabling you to leverage existing development skills and application components such as JSPs, servlets, and static HTML pages. PDK-Java also enables you to create portlets without having to deal directly with the complexity of communications between Oracle WebCenter Framework and producers.
The PDK-Java framework is divided into the following areas:
The Producer Adapter insulates the developer from the HTTP syntax defined by Oracle WebCenter Framework for communication with Web producers. It translates the information passed between Oracle WebCenter Framework and your Java Web producer. Without an adapter, your producer would not only manage portlets, but it would also have to communicate this information directly to Oracle WebCenter Framework in the expected language. The adapter eliminates the need for your Web producer to understand the portal language and vice-versa.
The Producer Interface defines the APIs (functions) required by your Java implementation to integrate with the Producer Adapter. The Producer Adapter receives messages from the WebCenter application, translates them into calls to the Producer Interface, and translates the producer's response into a format that the application can understand. The Producer Interface contains a set of Java classes that define the methods your producer 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 Producer Runtime provides a base implementation that follows the specification of the Producer Interface. The Producer Runtime includes a set of default classes that implement each one of the Producer Interfaces and enables you to leverage the rendering, personalization, and security frameworks provided with PDK-Java. These classes and the associated frameworks simplify the development of a producer by implementing common functions for Oracle WebCenter Framework requests and providing a declarative mechanism for configuring the producer. Using the Producer Runtime, you can focus your development efforts on the portlets themselves rather than the infrastructure needed to communicate with the WebCenter application. If the standard behavior of the Producer Runtime does not meet your requirements, then you can easily extend or override specific behaviors. Some of the primary classes are as follows:
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 Producer Utilities provide methods for simplifying the rendering of portlets. The utilities include methods for constructing valid links (hrefs), rendering the portlet's container (including the header), rendering HTML forms that work within a page, and supporting portlet caching.
Guidelines for PDK-Java Portlets
In Oracle WebCenter Framework, PDK-Java portlets work somewhat differently than they did in OracleAS Portal. As a result, you need to be aware of the following new design considerations when you build PDK-Java portlets in Oracle WebCenter Framework:
Your portlet should not contain any code that relies upon the URL format or parameters in the request that were not explicitly added by your portlet
You should never assume that your portlet is the only one on a page, regardless of the portlet mode. For example, even if your are in Edit mode, you should not assume that yours is the only portlet on the page.
Never write a portlet mode that simply redirects. A redirect can only be issued while processing a post to your portlet or following a link generated by your portlet.
Using the 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 modes. See Chapter 14, "Understanding Portlets" and Section 18.1, "Guidelines for Creating 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 walks you through the Java Portlet Wizard. You can choose which portlet 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.
Note:
The figures in this section were taken with a Look and Feel setting of Windows in Oracle JDeveloper. If your Look and Feel is set to Oracle, then what you see on your screen will vary slightly, but the content and functionality remains the same. To change the Look and Feel setting, select Preferences from the Tools menu, and then select Environment.The steps to create a portlet and producer are as follows:
Start Oracle JDeveloper.
In the Applications 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 such an application or project yet, then see Section 3.1, "Creating a WebCenter Application".In the New Gallery, expand the Web Tier category and select Portlets.
In the Items list, select Oracle PDK Java Portlet, as shown in Figure 18-20.
Note:
Selecting 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 18-20 New Gallery Dialog Box for Oracle PDK Java Portlet
Click OK. The Java Portlet Wizard displays.
If you are on the Welcome page of the wizard, then click Next to display the Web Application page (Figure 18-6).
Select the Web Application Version option for the project.
Note:
If your project already contains any JSPs or JSF JSPs, then the Web Application Version will have already been set. If this is the case, then you will not see this page, and will instead go straight to the General Portlet Properties page.Click Next to display the Portlet Description page (Figure 18-21).
In the Portlet Name field, enter a meaningful name for your portlet. This name is used internally and is not exposed to users.
In the Display Name field, enter a display name for your portlet. This name will be displayed in portlet selection lists, such as the Component Palette, where users choose which portlets to add to a page.
In the Description field, enter a description of your portlet.
Note:
This portlet attribute is not implemented in WebCenter applications, but may be useful with portlets consumed by other applications. For example, if you use this portlet in OracleAS Portal, then the description displays beneath the portlet in the Portlet Repository.In the Timeout field, enter the number of seconds to enable 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 portlet modes page (Figure 18-22).
Under Show page, 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 producer 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, then 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 18.1.1.1, "Shared Screen Mode (View Mode for JPS)".
If you want to implement Full Screen mode for your portlet, then select Show Details page, then select an Implementation style as described earlier for Show page.
For more information about Full Screen mode, see Section 18.1.1.5, "Full Screen Mode (PDK-Java)".
Click Next to display the Customize Modes page (Figure 18-23).
Edit page is selected by default. If you want to implement Edit mode for your portlet, then select an implementation style as described earlier for Show page. If you do not want to implement Edit mode, then clear the Edit page check box.
For more information about Edit mode, see Section 18.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 18.1.1.3, "Edit Defaults Mode (JPS and PDK-Java)".
Click Next to display the Additional Modes page (Figure 18-24).
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 18.1.1.6, "Help Mode (JPS and PDK-Java)".
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 18.1.1.7, "About Mode (JPS and PDK-Java)".
Click Next to display the Public Portlet Parameters page (Figure 18-25).
Figure 18-25 Public Portlet Parameters Page
If you want to add public parameters to your portlet, then click Add to create a blank row for entering parameter details. For more information about using parameters, see Section 19.2.2, "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 18-26).
For more information about using events, see Section 19.2.2, "Passing Parameters and Submitting Events".
Click Next to display the Producer Description page (Figure 18-27).
In the Producer name field, enter a name for the producer.
Select Generate deployment properties files to generate 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 Web 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 to automatically generate a provider.xml file for the producer. This is the producer definition file that contains details of the portlets, including those generated by the wizard, belonging to the producer.
Select Generate index JSP to automatically generate an index.jsp file. This file lists all the producers that reside in your Web application with hyperlinks that enable easy access to producer test pages.
Click Finish to generate the files for your portlet. The following files should be generated for your project in the Application Navigator (see Figure 18-28):
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.
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 about adding functionality and features. For a specific example, see Step 7: Adding Some Simple Logic to the Portlet in the Building and Testing Your First Portlet chapter of Oracle Oracle WebCenter Framework Tutorial.
After you finish the wizard and successfully generate your portlet, you are ready to deploy it to an application server.
If you chose to create a JPS-compliant portlet, then you can deploy it using the wizard for any vendor's JPS-compliant container. The steps in Section 18.9.1, "Deploying Your JPS-compliant WebCenter Application Portlet" show how to deploy a JPS-compliant portlet to Oracle's WSRP container running on OC4J. If you created a PDK-Java portlet, then you can deploy it to OC4J.
Note:
The WSRP portlets must be deployed to the OC4J_Webcenter instance in Oracle Application Server and not to the home instance.This section includes the following:
Section 18.9.1, "Deploying Your JPS-compliant WebCenter Application Portlet"
Section 18.9.3, "Deploying a Third-Party JPS-compliant Portlet"
Section 18.9.4, "Validating Your JPS-Compliant Portlet and Producer"
Section 18.9.5, "Validating Your PDK-Java Portlet and Producer"
This section describes the procedure to deploy a JPS-compliant WebCenter application portlet that you create using Oracle JDeveloper. You need to create a WAR deployment profile and deploy it to OC4J.
To create and deploy a WAR file, perform the following steps:
Make sure that a connection exists to your preconfigured OC4J instance. To start preconfigured OC4J, go to Tools and select Start WebCenter Preconfigured OC4J.
Note:
If you want to use a standalone OC4J instance, then see Section 12.2.6.2.1, "Defining Standalone OC4J Connection Details" to learn how to create a connection to it.To stop the preconfigured OC4J instance, go to Tools and select Stop WebCenter Preconfigured OC4J.
Connect to the preconfigured OC4J as described in the readme file. To open this file, go to Help and select Open WebCenter Preconfigured OC4J readme.
In the Applications 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.
Click OK to display the Create Deployment Profile dialog box.
In the Deployment Profile Name field, enter a meaningful name for the deployment profile.
In the Directory Name field, enter a location for the deployment profile. You can accept the default location or specify your own.
Click OK. This creates your deployment profile.
In the Application Navigator, expand the Resources node and double-click your .deploy file to display the WAR Deployment Profile Properties dialog box.
Under Web Application's Context Root, select Specify J2EE Web Context Root and enter the J2EE context root in the corresponding field.
Click OK.
Right-click the newly created deployment profile, select Deploy to, then select the application server connection to which you want to deploy the portlet.
The Select deployment type dialog box is displayed (Figure 18-29).
Note:
The Select deployment type dialog box displays only if you selected the Deploy to EAR option earlier. Select Yes if you are deploying to an Oracle Application Server 10.1.3.2.0 instance and select No if you are deploying to an Oracle Application Server 10.1.2.0.2 instance.The Oracle Portlet Container exposes JSR 168 portlets through the WSRP protocol. To make portlets accessible as a Web service, the portlet application must contain a Web service descriptor document, that is, a WSDL document. This dialog box is used to indicate that a Web Service Descriptor document (WSDL document) should be injected into the portlet application when the application is packaged as an EAR file.
Select Yes or No depending on your portlet container type and version, as follows:
Oracle Portlet Container (Oracle Application Server or OC4J) version 10.1.3.1, 10.1.3.2: Select Yes to inject the WSDL document into your portlet application.
Oracle Portlet Container version 10.1.2, 10.1.2.0.2: Select No to forgo injecting the WSDL document into your portlet application. The portlet container provided with Oracle Application Server version 10.1.3 includes a deployment servlet that automatically injects the WSDL document into the deployed application.
Third-party portlet containers: Select No to forgo injecting the WSDL document into your portlet application.
Select Do not show this dialog again. Use the option selected here for future deployments option to prevent future displays of the Select deployment type dialog box. The previous options (Yes or No) are used on future deployments of JSR 168 portlets from this application. To change this setting, delete the deployment profile and re-create. When the Select Deployment Type dialog box opens, select your preferred setting.
To insert the WSDL document into your portlet application, select the Yes option, if it is not selected already, and click OK. The Deployment Log window displays the application packaging and deployment status (Figure 18-30).
In the Configure Application dialog box, you can enter settings that are specific to the container configuration files (for example, orion-web.xml). In most cases, you can just accept the default values by clicking OK.
When the Deployment finished message displays in the Deployment Log at the bottom of Oracle JDeveloper, verify that no errors occurred. You can, however, safely ignore the following error message:
006-11-30 08:14:25.627 WARNING J2EE DEP-00002 There are multiple mappings for servlet name: WSRPServiceDescriptionService, but only the first one (/portlets/WSRPServiceDescriptionService) will be considered for webservice endpoint.
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, then 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 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.
This section describes the procedure to deploy a PDK-Java portlet that you create using Oracle JDeveloper. You need to create a WAR deployment profile and deploy it to OC4J.
To create and deploy a WAR file, perform the following steps:
Make sure that a connection exists to your preconfigured OC4J instance. To start preconfigured OC4J, go to Tools and select Start WebCenter Preconfigured OC4J.
Note:
If you want to use a standalone OC4J instance, then see Section 12.2.6.2.1, "Defining Standalone OC4J Connection Details" to learn how to create a connection to it.To stop the preconfigured OC4J instance, go to Tools and select Stop WebCenter Preconfigured OC4J.
Connect to the preconfigured OC4J as described in the readme file. To open this file, go to Help and select Open WebCenter Preconfigured OC4J readme.
In the Applications Navigator, right-click the project that contains your portlet, and select New.
In the Categories list, expand the General category and click Deployment Profiles.
In the Items list, click WAR File.
Click OK.
In the Create Deployment Profile dialog box, change the name to something meaningful (for example, myj2eeportlet1.deploy).
Click OK.
In the WAR Deployment Profile Properties dialog box, perform the following steps:
Click Specify J2EE Web Context Root and enter myj2eeportlet1.
In the pane on the left, select Contributors.
Select Portlet Development.
Click OK.
Select File, and Save All.
Expand the Resources node, right-click the deployment profile (for example, myj2eeportlet1.deploy), select Deploy to, and then select the application server connection (for example, PDKJavaOC4J).
In the Configure Application dialog, you can enter settings that are specific to the container configuration files (for example, orion-web.xml). In most cases, you can just accept the default values by clicking OK.
When the Deployment Finished message displays in the Deployment Log at the bottom of Oracle JDeveloper, verify that no errors have occurred.
Construct the URL you need to test and register 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 OracleAS 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.
Enter the URL you constructed in the preceding step in your browser to ensure the successful deployment of the portlet.
Note:
If you are deploying your portlets to standalone OC4J or a third party container, then for the shared library, you must copy the JARs by using any of the following methods:Copy the JARs from the 10.1.3.2 WebCenter installation.
Download the preconfigured OC4J from the Portal PDK page on OTN, that will have these JARs in the shared library.
Get these JARs from the 10.1.3.2 JDeveloper Studio Edition.
If you are using the preconfigured OC4J in the WebCenter instance of an Application Server 10.1.3.2 installation, then the shared library is already available.It is referred to as oracle.portal.
This section describes the procedure to deploy a third-party JPS-compliant portlet to OC4J.
To deploy a third-party portlet, perform the following steps:
Obtain the third-party JSR 168 portlet producer EAR file.
Convert a JSR 168 portlet producer EAR file into a WSRP EAR file: Conversion steps are covered in Converting a JSR 168 Portlet Producer EAR File into a WSRP EAR File.
Deploy the WSRP EAR file: The procedure to deploy a WSRP EAR file is similar to the procedure covered in Section 12.2.3, "Deploying Your WebCenter Application Using Application Server Control Console".
Converting a JSR 168 Portlet Producer EAR File into a WSRP EAR File
If deploying JSR-168 portlets to the WSRP Oracle Portlet Container the portlet application EAR files must be converted into a WSRP application containing the necessary WSDL documents. To convert the JSR 168 portlet producer EAR file into a WSRP EAR file, run the WSRP producer predeployment tool located in the JDEV_HOME/adfp/lib directory, as follows:
java -jar wsrp-predeploy.jar <source EAR> <targeted EAR>
The wsrp-predeploy.jar is also available at ORACLE_HOME/j2ee/OC4J_WebCenter/shared-lib/oracle.wsrp/1.0.
For JPS-compliant portlets developed with servlet version 2.3, you must specify Web proxies using the following command:
java -Dhttp.proxyHost=<proxy host> -Dhttp.proxyPort=<proxy port> -jar wsrp-predeploy.jar <Source EAR file> <Targeted EAR file>
where:
proxy host is the server to which your producer has been deployed.
proxy port is the HTTP Listener port.
wsrp-predeploy.jar is located in the JDEV_HOME/adfp/lib or ORACLE_HOME/j2ee/OC4J_Webcenter/shared-lib/oracle.wsrp/1.0 directory.
The source EAR file is the name of the JSR 168 EAR file.
The targeted EAR file is the name of the new EAR file to be created. If the file name for the targeted EAR file is not specified, then a new EAR file called WSRP-<source EAR> is produced.
In the following example Web proxy is specified:
java -Dhttp.proxyHost=myhttpproxy.com -Dhttp.proxyPort=80 -jar wsrp-predeploy.jar wsrp-samples.ear
This example produces WSRP-wsrp-samples.ear.
You can test your JPS-Compliant portlet and producer to check the configuration and to ensure that the portlet and its producer operate correctly. To test your WSRP portlet and producer, run the producer URL in your browser in the following syntax:
http://<host>:<port>/<context-root>/info
where:
host is the server to which your producer has been deployed.
port is the HTTP Listener port (set in the default-web-site.xml Web site configuration file created for the instance.).
context-root is the Web application's context root.
A test page similar to Figure 18-31 is displayed.
Note:
This procedure is for testing purposes only. After this procedure, you still need to register your producer as described in Section 18.10, "Registering and Viewing Your Portlet".To disable your test page, see the procedure in "Disabling a WSRP Test Page".
After you have deployed your portlet, you need to check the configuration to ensure that the portlet and its producer operate correctly.
Note:
This procedure is for testing purposes only. After this procedure, you still need to register your producer as described in Section 18.10, "Registering and Viewing Your Portlet".To validate your portlet and producer, perform the following steps:
In the Applications Navigator, under the project that contains your portlet, right-click index.jsp, and select Run.
Your browser should open with a page similar to the one shown in Figure 18-32.
Figure 18-32 Portlet Application Test Page
Click the link underneath Service Name. Your browser should open with a page similar to the one shown in Figure 18-33. Note that you need the URL from this page to register your producer, which is the next task.
Alternatively, enter the URL for your portlet to check that it is working. The URL is constructed as follows:
http://host:port/context-root/providers/producer_name
where:
host is the server to which your producer has been deployed.
port is the HTTP Listener port (set in the default-web-site.xml Web site configuration file created for the instance.).
context-root is the Web Application's Context Root, which you specified earlier and can be found in the WAR Deployment Profile Properties under General.
producer_name is the name of the portlet's producer. A WAR file may contain more than one producer, hence you should always include the name of the producer for clarity. Otherwise, you will get the default producer, which is simply the last producer created.
You should see a page similar to the one in Figure 18-33.
After you've created and deployed the producer and its portlets, you should register the producer with an application and add it to a page to check that it is working correctly. Registering a producer gives applications the information they need to locate and communicate with that producer. After you register a producer, the producer and its portlets become available in the Component Palette.
To register producers for your standards-based portlets, follow the instructions provided in Section 4.3.1.1, "Registering WSRP Portlet Producers".
To register producers for your PDK-Java portlets, follow the instructions provided in Section 4.3.1.2, "Registering PDK-Java Portlet Producers".
To add your portlets to a page, follow the instructions provided in Section 4.3.2, "Adding Portlets to a Page".
Footnote Legend
Footnote 1: The Java Portlet Specification 1.0 arose from Java Specification Request 168 and the JSR168 Expert Group.
