A portlet only delivers fragment output whereas a servlet typically
delivers document output. However, you can use the PortletServingServlet servlet,
which is similar to the FileServingServlet servlet, to address portlets like
servlets.
About this task
A default document servlet filter, the DefaultFilter filter, is
applied to the PortletServingServlet servlet to return the portlet‘s content
inside of a document. This filter only applies to requests, not to includes
or forwards using the RequestDispatcher method. A servlet filter that is used
to embed the portlet‘s content into a document is called the document servlet
filter. You can define additional document servlet filters in a .xml file.
The FilterRequestHelper attribute within com.ibm.wsspi.portletcontainer.util
is provided to assist the document servlet filters in analyzing a request
regarding filter chain and portlet information. It is used in supporting dynamic
portlet titles, as a marker for redirection for document servlet filters and
to ensure that document conversion is completed once.
Procedure
- Add a new document servlet filter. The filter capability
is a server feature, therefore all filters must be installed into the server
to use the filter capability of the server. The filters need to be available
in any classes or library directory on a server level. You must also register
the filter in a plugin.xml file within the root of a
Java archive (JAR) file. The following is an example of how to register the
filter in a plugin.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin id="sample.plugin" name="Customer_Plugin" provider-name="Customer" version="1.0.0">
<extension point="com.ibm.ws.portletcontainer.portlet-document-filter-config">
<portlet-document-filter class-name="sample.filter.CustomFilter" order="200" />
</extension>
</plugin>
- Optional: Set dynamic portlet titles by providing the
dynamic title as a request attribute. The PortletServingServlet
servlet supports dynamic portlet titles by providing the dynamic title as
a request attribute, FilterRequestHelper.DYNAMIC_TITLE. This attribute returns
the dynamic portlet title if it has been set by the portlet, otherwise it
returns the static portlet title of the portlet.xml file
if defined.
DYNAMIC_TITLE = ‘javax.portlet.title’
The DefaultFilter uses this request attribute to set the document
title while converting the fragment into a document. If you want the filter
to support browser caching or dynamic portlet titles, you must cache the complete
portlet content.
- Specify cache handling for the portlet rendering call to support
dynamic title. Redirection for document servlet filters
A document
servlet filter can set a marker as request attribute, FilterRequestHelper.REDIRECT.
This marker ensures that the portlet container returns to the document servlet
filter after the portlet action has been called prior to any render calls.
You must define the following constants, REDIRECT = ‘com.ibm.websphere.portlet.action' and REDIRECT_VALUE
= 'redirect'. The DefaultFilter uses this request attribute to
provide special cache handling for the portlet rendering call to support dynamic
title.
- Convert the portlet's fragment into a valid document. Document
conversion must be completed only once. Therefore each document servlet filter
must ensure that the fragment has not yet been converted to a document previously.
If the document servlet filter converts the fragment to a document, the request
attribute FilterRequestHelper.DOCUMENT must be set to FilterRequestHelper.DOCUMENT_VALUE.
This request attribute marks whether the conversion still needs to be completed.
The following constants are defined, DOCUMENT = ‘com.ibm.websphere.portlet.filter' and DOCUMENT_VALUE
= 'document'. The DefaultFilter uses this request attribute to
check whether it should convert the fragment to an Hypertext Markup Language
(HTML) document. For example, this allows another document servlet filter
in front to convert the fragment into a valid Wireless Markup Language (WML)
document instead.