org.apache.myfaces.trinidad.config.Configurator Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of trinidad-api Show documentation
Show all versions of trinidad-api Show documentation
Public API for the Apache MyFaces Trinidad project
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.myfaces.trinidad.config;
import javax.faces.context.ExternalContext;
import javax.servlet.ServletRequest;
import org.apache.myfaces.trinidad.skin.SkinFactory;
import org.apache.myfaces.trinidad.util.RequestStateMap;
/**
* 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.
*
* 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.
*
* 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.
*
* 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$
*/
public abstract class Configurator
{
/**
* 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
* {@link javax.faces.context.FacesContextFactory#getFacesContext}
* 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 {@link #getExternalContext(ExternalContext)} method. This object
* is intended only to be used as a container abstraction to the native
* Context object.
*
* @param externalContext a mocked up external context providing access
* to the native context object.
*/
public void init(ExternalContext externalContext) {}
/**
* 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.
*/
public void destroy() {}
/**
* This is called at the beginning of each "physical" request, sometime
* before {@link #getExternalContext(ExternalContext)} or
* {@link #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 {@link org.apache.myfaces.trinidad.context.RequestContext}
* object will be initialized and available when this method is run.
*
* @param externalContext a mocked up or life externalContext providing
* access to the native request, response, and context
* objects.
*/
public void beginRequest(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 {@link #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 {@link org.apache.myfaces.trinidad.context.RequestContext}
* object will be initialized and available when this method is run.
*
* @param externalContext the ExternalContext to wrap
* @return a wrapper of the ExternalContext
*/
public ExternalContext getExternalContext(ExternalContext externalContext)
{
return externalContext;
}
/**
* Executed at the end of each "physical" request. There will be a call to
* endRequest after each call to {@link #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 {@link org.apache.myfaces.trinidad.context.RequestContext}
* object will be initialized and available when this method is run.
*
* @param externalContext the external context
*/
public void endRequest(ExternalContext externalContext){}
/**
* Third parties can call SkinFactory#reload. This in turn calls this method. In response the Configurators
* can add their skins to the specified SkinFactory. Note that this is now deprecated in favor of SkinProvider SPI.
* SkinProvider introduces the flexibility to create and manage external skin repositories. Each SkinProvider
* implementation can support its own set of Skins. Thus creating, managing and disposing Skins is the responsibility
* of SkinProvider. This includes reloading of skins as well.
* @param externalContext the external context
* @param factory the SkinFactory instance to which the skins can be reloaded
* @deprecated use SkinProvider SPI. The reloading of 'dirty' skins has to be taken care inside SkinProvider
* implementations.
* @see org.apache.myfaces.trinidad.skin.SkinProvider
*/
@Deprecated
public void reloadSkins(ExternalContext externalContext, SkinFactory factory){}
/**
* Disables Configurator services for the current request. When this method
* has been called on a request, then the {{@link #beginRequest(ExternalContext)},
* {@link #endRequest(ExternalContext)}, and
* {@link #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.
*
* @param srq the servlet request
*/
public static final void disableConfiguratorServices(ServletRequest srq)
{
RequestStateMap.getInstance(srq).put(_DISABLE_SERVICES, Boolean.TRUE);
}
/**
* Returns true if the {@link #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 {{@link #getExternalContext(ExternalContext)}
* and {@link #endRequest(ExternalContext)} will still be called.
*
* @param ec the ExternalContext object
*
* @return a boolean containing true if the
* disableConfiguratorServices() method has been
* called and false if it has not.
*/
protected static final boolean isConfiguratorServiceDisabled(ExternalContext ec)
{
return Boolean.TRUE.equals(RequestStateMap.getInstance(ec).get(_DISABLE_SERVICES));
}
static private final String _DISABLE_SERVICES = Configurator.class.getName()+".DISABLE_SERVICES";
}