javax.portlet.faces

Interface Bridge

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.

Author:

Michael Freedman, Neil Griffin

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Bridge.PortletPhase Enumeration whose values describe the current portlet phase the bridge is executing Faces within.

Field Summary

Fields

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.

Method Summary

Methods

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.

Field Detail

BACK_LINK

static final 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. This reference is encoded as the value of a query string parameter whose name is the value of this back link token parameter.

See Also:

Constant Field Values

BRIDGE_EVENT_HANDLER

static final 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. 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"

See Also:

Constant Field Values

BRIDGE_PACKAGE_PREFIX

static final String BRIDGE_PACKAGE_PREFIX

Base attribute/context parameter prefix.

See Also:

Constant Field Values

BRIDGE_PUBLIC_RENDER_PARAMETER_HANDLER

static final 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. 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"

See Also:

Constant Field Values

DEFAULT_RENDERKIT_ID

static final 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. 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).

See Also:

Constant Field Values

DEFAULT_VIEWID_MAP

static final 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. 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"

See Also:

Constant Field Values

DIRECT_LINK

static final 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. Rather, the call to encodeActionURL merely returns this URL unchanged.

See Also:

Constant Field Values

EXCLUDED_REQUEST_ATTRIBUTES

static final 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. 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"

See Also:

Constant Field Values

FACES_USE_CURRENT_VIEW_PARAMETER

static final 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. 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.

See Also:

Constant Field Values

FACES_VIEW_ID_PARAMETER

static final String FACES_VIEW_ID_PARAMETER

Name of a request parameter (generally) encoded in a link from a non-Faces view response. It acts as a marker to the portlet that the non-Faces view intends to navigate to the Faces view expressed in the value of this parameter. It differs from the 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.

See Also:

Constant Field Values

FACES_VIEW_PATH_PARAMETER

static final String FACES_VIEW_PATH_PARAMETER

Name of a request parameter (generally) encoded in a link from a non-Faces view response. It acts as a marker to the portlet that the non-Faces view intends to navigate to the Faces view expressed in the value of this parameter. It differs from the 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.

See Also:

Constant Field Values

IN_PROTOCOL_RESOURCE_LINK

static final 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.

See Also:

Constant Field Values

IS_POSTBACK_ATTRIBUTE

static final String IS_POSTBACK_ATTRIBUTE

Portlet request attribute set by the bridge when processing a Faces request that signals this request is a Faces postback. Its provided as an alternative signal to the common reliance on the view state parameter as an indicator that this is a postback request. Implementations needing this information and not using the view state parameter indicator can check this attribute when running in a portlet environment.

See Also:

Constant Field Values

LIFECYCLE_ID

static final String LIFECYCLE_ID

Context initialization parameter that defines the lifecycle ID used to identify the Faces Lifecycle used for this application. See also javax.faces.webapp.FacesServlet#LIFECYCLE_ID_ATTR.

See Also:

Constant Field Values

MAX_MANAGED_REQUEST_SCOPES

static final 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.

See Also:

Constant Field Values

NONFACES_TARGET_PATH_PARAMETER

static final 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. Though the bridge recognizes non-Faces targets when it encodes a navigational link, it does not handle the subsequent request. It only handles requests for Faces targets. It is the portlet's responsibility to detect and handle these requests. When the non-Faces target is a path based resource (such as a JSP or servlet), the 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.

See Also:

Constant Field Values

PORTLET_LIFECYCLE_PHASE

static final String PORTLET_LIFECYCLE_PHASE

Portlet request attribute set by the bridge prior to creating/acquiring a 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.

See Also:

Constant Field Values

PORTLET_MODE_PARAMETER

static final 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.

See Also:

Constant Field Values

PORTLET_NAMESPACED_RESPONSE_PROPERTY

static final 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.

See Also:

Constant Field Values

PORTLET_SECURE_PARAMETER

static final 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.

See Also:

Constant Field Values

PORTLET_WINDOWSTATE_PARAMETER

static final 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.

See Also:

Constant Field Values

PRESERVE_ACTION_PARAMS

static final 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. 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"

See Also:

Constant Field Values

SAVESTATE_FIELD_MARKER

static final String SAVESTATE_FIELD_MARKER

Context initialization parameter that defines the 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.

See Also:

Constant Field Values

VIEW_ID

static final String VIEW_ID

Portlet request attribute that a portlet may set prior to calling the bridge's 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.

See Also:

Constant Field Values

VIEW_LINK

static final 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. This token is intended for use in URLs signifying a view navigation using components such as h:outputLink.

See Also:

Constant Field Values

VIEW_PATH

static final String VIEW_PATH

Portlet request attribute that a portlet may set prior to calling the bridge's 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.

See Also:

Constant Field Values

VIEWID_HISTORY

static final String VIEWID_HISTORY

Portlet session attribute set by the bridge to hold the last viewId accessed in a given mode. The attribute (key) is composed of this name + the mode name. For example: javax.portlet.faces.viewIdHistory.view. There is one attribute per supported portlet mode. The attributes are always set even if the user session has never entered the mode. Its initial setting/value is determined by the default viewId configured for the mode. Attribute is used by developers to reference/return to the last view in a given mode from another mode.

See Also:

Constant Field Values

Method Detail

destroy

void destroy()

Called by the portlet to take the bridge out of service. Once out of service, the bridge must be reinitialized before processing any further requests.

doFacesRequest

void doFacesRequest(javax.portlet.ActionRequest actionRequest,
                  javax.portlet.ActionResponse actionResponse)
                    throws BridgeDefaultViewNotSpecifiedException,
                           BridgeUninitializedException,
                           BridgeException

Called by the portlet when it wants the bridge to invoke action request/response processing.

Parameters:

actionRequest - The current action request.

actionResponse - The current action response.

Throws:

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.

doFacesRequest

void doFacesRequest(javax.portlet.EventRequest eventRequest,
                  javax.portlet.EventResponse eventResponse)
                    throws BridgeUninitializedException,
                           BridgeException

Called by the portlet when it wants the bridge to invoke event request/response processing.

Parameters:

eventRequest - The current event request.

eventResponse - The current event response.

Throws:

BridgeUninitializedException - - if the bridge is not initialized.

BridgeException - - if an error occurs during event request/response processing.

doFacesRequest

void doFacesRequest(javax.portlet.RenderRequest renderRequest,
                  javax.portlet.RenderResponse renderResponse)
                    throws BridgeDefaultViewNotSpecifiedException,
                           BridgeUninitializedException,
                           BridgeException

Called by the portlet when it wants the bridge to invoke render request/response processing.

Parameters:

renderRequest - The current render request.

renderResponse - The current render response.

Throws:

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.

doFacesRequest

void doFacesRequest(javax.portlet.ResourceRequest resourceRequest,
                  javax.portlet.ResourceResponse resourceResponse)
                    throws BridgeUninitializedException,
                           BridgeException

Called by the portlet when it wants the bridge to invoke resource request/response processing.

Parameters:

resourceRequest - The current resource request.

resourceResponse - The current resource response.

Throws:

BridgeUninitializedException - - if the bridge is not initialized.

BridgeException - - if an error occurs during resource request/response processing.

init

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.
  For convenience this interface defines the 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.
  For convenience this interfaces defines a number of constants that simplifies constructing and/or recognizing this name.

Parameters:

portletConfig - PortletConfig object containing the portlet's configuration and initialization parameters

Throws:

BridgeException - - if an exception has occurred that interferes with the bridge's normal operation. For example, if the bridge is already initialized.