The
portlet bridge isn't a portlet. It is a distinct subsystem a
portlet acquires, instantiates, and executes when it needs to handle
requests that target Faces artifacts. Though the bridge
has a simple API and relies
on familiar lifecycles and mechanisms, many portlets
will find it more convenient to subclass an object that
manages the details of the bridge's execution than to manage the bridge
directly. The GenericFacesPortlet is provided for this
purpose. Though a client of the bridge, GenrericFacesPortlet
is included as part of the specification to provide an out-of-the-box
solution for portlet developers as well as to provide
portlet developers a better appreciation of how and how much
work is involved in using the bridge.
4.1 Configuration
To provide flexibility, the GenericFacesPortlet recognizes the
following application initialization parameters:
javax.portlet.faces.BridgeClassName
BridgeClassName specifies the name of the
bridge class the GenericFacesPortlet uses to instantiate bridge
instances for all portlets in this web application. If not
specified, the GenericFacesPortlet defaults to finding the class
name by looking for the context resource (file) called "META-INF/services/javax.portlet.faces.Bridge" and reading the first line
(excluding preceding and succeeding white space).
Because bridge
implementations are expected to include such a context resource file in
their jar file, portlet applications
relying on the GenericFacesPortlet
typically do not set this initialization parameter. It is
provided for those environments where multiple such resource
files
exist (because there are multiple bridge implementations in
the
environment) and resource resolution doesn't yield the desired class
name.
In addition the GenericFacesPortlet
reads the following
portlet initialization parameters and either sets the appropriate
context attributes[4.1] to direct the
bridge's execution or uses it to impact its own
behavior:
javax.portlet.faces.defaultViewId.[mode]
javax.portlet.faces.excludedRequestAttributes
javax.portlet.faces.preserveActionParams
javax.portlet.faces.defaultContentType
javax.portlet.faces.defaultCharacterSetEncoding
javax.portlet.faces.bridgeEventHandler
javax.portlet.faces.bridgePublicRenderParameterHandler
javax.portlet.faces.autoDispatchEvents
javax.portlet.faces.defaultRenderKitId
javax.portlet.faces.bridgeWriteBehindResponseClassName
javax.portlet.faces.defaultViewId.[mode] specifies the name of the defaultViewId used for a named portlet PortletMode. Note: mode
is the String
form of portlet PortletMode.
javax.portlet.faces.excludedRequestAttributes
is a comma delimited list of attribute names the bridge is to exclude
from managing in the bridge request scope. The values in
this
list will either identify a specific attribute name to exclude
or a set of attributes. The later is identified by a
String
value with the wildcarded suffix ".*". Such wildcard usage
indicates the bridge is to exclude all those attributes within the
namespace identified by removing the "*", non-recursive.
javax.portlet.faces.preserveActionParams
is a boolean
valued String
that when true
indicates the bridge must maintain the
action's request parameters for the duration of the bridge request
scope
[5.1.2].
When this initialization parameter isn't present
or is
false
the action's request parameters are only maintained for the
duration of the portlet request scope. The exception to this
is the ResponseStateManager.VIEW_STATE_PARAM
parameter which is
always maintained in the bridge request scope
regardless of this setting.
javax.portlet.faces.defaultContentType
is a String
representing the default
response MIME
type the GenericFacesPortlet
sets before calling the bridge to render. This was needed for
the portlet 1.0 bridge because the jsp dispatch the bridge used to
render the Faces view could only use include() which required the
response content type to be set before the dispatch. Because
the portlet 2.0 bridge uses dispatch.forward() such presetting is no
longer necessary as the content type rendered by the jsp page now takes
precedent. a
portlet must set the response content type prior to dispatching as
setting a content type in a dispatch is ignored. When the
Faces
view is represented in a jsp, the bridge uses dispatch to render the
view. This portlet initialization parameter allows one to
configure the desired (default) content type that should be used when
normally the jsp is used/expected to set the response the content type.
javax.portlet.faces.defaultCharacterSetEncoding
is a String
representing the default
character set encoding being rendered. The
GenericFacesPortlet
uses
this value in conjunction with the content type to properly setup the
response prior to calling the bridge to render. In
Portlet 1.0 the portlet container is responsible for setting the
character set encoding of the actual response. However
because
existing web pages adapted into portlet applications (jsps) commonly
expect to set this, many portlet containers recognize the character
encoding setting included in a content type and uses it to translate
between the incoming encoding and the one it requires in its response.
javax.portlet.faces.bridgeEventHandler
is a String
naming the class that implements the javax.portlet.faces.BridgeEventHandler
interface that the bridge uses to process events. See section
[5.2.5]
for detail concerning event support.
javax.portlet.faces.bridgeRenderParameterHandler
is a String
naming the class that implements the javax.portlet.faces.BridgePublicRenderParameterHandler
interface that the bridge calls after pushing mapped public render
parameters into beans. This handler gives the portlet an
opportunity to recompute and get into a new consistent state after such
changes. See section [5.3]
for detail concerning public render parameter support.
javax.portlet.faces.autoDisptachEvents
is a boolean valued
String
defining whether
the bridge overrides regular
portlet
event processing dispatching all events to the bridge. If true the GenericFacesPortlet
overrides processEvent()
and dispatches all events to the bridge. If false the GenericFacesPortlet
delegates all event processing to the standard portlet model.
Use true if
the portlet is written entirely in JSF. Use false,
if your portlet uses a mixture of view technologies. In the
later
case, the portlet is responsible for recognizing the events which
should be handled in JSF and dispatch them directly to the bridge.
The default value is true.
See section [5.2.5]
for detail concerning handling events.
javax.portlet.faces.defaultRenderKitId
is a String
defining this portlet's default renderkit Id. Providing a
value will cause the GenericFacesPortlet
to configure the bridge to use this specific default renderkit Id for
the portlet rather than application level default (set in the faces-config.xml).
There are two portlet initialization parameters that were recognized by
the portlet 1.0 bridge that are no longer recognized and used in the
portlet 2.0 bridge:
javax.portlet.faces.defaultContentType
javax.portlet.faces.defaultCharacterSetEncoding
These parameters
were used by the GenericFacesPortlet to preset the response content
type before delegating to the bridge to handle the request.
Because the portlet 2.0 bridge now uses dispatch.forward() to
render Faces views that are jsps, this presetting is no longer needed.
The requirement to recognize these init parameters no longer
exists and their presence is ignored.
javax.portlet.faces.bridgeWriteBehindResponseClassName
is a String
naming the class that
implements the javax.portlet.faces.BridgeWriteBehindResponse
interface. Portlets provide an implementing class when they
are
using Faces views represented in JSP pages that itself outputs markup
before/after the embedded view definition and want the support for the
JSP after view write behavior to be implemented by a PortletResponseWrapper
instead of the bridge 1.0 style of support that relies on a servlet
filter/response wrapper. The implementing class must not only
implement the referenced behavior but must also be an instance of PortletResponseWrapper.
4.2 Structure
The GenericFacesPortlet
subclasses javax.portlet.GenericPortlet.
It overrides the init,
destroy,
doDispatch,
doEdit,
doHelp,
doView,
and processAction
methods. In addition it defines the following new methods:
getBridgeClassName
getDefaultViewIdMap
getExcludedRequestAttributes
isPreserveActionParameters
getResponseContentType
getResponseCharacterSetEncoding
getBridgeEventHandler
getBridgePublicRenderParameterHandler
isAutoDispatchEvents
getFacesBridge
getWriteBehindResponse
getBridgeClassName() allows a subclass to override
the GenericFacesPortlet mechanism for determining
which
bridge class to instantiate [4.2.6].
getDefaultViewIdMap() allows a subclass to override
the GenericFacesPortlet mechanism for determining the Map of the default viewId that should be used in each PortletMode when the request doesn't
otherwise indicate a specific view [4.2.7].
This Map contains one entry per PortletMode. The entry key is
the name of the PortletMode. The entry value is
the mode's default viewId.
getExcludedRequestAttributes() allows a subclass to
override the GenericFacesPortlet
mechanism for determining the set of request attributes to exclude from
the bridge request scope [4.2.8].
getPreserveActionParameters() allows a subclass to
override the GenericFacesPortlet
mechanism for determining whether the bridge needs to preserve action
parameters for subsequent renders [4.2.9].
getResponseContentType() is deprecated as it is no
longer called by the GenericFacesPortlet.
It exists merely for backwards compatibility in the off
chance that a subclass called it. allows
a subclass to
override the GenericFacesPortlet
mechanism for determining the content type that should be used for this
request/response [4.2.10].
It
is called
once per render request.
getResponseCharacterSetEncoding() is deprecated as it is no
longer called by the GenericFacesPortlet.
It exists merely for backwards compatibility in the off
chance that a subclass called. allows a subclass to
override the GenericFacesPortlet
mechanism for determining the character set encoding of the portlet's
response [4.2.11]. It
is called once per render
request.
getBridgeEventHandler() allows a subclass to override the GenericFacesPortlet mechanism for determining the BridgeEventHandler the bridge should use to process
events [4.2.12].
getBridgePublicRenderParameterHandler() allows a subclass to override the GenericFacesPortlet mechanism for determining the BridgePublicRenderParameterHandler the bridge should use to post process
incoming public render parameters [4.2.13].
isAutoDispatchEvents() allows a subclass to override the GenericFacesPortlet mechanism for determining the setting
for the autoDispatchEvents
boolean [4.2.14].
getFacesBridge() primarily used by a subclass to get
the GenericFacesPortlet's
bridge in situations where the subclass needs to directly call its doFacesRequest
method. [4.2.15].
getDefaultRenderKitId() allows a subclass to
override the GenericFacesPortlet mechanism for determining
the renderkit
Id (if
any) the bridge conveys to Faces for use as the default
renderkit Id when acquiring a RenderKit
and rendering
[4.2.16].
getWriteBehindResponse()
allows a subclass to
override the GenericFacesPortlet
mechanism for determine
the BridgeWriteBehindResponse
(if any) the bridge should
use when dispatching render requests via ExternalContext.dispatch()
[4.2.16].
4.2.1 init():
The
GenericFacesPortlet
overrides the
init
method and does the following
[4.2]: