public interface Bridge
The Bridge
interface is used by a portlet to execute a JSF application. Its lifecycle follows the
pattern used by other web components such as portlets or servlets, namely:
init
: one time (per portlet) initialization. Usually invoked during portlet init
but
may also occur lazily. Context is passed to the Bridge at initialization via PortletContext
attributes. See method description for details.doFacesRequest
: called for each portlet request that is to be handled by Faces. Must only be
called after the bridge has been initialized.destroy
: called to destroy this bridge instance. Usually invoked during portlet
destroy
but may also occur earlier if the portlet decides to reclaim resources.Portlet developers are encouraged to allow deployers an ability to configure the particular Bridge implementation
it uses within a given deployment. This ensures a best fit solution for a given application server, portlet
container, and/or Faces environment. The specifics for this configuration are undefined. Each portlet can define a
preferred mechanism. Subclasses of GenericFacesPortlet
automatically inherit this behavior as it recognizes a
defined portlet initialization parameter.
Implementations of this Bridge
interface are required to have a zero-arg constructor.
Modifier and Type | Interface and Description |
---|---|
static class |
Bridge.PortletPhase
Enumeration whose values describe the current portlet phase the bridge is executing Faces within.
|
Modifier and Type | Field and Description |
---|---|
static String |
BACK_LINK
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeResourceURL(String) that it recognizes as an indication that an URL
referring back to the page which contains this portlet should be encoded in the resource URL. |
static String |
BRIDGE_EVENT_HANDLER
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter value
"javax.portlet.faces.bridgeEventHandler" instead.
Portlet context attribute that a portlet can set prior to calling "javax.portlet.faces." + portletContext.getPortletName() + ".bridgeEventHandler" |
static String |
BRIDGE_PACKAGE_PREFIX
Base attribute/context parameter prefix.
|
static String |
BRIDGE_PUBLIC_RENDER_PARAMETER_HANDLER
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter value
"javax.portlet.faces.bridgePublicRenderParameterHandler" instead.
Portlet context attribute that a portlet can set prior to calling the "javax.portlet.faces." + portletContext.getPortletName() + ".bridgeEventHandler" |
static String |
DEFAULT_RENDERKIT_ID
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter value
"javax.portlet.faces.defaultRenderKitId" instead.
Portlet context attribute that a portlet can set prior to calling the |
static String |
DEFAULT_VIEWID_MAP
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter
"javax.portlet.faces.defaultViewId.view", "javax.portlet.faces.defaultViewId.edit", or
"javax.portlet.faces.defaultViewId.help", etc.
Portlet context attribute that a portlet must set prior to calling "javax.portlet.faces." + portletContext.getPortletName() + ".defaultViewIdMap" |
static String |
DIRECT_LINK
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeActionURL(String) that it recognizes as an indication that this action
should be treated as a direct link and hence shouldn't be encoded as a Portlet action. |
static String |
EXCLUDED_REQUEST_ATTRIBUTES
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter value
"javax.portlet.faces.excludedRequestAttributes" instead.
Portlet context attribute that a portlet can set prior to calling "javax.portlet.faces." + portletContext.getPortletName() + ".excludedRequestAttributes" |
static String |
FACES_AJAX_PARAMETER
Request parameter that can be set on a
ResourceURL . |
static String |
FACES_PARTIAL_PARAMETER
Request parameter that can be set on a
ResourceURL . |
static String |
FACES_USE_CURRENT_VIEW_PARAMETER
Special value recognized when encoding an action URL: It is a URL that contains either the
FACES_VIEW_ID_PARAMETER or FACES_VIEW_PATH_PARAMETER . |
static String |
FACES_VIEW_ID_PARAMETER
Name of a request parameter (generally) encoded in a link from a non-Faces view response.
|
static String |
FACES_VIEW_PATH_PARAMETER
Name of a request parameter (generally) encoded in a link from a non-Faces view response.
|
static String |
IN_PROTOCOL_RESOURCE_LINK
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeResourceURL(String) that it recognizes as an indication that this
resource should be handled in-protocol. |
static String |
IS_POSTBACK_ATTRIBUTE
Portlet request attribute set by the bridge when processing a Faces request that signals this request is a Faces
postback.
|
static String |
LIFECYCLE_ID
Context initialization parameter that defines the lifecycle ID used to identify the Faces Lifecycle used for this
application.
|
static String |
MAX_MANAGED_REQUEST_SCOPES
Context initialization parameter that specifies the maximum number of bridge request scopes to be preserved
across all uses within this application.
|
static String |
NONFACES_TARGET_PATH_PARAMETER
Name of the render parameter set by the bridge when it encodes a navigation link to a non-Faces target.
|
static String |
PORTLET_LIFECYCLE_PHASE
Portlet request attribute set by the bridge prior to creating/acquiring a
FacesContext . |
static String |
PORTLET_MODE_PARAMETER
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeActionURL(String) that it recognizes as an indication that this action
should encode a portlet mode change to the one indicated by the parameter's value. |
static String |
PORTLET_NAMESPACED_RESPONSE_PROPERTY
Name of the portlet response property set by the bridge when it recognizes that the view has been rendered using
a
NamingContainer that ensures all generated ids are namespaced using the consumer
provided unique portlet id. |
static String |
PORTLET_SECURE_PARAMETER
Special token parameter in the URL passed to bridge's implementation of
ExternalContext.encodeActionURL(String) that it recognizes as an indication that this action
should encode a security level change to the one indicated by the parameter's value. |
static String |
PORTLET_WINDOWSTATE_PARAMETER
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeActionURL(String) that it recognizes as an indication that this action
should encode a window state change to the one indicated by the parameter's value. |
static String |
PRESERVE_ACTION_PARAMS
Deprecated.
Call
ExternalContext.getInitParameter(String) with parameter value
"javax.portlet.faces.preserveActionParams" instead.
Portlet context attribute that a portlet can set prior to calling "javax.portlet.faces." + portletContext.getPortletName() + ".preserveActionParams" |
static String |
SAVESTATE_FIELD_MARKER
Context initialization parameter that defines the
SAVESTATE_FIELD_MARKER in use in the given
deployment. |
static String |
VIEW_ID
Portlet request attribute that a portlet may set prior to calling the bridge's
doFacesRequest(RenderRequest, RenderResponse) method. |
static String |
VIEW_LINK
Special token parameter in the URL passed to the bridge's implementation of
ExternalContext.encodeResourceURL(String) that it recognizes as an indication that this URL
refers to Faces view (navigation) and hence should be encoded as a portlet ActionURL rather then a portlet
ResourceURL. |
static String |
VIEW_PATH
Portlet request attribute that a portlet may set prior to calling the bridge's
doFacesRequest(RenderRequest, RenderResponse) method. |
static String |
VIEWID_HISTORY
Portlet session attribute set by the bridge to hold the last viewId accessed in a given mode.
|
Modifier and Type | Method and Description |
---|---|
void |
destroy()
Called by the portlet to take the bridge out of service.
|
void |
doFacesRequest(javax.portlet.ActionRequest actionRequest,
javax.portlet.ActionResponse actionResponse)
Called by the portlet when it wants the bridge to invoke action request/response processing.
|
void |
doFacesRequest(javax.portlet.EventRequest eventRequest,
javax.portlet.EventResponse eventResponse)
Called by the portlet when it wants the bridge to invoke event request/response processing.
|
void |
doFacesRequest(javax.portlet.RenderRequest renderRequest,
javax.portlet.RenderResponse renderResponse)
Called by the portlet when it wants the bridge to invoke render request/response processing.
|
void |
doFacesRequest(javax.portlet.ResourceRequest resourceRequest,
javax.portlet.ResourceResponse resourceResponse)
Called by the portlet when it wants the bridge to invoke resource request/response processing.
|
void |
init(javax.portlet.PortletConfig portletConfig)
Called by the portlet.
|
static final String BACK_LINK
ExternalContext.encodeResourceURL(String)
that it recognizes as an indication that an URL
referring back to the page which contains this portlet should be encoded in the resource URL. This reference is
encoded as the value of a query string parameter whose name is the value of this back link token parameter.@Deprecated static final String BRIDGE_EVENT_HANDLER
ExternalContext.getInitParameter(String)
with parameter value
"javax.portlet.faces.bridgeEventHandler" instead.
Portlet context attribute that a portlet can set prior to calling init(PortletConfig)
to configure the bridge to use/call the associated BridgeEventHandler
when processing an event. Value is an instance of
BridgeEventHandler
. As this attribute is scoped to a specific portlet in an application-wide
context the attribute name must be include the portlet name as follows:
"javax.portlet.faces." + portletContext.getPortletName() + ".bridgeEventHandler"
static final String BRIDGE_PACKAGE_PREFIX
@Deprecated static final String BRIDGE_PUBLIC_RENDER_PARAMETER_HANDLER
ExternalContext.getInitParameter(String)
with parameter value
"javax.portlet.faces.bridgePublicRenderParameterHandler" instead.
Portlet context attribute that a portlet can set prior to calling the init(PortletConfig)
method to configure the bridge to use/call the associated BridgePublicRenderParameterHandler
. This handler is used to process updates that result from public
render parameter changes passed in a request. The bridge first pushs all the public render parameter
values into the models and then calls this handler's processUpdates method. The handler can then
compute further model changes based on the changes. Value is an instance of
BridgePublicRenderParameterHandler
. As this attribute is scoped to a specific portlet in an
application-wide context the attribute name must be include the portlet name as follows:
"javax.portlet.faces." + portletContext.getPortletName() + ".bridgeEventHandler"
@Deprecated static final String DEFAULT_RENDERKIT_ID
ExternalContext.getInitParameter(String)
with parameter value
"javax.portlet.faces.defaultRenderKitId" instead.
Portlet context attribute that a portlet can set prior to calling the init(PortletConfig)
method to configure the bridge to default the renderKitId used for rendering
this portlet to the named Id. In Faces, the default renderKitId is set in the faces-config.xml and
is application wide. In 1.2 this can be overidden by a specially named request parameter. To allow
differing portlets in the same app to use different default render kits, without having to add this
parameter, the portlet can set this attribute prior to the bridge init(). The bridge will recognize
this configuration value and on each request add the special faces request parameter to the request
(if its not already present).
@Deprecated static final String DEFAULT_VIEWID_MAP
ExternalContext.getInitParameter(String)
with parameter
"javax.portlet.faces.defaultViewId.view", "javax.portlet.faces.defaultViewId.edit", or
"javax.portlet.faces.defaultViewId.help", etc.
Portlet context attribute that a portlet must set prior to calling init(PortletConfig)
to convey to the bridge the set of default viewIds that correspond to
this portlet's supported portlet modes. Its value is a Map
with one entry per
mode. The mode name is the key. The entry's value is the corresponding default viewId the bridge
should use for this mode. As this attribute is scoped to a specific portlet in an application-wide
context the attribute name must be include the portlet name as follows:
"javax.portlet.faces." + portletContext.getPortletName() + ".defaultViewIdMap"
static final String DIRECT_LINK
ExternalContext.encodeActionURL(String)
that it recognizes as an indication that this action
should be treated as a direct link and hence shouldn't be encoded as a Portlet action. Rather, the call to
encodeActionURL
merely returns this URL unchanged.@Deprecated static final String EXCLUDED_REQUEST_ATTRIBUTES
ExternalContext.getInitParameter(String)
with parameter value
"javax.portlet.faces.excludedRequestAttributes" instead.
Portlet context attribute that a portlet can set prior to calling init(PortletConfig)
to configure the bridge to exclude specific attributes from its bridge
request scope. Value is a comma delimited list containing either a fully qualified attribute name or
package name terminated with a ".*" wildcard indicator. In this later case, all attributes in the
package name which precedes the ".*" are excluded, non recursive. As this attribute is scoped to a
specific portlet in an application-wide context the attribute name must be include the portlet name
as follows:
"javax.portlet.faces." + portletContext.getPortletName() + ".excludedRequestAttributes"
static final String FACES_AJAX_PARAMETER
ResourceURL
. When set to a value of "true", the
bridge will invoke the JSF lifecycle in the PortletRequest.RESOURCE_PHASE
of the portlet
lifecycle. In addition, it will cause ExternalContext.getRequestHeaderMap()
to
contain a "partial/ajax" header so that PartialViewContext.isAjaxRequest()
will
return true
.static final String FACES_PARTIAL_PARAMETER
ResourceURL
. When set to a value of "true", the
bridge will cause ExternalContext.getRequestHeaderMap()
to contain a
"partial/process" header so that PartialViewContext.isPartialRequest()
will return
true
.static final String FACES_USE_CURRENT_VIEW_PARAMETER
FACES_VIEW_ID_PARAMETER
or FACES_VIEW_PATH_PARAMETER
. The bridge's implementation of ExternalContext.encodeActionURL(String)
recognizes this value as indicating it needs to
generate and encode an URL to the current JSF including its current state. For example: It not only encodes the
link reference but also the existing render parameters so they can be carried forward to reestablish the state.static final String FACES_VIEW_ID_PARAMETER
FACES_VIEW_PATH_PARAMETER
in that its value is the actual Faces viewId of
the target while the former is a ContextPath
relative path containing the viewId. Portlets receiving
such a parameter should set the the corresponding request attribute VIEW_ID
before calling the bridge to
handle the request.static final String FACES_VIEW_PATH_PARAMETER
FACES_VIEW_ID_PARAMETER
in that its value is a ContextPath
relative path containing the viewId while the former is the viewId itself. Portlets receiving such a parameter
should set the the corresponding request attribute javax.portlet.faces.viewPath
before calling the
bridge to handle the request.static final String IN_PROTOCOL_RESOURCE_LINK
ExternalContext.encodeResourceURL(String)
that it recognizes as an indication that this
resource should be handled in-protocol.static final String IS_POSTBACK_ATTRIBUTE
static final String LIFECYCLE_ID
FacesServlet.LIFECYCLE_ID_ATTR
.static final String MAX_MANAGED_REQUEST_SCOPES
static final String NONFACES_TARGET_PATH_PARAMETER
ContextPath
relative path of the resource is written as the value of this render parameter. For
convenience, the GenericFacesPortlet
recognizes this render parameter in received requests and uses
the PortletRequestDispatcher
to dispatch to the encoded path instead of calling the bridge
to execute the request.static final String PORTLET_LIFECYCLE_PHASE
FacesContext
. Its value indicates which portlet phase this Faces is executing in. It can be
used by Faces subsystems not only to determine the portlet execution phase but if present (not null) as an
indication the request is being processed in a portlet container.static final String PORTLET_MODE_PARAMETER
ExternalContext.encodeActionURL(String)
that it recognizes as an indication that this action
should encode a portlet mode change to the one indicated by the parameter's value.static final String PORTLET_NAMESPACED_RESPONSE_PROPERTY
NamingContainer
that ensures all generated ids are namespaced using the consumer
provided unique portlet id.static final String PORTLET_SECURE_PARAMETER
ExternalContext.encodeActionURL(String)
that it recognizes as an indication that this action
should encode a security level change to the one indicated by the parameter's value.static final String PORTLET_WINDOWSTATE_PARAMETER
ExternalContext.encodeActionURL(String)
that it recognizes as an indication that this action
should encode a window state change to the one indicated by the parameter's value.@Deprecated static final String PRESERVE_ACTION_PARAMS
ExternalContext.getInitParameter(String)
with parameter value
"javax.portlet.faces.preserveActionParams" instead.
Portlet context attribute that a portlet can set prior to calling init(PortletConfig)
to configure the bridge to preserve action parameters received by this
portlet along with bridge's request scope so that they may be restored and acessed in subsequent
renders. If true
, the action parameters are preserved. If false
, they are
not preserved. The bridge default is false
.
As this attribute is scoped to a specific portlet in an application-wide context the attribute name
must be include the portlet name as follows:
"javax.portlet.faces." + portletContext.getPortletName() + ".preserveActionParams"
static final String SAVESTATE_FIELD_MARKER
SAVESTATE_FIELD_MARKER
in use in the given
deployment. If not set, consult your bridge implementation documentation to determine which Faces implementations
it automatically detects and supports. For example the bridge RI will detect and run properly in either the Faces
RI or MyFaces environments without this being set.static final String VIEW_ID
doFacesRequest(RenderRequest, RenderResponse)
method. The value of this attribute is a String
representing the Faces viewId the bridge is to target for this request. Used by a portlet to specifically control
a request's view target in situations such as navigating from a non-Faces view to a specific Faces view (other
than the default). Generally, the use of this attribute is mutually exclusive with the use of VIEW_PATH
.
If both have been set in a given request, the bridge gives precedence to VIEW_ID
.static final String VIEW_LINK
ExternalContext.encodeResourceURL(String)
that it recognizes as an indication that this URL
refers to Faces view (navigation) and hence should be encoded as a portlet ActionURL rather then a portlet
ResourceURL. This token is intended for use in URLs signifying a view navigation using components such as
h:outputLink
.static final String VIEW_PATH
doFacesRequest(RenderRequest, RenderResponse)
method. The value of this attribute is a String
containing a ContextPath
relative path in which the Faces viewId is encoded. Like VIEW_ID
,
this attribute provides a means for a portlet to explicitly control the Faces target for a specific request. It
is used in situations such as navigating from a non-Faces view to a specific Faces view (other than the default).
Generally, the use of this attribute is mutually exclusive with the use of VIEW_PATH
. If both have
been set in a given request, the bridge gives precedence to VIEW_ID
.static final String VIEWID_HISTORY
void destroy()
void doFacesRequest(javax.portlet.ActionRequest actionRequest, javax.portlet.ActionResponse actionResponse) throws BridgeDefaultViewNotSpecifiedException, BridgeUninitializedException, BridgeException
actionRequest
- The current action request.actionResponse
- The current action response.BridgeDefaultViewNotSpecifiedException
- thrown if the request indicates to the Bridge that is should use
the default viewId and the portlet hasn't supplied one.BridgeUninitializedException
- thrown if the bridge is not initialized.BridgeException
- - if an error occurs during action request/response processing.void doFacesRequest(javax.portlet.EventRequest eventRequest, javax.portlet.EventResponse eventResponse) throws BridgeUninitializedException, BridgeException
eventRequest
- The current event request.eventResponse
- The current event response.BridgeUninitializedException
- - if the bridge is not initialized.BridgeException
- - if an error occurs during event request/response processing.void doFacesRequest(javax.portlet.RenderRequest renderRequest, javax.portlet.RenderResponse renderResponse) throws BridgeDefaultViewNotSpecifiedException, BridgeUninitializedException, BridgeException
renderRequest
- The current render request.renderResponse
- The current render response.BridgeDefaultViewNotSpecifiedException
- - if the request indicates to the Bridge that is should use the
default viewId and the portlet hasn't supplied one.BridgeUninitializedException
- - if the bridge is not initialized.BridgeException
- - if an error occurs during render request/response processing.void doFacesRequest(javax.portlet.ResourceRequest resourceRequest, javax.portlet.ResourceResponse resourceResponse) throws BridgeUninitializedException, BridgeException
resourceRequest
- The current resource request.resourceResponse
- The current resource response.BridgeUninitializedException
- - if the bridge is not initialized.BridgeException
- - if an error occurs during resource request/response processing.void init(javax.portlet.PortletConfig portletConfig) throws BridgeException
Called by the portlet. It indicates that the bridge is being placed into service.
The portlet calls the init
method exactly once before invoking other lifecycle methods. Usually,
done immediately after instantiating the bridge. The init
method must complete successfully before
the bridge can receive any requests.
The portlet cannot place the bridge into service if the init
method throws a
BridgeException
.
Initialization context is passed to bridge via PortletContext
attributes. The following
attributes are defined:
javax.portlet.faces.encodeRedirectURL
: instructs the bridge to call
ExternalContext.encodeActionURL()
before processing the redirect request. This exists because some
(newer) versions of JSF 1.2 call encodeActionURL
before calling redirect
while
others do not. This flag adjusts the behavior of the bridge in accordance with the JSF 1.2 implementation it
runs with.javax.portlet.faces.MAX_MANAGED_REQUEST_SCOPES
: defines the maximum number of bridge request
scopes this bridge preserves at any given time. Value is an integer. Bridge request scopes are managed on a
per Bridge class portlet context wide basis. As a typical portlet application uses the same bridge
implementation for all its Faces based portlets, this means that all bridge request scopes are managed in a
single bucket.MAX_MANAGED_REQUEST_SCOPES
constant.javax.faces.lifecycleID
: defines the Faces Lifecycle
id that bridge uses when
acquiring the Faces.Lifecycle
via which it executes the request. As a context wide attribute,
all bridge instances in this portlet application will use this lifecycle.javax.portlet.faces.[portlet name].preserveActionParams
: instructs the bridge to preserve
action parameters in the action scope and represent them in subsequent renders. Should be used only when
binding to a Faces implementation that relies on accessing such parameters during its render phase. As this
is a portlet/bridge instance specific attribute, the PortletContext
attribute name is qualified
by the portlet instance name. This allows different portlets within the same portlet application to have
different settings.portletConfig
- PortletConfig
object containing the portlet's configuration and
initialization parametersBridgeException
- - if an exception has occurred that interferes with the bridge's normal operation. For
example, if the bridge is already initialized.Copyright © 2018 Liferay, Inc. All rights reserved.