Oracle9iAS Portal Developer Kit
Getting Started - An Overview of Portlet Development

This article contains an overview of the concepts and technologies used for developing portlets for Oracle9iAS Portal. It also includes links to Oracle9iAS Portal Developer Kit (PDK) articles and white papers for further study. It is not a step-by-step guide to portlet development as there are many articles in the PDK that do this very well. This article introduces several different implementation styles and discusses their advantages and disadvantages. It also highlights some important issues you need to consider when designing and developing portlets with support for popular features such as personalization, security, portlet caching, and more.

Oracle9iAS Portal Developer Kit is a resource for developers and it is available at http://portalstudio.oracle.com. It is full of articles and samples that explain and guide you through portlet development. This document is a guide to accompany the Oracle PDK.


INTRODUCING PORTLETS AND ORACLE9iAS PORTAL

Oracle9iAS Portal provides a framework for integrating content from external sources. These sources may be Internet services provided by network services vendors, or applications that are essential to end users of Oracle9iAS Portal. The external content is displayed to the user as 'windows' on a portal page. We call these windows, portlets.

Portlets are windows in a portal that incorporate content from external sources.

Portlets are owned and managed by an application called a provider that is registered with Oracle9iAS Portal. A provider can own one or more portlets and it facilitates communication between Oracle9iAS Portal and the portlets that it owns. You may hear the term 'portlet' used informally to refer to the whole entity, i.e. both provider and portlet. This is because the end user interacts and can 'see' the portlet, whilst the provider is communicating behind the scenes with Oracle9iAS Portal to expose the portlet. In fact, both the provider and the portlet are required to supply a service.

Many functions within Oracle9iAS Portal are implemented as portlets. They include administrative functions such as user and group management, monitoring and reporting tools, and utilities such as search and user directories, among others.

There are also many other portlets available via the Oracle Portal Catalog that have been created by members of the Oracle Portal Partner Initiative (OPPI). Here, you can find hundreds of portlets developed by our partners supplying Internet services, application services, and consulting and integration services.

In many enterprises, the portal is the desktop. Portlets enable application providers to integrate their application into this desktop. While portlets are rendered in Oracle9iAS Portal pages, the underlying application need not be Web enabled. The portlets can communicate with the underlying application in its native language and render the content for display in a Web page.


PLANNING YOUR PORTLET

For a successful implementation of your portlet, it is imperative to first gather all of the requirements. There are several key things to consider, including:

Portlet Objectives

Consider what the portlet must offer and the business requirements to be satisfied by this portlet. Your objective may be to provide a mechanism for integrating your application into Oracle9iAS Portal. In that case, consider the benefit this will provide to your customers.

Here are some examples of portlet objectives:

Application Exposure in the Portlet

Since portlets provide 'windows' to application content, it is advisable to expose a snapshot of key information from the application, with links to drill down for more detail.

Application portlets typically provide summary information with drill down capability.

Consider the following sample portlets. A News Service portlet may show a list of headlines each followed by a short description, or maybe just the first sentence of the news article. The headlines are links that take the user to the full text of the article.


Figure 1: News Service Portlet

Another example is a Search portlet that displays some branding text to identify and describe the service, together with a text box to enter a search string.


Figure 2: Search Portlet

A Human Resources application portlet that allows users to search their company directory for co-workers' contact information.


Figure 3: Human Resources Search portlet

An appointments and calendar portlet highlighting today's scheduled appointments with links to take the user to the full-featured calendar to manage their appointments.


Figure 4: Calendar Portlet

An email portlet displaying a snapshot of your most recent email messages.


Figure 5: Recent Email Message Portlet


DESIGNING YOUR PORTLET

In this section, we take a closer look at the types of features your portlet can support, and provide some hints and tips for designing such features.

User Interface: Look and feel considerations

As with any application, an appealing user interface is one that is intuitive to end-users. There are some additional things to consider when building portlets for Oracle9iAS Portal. All portlets share a page with other portlets, and each portlet is rendered within an HTML table cell. This implies several things. If one portlet renders incorrect HTML, depending on the browser, the entire page may not be displayed. This means that each portlet must be a good portal citizen, and obey the laws of HTML.

The second fact, that all portlets are rendered inside their own table cell, is also very important to remember when designing the portlet user interface and coding the HTML. Some browsers (Netscape, for example) do not handle multiple levels of nested tables very well. When designing your portlet, keep in mind that it will be rendered inside a table, thus, at least one level of nesting is already guaranteed. Keep any additional nesting to a minimum.

Refer to the Oracle PDK article, Guidelines for Portlets in Shared Screen Mode for more detailed information.

Personalization: Settings configurable by an end user

Personalization support can be built into any portlet and it allows end users to personalize their experience when using the portlet. Common customizations include the ability to manipulate the look of the portlet and also its behavior.

For example, if your portlet displays a list of items, it may be desirable to allow users to select the number of items to be displayed. The news service portlet discussed above can be built to support user level personalization, such as the number of headlines to display.

The ability to manipulate the behavior of a portlet can be a powerful tool for end users. The personalization settings are persistent, such that the next time the user accesses the same instance of the portlet, the settings are still in effect.

For example, the same news service portlet may offer industry specific headlines and articles and allow the end user to select their industry choice such as: automotive, information technology, or medicine, among others. Each time the user returns to the page containing the portlet, the news portlet displays articles for their configured industry.

Portlets that support personalization display a Customize link in the banner. Refer to the sample portlets My Calendar and Recent Messages shown in Figures 4 and 5 above.

These Oracle PDK articles provide additional material on personalization:

PDK-PL/SQL  A Primer on End User Personalization
PDK-Java        Adding Customization

Help: Providing instructions or hint text

Consider adding help support when hints/suggestions may help your end user, or if you need to provide portlet feature information. Portlets that support help display a Help link in the banner as shown in Figure 6 below.


Figure 6: Portlet with Help Support

Refer to the Oracle PDK article Guidelines for Portlets in Help Mode for more detailed information.

Security: Exposing sensitive information

If your portlet exposes secure information, such as employee data from a Human Resources application, or email messages for the current user, the content should be protected from unauthorized users. Applications of this nature are typically password protected and to be authenticated you must provide a valid user ID and password.

When designing security features for a portlet, also consider whether you want the existence of the portlet to be known to unauthorized users. For example, it is possible to implement security such that unauthorized users do not see the portlet name and description when they browse through the portlet repository. A good example of this is an administration portlet that you don't want exposed to end-users. This way, not only is the unauthorized user unable to view the portlet content, the user isn't even aware that such a portlet exists.

Other security considerations include the type of authentication required. The portlet may trust Oracle9iAS Portal, such that users authenticated by Oracle9iAS Portal can access the portlet. We call this a partner application, and the provider that implements it is referred to as a partner application provider. Applications that already use the Single Sign-On (SSO) Server for authentication are good candidates for this type of implementation since Oracle9iAS Portal itself authenticates through the SSO Server.

Alternatively, the portlet can expose content from a secure application that manages its own user accounts. These types of applications are called external applications, and the provider that implements it is referred to as an external application provider. This is typical of many existing password protected applications that have their own user management capabilities. In these cases, a user mapping is stored in the SSO Server, mapping the Oracle9iAS Portal user with the external application user credentials.

Another feature that is implied when implementing a secure portlet is support for session management. This means that once a user is authenticated, subsequent requests are already authenticated. When you first access the application, it checks to see if you have been authenticated and if not, displays the Login screen. When you successfully login to the application, it creates a cookie (or employs another session storage mechanism) so it knows you are logged in when subsequent requests are processed.

Refer to these Oracle PDK articles for an introduction to portlet security:

PDK-PL/SQL  Primer on Security Services
PDK-Java        Understanding Portlet Security

Caching: Minimizing content retrieval time

For a performant portlet it is good design practice to identify content that can be cached for fast subsequent retrieval. Oracle9iAS Portal supports two types of caching for portlets:

Validation based caching uses a pre-defined key value to test whether the cache is still valid. Before rendering a portlet, a request is made to the application to determine if the key value is valid for reuse. The application determines its current state compared to the key value. It does this by comparing the current value with the key value to determine if the cached data is still valid. If the key value has not changed, it sends a message to use the cached content.

Expiry based caching uses a given expiration period to determine whether to render cached content or to fetch it again. A good use for this type of caching is a news service portlet that receives new feeds every 20 minutes. Expiry based caching can be set up to expire every 20 minutes, causing the cache to be updated as often as required.

The caching method you use depends on your portlet functionality, and the nature of the content. Certain cases are suited to expiry based caching. For example, a portlet that renders content from an external source that is refreshed at predictable intervals. Another example is where the portlet always renders static content, such as a search box that allows users to search an external source. This type of portlet content can be cached using a large expiration period.

More often, portlets render content that change at infrequent intervals in response to user interaction with the application. In these cases, if you can generate a key that can be used to check whether the content has changed, then validation based caching should be employed.

Refer to the Oracle PDK article Primer on Caching for more information.


BUILDING YOUR PORTLET

This section reviews the implementation styles available for building portlets and discusses the advantages and disadvantages of each style. After reading this section, you should be able to choose the implementation style that is best suited for your portlet. We also take another look at the features discussed in the previous section and provide hints on how to implement such features.

Implementation Style Overview

Oracle9iAS Portal provides two main styles for implementing portlets:

A database provider is implemented as a PL/SQL stored procedure and is installed in the Oracle9iAS Portal database.

A Web provider is implemented in any Web capable language (Java, JSP, Perl, ASP, etc.) and is installed and hosted in a Web server that is typically remote from Oracle9iAS Portal.

Oracle9iAS Portal communicates with a database provider by making local procedure calls, and communicates with a Web provider using HTTP.

Another way to implement portlets is to employ URL Services, which is an extension of the Web provider. The architecture of these styles is discussed later in this paper.

Oracle9iAS Portal Architecture

This section introduces the architecture of Oracle9iAS Portal and then discusses how database and Web providers fit into that architecture.


Figure 7: Oracle9iAS Portal Architecture

A good way to discuss Oracle9iAS Portal's architecture is to examine how the components work together. Let's look at how Oracle9iAS Portal assembles and renders a page containing portlets.

When the PPE makes requests for the portlets on the page, it sends the requests to the respective providers of those portlets. The providers communicate with the portlets and return the portlet content to the PPE that then assembles the page and returns it to the calling browser.

Refer to these Oracle PDK articles for further reading on the Oracle9iAS Portal architecture and page request flow:

Parallel Page Engine Architecture
Oracle9iAS Portal Page Request Flow

Let's now look at the provider architecture.

Database Provider Architecture


Figure 8: Oracle9iAS Portal Database Provider Architecture

The database provider and its portlets are installed in the database together with Oracle9iAS Portal. The portal communicates with the database provider which in turn communicates with the portlets that it owns and manages. This communication is done by making local procedure calls, since both are in the database. Database providers can leverage PDK-PL/SQL Services to simplify building PL/SQL portlets. These services include support for: security, logging, preference store, NLS, error handling, context, session store, and parameter passing.

Oracle PDK articles relating to database providers can be found on the PDK-PL/SQL Home Page.

Each database portlet and provider must implement a set of procedures that are invoked in response to requests made by Oracle9iAS Portal when pages containing database provider portlets are requested. The portal invokes the provider's procedures which will perform its own actions and in turn invoke the portlet's procedures to render the portlet.

An example of a procedure implemented by the provider is register_provider. This procedure is invoked when the provider is registered with Oracle9iAS Portal and it is where provider-level initializations are performed.

An example of a procedure implemented by a portlet is show. This procedure is invoked to render portlet content.

Oracle PDK articles containing portlet development guidelines can be accessed from the PDK-PL/SQL Home Page.

There is a hosted utility called the PL/SQL Generator which can be employed to generate installable database provider PL/SQL packages based on a provider definition file. To use the utility you must first describe the provider and the portlets it manages in the provider definition file. Next, provide the file to the generator to generate a database provider and portlets code stub. This package can then be implemented and installed.

Advantages of Database Providers

Drawbacks of Database Providers

Web Provider Architecture


Figure 9: Oracle9iAS Portal Web Provider Architecture

While Web provider portlets can be developed in any Web capable language, to simplify developing Java Web providers, the Oracle PDK supplies a set of services called PDK-Java. These services enable Java programmers to integrate existing Java based applications (Java applications, Java Servlets, Java Server Pages) into portlets. It provides abstractions for the underlying communication mechanisms, and exposes APIs for end-user customization, session storage, security, and logging.

The diagram above illustrates the PDK-Java architecture. Oracle9iAS Portal sends requests for portlet content via a provider servlet called the Web Provider Adapter. The request uses Simple Object Access Protocol (SOAP), a general purpose XML messaging protocol transmitted over HTTP. The portlet content is returned to the Portal using the same standard.

PDK-Java provides an implementation of the Web Provider Adapter that insulates the developer from the HTTP syntax defined by Oracle9iAS Portal for communicating to Web providers. The Web Provider Adapter is responsible for receiving Oracle9iAS Portal requests, un-marshaling the details, locating the target provider, calling the provider methods to perform the functions, and marshaling the results into the HTTP response.

Similar to the database implementation, the Web provider and portlets have a set of methods that must be implemented. These methods are specified in the Web provider interfaces.

To simplify building Web portlets, PDK-Java supplies a base implementation that follows the specification of the Web provider interfaces. PDK-Java includes a set of default classes that implement each of the Web provider interfaces. These classes reduce the development work for a provider by implementing the common functions. Used along with a declarative programming mechanism called provider.xml, the developer works by sub classing and overriding only those behaviors that need to be extended or implemented differently. The base implementation includes a class file that corresponds to each of the Web provider interfaces, supplying the objects provider, and portlet, and controllers, render manager, security manager, and personalization manager that implement those specific roles.

For more information about Web providers and PDK Services for Java, refer to Building Web Portlets with Oracle9iAS Portal and the PDK.

Advantages of Web Providers

Disadvantages of Web Providers

URL Services Architecture


Figure 10: URL Services Architecture

URL Services is built on top of the PDK-Java Web provider services supplied by Oracle9iAS Portal. URL Services takes the URL of an application, parses the content, and uses the PDK-Java framework to create a portlet. When a user views a portal page containing a portlet from the URL Services provider, a provider session is established between the portal and the provider.

The authentication information in a provider definition file (which is used to describe the provider) is used to construct a login URL for the remote application. The URL Services provider then submits an HTTP request using that login. The remote application receives the HTTP request and processes it as it would if the request had come from the remote application itself - the remote application does not need to be modified, nor does the portlet developer need to know how it functions internally. Since the URL Services provider submitted the HTTP request, it is able to take the returned HTML, parse it, and render it to the portal user according to the filters specified in the provider definition file. In this way, a subset of the remote application can be displayed as a portlet.

URL Services itself is implemented using the PDK-Java Web provider services where the provider interface is implemented by a DefaultURLProvider object, the portlet interface is implemented by a PortletNodeHandler object, security is implemented by URLSecurityManager, and rendering is implemented by a URLPageRenderer which uses two objects, HTMLFilter and XMLFilter to filter and render content. To use the URL Services framework it isn't necessary to know how these objects are implemented, but it is helpful to know the overall architecture. The URL services MyYahoo! example included in the Oracle PDK contains step-by-step instruction for creating a MyYahoo! portlet using URL Services.

If your application has authenticated hyperlinks, it is imperative that the login page of the application has a redirect URL that specifies the page to go to upon a successful login. It is this page that URL Services will use to render portlet content. While this is typically true of most Web based applications, it is something to consider when planning your URL Services portlet.

Advantages of URL Services

Disadvantages of URL Services

Refer to these Oracle PDK articles for more information on URL Services:

A Primer on URL Services
Understanding the URL Services Runtime
Understanding the provider.xml for URL Services Runtime
Understanding the MyYahoo External Applications Portlet

Implementing Personalization

There are two types of personalization data; default and individual. Default personalization data is typically set by an administrator who sets the default values. Individual users who have not yet set their own preferences see the default settings. Individual personalization data is both user and instance specific, meaning that each user can personalize each instance of the portlet differently.

Portlet instances are managed using portlet references, where each reference is equivalent to each instance of the portlet. By following the guidelines and samples in the PDK this can be achieved for both database provider portlets and Web provider portlets.

Database provider portlets (or PL/SQL portlets) support personalization through a preference store which is maintained in the database. The Oracle9iAS Portal environment allows you to store preferences for each unique portlet instance in a persistent manner. It provides a unique identifier for each individual, a preference store automatically mapped by user, and access mechanisms for storing and retrieving personalization information.

PDK-Java supports two options for implementing personalization, file personalization and database personalization. File personalization is used to store personalization data to the file system and database personalization is used to store personalization data in the database.

Refer to the following PDK-Java articles for personalization:

PDK-Java   Adding Customization
PDK-Java   Installing the DBPersonalizationManager Sample

Implementing Security

Let's revisit the methods available for integrating secure remote applications into Oracle9iAS Portal. They can be integrated as partner application providers, external application providers, or using URL Services. Partner application providers allow for the tightest integration, but require that the remote application be modified to relegate authentication to the Single Sign-On (SSO) Server. External application providers allow for an integration which does not require that the remote application be modified, but requires that the integration be coded. URL Services allows users to access existing content using a URL without any coding. As such, it does have its limitations.

Choosing an implementation method is dependent on the remote application and the functionality you wish to provide through your portlets. The following should help you decide which approach to take.

Partner Application

External Application

URL Services

It is important to note that database providers are better suited for integrating remote applications as partner applications rather than as external applications. Database provider portlets typically leave authentication to Oracle9iAS Portal and trust that the portal will return an authenticated user upon request.

It is not to say that the portlet does not implement any security of its own, but that it doesn't maintain its own user management scheme. In fact, Oracle9iAS Portal requires that database providers implement specific procedures telling it whether the current user has enough privileges to access the portlets. For public information, these procedures are implemented to simply return true, indicating to the portal that access is permitted. For secured information, the portlet has the opportunity to test the user's security level as defined in the SSO Server, which in this case is being employed to define the access level for both Oracle9iAS Portal and the remote application.

Refer to the white paper, Integrating Password Protected Applications for a good discussion of the above approaches.

These Oracle PDK articles provide additional information about implementing portlet security in PL/SQL portlets:

PDK-PL/SQL  Implementing Security Services
PDK-PL/SQL  Implementing Session Context

Implementing Session Storage

HTTP is a stateless protocol, which means that each request is handled singularly, without knowledge of previous requests. This means that Web based applications have to do something 'extra' to maintain state. To maintain state, Web based applications use mechanisms to store request information that subsequent requests can access. While session storage isn't necessarily a feature of a portlet, it can certainly be an important function of a portlet.

Oracle9iAS Portal implements session storage to keep and manipulate temporary data for a user's current session with the portal. Database provider portlet developers can leverage this session store to maintain state in their portlets. The Oracle9iAS Portal portlet framework supplies PL/SQL services (APIs) to use its session storage mechanism.

It is important to note that the persistency of the data stored in the session store is the same as the persistency of the portal session. When the session ends, the data stored in the session store for that session is lost. This happens when end users log out of the portal, or when they close all instances of their browser -since at this time their current Oracle9iAS Portal session ends. If this information needs to be maintained longer, it should be saved to a preference store which is used to store personalization data.

Session management is implemented in database providers using the portal session object. Web provider portlets implement their own session store, which is typically done through the creation of browser cookies. Web providers that implement session storage implement a method in the Provider interface called initSession. The number of times this method is invoked is configurable. It can 'never' be invoked, for Web provider portlets that don't do any session management, 'once', for Web provider portlets that create one cookie per user session, or 'always', for portlets that create a cookie each time the portlet is viewed.

These Oracle PDK articles provide additional information about implementing session storage:

A Primer on Portal Management of Provider Sessions

PDK-PL/SQL  A Primer on Session Storage
PDK-PL/SQL  Implementing Session Storage
PDK-Java       How to Add Session Storage to Your Java Portlet

Implementing Caching

Caching can be employed to store portlet content in the middle tier Oracle9i Application Server for quick subsequent retrieval.

The first step is to choose the type of caching to employ, i.e. validation based caching, or expires based caching. In general, think about whether it makes more sense to use the cache for a fixed period of time, which might be the case if you know that the portlet usually doesn't change often. Otherwise, choose to use validation based caching where you can generate a key that can be used to check whether the content has changed.

For database providers, if you plan to use expiry-based caching, you can set the caching_period field of the portlet_runtime_record parameter that the Show procedure of the portlet receives. If you plan to use validation-based caching, you can use the caching_key field of the portlet_runtime_record parameter that the Show procedure of the portlet receives. You will also need to add a check to compare the value of the current caching key with the value of the caching_key field of the portlet_runtime_record. The first time the Show procedure is called, the key will be null. Set the appropriate key value for subsequent calls.

Another supported feature of database provider caching is the concept of a caching level, which is used to specify whether the cache is 'system level' or 'user level'. System level caching indicates that the content is appropriate for general consumption, while user level caching indicates that the cache is only valid for a specific user.

Web provider content can also be cached in the Oracle9iAS Portal middle tier, improving performance. With expiry-based caching, when a provider receives a render request, it stamps its response with an expiry time. The rendered response is stored in the cache, and is used to handle all subsequent requests for the same content until the expiry time has passed. With validation-based caching, when a provider receives a render request, it stamps its response with a version identifier and caches it. Subsequent requests for the same content are first validated. It does this by sending the provider a render request which includes the version identifier of the previously-cached version of the response. If the provider decides that this version identifier is still valid, it immediately sends a lightweight response without any content, to indicate to the Parallel Page Engine (PPE) that it can reuse the cached version.

These Oracle PDK articles provide additional information about implementing caching:

PDK-PL/SQL   A Primer on Caching in PL/SQL Portlets
PDK-PL/SQL   Implementing Validation-Based Caching
PDK-PL/SQL   Implementing Expiry-Based Caching
PDK-Java        Adding Simple Caching to Your Java Portlet

DEPLOYING YOUR PORTLET

Once portlets have been developed, they should be packaged for deployment following the guidelines specified in the Oracle PDK

For more information, refer to Portlet Packaging Guidelines.

If the portlets are to be supplied as a hosted service, then, instructions for registering the provider should be made available to Oracle9iAS Portal administrators along with any instructions that may be required or useful to end users. One important note to include in the instructions is a reminder that administrators must configure their proxy settings, if they use a proxy server to access the internet. Proxy settings must be configured in two places in Oracle9iAS Portal:

To configure the proxy server in Global Settings:

  1. Login to Oracle9iAS Portal as a portal administrator
  2. Click the Administer tab.
  3. Under the Administer tab, click on Global Settings.
  4. Enter the following information in appropriate fields, under the section titled Proxy Server:
    5. HTTP Server
    		 <your proxy host here>
    HTTP Server Port
    		 <your proxy port here>
    No Proxy Servers for Domains Beginning With
    		 <your ignored domains here (need not begin with ".")>
    URL Connection Time-out (seconds)
    		 <your connection time-out value here>
  5. Click OK.

To configure the proxy server in the Parallel Page Engine:

  1. Initialize the Parallel Page Engine servlet with your proxy server information by editing your zone.properties file and adding the following initialization parameters to the 'Aliased Servlet Init Parameters' section:
    2. servlet.page.initArgs=proxyHost=<your proxy host here>
    servlet.page.initArgs=proxyPort=<your proxy port here>
    servlet.page.initArgs=proxyIgnore=<your ignored domains here>
    The proxyHost parameter should just be the hostname of the proxy server you are using (e.g., proxy-server.domain.com).  Any domain names you include in the proxyIgnore setting must begin with a dot (e.g., .domain.com).
  2. Stop and restart the HTTP server.

CONCLUSION

The portlet framework allows service providers and applications vendors to expose aspects of their services and applications through Oracle9iAS Portal by leveraging its portlet architecture. The portlet architecture supplies services for building portlets that support personalization, help, security, caching, and other features.

The Oracle PDK contains many detailed articles to guide a developer through the design and implementation of portlets and these can be read online, or downloaded from http://portalstudio.oracle.com. There are also white papers available from the Oracle Technology Network that explain how to leverage Oracle9iAS Portal and its portlet framework to build your own portlets.

Revision History: