Skip navigation links

org.apache.myfaces.trinidad.config
Class Configurator

java.lang.Object
org.apache.myfaces.trinidad.config.Configurator

public abstract class Configurator

extends java.lang.Object

This defines an abstract class for the Configurator. Classes implementing this abstraction should be listed in the jar's /META-INF/services folder inside of a text file named "org.apache.myfaces.trinidad.config.Configurator". These services will then be run by Trinidad's global configurator. <p/> This abstract class allows Trinidad and various renderkits to move some of their initialization and request/response wrapping code into a configurator so that they may be handled in a container agnostic fashion supporting both Portlets and Servlets. This allows Trinidad and its various renderkits to offload some of their filter logic such as multi-part request handling (file uploads), skin initialization, and other tasks. <p/> Depending on the container,these methods may be called at different times during the actual request. The only thing guaranteed to Configurator developers are the constraints listed below in the following methods. <p/> Use of this abstract class is encouraged, where possible, instead of using Trinidad filter services. While configurators and filter services should be able to coexist, any services provided by the filter service will not run in a portal and should therefore be considered optional to the run of the renderkit or application if Portal compatibility is important.

Version:

$Revision$ $Date$

Constructor Summary

Configurator()

Method Summary

void	beginRequest(javax.faces.context.ExternalContext externalContext) This is called at the beginning of each "physical" request, sometime before getExternalContext(ExternalContext) or endRequest(ExternalContext).
void	destroy() Cleans up the Configurator.
static void	disableConfiguratorServices(javax.servlet.ServletRequest srq) Disables Configurator services for the current request.
void	endRequest(javax.faces.context.ExternalContext externalContext) Executed at the end of each "physical" request.
javax.faces.context.ExternalContext	getExternalContext(javax.faces.context.ExternalContext externalContext) Returns an ExternalContext wrapper based on the provided ExternalContext.
void	init(javax.faces.context.ExternalContext externalContext) Initializes the Configurator.
protected static boolean	isConfiguratorServiceDisabled(javax.faces.context.ExternalContext ec) Returns true if the disableConfiguratorServices(ServletRequest) has been executed on the current request and false if it has not.
void	reloadSkins(javax.faces.context.ExternalContext externalContext, SkinFactory factory) The skinning framework calls this method to notify Configurators that the specified SkinFactory has been reloaded.

Methods inherited from class java.lang.Object

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

Constructor Detail

Configurator

public Configurator()

Method Detail

init

public void init(javax.faces.context.ExternalContext externalContext)

Initializes the Configurator. This method is guaranteed to run before any other method within this Configurator and will be called only once per webapp context. This init is guaranteed to be executed before completion of the first call to the FacesContextFactory.getFacesContext(java.lang.Object, java.lang.Object, java.lang.Object, javax.faces.lifecycle.Lifecycle) is completed. Note:the ExternalContext provided to this method may not contain any of the Request/Response functionality within the external context and will NOT contain any ExternalContext wrapping provided by the getExternalContext(ExternalContext) method. This object is intended only to be used as a container abstraction to the native Context object.

Parameters:

externalContext - a mocked up external context providing access to the native context object.

destroy

public void destroy()

Cleans up the Configurator. This method is guaranteed to run at some point after the Servlet or Portlet context falls out of scope and will typically be determined by the context listener.

beginRequest

public void beginRequest(javax.faces.context.ExternalContext externalContext)

This is called at the beginning of each "physical" request, sometime before getExternalContext(ExternalContext) or endRequest(ExternalContext). When using the TrinidadFilter, this will be called during filter execution, but is not guaranteed to happen until just before the creation of the Trinidad FacesContext wrapper. All Configurator services will have thier beginRequest() methods called before any calls to getExternalContext(). So any context wrapping done by this method will not happen until after the beginRequest() is called.It is also important to note that the ExternalContext provided may or may not be the same as the ExternalContext provided to getExternalContext(). But it will have a valid request and response object. By contract, the RequestContext object will be initialized and available when this method is run.

Parameters:

externalContext - a mocked up or life externalContext providing access to the native request, response, and context objects.

getExternalContext

public javax.faces.context.ExternalContext getExternalContext(javax.faces.context.ExternalContext externalContext)

Returns an ExternalContext wrapper based on the provided ExternalContext. This method is executed durring the creation of the FacesContext when using Trinidad's FacesContextFactory. The ExternalContext returned from this method will be a part of the FacesContext that is returned from this factory but may also be wrapped be externalContext's from other services. Especially in Portlet environments, this method may be executed multiple times after a call to beginRequest(ExternalContext). Please note that it is important that this method returns a wrapper of the original context, or the behavior provided by other services and by Trinidad may not function By contract, the RequestContext object will be initialized and available when this method is run.

Parameters:

externalContext - the ExternalContext to wrap

Returns:

a wrapper of the ExternalContext

endRequest

public void endRequest(javax.faces.context.ExternalContext externalContext)

Executed at the end of each "physical" request. There will be a call to endRequest after each call to beginRequest(ExternalContext). It is also important to note that the ExternalContext provided may or may not be the same as the ExternalContext provided to getExternalContext(). But it will have a valid request and response object. By contract, the RequestContext object will be initialized and available when this method is run.

Parameters:

externalContext - the external context

reloadSkins

public void reloadSkins(javax.faces.context.ExternalContext externalContext,
                        SkinFactory factory)

The skinning framework calls this method to notify Configurators that the specified SkinFactory has been reloaded. In response the Configurators can add their skins to the specified SkinFactory.

Parameters:

externalContext - the external context

factory - the SkinFactory instance to which the skins can be reloaded

disableConfiguratorServices

public static final void disableConfiguratorServices(javax.servlet.ServletRequest srq)

Disables Configurator services for the current request. When this method has been called on a request, then the {beginRequest(ExternalContext), endRequest(ExternalContext), and getExternalContext(ExternalContext) methods will not be called durring a request. Note: is this method is called after the beginRequest() method, an error will be logged in the trinidad logger and the services will continue to execute.

Parameters:

srq - the servlet request

isConfiguratorServiceDisabled

protected static final boolean isConfiguratorServiceDisabled(javax.faces.context.ExternalContext ec)

Returns true if the disableConfiguratorServices(ServletRequest) has been executed on the current request and false if it has not. Note:it is important to understand that this method will not properly reflect if the services have actually been disabled or not. It simply returns whether they "should" have been disabled. If the disableConfiguratorServices was executed after the beginRequest methods have been executed, then the services will continue to function so that {getExternalContext(ExternalContext) and endRequest(ExternalContext) will still be called.

Parameters:

ec - the ExternalContext object

Returns:

a boolean containing true if the disableConfiguratorServices() method has been called and false if it has not.

Skip navigation links