oracle.portal.provider.v2.render.http
Class HttpPortletRendererUtil

java.lang.Object
  oracle.portal.provider.v2.render.PortletRendererUtil
      oracle.portal.provider.v2.render.http.HttpPortletRendererUtil

public class HttpPortletRendererUtil
extends PortletRendererUtil

The HttpPortletRendererUtil class provides many useful utility methods designed to simplify coding your renderer. HttpPortletRendererUtil extends PortletRendererUtil. It implements those utilities that have a dependency on the (Http) servlet interfaces. These are grouped into three categories: wrappers for PortletRendererUtil utilities, utilities to managing caching, and covers for servlet function. The wrappers for PortletRendererUtil utilities are provided as a convenience for renderers implemented as JSPs or servlets. They give you the convenience of passing servlet objects thus avoiding extracting the PortletRenderRequest that is required in the PortletRendererUtil utilities. The caching utilities simplify enabling either the validation or expiry based caching provided by the Portal. As for servlet covers, there is currently only one, sendRedirect, that allows you send a redirect response without directly accessing the servlet response object.

Field Summary

Fields inherited from class oracle.portal.provider.v2.render.PortletRendererUtil

BACK_LINK, DESIGN_LINK, EVENT_LINK, LOGIN_LINK, PAGE_LINK, PORTLET_PARAMETER_PREFIX, REQUEST_LINK

Constructor Summary

HttpPortletRendererUtil()

Method Summary

static java.lang.String	absoluteLink(javax.servlet.http.HttpServletRequest request, java.lang.String relativePath) Returns a fully-qualified URI for a path relative to the current request.
static void	addGeneratesESIHeader(PortletRenderRequest request) Adds response header that enables processing of ESI tags by Web Cache.
static int	getCachedLevel(javax.servlet.http.HttpServletRequest request) Gets the (cached) level passed by the portal for the current request.
static int	getCachedLevel(PortletRenderRequest request) Gets the (cached) level passed by the portal for the current request.
static java.lang.String	getCachedVersion(javax.servlet.http.HttpServletRequest request) Gets the (cached) version Id passed by the portal for the current request.
static java.lang.String	getCachedVersion(PortletRenderRequest request) Gets the (cached) version Id passed by the portal for the current request.
static java.lang.Object	getEditData(javax.servlet.http.HttpServletRequest request) Retrieves this requests customization data object.
static void	handleEditAction(PortletRenderRequest pr, java.lang.String action) Utility for generating redirects after processing edit/edit default forms
static java.lang.String	htmlFormActionLink(javax.servlet.http.HttpServletRequest request, int linkType) Transforms one of the various URIs known to the request into the appropriate form to be used in a FORM action tag.
static java.lang.String	htmlFormHiddenFields(javax.servlet.http.HttpServletRequest request, int linkType) Encodes the parameters in the query string of the passed URL as hidden form fields.
static java.lang.String	parameterizeLink(javax.servlet.http.HttpServletRequest request, int linkType, java.lang.String queryString) Adds new parameters to an existing link.
static java.lang.String	portletParameter(javax.servlet.http.HttpServletRequest request, java.lang.String param) Utility that turns a query string parameter name into fully qualified (unique) name.
static void	renderPortletFooter(javax.servlet.http.HttpServletRequest request, java.io.Writer writer) Closes rendering of the portlet container.
static void	renderPortletHeader(javax.servlet.http.HttpServletRequest request, java.io.Writer writer, java.lang.String title) Opens rendering of the portlet's container.
static void	renderPortletTitlebar(javax.servlet.http.HttpServletRequest request, java.io.Writer writer, java.lang.String title) Renders a portlet's titlebar.
static void	sendRedirect(PortletRenderRequest pr, java.lang.String url)
static void	setCachedVersion(javax.servlet.http.HttpServletResponse response, java.lang.String version, int level) Sets the response (cached) version Id and level.
static void	setCachedVersion(PortletRenderRequest request, java.lang.String version, int level) Sets the response (cached) version Id and level.
static void	setCacheExpires(javax.servlet.http.HttpServletResponse response, int level, int minutes) Sets the expiration duration of the current response.
static void	setCacheExpires(PortletRenderRequest request, int level, int minutes) Sets the expiration duration of the current response.
static void	submitEditData(javax.servlet.http.HttpServletRequest request, java.lang.Object o) Updates this requests customization data object creating the customization instance if necessary.
static void	useCachedVersion(javax.servlet.http.HttpServletResponse response) Indicates to the portal that the cached version should be used to respond to the client.
static void	useCachedVersion(PortletRenderRequest request) Indicates to the portal that the cached version should be used to respond to the client.
static void	useInvalidationCaching(PortletRenderRequest request) Set the response header to cache content in Web Cache.
static void	useInvalidationCaching(PortletRenderRequest request, int minutes) Set the response header to cache the content for a specified duration in Web Cache.

Methods inherited from class oracle.portal.provider.v2.render.PortletRendererUtil

absoluteLink, constructDetailLink, constructHelpLink, constructLink, emitHiddenField, encodeParameter, getEditData, getEditDefaultData, getEditFormParameter, getModeName, getModeTitle, getModeValue, getShortTitle, getTitle, htmlFormActionLink, htmlFormActionLink, htmlFormHiddenFields, htmlFormHiddenFields, parameterizeLink, parameterizeLink, portletParameter, renderCustomizeFormFooter, renderCustomizeFormHeader, renderError, renderErrorFooter, renderErrorHeader, renderErrorLine, renderInformationFormFooter, renderInformationFormHeader, renderPortletFooter, renderPortletFooter, renderPortletHeader, renderPortletHeader, renderPortletHeader, renderPortletTitlebar, renderPortletTitlebar, submitEditData

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpPortletRendererUtil

public HttpPortletRendererUtil()

Method Detail

renderPortletHeader

public static void renderPortletHeader(javax.servlet.http.HttpServletRequest request,
                                       java.io.Writer writer,
                                       java.lang.String title)
                                throws java.io.IOException

Opens rendering of the portlet's container. Portlets are responsible for rendering their container. This method used in conjunction with renderPortletFooter renders the standard container including borders and titlebar. Use the methods as bookends. renderPortletHeader should be called before the portlet renders (its body) and renderPortletFooter should be called after the portlet renders (its body).

This is a convenience routine for use by renderers written as servlets or JSPs. I.e. those whose code objects are the servlet objects not the WebProvider objects.

Parameters:

request - the servlet request.

writer - the response writer.

title - the titlebar label. If null the portlet's static title is used.

Throws:

java.io.IOException

renderPortletFooter

public static void renderPortletFooter(javax.servlet.http.HttpServletRequest request,
                                       java.io.Writer writer)
                                throws java.io.IOException

Closes rendering of the portlet container. Portlets are responsible for rendering their container. This method used in conjunction with renderPortletHeader renders the standard container including borders and titlebar. Use the methods as bookends. renderPortletHeader should be called before the portlet renders (its body) and renderPortletFooter should be called after the portlet renders (its body).

This is a convenience routine for use by renderers written as servlets or JSPs. I.e. those whose code objects are the servlet objects not the WebProvider objects.

Parameters:

request - the servlet request.

writer - the response writer.

Throws:

java.io.IOException

renderPortletTitlebar

public static void renderPortletTitlebar(javax.servlet.http.HttpServletRequest request,
                                         java.io.Writer writer,
                                         java.lang.String title)
                                  throws java.io.IOException

Renders a portlet's titlebar. Portlets are responsible for rendering their container. This method renders the standard portlet titlebar using information from the request and Portlet meta-data. Typically, clients will not use this method. Rather they will rely on renderPortletHeader() to render the entire container including the titlebar. If however, renderPortletHeader is not used, this method is provided for convenience.

This is a convenience routine for use by renderers written as servlets or JSPs. I.e. those whose code objects are the servlet objects not the WebProvider objects.

Parameters:

request - the servlet request.

writer - the response writer.

title - the label that should be displayed as the title. if null then the method will render the static title retrieved via Portlet.getTitle();

Throws:

java.io.IOException

parameterizeLink

public static java.lang.String parameterizeLink(javax.servlet.http.HttpServletRequest request,
                                                int linkType,
                                                java.lang.String queryString)
                                         throws java.lang.IllegalArgumentException

Adds new parameters to an existing link. There are various links available to the portlet for use while rendering its response. This utility method conveniently adds parameters to one of these links. The method overrides existing parameters if they exist. I.e. existing (queryString) parameters will be removed if it duplicates (by name) a new parameter.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Parameters:

request - the servlet request.

linkType - the id for the link we want to parameterize. ID constants are defined in PortletRendererUtil.

queryString - the parameters to be added in properly encodes queryString form. The string should begin with the first parameter name not a "?".

Throws:

java.lang.IllegalArgumentException

absoluteLink

public static java.lang.String absoluteLink(javax.servlet.http.HttpServletRequest request,
                                            java.lang.String relativePath)

Returns a fully-qualified URI for a path relative to the current request. As Web (Http) Portlets are called indirectly via the portal the client browser's current path is to the portal not to the portlet. Because of this all HREFs must be expressed using fully qualified paths vs. the traditional relative paths. This method differs from PortletRendererUtil.absoluteLink() in that it uses the current renderer's servlet request path to generate the absolute link. When the renderer is a JSP or servlet this is the "forwarded" path vs. the originating portlet request path. I.e. a path relative to the JSP or servlet path rather then then original request path.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Parameters:

request - the servlet request

relativePath - the path you want to make absolute

htmlFormActionLink

public static java.lang.String htmlFormActionLink(javax.servlet.http.HttpServletRequest request,
                                                  int linkType)
                                           throws java.lang.IllegalArgumentException

Transforms one of the various URIs known to the request into the appropriate form to be used in a FORM action tag.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Parameters:

request - the serlvet request object

linkType - the link in this request that should be transformed. Constants representing these types are defined in PortletRendererUtil.

Throws:

java.lang.IllegalArgumentException

htmlFormHiddenFields

public static java.lang.String htmlFormHiddenFields(javax.servlet.http.HttpServletRequest request,
                                                    int linkType)
                                             throws java.lang.IllegalArgumentException

Encodes the parameters in the query string of the passed URL as hidden form fields. When "linking" back to the portlet via a form, the URI parameters must be added as hidden fields. These parameters are found in the querystring of your URI. This utility method generates the hidden field tags from this URL and returns them as a String.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Parameters:

request - the servlet request.

linkType - the link to use. Constants representing these types are defined in PortletRendererUtil.

Throws:

java.lang.IllegalArgumentException

portletParameter

public static java.lang.String portletParameter(javax.servlet.http.HttpServletRequest request,
                                                java.lang.String param)

Utility that turns a query string parameter name into fully qualified (unique) name. Portlets on the same page share request parameters. To ensure each Portlet can locate its specific parameters, query string parameter names must be fully qualified. A fully qualified parameter name is one that contains the portlet reference in the parameter name. For example if a portlet used the query string parameter "symbol", the fully qualified form of this parameter name would be "providerID.portletID.portletInstanceName.symbol". This utility constructs such references from the PortletReference and starting parameter name.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Parameters:

request - the current servlet request.

param - the name of the parameter to be qualified.

getEditData

public static java.lang.Object getEditData(javax.servlet.http.HttpServletRequest request)
                                    throws PortletNotFoundException,
                                           java.io.IOException,
                                           AccessControlException

Retrieves this requests customization data object. By convention, the Portal expects portlets to implement a tiered search order for a given customization. This utility implements this convention. This allows developers to retrieve a requests customization object in a single call.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Throws:

PortletNotFoundException

java.io.IOException

AccessControlException

submitEditData

public static void submitEditData(javax.servlet.http.HttpServletRequest request,
                                  java.lang.Object o)
                           throws java.io.IOException,
                                  AccessControlException

Updates this requests customization data object creating the customization instance if necessary.

Note: this is a convenience routine for renderers implemented as servlets or JSPs in that it merely extracts the PortletRenderRequest from the servlet request and then calls the (real) utility method.

Throws:

java.io.IOException

AccessControlException

handleEditAction

public static void handleEditAction(PortletRenderRequest pr,
                                    java.lang.String action)
                             throws java.io.IOException

Utility for generating redirects after processing edit/edit default forms

Parameters:

pr - the request

action - the action submitted with the edit form (OK/APPLY)

Throws:

java.io.IOException

setCacheExpires

public static void setCacheExpires(javax.servlet.http.HttpServletResponse response,
                                   int level,
                                   int minutes)
                            throws java.lang.IllegalArgumentException

Sets the expiration duration of the current response. Oracle Portal supports expires-based caching. I.e. a portlet can add a header field to its response that informs the Portal to reuse this response for a specified duration (in minutes). Once the time expires, the Portal will recontact the portlet to generate a new response. This method writes the set of header values that the Portal uses to identify and implement expiration based caching.

Note: this is a convenience routine for renderers implemented as servlets or JSPs.

Parameters:

response - the servlet response.

level - identifies whether this is a user specific response or a system (default) response. Constants representing these levels are available in HttpCommonConstants.

minutes - the number of minutes this response can be reused before it expires. The minimum is 0 and the maximum is 525600 (1 year).

Throws:

java.lang.IllegalArgumentException

setCacheExpires

public static void setCacheExpires(PortletRenderRequest request,
                                   int level,
                                   int minutes)
                            throws java.lang.IllegalArgumentException

Sets the expiration duration of the current response. Oracle Portal supports expires-based caching. I.e. a portlet can add a header field to its response that informs the Portal to reuse this response for a specified duration (in minutes). Once the time expires, the Portal will recontact the portlet to generate a new response. This method writes the set of header values that the Portal uses to identify and implement expiration based caching.

Parameters:

request - the current portlet request

level - identifies whether this is a user specific response or a system (default) response. Constants representing these levels are available in HttpCommonConstants.

minutes - the number of minutes this response can be reused before it expires. The minimum is 0 and the maximum is 525600 (1 year).

Throws:

java.lang.IllegalArgumentException

useInvalidationCaching

public static void useInvalidationCaching(PortletRenderRequest request)

Set the response header to cache content in Web Cache. This uses the max expiry time specified in the request's render context for this portlet.

Parameters:

request - the current portlet request

useInvalidationCaching

public static void useInvalidationCaching(PortletRenderRequest request,
                                          int minutes)

Set the response header to cache the content for a specified duration in Web Cache. This uses the max. expiry time in the render context which is set when the portal request is first processed in ProviderAdapter. The max expiry time is set to the minimum of the render context max expiry time and the expiry time passed to this funtion.

Parameters:

request - the current portlet request

minutes - The time for which the content should be cached in Web Cache before it expires.

addGeneratesESIHeader

public static void addGeneratesESIHeader(PortletRenderRequest request)

Adds response header that enables processing of ESI tags by Web Cache.

Adds the header: Surrogate-Control: content="ORAESI/9.0.2"

Parameters:

request - the current portlet request

setCachedVersion

public static void setCachedVersion(javax.servlet.http.HttpServletResponse response,
                                    java.lang.String version,
                                    int level)
                             throws java.lang.IllegalArgumentException

Sets the response (cached) version Id and level. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method registers (by setting response header fields) the portlet's cached version ID and user level for the response it has generated.

Parameters:

response - the serlvet response object

version - identifies the response version. Portlets should be able to use this in subsequent requests to determine if a new response should be generated.

level - whether this is a user or system level response. Constants for these levels are defined in HttpCommonConstants.

Throws:

java.lang.IllegalArgumentException

setCachedVersion

public static void setCachedVersion(PortletRenderRequest request,
                                    java.lang.String version,
                                    int level)
                             throws java.lang.IllegalArgumentException

Sets the response (cached) version Id and level. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method registers (by setting response header fields) the portlet's cached version ID and user level for the response it has generated.

Parameters:

request - the portlet render response object

version - identifies the response version. Portlets should be able to use this in subsequent requests to determine if a new response should be generated.

level - whether this is a user or system level response. Constants for these levels are defined in HttpCommonConstants.

Throws:

java.lang.IllegalArgumentException

useCachedVersion

public static void useCachedVersion(javax.servlet.http.HttpServletResponse response)

Indicates to the portal that the cached version should be used to respond to the client. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet determines that the cached version is still valid and should be used. The method writes the appropriate response header indicating the cached version is still valid.

Parameters:

response - the servlet response object.

useCachedVersion

public static void useCachedVersion(PortletRenderRequest request)

Indicates to the portal that the cached version should be used to respond to the client. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet determines that the cached version is still valid and should be used. The method writes the appropriate response header indicating the cached version is still valid.

Parameters:

request - the portlet render request object.

getCachedVersion

public static java.lang.String getCachedVersion(javax.servlet.http.HttpServletRequest request)

Gets the (cached) version Id passed by the portal for the current request. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet (using validation based caching) receives a request. It returns the version ID for the current cached version held by the portal. Portlets use this value in conjunction with getCachedLevel() to determine whether to generate a new response or indicate that the portal can reuse its cached version.

Parameters:

request - the servlet request object.

getCachedVersion

public static java.lang.String getCachedVersion(PortletRenderRequest request)

Gets the (cached) version Id passed by the portal for the current request. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet (using validation based caching) receives a request. It returns the version ID for the current cached version held by the portal. Portlets use this value in conjunction with getCachedLevel() to determine whether to generate a new response or indicate that the portal can reuse its cached version.

Parameters:

request - the portlet render request object.

getCachedLevel

public static int getCachedLevel(javax.servlet.http.HttpServletRequest request)
                          throws java.lang.IllegalStateException

Gets the (cached) level passed by the portal for the current request. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet (using validation based caching) receives a request. It returns the cache level for the current cached version held by the portal. Portlets use this value in conjunction with getCachedVersion() to determine whether to generate a new response or indicate that the portal can reuse its cached version.

Parameters:

request - the servlet request object.

Throws:

java.lang.IllegalStateException

getCachedLevel

public static int getCachedLevel(PortletRenderRequest request)
                          throws java.lang.IllegalStateException

Gets the (cached) level passed by the portal for the current request. Oracle Portal supports validation-based caching. I.e. a portlet can validate on a per request basis if the current cached version is still valid (and can be used instead of regenerating the response). The mechanism works by having the portlet set special header fields that indicate to the portal (cache) both a version ID and a level (whether this response is the public, default or a paticular user response). When the portlet is rerendered the portal calls the portlets render method. However the version id and user level are passed in the request (in header fields). The portlet is expected to check these values and determine whether the specified version is still valid. If it is then the portlet doesn't generate a new reponse. Rather it replies to the portal (via a header) that the portal should use its cached version. If a new version needs to be generated, the portlet does so, and adds the new version id to the response header.

This method is used when a portlet (using validation based caching) receives a request. It returns the cache level for the current cached version held by the portal. Portlets use this value in conjunction with getCachedVersion() to determine whether to generate a new response or indicate that the portal can reuse its cached version.

Parameters:

request - the portlet render request object.

Throws:

java.lang.IllegalStateException

sendRedirect

public static void sendRedirect(PortletRenderRequest pr,
                                java.lang.String url)
                         throws java.lang.IllegalStateException,
                                java.io.IOException

Throws:

java.lang.IllegalStateException

java.io.IOException