javax.portlet.faces
Interface Bridge


public interface Bridge

The Bridge interface is used by a portlet to execute a JSF artifact. Its lifecycle follows the pattern used by other web components such as portlets or servlets, namely:

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 configuation 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 code constructor.


Nested Class Summary
static class Bridge.BridgeRenderPolicy
          Enumeration whose values describe the render policy used by the bridge to render portlets in this application.
static class Bridge.PortletPhase
          Enumeration whose values describe the current portlet phase the bridge is executing Faces within.
 
Field Summary
static String AFTER_VIEW_CONTENT
          A PortletRequest attribute set by an include filter in recognition of the RenderContentAfterView bridge attribute.
static String BACK_LINK
          Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() that it recognizes as an indication that an URL refering back to the page which contains this portlet should be encoded in the resource url.
static String BRIDGE_PACKAGE_PREFIX
           
static String DEFAULT_VIEWID
          PortletRequest attribute set by the portlet prior to calling the bridge's doFacesRequest() method.
static String DIRECT_LINK
          Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 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
          A PortletContext attribute that a portlet can set prior to calling the bridge's init() method to configure the bridge to exclude specific attributes from its bridge request scope.
static String IS_POSTBACK_ATTRIBUTE
          Bridge attribute 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 preserved across all uses within this application.
static String PORTLET_LIFECYCLE_PHASE
          PortletRequest 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 ExternalContext.encodeActionURL() that it recognizes as an indication that this action should encode a PortletMode change to the one indicated by the parameter's value.
static String PORTLET_NAMESPACED_RESPONSE_PROPERTY
          Name of PortletResponse 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 the bridge's ExternalContext.encodeActionURL() 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 ExternalContext.encodeActionURL() that it recognizes as an indication that this action should encode a WindowState change to the one indicated by the parameter's value.
static String PRESERVE_ACTION_PARAMS
          A PortletContext attribute that a portlet can set prior to calling the bridge's init() method 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 RENDER_CONTENT_AFTER_VIEW
          A PortletRequest attribute set by the bridge in its ViewHandler.renderView prior to dispatching the request to the view (jsp)to indicating a filter should put the AFTER_VIEW_CONTENT in a buffer on the request for it to process after rendering the view components.
static String RENDER_POLICY
          Context initialization parameter that defines the policy the bridge uses for rendering.
static String VIEW_LINK
          Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() that it recognizes as an indication that this url refers to Faces view (navigation) and hence should be encoded as an portlet ActionURL rather then a portlet resource url.
 
Method Summary
 void destroy()
          Called by the portlet to take the bridge out of service.
 void doFacesRequest(ActionRequest request, ActionResponse response)
          Called by the portlet when it wants the bridge to process an action request.
 void doFacesRequest(RenderRequest request, RenderResponse response)
          Called by the portlet when it wants the bridge to process a render request.
 void init(PortletConfig config)
          Called by the portlet.
 

Field Detail

BRIDGE_PACKAGE_PREFIX

static final String BRIDGE_PACKAGE_PREFIX
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 preserved across all uses within this application.

See Also:
Constant Field Values

RENDER_POLICY

static final String RENDER_POLICY
Context initialization parameter that defines the policy the bridge uses for rendering. Parameter value is the string representaiton of one of the BridgeRenderPolicy enum values.

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:
Constant Field Values

IS_POSTBACK_ATTRIBUTE

static final String IS_POSTBACK_ATTRIBUTE
Bridge attribute 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

PORTLET_MODE_PARAMETER

static final String PORTLET_MODE_PARAMETER
Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() that it recognizes as an indication that this action should encode a PortletMode 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 ExternalContext.encodeActionURL() that it recognizes as an indication that this action should encode a WindowState change to the one indicated by the parameter's value.

See Also:
Constant Field Values

PORTLET_SECURE_PARAMETER

static final String PORTLET_SECURE_PARAMETER
Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 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

DIRECT_LINK

static final String DIRECT_LINK
Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 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 encodeActionURL merely returns this url unchanged.

See Also:
Constant Field Values

BACK_LINK

static final String BACK_LINK
Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() that it recognizes as an indication that an URL refering 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

VIEW_LINK

static final String VIEW_LINK
Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() that it recognizes as an indication that this url refers to Faces view (navigation) and hence should be encoded as an portlet ActionURL rather then a portlet resource url. This token is intended for use in urls signifying a view navigation using components such as h:outputLink.

See Also:
Constant Field Values

PRESERVE_ACTION_PARAMS

static final String PRESERVE_ACTION_PARAMS
A PortletContext attribute that a portlet can set prior to calling the bridge's init() method 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: BRIDGE_PACKAGE_PREFIX + context.getPortletName() + preserveActionParams

See Also:
Constant Field Values

EXCLUDED_REQUEST_ATTRIBUTES

static final String EXCLUDED_REQUEST_ATTRIBUTES
A PortletContext attribute that a portlet can set prior to calling the bridge's init() method 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: BRIDGE_PACKAGE_PREFIX + context.getPortletName() + excludedRequestAttributes

See Also:
Constant Field Values

RENDER_CONTENT_AFTER_VIEW

static final String RENDER_CONTENT_AFTER_VIEW
A PortletRequest attribute set by the bridge in its ViewHandler.renderView prior to dispatching the request to the view (jsp)to indicating a filter should put the AFTER_VIEW_CONTENT in a buffer on the request for it to process after rendering the view components. In conjunction with the filter this enables preserving rendering order of native JSP rendering and Faces rendering in a jsp.

See Also:
Constant Field Values

AFTER_VIEW_CONTENT

static final String AFTER_VIEW_CONTENT
A PortletRequest attribute set by an include filter in recognition of the RenderContentAfterView bridge attribute. Its value is either char[] or byte[] holding the AFTER_VIEW_CONTENT generated while rendering this jsp. In conjunction with the bridge this enables preserving rendering order of native JSP rendering and Faces rendering in a jsp.

See Also:
Constant Field Values

DEFAULT_VIEWID

static final String DEFAULT_VIEWID
PortletRequest attribute set by the portlet prior to calling the bridge's doFacesRequest() method. Its value is the default viewId the bridge is to use if it can't otherwise decode one from the request.

See Also:
Constant Field Values

PORTLET_LIFECYCLE_PHASE

static final String PORTLET_LIFECYCLE_PHASE
PortletRequest 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 exectution phase but if present (not null) as an indication the request is being processed in a portlet container.

See Also:
Constant Field Values

PORTLET_NAMESPACED_RESPONSE_PROPERTY

static final String PORTLET_NAMESPACED_RESPONSE_PROPERTY
Name of PortletResponse 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
Method Detail

init

void init(PortletConfig config)
          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:

Parameters:
config - a 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.
UnavailableException - if the portlet cannot perform the initialization at this time.

doFacesRequest

void doFacesRequest(ActionRequest request,
                    ActionResponse response)
                    throws BridgeDefaultViewNotSpecifiedException,
                           BridgeException
Called by the portlet when it wants the bridge to process an action request.

Parameters:
request - the request object.
response - the response object.
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 - all other internal exceptions are converted to a BridgeException.

doFacesRequest

void doFacesRequest(RenderRequest request,
                    RenderResponse response)
                    throws BridgeDefaultViewNotSpecifiedException,
                           BridgeException
Called by the portlet when it wants the bridge to process a render request.

Parameters:
request - the request object.
response - the response object.
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 - all other internal exceptions are converted to a BridgeException.

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.



Copyright © 2007-2008 The Apache Software Foundation. All Rights Reserved.