Oracle9iAS Portal Developer Kit
Understanding the Web Provider Utilities

A portlet's main function is to display information. A set of Web Provider Interfaces specifies the functions required to display information as a Java portlet within Oracle9iAS Portal. The PortletRenderer interface is one of a set of the Web Provider Interfaces. The PortletRenderer specifies the functions required by your implementation to render display modes of a portlet. The Provider Runtime supplies a default implementation called PageRenderer. The PageRenderer is a base class that renders JSP Pages. Using a servlet based portlet, you write your own implementation of the PortletRenderer. Whether rendering portlets as JSP or Servlets, there are many repetitive functions such as creating the portlet titlebar, portlet header, portlet footer, etc. PDK-Java (JPDK) provides a set of utilities to simplify coding your renderer.

This article describes HttpPortletRendererUtil, its function and the default behavior of its utility methods. This article is separated into two main sections, Function and Behavior.

### FUNCTION

The HttpPortletRendererUtil class provides many useful utility methods designed to simplify coding your implementation of the PortletRenderer. It implements utilities to perform the basic tasks that may occur for every portlet rendered. These utilities allow you to simplify coding of repetitive functions as well as easily use new features of the Web Provider.

### BEHAVIOR

The HttpPortletRendererUtil's main funtion is to provide utilities that ease the development and programming required to render your Java portlet. There are three types of utilities within this class file, wrappers for the utilities within PortletRenderUtil, utilities to manage caching, and covers for servlet function. This section describes the utility methods within HttpPortletRendererUtil and is grouped by the utility type.

Wrappers

Wrapper utility methods are convenience utilities. These utilities are used when creating your renderer as a JSP or Servlet implementation. They provide such functionality as creating the portlet borders and titlebar, retrieving and setting customization data, or performing form actions. The following are a list of wrapper utility methods and their function.

renderPortletHeader(HttpServletRequest request, Writer writer, String title)

This method is used to render the top container for your portlet. The top container includes the titlebar and shoe mode links. This method is used in conjunction with renderPortletFooter(). Call this method from your renderer before displaying the body of your portlet and pass it the portletrequest, writer, and portlet title.

public static void renderPortletFooter(HttpServletRequest request, Writer writer)

This method is used to render the bottom container of your portlet. Call this method after displaying the body of your portlet and pass it the portletrequest and writer.

public static void renderPortletTitlebar(HttpServletRequest request, Writer writer, String title)

This method is used to render a portlet's titlebar. Typically this method is not used as renderPortletHeader() renders the cotainer and includes the titlebar.

public static String parameterizeLink(HttpServletRequest request, int linkType, String queryString)

This method is used to add new parameters to links available to a portlet. It queries the link as a String and add new parameters by name. Duplicate parameters will not be added to the link.

public static String absoluteLink(HttpServletRequest request, String relativePath)

This method is used to fully-qualified URI. The current URL refers to the Portal and not the portlet. This method creates a fully-qualified path based on the current request.

public static String htmlFormActionLink(HttpServletRequest request, int linkType)

This method is used to create a form that will be used within a form action tag and submit data.

public static String htmlFormHiddenFields(HttpServletRequest request, int linkType)

This method is used to transform parameters received from a URI into hidden form fields. This is used when linking back to a portlet.

public static String portletParameter(HttpServletRequest request, String param)

This method is used to create a fully qualified name from a query string parameters name. A portlet on a page shares request parameters with other portlets. It recognizes a parameter by a fully qualified (unique) name. A fully qualified parameter is of the type: "providerID.portletID.portletInstanceName.symbol".

public static Object getEditData(HttpServletRequest request)

This method is used to retrieve the customization data object for a given request.

public static void submitEditData(HttpServletRequest request, Object o)

This method is used to update the customization and store the personalized data submitted by a user.

Caching

The caching utility methods simply using either time-based or validation-based caching in your portlet. They have such functions as setting the expiration time, validating a portlet, and retrieving the caching information to display a cached version of the portlet.

public static void setCacheExpires(HttpServletResponse response, int level, int minutes)

This method is used to set the duration in minutes that a portlet uses cached data before expiring. This expire-based caching is added to the portlet header field and notifies the Portal of the expiry time.

public static void setCachedVersion(HttpServletResponse response, String version, int level)

This method is used to set a validation-based caching with the portlet. This validation-based caching notifies the Portal to check to see if the portal data is still valid before displaying the cached version of the portlet.

public static void useCachedVersion(HttpServletResponse response)

This method is used to display the cached version of the portlet to the client. This method is used along with setCachedVersion(). When the Portal verifies that the portlet is still valid, this method tells the Portal to use the cached version of the portlet.

public static String getCachedVersion(HttpServletRequest request)

This method is used to get the cached version ID passed by the Portal for the current request. This method is used along with setCachedVersion() and useCachedVersion().

public static int getCachedLevel(HttpServletRequest request)

This method is used to get the cached user level for the portlet passed by the Portal for the current request. This method is used long with getCachedVersion(). Together, they retrieve the version ID and user level when displaying the cached version of the portlet to the client.

Covers

There is only one servlet cover within the utility methods. The servlet covers allow you to perform servlet requests without accessing the servlet response object.

public static void sendRedirect(PortletRenderRequest pr, String url)

This method is use to send a redirection response from within the portlet to the Portal. This is used when refreshing the page, or accessing the previous page.

Revision History:

- November 16, 2000