org.apache.myfaces.trinidad.config

## Class Configurator

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

-     public abstract class Configurator
      extends 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.

  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$

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Configurator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.

    - ### 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

    - #### 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.

Copyright © 2001-2016 The Apache Software Foundation. All Rights Reserved.