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
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. |
static String |
BRIDGE_PACKAGE_PREFIX
Base attribute/context parameter prefix.
|
static String |
BRIDGE_PUBLIC_RENDER_PARAMETER_HANDLER
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. |
static String |
DEFAULT_RENDERKIT_ID
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. |
static String |
DEFAULT_VIEWID_MAP
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. |
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
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. |
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
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. |
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.static final String BRIDGE_EVENT_HANDLER
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
static final String BRIDGE_PUBLIC_RENDER_PARAMETER_HANDLER
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"
static final String DEFAULT_RENDERKIT_ID
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).static final String DEFAULT_VIEWID_MAP
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.static final String EXCLUDED_REQUEST_ATTRIBUTES
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_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
javax.faces.webapp.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.static final String PRESERVE_ACTION_PARAMS
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."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 PortletContextattribute 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 © 2016 Liferay, Inc. All rights reserved.