javax.faces.application
Class Application

java.lang.Object
  |
  +--javax.faces.application.Application

public abstract class Application

extends java.lang.Object

Application represents a per-web-application singleton object where applications based on JavaServer Faces (or implementations wishing to provide extended functionality) can register application-wide singletons that provide functionality required by JavaServer Faces. Default implementations of each object are provided for cases where the application does not choose to customize the behavior.

The instance of Application is created by calling the getApplication() method of ApplicationFactory. Because this instance is shared, it must be implemented in a thread-safe manner.

The application also acts as a factory for several types of Objects specified in the Faces Configuration file. Please see createComponent(java.lang.String), createConverter(java.lang.String), createMethodBinding(java.lang.String, java.lang.Class[]), createValidator(java.lang.String), and createValueBinding(java.lang.String).

Constructor Summary

Application()

Method Summary

abstract void	addComponent(java.lang.String componentType, java.lang.String componentClass) Register a new mapping of component type to the name of the corresponding UIComponent class.
abstract void	addConverter(java.lang.Class targetClass, java.lang.String converterClass) Register a new converter class that is capable of performing conversions for the specified target class.
abstract void	addConverter(java.lang.String converterId, java.lang.String converterClass) Register a new mapping of converter id to the name of the corresponding Converter class.
abstract void	addValidator(java.lang.String validatorId, java.lang.String validatorClass) Register a new mapping of validator id to the name of the corresponding Validator class.
abstract javax.faces.component.UIComponent	createComponent(java.lang.String componentType) Instantiate and return a new UIComponent instance of the class specified by a previous call to addComponent() for the specified component type.
abstract javax.faces.component.UIComponent	createComponent(javax.faces.el.ValueBinding componentBinding, javax.faces.context.FacesContext context, java.lang.String componentType) Call the getValue() method on the specified ValueBinding.
abstract javax.faces.convert.Converter	createConverter(java.lang.Class targetClass) Instantiate and return a new Converter instance of the class that has registered itself as capable of performing conversions for objects of the specified type.
abstract javax.faces.convert.Converter	createConverter(java.lang.String converterId) Instantiate and return a new Converter instance of the class specified by a previous call to addConverter() for the specified converter id.
abstract javax.faces.el.MethodBinding	createMethodBinding(java.lang.String ref, java.lang.Class[] params) Instantiate and return a new MethodBinding for the specified method binding expression, which may be used to call the corresponding method later.
abstract javax.faces.validator.Validator	createValidator(java.lang.String validatorId) Instantiate and return a new Validator instance of the class specified by a previous call to addValidator() for the specified validator id.
abstract javax.faces.el.ValueBinding	createValueBinding(java.lang.String ref) Instantiate and return a new ValueBinding for the specified value binding expression, which may be used to manipulate the corresponding property value later.
abstract javax.faces.event.ActionListener	getActionListener() Return the default ActionListener to be registered for all ActionSource components in this appication.
abstract java.util.Iterator	getComponentTypes() Return an Iterator over the set of currently defined component types for this Application.
abstract java.util.Iterator	getConverterIds() Return an Iterator over the set of currently registered converter ids for this Application.
abstract java.util.Iterator	getConverterTypes() Return an Iterator over the set of Class instances for which Converter classes have been explicitly registered.
abstract java.util.Locale	getDefaultLocale() Return the default Locale for this application.
abstract java.lang.String	getDefaultRenderKitId() Return the renderKitId to be used for rendering this application.
abstract java.lang.String	getMessageBundle() Return the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application.
abstract javax.faces.application.NavigationHandler	getNavigationHandler() Return the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application.
abstract javax.faces.el.PropertyResolver	getPropertyResolver() Return the PropertyResolver instance that will be utilized to resolve method and value bindings.
abstract javax.faces.application.StateManager	getStateManager() Return the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
abstract java.util.Iterator	getSupportedLocales() Return an Iterator over the supported Locales for this appication.
abstract java.util.Iterator	getValidatorIds() Return an Iterator over the set of currently registered validator ids for this Application.
abstract javax.faces.el.VariableResolver	getVariableResolver() Return the VariableResolver instance that will be utilized to resolve method and value bindings.
abstract javax.faces.application.ViewHandler	getViewHandler() Return the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
abstract void	setActionListener(javax.faces.event.ActionListener listener) Set the default ActionListener to be registered for all ActionSource components.
abstract void	setDefaultLocale(java.util.Locale locale) Set the default Locale for this application.
abstract void	setDefaultRenderKitId(java.lang.String renderKitId) Set the renderKitId to be used to render this application.
abstract void	setMessageBundle(java.lang.String bundle) Set the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application.
abstract void	setNavigationHandler(javax.faces.application.NavigationHandler handler) Set the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application.
abstract void	setPropertyResolver(javax.faces.el.PropertyResolver resolver) Set the PropertyResolver instance that will be utilized to resolve method and value bindings.
abstract void	setStateManager(javax.faces.application.StateManager manager) Set the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
abstract void	setSupportedLocales(java.util.Collection locales) Set the Locale instances representing the supported Locales for this application.
abstract void	setVariableResolver(javax.faces.el.VariableResolver resolver) Set the VariableResolver instance that will be utilized to resolve method and value bindings.
abstract void	setViewHandler(javax.faces.application.ViewHandler handler) Set the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.

Methods inherited from class java.lang.Object

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

Constructor Detail

Application

public Application()

Method Detail

getActionListener

public abstract javax.faces.event.ActionListener getActionListener()

Return the default ActionListener to be registered for all ActionSource components in this appication. If not explicitly set, a default implementation must be provided that performs the following functions:

• The processAction() method must first call FacesContext.renderResponse() in order to bypass any intervening lifecycle phases, once the method returns.
• The processAction() method must next determine the logical outcome of this event, as follows:
  • If the originating component has a non-null action property, retrieve the MethodBinding from the property, and call invoke() on it. Convert the returned value (if any) to a String, and use it as the logical outcome.
  • Otherwise, the logical outcome is null.
• The processAction() method must finally retrieve the NavigationHandler instance for this application and call NavigationHandler.handleNavigation(javax.faces.context.FacesContext, java.lang.String, java.lang.String) passing:
  • the FacesContext for the current request
  • If there is a MethodBinding instance for the action property of this component, the result of calling MethodBinding.getExpressionString() on it, null otherwise
  • the logical outcome as determined above

setActionListener

public abstract void setActionListener(javax.faces.event.ActionListener listener)

Set the default ActionListener to be registered for all ActionSource components.

Parameters:

listener - The new default ActionListener

Throws:

java.lang.NullPointerException - if listener is null

getDefaultLocale

public abstract java.util.Locale getDefaultLocale()

Return the default Locale for this application. If not explicitly set, null is returned.

setDefaultLocale

public abstract void setDefaultLocale(java.util.Locale locale)

Set the default Locale for this application.

Parameters:

locale - The new default Locale

Throws:

java.lang.NullPointerException - if locale is null

getDefaultRenderKitId

public abstract java.lang.String getDefaultRenderKitId()

Return the renderKitId to be used for rendering this application. If not explicitly set, null is returned.

setDefaultRenderKitId

public abstract void setDefaultRenderKitId(java.lang.String renderKitId)

Set the renderKitId to be used to render this application. Unless the client has provided a custom ViewHandler that supports the use of multiple RenderKit instances in the same application, this method must only be called at application startup, before any Faces requests have been processed. This is a limitation of the current Specification, and may be lifted in a future release.

getMessageBundle

public abstract java.lang.String getMessageBundle()

Return the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application. If not explicitly set, null is returned.

setMessageBundle

public abstract void setMessageBundle(java.lang.String bundle)

Set the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application. See the JavaDocs for the java.util.ResourceBundle class for more information about the syntax for resource bundle names.

Parameters:

bundle - Base name of the resource bundle to be used

Throws:

java.lang.NullPointerException - if bundle is null

getNavigationHandler

public abstract javax.faces.application.NavigationHandler getNavigationHandler()

Return the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application. If not explicitly set, a default implementation must be provided that performs the functions described in the NavigationHandler class description.

setNavigationHandler

public abstract void setNavigationHandler(javax.faces.application.NavigationHandler handler)

Set the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application.

Parameters:

handler - The new NavigationHandler instance

Throws:

java.lang.NullPointerException - if handler is null

getPropertyResolver

public abstract javax.faces.el.PropertyResolver getPropertyResolver()

Return the PropertyResolver instance that will be utilized to resolve method and value bindings. If not explicitly set, a default implementation must be provided that performs the functions described in the PropertyResolver class description.

setPropertyResolver

public abstract void setPropertyResolver(javax.faces.el.PropertyResolver resolver)

Set the PropertyResolver instance that will be utilized to resolve method and value bindings.

Parameters:

resolver - The new PropertyResolver instance

Throws:

java.lang.NullPointerException - if resolver is null

getVariableResolver

public abstract javax.faces.el.VariableResolver getVariableResolver()

Return the VariableResolver instance that will be utilized to resolve method and value bindings. If not explicitly set, a default implementation must be provided that performs the functions described in the VariableResolver class description.

setVariableResolver

public abstract void setVariableResolver(javax.faces.el.VariableResolver resolver)

Set the VariableResolver instance that will be utilized to resolve method and value bindings.

Parameters:

resolver - The new VariableResolver instance

Throws:

java.lang.NullPointerException - if resolver is null

getViewHandler

public abstract javax.faces.application.ViewHandler getViewHandler()

Return the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle. If not explicitly set, a default implementation must be provided that performs the functions described in the ViewHandler description in the JavaServer Faces Specification.

setViewHandler

public abstract void setViewHandler(javax.faces.application.ViewHandler handler)

Set the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.

Parameters:

handler - The new ViewHandler instance

Throws:

java.lang.IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.

java.lang.NullPointerException - if handler is null

getStateManager

public abstract javax.faces.application.StateManager getStateManager()

Return the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle. If not explicitly set, a default implementation must be provided that performs the functions described in the StateManager description in the JavaServer Faces Specification.

setStateManager

public abstract void setStateManager(javax.faces.application.StateManager manager)

Set the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.

Parameters:

manager - The new StateManager instance

Throws:

java.lang.IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.

java.lang.NullPointerException - if manager is null

addComponent

public abstract void addComponent(java.lang.String componentType,
                                  java.lang.String componentClass)

Register a new mapping of component type to the name of the corresponding UIComponent class. This allows subsequent calls to createComponent() to serve as a factory for UIComponent instances.

Parameters:

componentType - The component type to be registered

componentClass - The fully qualified class name of the corresponding UIComponent implementation

Throws:

java.lang.NullPointerException - if componentType or componentClass is null

createComponent

public abstract javax.faces.component.UIComponent createComponent(java.lang.String componentType)
                                                           throws FacesException

Instantiate and return a new UIComponent instance of the class specified by a previous call to addComponent() for the specified component type.

Parameters:

componentType - The component type for which to create and return a new UIComponent instance

Throws:

FacesException - if a UIComponent of the specified type cannot be created

java.lang.NullPointerException - if componentType is null

createComponent

public abstract javax.faces.component.UIComponent createComponent(javax.faces.el.ValueBinding componentBinding,
                                                                  javax.faces.context.FacesContext context,
                                                                  java.lang.String componentType)
                                                           throws FacesException

Call the getValue() method on the specified ValueBinding. If it returns a UIComponent instance, return it as the value of this method. If it does not, instantiate a new UIComponent instance of the specified component type, pass the new component to the setValue() method of the specified ValueBinding, and return it.

Parameters:

componentBinding - ValueBinding representing a component value binding expression (typically specified by the component attribute of a custom tag)

context - FacesContext for the current request

componentType - Component type to create if the ValueBinding does not return a component instance

Throws:

FacesException - if a UIComponent cannot be created

java.lang.NullPointerException - if any parameter is null

getComponentTypes

public abstract java.util.Iterator getComponentTypes()

Return an Iterator over the set of currently defined component types for this Application.

addConverter

public abstract void addConverter(java.lang.String converterId,
                                  java.lang.String converterClass)

Register a new mapping of converter id to the name of the corresponding Converter class. This allows subsequent calls to createConverter() to serve as a factory for Converter instances.

Parameters:

converterId - The converter id to be registered

converterClass - The fully qualified class name of the corresponding Converter implementation

Throws:

java.lang.NullPointerException - if converterId or converterClass is null

addConverter

public abstract void addConverter(java.lang.Class targetClass,
                                  java.lang.String converterClass)

Register a new converter class that is capable of performing conversions for the specified target class.

Parameters:

targetClass - The class for which this converter is registered

converterClass - The fully qualified class name of the corresponding Converter implementation

Throws:

java.lang.NullPointerException - if targetClass or converterClass is null

createConverter

public abstract javax.faces.convert.Converter createConverter(java.lang.String converterId)

Instantiate and return a new Converter instance of the class specified by a previous call to addConverter() for the specified converter id. If there is no such registration for this converter id, return null.

Parameters:

converterId - The converter id for which to create and return a new Converter instance

Throws:

FacesException - if the Converter cannot be created

java.lang.NullPointerException - if converterId is null

createConverter

public abstract javax.faces.convert.Converter createConverter(java.lang.Class targetClass)

Instantiate and return a new Converter instance of the class that has registered itself as capable of performing conversions for objects of the specified type. If no such Converter class can be identified, return null.

To locate an appropriate Converter class, the following algorithm is performed, stopping as soon as an appropriate Converter class is found:

• Locate a Converter registered for the target class itself.
• Locate a Converter registered for interfaces that are implemented by the target class (directly or indirectly).
• Locate a Converter registered for the superclass (if any) of the target class, recursively working up the inheritance hierarchy.

Parameters:

targetClass - Target class for which to return a Converter

Throws:

FacesException - if the Converter cannot be created

java.lang.NullPointerException - if targetClass is null

getConverterIds

public abstract java.util.Iterator getConverterIds()

Return an Iterator over the set of currently registered converter ids for this Application.

getConverterTypes

public abstract java.util.Iterator getConverterTypes()

Return an Iterator over the set of Class instances for which Converter classes have been explicitly registered.

createMethodBinding

public abstract javax.faces.el.MethodBinding createMethodBinding(java.lang.String ref,
                                                                 java.lang.Class[] params)
                                                          throws ReferenceSyntaxException

Instantiate and return a new MethodBinding for the specified method binding expression, which may be used to call the corresponding method later.

Parameters:

ref - Method binding expression for which to return a MethodBinding instance

params - Parameter signatures that must be compatible with those of the method to be invoked, or a zero-length array or null for a method that takes no parameters

Throws:

java.lang.NullPointerException - if ref is null

ReferenceSyntaxException - if the specified ref has invalid syntax

getSupportedLocales

public abstract java.util.Iterator getSupportedLocales()

Return an Iterator over the supported Locales for this appication.

setSupportedLocales

public abstract void setSupportedLocales(java.util.Collection locales)

Set the Locale instances representing the supported Locales for this application.

Parameters:

locales - The set of supported Locales for this application

Throws:

java.lang.NullPointerException - if the argument newLocales is null.

addValidator

public abstract void addValidator(java.lang.String validatorId,
                                  java.lang.String validatorClass)

Register a new mapping of validator id to the name of the corresponding Validator class. This allows subsequent calls to createValidator() to serve as a factory for Validator instances.

Parameters:

validatorId - The validator id to be registered

validatorClass - The fully qualified class name of the corresponding Validator implementation

Throws:

java.lang.NullPointerException - if validatorId or validatorClass is null

createValidator

public abstract javax.faces.validator.Validator createValidator(java.lang.String validatorId)
                                                         throws FacesException

Instantiate and return a new Validator instance of the class specified by a previous call to addValidator() for the specified validator id.

Parameters:

validatorId - The validator id for which to create and return a new Validator instance

Throws:

FacesException - if a Validator of the specified id cannot be created

java.lang.NullPointerException - if validatorId is null

getValidatorIds

public abstract java.util.Iterator getValidatorIds()

Return an Iterator over the set of currently registered validator ids for this Application.

createValueBinding

public abstract javax.faces.el.ValueBinding createValueBinding(java.lang.String ref)
                                                        throws ReferenceSyntaxException

Instantiate and return a new ValueBinding for the specified value binding expression, which may be used to manipulate the corresponding property value later.

Parameters:

ref - Value binding expression for which to return a ValueBinding instance

Throws:

java.lang.NullPointerException - if ref is null

ReferenceSyntaxException - if the specified ref has invalid syntax