javax.faces.application
Class Application

java.lang.Object
  javax.faces.application.Application

Direct Known Subclasses:

ApplicationWrapper

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 Application#createComponent, Application#createConverter, and Application#createValidator.

Constructor Summary

Application()

Method Summary

void	addBehavior(java.lang.String behaviorId, java.lang.String behaviorClass) Register a new mapping of behavior id to the name of the corresponding Behavior class.
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.
void	addDefaultValidatorId(java.lang.String validatorId) Register a validator by its id that is applied to all UIInput components in a view.
void	addELContextListener(ELContextListener listener) Provide a way for Faces applications to register an ELContextListener that will be notified on creation of ELContext instances.
void	addELResolver(ELResolver resolver) Cause an the argument resolver to be added to the resolver chain as specified in section JSF.5.5.1 of the JavaServer Faces Specification.
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.
Behavior	createBehavior(java.lang.String behaviorId) Instantiate and return a new Behavior instance of the class specified by a previous call to addBehavior() for the specified behavior id.
UIComponent	createComponent(FacesContext context, Resource componentResource) Instantiate and return a new UIComponent instance from the argument Resource.
UIComponent	createComponent(FacesContext context, java.lang.String componentType, java.lang.String rendererType) Like createComponent(String) except the Renderer for the component to be returned must be inspected for the annotations mentioned in createComponent(ValueExpression, FacesContext, String) as specified in the documentation for that method.
abstract 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 UIComponent	createComponent(ValueBinding componentBinding, FacesContext context, java.lang.String componentType) Deprecated. This has been replaced by createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).
UIComponent	createComponent(ValueExpression componentExpression, FacesContext context, java.lang.String componentType) Call the getValue() method on the specified ValueExpression.
UIComponent	createComponent(ValueExpression componentExpression, FacesContext context, java.lang.String componentType, java.lang.String rendererType) Like createComponent(ValueExpression, FacesContext, String) except the Renderer for the component to be returned must be inspected for the annotations mentioned in createComponent(ValueExpression, FacesContext, String) as specified in the documentation for that method.
abstract 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 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 MethodBinding	createMethodBinding(java.lang.String ref, java.lang.Class<?>[] params) Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createMethodExpression.
abstract 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 ValueBinding	createValueBinding(java.lang.String ref) Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createValueExpression.
<T> T	evaluateExpressionGet(FacesContext context, java.lang.String expression, java.lang.Class<? extends T> expectedType) Get a value by evaluating an expression.
abstract ActionListener	getActionListener() Return the default ActionListener to be registered for all ActionSource components in this appication.
java.util.Iterator<java.lang.String>	getBehaviorIds() Return an Iterator over the set of currently registered behavior ids for this Application.
abstract java.util.Iterator<java.lang.String>	getComponentTypes() Return an Iterator over the set of currently defined component types for this Application.
abstract java.util.Iterator<java.lang.String>	getConverterIds() Return an Iterator over the set of currently registered converter ids for this Application.
abstract java.util.Iterator<java.lang.Class<?>>	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.
java.util.Map<java.lang.String,java.lang.String>	getDefaultValidatorInfo() Return an immutable Map over the set of currently registered default validator IDs and their class name for this Application.
ELContextListener[]	getELContextListeners() If no calls have been made to addELContextListener(javax.el.ELContextListener), this method must return an empty array.
ELResolver	getELResolver() Return the singleton ELResolver instance to be used for all EL resolution.
ExpressionFactory	getExpressionFactory() Return the ExpressionFactory instance for 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 NavigationHandler	getNavigationHandler() Return the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application.
ProjectStage	getProjectStage() Return the project stage for the currently running application instance.
abstract PropertyResolver	getPropertyResolver() Deprecated. This has been replaced by getELResolver().
java.util.ResourceBundle	getResourceBundle(FacesContext ctx, java.lang.String name) Find a ResourceBundle as defined in the application configuration resources under the specified name.
ResourceHandler	getResourceHandler() Return the singleton, stateless, thread-safe ResourceHandler for this application.
abstract 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<java.util.Locale>	getSupportedLocales() Return an Iterator over the supported Locales for this appication.
abstract java.util.Iterator<java.lang.String>	getValidatorIds() Return an Iterator over the set of currently registered validator ids for this Application.
abstract VariableResolver	getVariableResolver() Deprecated. This has been replaced by getELResolver().
abstract ViewHandler	getViewHandler() Return the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
void	publishEvent(FacesContext context, java.lang.Class<? extends SystemEvent> systemEventClass, java.lang.Class<?> sourceBaseType, java.lang.Object source) This method functions exactly like publishEvent(FacesContext,Class,Object), except the run-time must use the argument sourceBaseType to find the matching listener instead of using the Class of the source argument.
void	publishEvent(FacesContext context, java.lang.Class<? extends SystemEvent> systemEventClass, java.lang.Object source) If FacesContext.isProcessingEvents() is true and there are one or more listeners for events of the type represented by systemEventClass, call those listeners, passing source as the source of the event.
void	removeELContextListener(ELContextListener listener) Remove the argument listener from the list of ELContextListeners.
abstract void	setActionListener(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(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(PropertyResolver resolver) Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).
void	setResourceHandler(ResourceHandler resourceHandler) Set the ResourceHandler instance that will be utilized for rendering the markup for resources, and for satisfying client requests to serve up resources.
abstract void	setStateManager(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<java.util.Locale> locales) Set the Locale instances representing the supported Locales for this application.
abstract void	setVariableResolver(VariableResolver resolver) Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).
abstract void	setViewHandler(ViewHandler handler) Set the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
void	subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass, java.lang.Class<?> sourceClass, SystemEventListener listener) Install the listener instance referenced by argument listener into the application as a listener for events of type systemEventClass that originate from objects of type sourceClass.
void	subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Install the listener instance referenced by argument listener into application as a listener for events of type systemEventClass.
void	unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass, java.lang.Class<?> sourceClass, SystemEventListener listener) Remove the listener instance referenced by argument listener from the application as a listener for events of type systemEventClass that originate from objects of type sourceClass.
void	unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Remove the listener instance referenced by argument listener from the application as a listener for events of type systemEventClass.

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

Note that the specification for the default ActionListener contiues to call for the use of a deprecated property (action) and class (MethodBinding). Unfortunately, this is necessary because the default ActionListener must continue to work with components that do not implement ActionSource2, and only implement ActionSource.

setActionListener

public abstract void setActionListener(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 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(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

getResourceHandler

public ResourceHandler getResourceHandler()

Return the singleton, stateless, thread-safe ResourceHandler for this application. The JSF implementation must support the following techniques for declaring an alternate implementation of ResourceHandler.

• The ResourceHandler implementation is declared in the application configuration resources by giving the fully qualified class name as the value of the <resource-handler> element within the <application> element.

In all of the above cases, the runtime must employ the decorator pattern as for every other pluggable artifact in JSF.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Since:

2.0

setResourceHandler

public void setResourceHandler(ResourceHandler resourceHandler)

Set the ResourceHandler instance that will be utilized for rendering the markup for resources, and for satisfying client requests to serve up resources.

Parameters:

resourceHandler - The new ResourceHandler instance

Throws:

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 resourceHandler is null

Since:

2.0

getPropertyResolver

public abstract PropertyResolver getPropertyResolver()

Deprecated. This has been replaced by getELResolver().

Return a PropertyResolver instance that wraps the ELResolver instance that Faces provides to the unified EL for the resolution of expressions that appear programmatically in an application.

Note that this no longer returns the default PropertyResolver since that class is now a no-op that aids in allowing custom PropertyResolvers to affect the EL resolution process.

setPropertyResolver

public abstract void setPropertyResolver(PropertyResolver resolver)

Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).

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

This method is now deprecated but the implementation must cause the argument to be set as the head of the legacy PropertyResolver chain, replacing any existing value that was set from the application configuration resources.

It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.

Parameters:

resolver - The new PropertyResolver instance

Throws:

java.lang.NullPointerException - if resolver is null

IllegalStateException - if called after the first request to the FacesServlet has been serviced.

getResourceBundle

public java.util.ResourceBundle getResourceBundle(FacesContext ctx,
                                                  java.lang.String name)

Find a ResourceBundle as defined in the application configuration resources under the specified name. If a ResourceBundle was defined for the name, return an instance that uses the locale of the current UIViewRoot.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Returns:

ResourceBundle for the current UIViewRoot, otherwise null

Throws:

FacesException - if a bundle was defined, but not resolvable

java.lang.NullPointerException - if ctx == null || name == null

Since:

1.2

getProjectStage

public ProjectStage getProjectStage()

Return the project stage for the currently running application instance. The default value is ProjectStage#Production

The implementation of this method must perform the following algorithm or an equivalent with the same end result to determine the value to return.

If the value has already been determined by a previous call to this method, simply return that value.

Look for a JNDI environment entry under the key given by the value of ProjectStage#PROJECT_STAGE_JNDI_NAME (return type of java.lang.String). If found, continue with the algorithm below, otherwise, look for an entry in the initParamMap of the ExternalContext from the current FacesContext with the key given by the value of ProjectStage#PROJECT_STAGE_PARAM_NAME

If a value is found, see if an enum constant can be obtained by calling ProjectStage.valueOf(), passing the value from the initParamMap. If this succeeds without exception, save the value and return it.

If not found, or any of the previous attempts to discover the enum constant value have failed, log a descriptive error message, assign the value as ProjectStage.Production and return it.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Since:

2.0

getVariableResolver

public abstract VariableResolver getVariableResolver()

Deprecated. This has been replaced by getELResolver().

Return the VariableResolver that wraps the ELResolver instance that Faces provides to the unified EL for the resolution of expressions that appear programmatically in an application. The implementation of the VariableResolvermust pass null as the base argument for any methods invoked on the underlying ELResolver.

Note that this method no longer returns the default VariableResolver, since that class now is a no-op that aids in allowing custom VariableResolvers to affect the EL resolution process.

setVariableResolver

public abstract void setVariableResolver(VariableResolver resolver)

Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).

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

This method is now deprecated but the implementation must cause the argument to be set as the head of the legacy VariableResolver chain, replacing any existing value that was set from the application configuration resources.

It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.

Parameters:

resolver - The new VariableResolver instance

Throws:

java.lang.NullPointerException - if resolver is null

IllegalStateException - if called after the first request to the FacesServlet has been serviced.

addELResolver

public void addELResolver(ELResolver resolver)

Cause an the argument resolver to be added to the resolver chain as specified in section JSF.5.5.1 of the JavaServer Faces Specification.

It is not possible to remove an ELResolver registered with this method, once it has been registered.

It is illegal to register an ELResolver after the application has received any requests from the client. If an attempt is made to register a listener after that time, an IllegalStateException must be thrown. This restriction is in place to allow the JSP container to optimize for the common case where no additional ELResolvers are in the chain, aside from the standard ones. It is permissible to add ELResolvers before or after initialization to a CompositeELResolver that is already in the chain.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend Application.

Throws:

IllegalStateException - if called after the first request to the FacesServlet has been serviced.

Since:

1.2

getELResolver

public ELResolver getELResolver()

Return the singleton ELResolver instance to be used for all EL resolution. This is actually an instance of CompositeELResolver that must contain the following ELResolver instances in the following order:

1. ELResolver instances declared using the <el-resolver> element in the application configuration resources.

2. An implementation that wraps the head of the legacy VariableResolver chain, as per section VariableResolver ChainWrapper in Chapter JSF.5 in the spec document.

3. An implementation that wraps the head of the legacy PropertyResolver chain, as per section PropertyResolver ChainWrapper in Chapter JSF.5 in the spec document.

4. Any ELResolver instances added by calls to addELResolver(javax.el.ELResolver).

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend Application.

Since:

1.2

getViewHandler

public abstract 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(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:

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 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(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:

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

addBehavior

public void addBehavior(java.lang.String behaviorId,
                        java.lang.String behaviorClass)

Register a new mapping of behavior id to the name of the corresponding Behavior class. This allows subsequent calls to createBehavior() to serve as a factory for Behavior instances.

Parameters:

behaviorId - The behavior id to be registered

behaviorClass - The fully qualified class name of the corresponding Behavior implementation

Throws:

java.lang.NullPointerException - if behaviorId or behaviorClass is null

Since:

2.0

createBehavior

public Behavior createBehavior(java.lang.String behaviorId)
                        throws FacesException

Instantiate and return a new Behavior instance of the class specified by a previous call to addBehavior() for the specified behavior id.

Parameters:

behaviorId - The behavior id for which to create and return a new Behavior instance

Throws:

FacesException - if the Behavior cannot be created

java.lang.NullPointerException - if behaviorId is null

getBehaviorIds

public java.util.Iterator<java.lang.String> getBehaviorIds()

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

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

Before the component instance is returned, it must be inspected for the presence of a ListenerFor (or ListenersFor) or ResourceDependency (or ResourceDependencies) annotation. If any of these annotations are present, the action listed in ListenerFor or ResourceDependency must be taken on the component, before it is returned from this method. This variant of createComponent must not inspect the Renderer for the component to be returned for any of the afore mentioned annotations. Such inspection is the province of createComponent(ValueExpression, FacesContext, String, String) or createComponent(FacesContext, String, String).

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 UIComponent createComponent(ValueBinding componentBinding,
                                            FacesContext context,
                                            java.lang.String componentType)
                                     throws FacesException

Deprecated. This has been replaced by createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).

Wrap the argument componentBinding in an implementation of ValueExpression and call through to createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).

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

createComponent

public UIComponent createComponent(ValueExpression componentExpression,
                                   FacesContext context,
                                   java.lang.String componentType)
                            throws FacesException

Call the getValue() method on the specified ValueExpression. 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 ValueExpression, and return it.

Before the component instance is returned, it must be inspected for the presence of a ListenerFor (or ListenersFor) or ResourceDependency (or ResourceDependencies) annotation. If any of these annotations are present, the action listed in ListenerFor or ResourceDependency must be taken on the component, before it is returned from this method. This variant of createComponent must not inspect the Renderer for the component to be returned for any of the afore mentioned annotations. Such inspection is the province of createComponent(ValueExpression, FacesContext, String, String) or createComponent(FacesContext, String, String).

Parameters:

componentExpression - ValueExpression representing a component value expression (typically specified by the component attribute of a custom tag)

context - FacesContext for the current request

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

Throws:

FacesException - if a UIComponent cannot be created

java.lang.NullPointerException - if any parameter is null

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function.

Since:

1.2

createComponent

public UIComponent createComponent(ValueExpression componentExpression,
                                   FacesContext context,
                                   java.lang.String componentType,
                                   java.lang.String rendererType)

Like createComponent(ValueExpression, FacesContext, String) except the Renderer for the component to be returned must be inspected for the annotations mentioned in createComponent(ValueExpression, FacesContext, String) as specified in the documentation for that method. The Renderer instance to inspect must be obtained by calling FacesContext#getRenderKit and calling RenderKit.getRenderer(java.lang.String, java.lang.String) on the result, passing the argument componentType as the first argument and the result of calling UIComponent#getFamily on the newly created component as the second argument. If no such Renderer can be found, a message must be logged with a helpful error message. Otherwise, UIComponent#setRendererType must be called on the newly created UIComponent instance, passing the argument rendererType as the argument.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function.

Parameters:

componentExpression - ValueExpression representing a component value expression (typically specified by the component attribute of a custom tag)

context - FacesContext for the current request

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

rendererType - The renderer-type of the Renderer that will render this component. A null value must be accepted for this parameter.

Throws:

FacesException - if a UIComponent cannot be created

java.lang.NullPointerException - if any of the parameters componentExpression, context, or componentType are null

Since:

2.0

createComponent

public UIComponent createComponent(FacesContext context,
                                   java.lang.String componentType,
                                   java.lang.String rendererType)

Like createComponent(String) except the Renderer for the component to be returned must be inspected for the annotations mentioned in createComponent(ValueExpression, FacesContext, String) as specified in the documentation for that method. The Renderer instance to inspect must be obtained by calling FacesContext#getRenderKit and calling RenderKit.getRenderer(java.lang.String, java.lang.String) on the result, passing the argument componentType as the first argument and the result of calling UIComponent#getFamily on the newly created component as the second argument. If no such Renderer can be found, a message must be logged with a helpful error message. Otherwise, UIComponent#setRendererType must be called on the newly created UIComponent instance, passing the argument rendererType as the argument.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Parameters:

context - FacesContext for the current request

componentType - Component type to create

rendererType - The renderer-type of the Renderer that will render this component. A null value must be accepted for this parameter.

Throws:

FacesException - if a UIComponent cannot be created

java.lang.NullPointerException - if any of the parameters context, or componentType are null

Since:

2.0

createComponent

public UIComponent createComponent(FacesContext context,
                                   Resource componentResource)

Instantiate and return a new UIComponent instance from the argument Resource. An algorithm semantically equivalent to the following must be followed to instantiate the UIComponent to return.

• Obtain a reference to the ViewDeclarationLanguage for this Application instance by calling ViewHandler#getViewDeclarationLanguage, passing the viewId found by calling UIViewRoot.getViewId() on the UIViewRoot in the argument FacesContext.

• Obtain a reference to the composite component metadata for this composite component by calling ViewDeclarationLanguage#getComponentMetadata, passing the facesContext and componentResource arguments to this method. This version of JSF specification uses JavaBeans as the API to the component metadata.

• Determine if the component author declared a component-type for this component instance by obtaining the BeanDescriptor from the component metadata and calling its getValue() method, passing UIComponent#COMPOSITE_COMPONENT_TYPE_KEY as the argument. If non-null, the result must be a ValueExpression whose value is the component-type of the UIComponent to be created for this Resource component. Call through to createComponent(java.lang.String) to create the component.

• Otherwise, determine if a script based component for this Resource can be found by calling ViewDeclarationLanguage#getScriptComponentResource. If the result is non-null, and is a script written in one of the languages listed in JSF.4.3 of the specification prose document, create a UIComponent instance from the script resource.

• Otherwise, let library-name be the return from calling Resource#getLibraryName on the argument componentResource and resource-name be the return from calling Resource#getResourceName on the argument componentResource. Create a fully qualified Java class name by removing any file extension from resource-name and let fqcn be library-name + "." + resource-name. If a class with the name of fqcn cannot be found, take no action and continue to the next step. If any of InstantiationException, IllegalAccessException, or ClassCastException are thrown, wrap the exception in a FacesException and re-throw it. If any other exception is thrown, log the exception and continue to the next step.

• If none of the previous steps have yielded a UIComponent instance, call createComponent(java.lang.String) passing "javax.faces.NamingContainer" as the argument.

• Call UIComponent#setRendererType on the UIComponent instance, passing "javax.faces.Composite" as the argument.

• Store the argument Resource in the attributes Map of the UIComponent under the key, Resource#COMPONENT_RESOURCE_KEY.

• Store composite component metadata in the attributes Map of the UIComponent under the key, UIComponent#BEANINFO_KEY.

Before the component instance is returned, it must be inspected for the presence of a ListenerFor annotation. If this annotation is present, the action listed in ListenerFor must be taken on the component, before it is returned from this method.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function.

Parameters:

context - FacesContext for the current request

componentResource - A Resource that points to a source file that provides an implementation of a component.

Throws:

FacesException - if a UIComponent from the Resource cannot be created

NullPointerException - if any parameter is null

java.lang.NullPointerException - if unable, for any reason, to obtain a ViewDeclarationLanguage instance as described above.

Since:

2.0

getComponentTypes

public abstract java.util.Iterator<java.lang.String> 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 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 the toLowerCase() of the String represenation of the value of the "javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE" application configuration parameter is "true" (without the quotes) and the Converter instance to be returned is an instance of DateTimeConverter, DateTimeConverter.setTimeZone(java.util.TimeZone) must be called, passing the return from TimeZone.getDefault().

The argument converter must be inspected for the presence of the ResourceDependency annotation. If the ResourceDependency annotation is present, the action described in ResourceDependency must be taken. If the ResourceDependency annotation is not present, the argument converter must be inspected for the presence of the ResourceDependencies annotation. If the ResourceDependencies annotation is present, the action described in ResourceDependencies must be taken.

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

If the Converter has a single argument constructor that accepts a Class, instantiate the Converter using that constructor, passing the argument targetClass as the sole argument. Otherwise, simply use the zero-argument constructor.

If the toLowerCase() of the String represenation of the value of the "javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE" application configuration parameter is "true" (without the quotes) and the Converter instance to be returned is an instance of DateTimeConverter, DateTimeConverter.setTimeZone(java.util.TimeZone) must be called, passing the return from TimeZone.getDefault().

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<java.lang.String> getConverterIds()

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

getConverterTypes

public abstract java.util.Iterator<java.lang.Class<?>> getConverterTypes()

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

addDefaultValidatorId

public void addDefaultValidatorId(java.lang.String validatorId)

Register a validator by its id that is applied to all UIInput components in a view. The validator to most often serve this role is the BeanValidator. The usage contract for this method assumes that the validator has been registered using the normal “by-id” registration mechanism.

An implementation is provided that takes no action so that users that decorate the Application continue to work.

Since:

2.0

getDefaultValidatorInfo

public java.util.Map<java.lang.String,java.lang.String> getDefaultValidatorInfo()

Return an immutable Map over the set of currently registered default validator IDs and their class name for this Application.

An implementation is provided that returns Collections.emptyMap so that users that decorate the Application continue to work.

Since:

2.0

getExpressionFactory

public ExpressionFactory getExpressionFactory()

Return the ExpressionFactory instance for this application. This instance is used by the convenience method evaluateExpressionGet(javax.faces.context.FacesContext, java.lang.String, java.lang.Class).

The implementation must return the ExpressionFactory from the JSP container by calling JspFactory.getDefaultFactory().getJspApplicationContext(servletContext).getExpressionFactory().

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

evaluateExpressionGet

public <T> T evaluateExpressionGet(FacesContext context,
                                   java.lang.String expression,
                                   java.lang.Class<? extends T> expectedType)
                        throws ELException

Get a value by evaluating an expression.

Call getExpressionFactory() then call ExpressionFactory#createValueExpression passing the argument expression and expectedType. Call FacesContext#getELContext and pass it to ValueExpression#getValue, returning the result.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Throws:

ELException

createMethodBinding

public abstract MethodBinding createMethodBinding(java.lang.String ref,
                                                  java.lang.Class<?>[] params)
                                           throws ReferenceSyntaxException

Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createMethodExpression.

Call getExpressionFactory() then call ExpressionFactory#createMethodExpression, passing the given arguments, and wrap the result in a MethodBinding implementation, returning it.

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<java.util.Locale> getSupportedLocales()

Return an Iterator over the supported Locales for this appication.

setSupportedLocales

public abstract void setSupportedLocales(java.util.Collection<java.util.Locale> 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.

addELContextListener

public void addELContextListener(ELContextListener listener)

Provide a way for Faces applications to register an ELContextListener that will be notified on creation of ELContext instances. This listener will be called once per request.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

removeELContextListener

public void removeELContextListener(ELContextListener listener)

Remove the argument listener from the list of ELContextListeners. If listener is null, no exception is thrown and no action is performed. If listener is not in the list, no exception is thrown and no action is performed.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

getELContextListeners

public ELContextListener[] getELContextListeners()

If no calls have been made to addELContextListener(javax.el.ELContextListener), this method must return an empty array.

Otherwise, return an array representing the list of listeners added by calls to addELContextListener(javax.el.ELContextListener).

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

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

The argument validator must be inspected for the presence of the ResourceDependency annotation. If the ResourceDependency annotation is present, the action described in ResourceDependency must be taken. If the ResourceDependency annotation is not present, the argument validator must be inspected for the presence of the ResourceDependencies annotation. If the ResourceDependencies annotation is present, the action described in ResourceDependencies must be taken.

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<java.lang.String> getValidatorIds()

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

createValueBinding

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

Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createValueExpression.

Call getExpressionFactory() then call ExpressionFactory#createValueExpression, passing the argument ref, Object.class for the expectedType, and null, for the fnMapper.

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

publishEvent

public void publishEvent(FacesContext context,
                         java.lang.Class<? extends SystemEvent> systemEventClass,
                         java.lang.Object source)

If FacesContext.isProcessingEvents() is true and there are one or more listeners for events of the type represented by systemEventClass, call those listeners, passing source as the source of the event. The implementation should be as fast as possible in determining whether or not a listener for the given systemEventClass and source has been installed, and should return immediately once such a determination has been made. The implementation of publishEvent must honor the requirements stated in subscribeToEvent(java.lang.Class, java.lang.Class, javax.faces.event.SystemEventListener) regarding the storage and retrieval of listener instances. Specifically, if subscribeToEvent(Class,Class,SystemEventListener) was called, the sourceClass argument must match exactly the Class of the source argument in the call to publishEvent(). The implementation must not do any inheritance hierarachy inspection when looking for a match between the sourceClass passed to subscribeToEvent(Class,Class,SystemEventListener) and the sourceClass passed to publishEvent() in order to find any listeners to which the event should be published. In the case where the Class of the source argument does not match the Class of the sourceClass used when the listener was subscribed using subscribeToEvent(), publishEvent(FacesContext,Class,Class,Object) can be used to provide the Class used to perform the listener lookup and match.

The default implementation must implement an algorithm semantically equivalent to the following to locate listener instances and to invoke them.

• If the source argument implements SystemEventListenerHolder, call SystemEventListenerHolder.getListenersForEventClass(java.lang.Class) on it, passing the systemEventClass argument. If the list is not empty, perform algorithm traverseListenerList on the list.

• If any view level listeners have been installed by previous calls to subscribeToEvent(Class, Class, javax.faces.event.SystemEventListener) on the UIViewRoot, perform algorithm traverseListenerList on the list of listeners for that event installed on the UIViewRoot.

• If any Application level listeners have been installed by previous calls to subscribeToEvent(Class, Class, javax.faces.event.SystemEventListener), perform algorithm traverseListenerList on the list.

• If any Application level listeners have been installed by previous calls to subscribeToEvent(Class, javax.faces.event.SystemEventListener), perform algorithm traverseListenerList on the list.

If the act of invoking the processListener method causes an AbortProcessingException to be thrown, processing of the listeners must be aborted, no further processing of the listeners for this event must take place, and the exception must be logged with Level.SEVERE.

Algorithm traverseListenerList: For each listener in the list,

• Call SystemEventListener.isListenerForSource(java.lang.Object), passing the source argument. If this returns false, take no action on the listener.

• Otherwise, if the event to be passed to the listener instances has not yet been constructed, construct the event, passing source as the argument to the one-argument constructor that takes an Object. This same event instance must be passed to all listener instances.

• Call SystemEvent.isAppropriateListener(javax.faces.event.FacesListener), passing the listener instance as the argument. If this returns false, take no action on the listener.

• Call SystemEvent.processListener(javax.faces.event.FacesListener), passing the listener instance.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Parameters:

context - the FacesContext for the current request

systemEventClass - The Class of event that is being published.

source - The source for the event of type systemEventClass.

Throws:

java.lang.NullPointerException - if either context, systemEventClass or source is null

Since:

2.0

publishEvent

public void publishEvent(FacesContext context,
                         java.lang.Class<? extends SystemEvent> systemEventClass,
                         java.lang.Class<?> sourceBaseType,
                         java.lang.Object source)

This method functions exactly like publishEvent(FacesContext,Class,Object), except the run-time must use the argument sourceBaseType to find the matching listener instead of using the Class of the source argument.

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Parameters:

context - the FacesContext for the current request

systemEventClass - The Class of event that is being published.

sourceBaseType - The Class of the source event that must be used to lookup the listener to which this event must be published. If this argument is null the return from source.getClass() must be used as the sourceBaseType.

source - The source for the event of type systemEventClass.

Throws:

java.lang.NullPointerException - if any arguments are null

Since:

2.0

subscribeToEvent

public void subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
                             java.lang.Class<?> sourceClass,
                             SystemEventListener listener)

Install the listener instance referenced by argument listener into the application as a listener for events of type systemEventClass that originate from objects of type sourceClass.

If argument sourceClass is non-null, sourceClass and systemEventClass must be used to store the argument listener in the application in such a way that the listener can be quickly looked up by the implementation of publishEvent(javax.faces.context.FacesContext, java.lang.Class, java.lang.Object) given systemEventClass and an instance of the Class referenced by sourceClass. If argument sourceClass is null, the listener must be discoverable by the implementation of publishEvent(javax.faces.context.FacesContext, java.lang.Class, java.lang.Object) given only systemEventClass.

Parameters:

systemEventClass - the Class of event for which listener must be fired.

sourceClass - the Class of the instance which causes events of type systemEventClass to be fired. May be null.

listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(javax.faces.event.SystemEvent) method must be called when events of type systemEventClass are fired.

Throws:

NullPointerException - if any combination of systemEventClass, or listener are null.

Since:

2.0

subscribeToEvent

public void subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
                             SystemEventListener listener)

Install the listener instance referenced by argument listener into application as a listener for events of type systemEventClass. The default implementation simply calls through to subscribeToEvent(Class, Class, javax.faces.event.SystemEventListener) passing null as the sourceClass argument

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Parameters:

systemEventClass - the Class of event for which listener must be fired.

listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(javax.faces.event.SystemEvent) method must be called when events of type systemEventClass are fired.

Throws:

NullPointerException - if any combination of systemEventClass, or listener are null.

Since:

2.0

unsubscribeFromEvent

public void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
                                 java.lang.Class<?> sourceClass,
                                 SystemEventListener listener)

Remove the listener instance referenced by argument listener from the application as a listener for events of type systemEventClass that originate from objects of type sourceClass. See subscribeToEvent(Class, Class, javax.faces.event.SystemEventListener) for the specification of how the listener is stored, and therefore, how it must be removed.

Parameters:

systemEventClass - the Class of event for which listener must be fired.

sourceClass - the Class of the instance which causes events of type systemEventClass to be fired. May be null.

listener - the implementation of SystemEventListener to remove from the internal data structure.

Throws:

NullPointerException - if any combination of context, systemEventClass, or listener are null.

Since:

2.0

unsubscribeFromEvent

public void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
                                 SystemEventListener listener)

Remove the listener instance referenced by argument listener from the application as a listener for events of type systemEventClass. The default implementation simply calls through to unsubscribeFromEvent(Class, javax.faces.event.SystemEventListener) passing null as the sourceClass argument

Parameters:

systemEventClass - the Class of event for which listener must be fired.

listener - the implementation of SystemEventListener to remove from the internal data structure.

Throws:

NullPointerException - if any combination of context, systemEventClass, or listener are null. http://java.sun.com/javaee/javaserverfaces/reference/api/index.html

Since:

2.0