org.jboss.portletbridge.bridge.context

Class BridgeContext

java.lang.Object

org.jboss.portletbridge.bridge.context.BridgeContext

public abstract class BridgeContext
extends Object

The BridgeContext contains the runtime specific state the bridge makes public so its various independent pieces can work together to properly operate. Simplistically, the bridge is a controller and a set of Faces extensions that work together execute Faces requests in a portlet container. By encapsulating state that is shared between these pieces, an extensible, pluggable bridge is supported as bridge implementors can now extend a base implementation by extending or overriding any of the Faces extensions (and other hook points) required to add their specific behaviors.

A new BridgeContext is created in each bridge request doFacesRequest(). After the bridge controller has initialized the context the SystemEvent BridgeContextInitializedEvent is dispatched to any registered listeners for further transformation. Once the bridge has acquired the FacesContext, the BridgeContext is added to the FacesContext scope making it freely available from anywhere within Faces during that request.

Constructor Summary

Constructors

Constructor and Description
BridgeContext()

Method Summary

Methods

Modifier and Type	Method and Description
abstract String	appendClientWindowId(String url) Provide the ability to append the Client Window Id to urls that need to be encoded.
abstract Map<String,Object>	getAttributes() This Map is a place to put extra (implementation specific) bridge state or anything else whose lifetime matches this scope.
abstract BridgeConfig	getBridgeConfig()
abstract BridgeRequestScopeManager	getBridgeRequestScopeManager()
abstract BridgeRequestScope	getBridgeScope() Returns the Bridge request scope corresponding to current view and mode.
abstract BridgeRequestScope	getBridgeScope(String viewId, String mode) Returns the Bridge request scope corresponding to passed viewId and mode.
static BridgeContext	getCurrentInstance() Return the BridgeContext instance for the request that is being processed by the current thread.
abstract String	getDefaultFacesViewIdForRequest(boolean excludeQueryString) Returns the default Faces (viewid) target configured for the current request's PortletMode.
abstract String	getFacesViewId(boolean excludeQueryString) Returns the Faces (viewid) currently targeted.
abstract String	getFacesViewIdFromPath(String path) Returns the Faces (viewid) target as represented in the path.
abstract String	getFacesViewIdFromRequest(boolean excludeQueryString) Returns the Faces (viewid) target as described by the request.
abstract String	getNavigationalQueryString() The bridge allows viewIds in the faces-config.xml to contain queryStrings.
abstract javax.portlet.PortletContext	getPortletContext()
abstract javax.portlet.PortletRequest	getPortletRequest()
abstract Bridge.PortletPhase	getPortletRequestPhase() Gets the request phase govering this context.
abstract javax.portlet.PortletResponse	getPortletResponse()
abstract List<String>	getPreFacesRequestAttrNames()
abstract Map<String,String[]>	getPreservedActionParams()
abstract String	getRedirectViewId()
abstract String	getRenderRedirectQueryString() The bridge is required to support redirects to other Faces views during render.
abstract String	getSavedViewStateParam() Faces stores the current view state in a hidden field in the response.
abstract String	getViewHistory(String mode) Returns the last viewId rendered for a given mode.
abstract boolean	hasRenderRedirect()
abstract boolean	hasRenderRedirectAfterDispatch()
abstract boolean	isBridgeRequestScopePreserved()
static void	log(String s) Convenience methods for classes that need to log without having or knowing whether they are currently executing in a BridgeContext
static void	log(String s, Throwable t) Convenience methods for classes that need to log without having or knowing whether they are currently executing in a BridgeContext
abstract void	release() Called at the end of bridge request processing.
abstract void	setBridgeConfig(BridgeConfig config) Sets the BridgeConfig that corresponds to this instance.
abstract void	setBridgeRequestScopePreserved(boolean preserve) Indicates whether the controller should preserve the bridge request scope.
protected static void	setCurrentInstance(BridgeContext context) Set the FacesContext instance for the request that is being processed by the current thread.
abstract void	setNavigationQueryString(String queryString) The bridge allows viewIds in the faces-config.xml to contain queryStrings.
abstract void	setPortletContext(javax.portlet.PortletContext context) Sets the PortletContext of the portlet invoking this bridge.
abstract void	setPortletRequest(javax.portlet.PortletRequest request) Sets the PortletRequest that invoked the bridge.
abstract void	setPortletRequestPhase(Bridge.PortletPhase phase) Sets the request phase govering this context.
abstract void	setPortletResponse(javax.portlet.PortletResponse response) Sets the PortletResponse that invoked the bridge.
abstract void	setPreFacesRequestAttrNames(List<String> names) Sets the names of the attributes which existed before the FacesContext is acquired.
abstract void	setPreservedActionParams(Map<String,String[]> actionParamMap) Map of the action parameters that have been preserved for this render request.
abstract void	setRedirectViewId(String viewId)
abstract void	setRenderRedirect(boolean redirect) Sets whether a render redirect has occurred in this request.
abstract void	setRenderRedirectAfterDispatch(boolean afterDispatch) Set if the renderRedirect occurred after the (JSP) dispatch.
abstract void	setRenderRedirectQueryString(String queryString) The bridge is required to support redirects to other Faces views during render.
abstract void	setSavedViewStateParam(String savedViewStateParam) Faces stores the current view state in a hidden field in the response.
abstract void	setViewHistory(String mode, String viewId, boolean preserveRenderParams) Bridge maintains in the session the last viewId accessed in each mode.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BridgeContext

public BridgeContext()

Method Detail

release

public abstract void release()

Called at the end of bridge request processing. It releases associated state.

setPortletContext

public abstract void setPortletContext(javax.portlet.PortletContext context)

Sets the PortletContext of the portlet invoking this bridge.

Parameters:

context -

getPortletContext

public abstract javax.portlet.PortletContext getPortletContext()

Returns:

the PortletContext of the portlet invoking this bridge.

setPortletRequest

public abstract void setPortletRequest(javax.portlet.PortletRequest request)

Sets the PortletRequest that invoked the bridge.

Parameters:

request -

getPortletRequest

public abstract javax.portlet.PortletRequest getPortletRequest()

Returns:

the PortletRequest that invoked the bridge.

setPortletResponse

public abstract void setPortletResponse(javax.portlet.PortletResponse response)

Sets the PortletResponse that invoked the bridge.

Parameters:

response -

getPortletResponse

public abstract javax.portlet.PortletResponse getPortletResponse()

Returns:

the PortletResponse that invoked the bridge.

setPortletRequestPhase

public abstract void setPortletRequestPhase(Bridge.PortletPhase phase)

Sets the request phase govering this context. Used to both detect whether one is executing in a portlet request without referencing potential unbound classes as well as to determine the type of request and response one is dealing with as there are distinct portlet request and response objects per portlet lifecycle phase.

Note: as per specification, its more typical for the Faces developer to rely on the request attribute containing this same information. Its included in the BridgeContext primarily for bridge (extension) implementors.

Parameters:

phase -

getPortletRequestPhase

public abstract Bridge.PortletPhase getPortletRequestPhase()

Gets the request phase govering this context. Used to both detect whether one is executing in a portlet request without referencing potential unbound classes as well as to determine the type of request and response one is dealing with as there are distinct portlet request and response objects per portlet lifecycle phase.

Note: as per specification, its more typical for the Faces developer to rely on the request attribute containing this same information. Its included in the BridgeContext primarily for bridge (extension) implementors.

Returns:

the current portlet request lifcycle phase we are executing in.

setBridgeConfig

public abstract void setBridgeConfig(BridgeConfig config)

Sets the BridgeConfig that corresponds to this instance.

Parameters:

config -

getBridgeConfig

public abstract BridgeConfig getBridgeConfig()

Returns:

the BridgeConfig that corresponds to this instance.

getAttributes

public abstract Map<String,Object> getAttributes()

This Map is a place to put extra (implementation specific) bridge state or anything else whose lifetime matches this scope.

Returns:

a mutable Map of bridge context scoped attributes

setBridgeRequestScopePreserved

public abstract void setBridgeRequestScopePreserved(boolean preserve)

Indicates whether the controller should preserve the bridge request scope. By specification there are a variety of reasons why the bridge shouldn't preserve a request scope. Sometimes this is determined in one of the bridge's Faces extensions that is separate from the controller. The dectector used this method to convery to the controller its behavior when its done with the request and considers whether to save the bridge request scope or not. true means the request scope should be preserved. false means the request scope should not be preserved. The default is true

Parameters:

preserve -

isBridgeRequestScopePreserved

public abstract boolean isBridgeRequestScopePreserved()

Returns:

the boolean indicating whether the controller should preserve the bridge request scope or not. true means the request scope should be preserved. false means the request scope should not be preserved. The default is true

setSavedViewStateParam

public abstract void setSavedViewStateParam(String savedViewStateParam)

Faces stores the current view state in a hidden field in the response. When this is resupplied as part of the POSTBACK, Faces is able to restore the view and process the action. In the portlet model, however, not every (following) request is a POSTBACK. The portal can ask the portlet to redisplay itself at any time merely because something has else has occurred on the page (outside the portlet) that causes the portal to rerender the entire page. As this isn't a POSTBACK the view state hidden field isn't supplied, yet Faces still needs to restore the view from this state if its to properly re-render. To support this bridge must capture the value of this hidden field and manage it in its state (often the bridge request scope). This capture involves using a Faces extension (StateManager) to extract the parameter value and the controller to manage the state. The value is conveyed between these two subsystems through here. This method sets the captured view state parameter value for later retrieval.

Parameters:

savedViewStateParam -

getSavedViewStateParam

public abstract String getSavedViewStateParam()

Faces stores the current view state in a hidden field in the response. When this is resupplied as part of the POSTBACK, Faces is able to restore the view and process the action. In the portlet model, however, not every (following) request is a POSTBACK. The portal can ask the portlet to redisplay itself at any time merely because something has else has occurred on the page (outside the portlet) that causes the portal to rerender the entire page. As this isn't a POSTBACK the view state hidden field isn't supplied, yet Faces still needs to restore the view from this state if its to properly re-render. To support this bridge must capture the value of this hidden field and manage it in its state (often the bridge request scope). This capture involves using a Faces extension (StateManager) to extract the parameter value and the controller to manage the state. The value is conveyed between these two subsystems through here.

Returns:

the captured view state parameter.

setNavigationQueryString

public abstract void setNavigationQueryString(String queryString)

The bridge allows viewIds in the faces-config.xml to contain queryStrings. As the NavigationHandler resolves such navigation and create the asscoiated view and Faces itself doesn't expect these query strings, the bridge needs to extract this query string and stash its value for later retrieval/use by the controller which encodes these extra parameters as part of its action response.

Parameters:

queryString - query string portion of a viewId

getNavigationalQueryString

public abstract String getNavigationalQueryString()

The bridge allows viewIds in the faces-config.xml to contain queryStrings. As the NavigationHandler resolves such navigation and create the associated view and Faces itself doesn't expect these query strings, the bridge needs to extract this query string and stash its value for later retrieval/use by the controller which encodes these extra parameters as part of its action response.

Returns:

the queryString portion associated with the viewId that created the current UIViewRoot

setRenderRedirectQueryString

public abstract void setRenderRedirectQueryString(String queryString)

The bridge is required to support redirects to other Faces views during render. As the portlet model doesn't support redirects, the bridge controller must simulate the redirect by unwinding the current lifecycle execution and restarting a new lifecycle execution based on the new target. In addition any additional query string parameters must be represented in the request when this lifecycle is rerun.

Such redirects are detected in ExternalContext.redirect() but implemented by the controller. This sets the query string portion of the redirect url (exclusive of the ?) so its available to the controller in handling the render redirect. This method automatically calls setRenderRedirect(true); to flag that a renderRedirect has been detected.

Parameters:

queryString -

getRenderRedirectQueryString

public abstract String getRenderRedirectQueryString()

The bridge is required to support redirects to other Faces views during render. As the portlet model doesn't support redirects, the bridge controller must simulate the redirect by unwinding the current lifecycle execution and restarting a new lifecycle execution based on the new target. In addition any additional query string parameters must be represented in the request when this lifecycle is rerun.

Such redirects are detected in ExternalContext.redirect() but implemented by the controller.

Returns:

prevously set query string (exclusive of the ?) portion of the render redirect url

setRedirectViewId

public abstract void setRedirectViewId(String viewId)

Parameters:

viewId -

getRedirectViewId

public abstract String getRedirectViewId()

Returns:

prevously set redirect view id

setRenderRedirect

public abstract void setRenderRedirect(boolean redirect)

Sets whether a render redirect has occurred in this request. Generally this is set automatically by setRenderRedirectQueryString.

Parameters:

redirect -

hasRenderRedirect

public abstract boolean hasRenderRedirect()

Returns:

indication of whether a render redirect has occured. true if there has been one in this request. Default is false.

setRenderRedirectAfterDispatch

public abstract void setRenderRedirectAfterDispatch(boolean afterDispatch)

Set if the renderRedirect occurred after the (JSP) dispatch. Needed because dispatch.forward() can't be called twice in the same request. Setting this will allow the bridge to know to use dispatch.include() for rendering the "redirected" view.

Parameters:

afterDispatch -

hasRenderRedirectAfterDispatch

public abstract boolean hasRenderRedirectAfterDispatch()

Returns:

indication of whether the renderRedirect occurred before or after the dispatch. true indicates the redirect ocurred after the dispatch. false by default.

setPreFacesRequestAttrNames

public abstract void setPreFacesRequestAttrNames(List<String> names)

Sets the names of the attributes which existed before the FacesContext is acquired. Used for attribute exclusion, request resetting before a render redirect, as well as allowing the FacesContext to release request attrs during its release.

Parameters:

names - list of attribute names that exist in the request scope before acquiring the FacesContext

getPreFacesRequestAttrNames

public abstract List<String> getPreFacesRequestAttrNames()

Returns:

the names of the request attributes that existed before the FacesContext was acquired.

setPreservedActionParams

public abstract void setPreservedActionParams(Map<String,String[]> actionParamMap)

Map of the action parameters that have been preserved for this render request. Set by the controller when processing a render so the ExternalContext.encodeActionURL() can exclude them from its encoding of a self-referencing portlet: url. I.e. one that is supposed to redisplay preserving the existing state.

Parameters:

actionParamMap - Map of the action parameters in this render request.

getPreservedActionParams

public abstract Map<String,String[]> getPreservedActionParams()

Returns:

previously set Map of the action parameters in this render request.

setViewHistory

public abstract void setViewHistory(String mode,
                  String viewId,
                  boolean preserveRenderParams)

Bridge maintains in the session the last viewId accessed in each mode. This allows developers to use EL access to get the viewId (with appropriate QS) to navigate back to the view that was left when a new mode was entered. Key in the session is: javax.portlet.faces.viewIdHistory.modeName. value is the corresponding viewId with an encoded QS containing the pertinent state (scope id, etc) to return you to the state you left. Prior to the first request the bridge sets up a default history by adding one session attribute per supported mode. The value is the default viewId configured for this mode for this portlet. This is done so a developers EL will always resolve to non-null.

Parameters:

mode - name of the portlet mode

viewId - JSF view that we are currently in/adding to the history. Includes a QS of the various state needed to restore this view

preserveRenderParams - indicates whether the render params are carried into the history. Generally true is the view's mode hasn't changed from what the bridge finds encoded in its render params and false otherwise.

getViewHistory

public abstract String getViewHistory(String mode)

Returns the last viewId rendered for a given mode. Allows one to return to the view you left when you entered a new mode. Generally this isn't called directly other than potentially to verify that the attributes have initially been set up as the primary use case is to allow developers to access this value directly from the session object using EL.

Parameters:

mode -

Returns:

getFacesViewIdFromRequest

public abstract String getFacesViewIdFromRequest(boolean excludeQueryString)
                                          throws BridgeInvalidViewPathException

Returns the Faces (viewid) target as described by the request. Note: This value must always be calculated (never cached). The value must reflect the target described by the request object contained in the ExternalContext if available. If not, then the target is computed from the BridgeContext's PortletRequest

Parameters:

excludeQueryString - if true then only the target Faces viewId is returned regardless of whether the viewId contains a query string. I.e. unlike core Faces, the bridge allows the default viewIds and viewIds in the Faces navigation rules to contain query strings that augment the view. For example one can include a new mode in a Faces navigation rule. This boolean controls whether this extra query string portion of a viewid is returned or not.

Returns:

Returns the Faces (viewid) target as described by the request. Returns null if the request doesn't explicitly specify a target or if the target specified in the request doesn't match the request's PortletMode. When a target viewId is returned it may contain contain (an optional) query string if not specifically excluded.

Throws:

BridgeInvalidViewPathException

getFacesViewId

public abstract String getFacesViewId(boolean excludeQueryString)
                               throws BridgeInvalidViewPathException

Returns the Faces (viewid) currently targeted. Note: This value must always be calculated (never cached). If the FacesContext has a current UIViewRoot, it returns its id. Otherwise it computes the target viewId as follows: returns the result of calling getFacesViewIdFromRequest() if not null otherwise return the result of getDefaultViewIdForRequest().

Parameters:

excludeQueryString - if true then only the target Faces viewId is returned regardless of whether the viewId contains a query string. I.e. unlike core Faces, the bridge allows the default viewIds and viewIds in the Faces navigation rules to contain query strings that augment the view. For example one can include a new mode in a Faces navigation rule. This boolean controls whether this extra query string portion of a viewid is returned or not.

Returns:

Returns the Faces (viewid) target as described by the request.

Throws:

BridgeInvalidViewPathException

getBridgeScope

public abstract BridgeRequestScope getBridgeScope()

Returns the Bridge request scope corresponding to current view and mode. I.e. the result of calling getFacesViewId and PortletRequest.getPortletMode().toString().

Returns:

the current Bridge request scope or null if no scope corresponding to the current view and mode

getBridgeScope

public abstract BridgeRequestScope getBridgeScope(String viewId,
                                String mode)

Returns the Bridge request scope corresponding to passed viewId and mode.

Parameters:

viewId - scope's viewId

mode - scope's portlet mode

Returns:

the current Bridge request scope or null if no scope corresponding to the current view and mode

getBridgeRequestScopeManager

public abstract BridgeRequestScopeManager getBridgeRequestScopeManager()

Returns:

the Bridge's RequestScopeManager used by this portlet

getFacesViewIdFromPath

public abstract String getFacesViewIdFromPath(String path)
                                       throws BridgeInvalidViewPathException

Returns the Faces (viewid) target as represented in the path. Basically, this does a path to viewId mapping based on the Faces servlet mappings in the web.xml. I.e. if Faces is suffix mapped (*.jsf) then a path of /foo.jsf will return foo.jsp (or whatever is the configured mapping from .jsf to .xxx). If Faces is prefix mapped (/faces/*) then a path of /faces/foo.jsp will return foo.jsp. Note:

Parameters:

path - contains encoded viewId to be extracted. path can either contain the context path or be relative to it. If path contains a query string it is ignored.

Returns:

the target viewId extracted from the path. This viewId will never contain a query string.

Throws:

BridgeInvalidViewPathException

getDefaultFacesViewIdForRequest

public abstract String getDefaultFacesViewIdForRequest(boolean excludeQueryString)
                                                throws BridgeDefaultViewNotSpecifiedException

Returns the default Faces (viewid) target configured for the current request's PortletMode. The value must use the request contained in the ExternalContext if available. If not, then the target is computed from the BridgeContext's PortletRequest

Parameters:

excludeQueryString - if true then only the target Faces viewId is returned regardless of whether the viewId contains a query string. I.e. unlike core Faces, the bridge allows the default viewIds and viewIds in the Faces navigation rules to contain query strings that augment the view. For example one can include a new mode in a Faces navigation rule. This boolean controls whether this extra query string portion of a viewid is returned or not.

Returns:

Returns the default Faces (viewid) target configured for the current request's PortletMode. The return value may contain contain (an optional) query string if not specifically excluded.

Throws:

BridgeDefaultViewNotSpecifiedException

appendClientWindowId

public abstract String appendClientWindowId(String url)

Provide the ability to append the Client Window Id to urls that need to be encoded. This is only expected to result in a modified url being returned when running under JSF 2.2.

Parameters:

url - URL that requires the Client Window Id appended to it.

Returns:

String representing a URL that will have the Client Window Id appended when running under JSF 2.2.

getCurrentInstance

public static BridgeContext getCurrentInstance()

Return the BridgeContext instance for the request that is being processed by the current thread.

setCurrentInstance

protected static void setCurrentInstance(BridgeContext context)

Set the FacesContext instance for the request that is being processed by the current thread.

Parameters:

context - The FacesContext instance for the current thread, or null if this thread no longer has a FacesContext instance.

log

public static void log(String s,
       Throwable t)

Convenience methods for classes that need to log without having or knowing whether they are currently executing in a BridgeContext

Parameters:

s -

t -

log

public static void log(String s)

Convenience methods for classes that need to log without having or knowing whether they are currently executing in a BridgeContext

Parameters:

s -