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.