Class Application

java.lang.Object
jakarta.faces.application.Application
Direct Known Subclasses:
ApplicationWrapper

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

Holds webapp-wide resources for a Faces application. There is a single one of these for a web application, accessable via
 FacesContext.getCurrentInstance().getApplication()
 
In particular, this provides a factory for UIComponent objects. It also provides convenience methods for creating ValueBinding objects. See Javadoc of Faces Specification
  • Constructor Details

    • Application

      public Application()
  • Method Details

    • addBehavior

      public void addBehavior(String behaviorId, String behaviorClass)
      Parameters:
      behaviorId -
      behaviorClass -
      Since:
      2.0 FIXME: Notify EG, this should not be abstract and throw UnsupportedOperationException
    • addComponent

      public abstract void addComponent(String componentType, 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:
      NullPointerException - if componentType or componentClass is null
    • addConverter

      public abstract void addConverter(Class<?> targetClass, 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:
      NullPointerException - if targetClass or converterClass is null
    • addConverter

      public abstract void addConverter(String converterId, 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 converterId to be registered
      converterClass - - The fully qualified class name of the corresponding Converter implementation
      Throws:
      NullPointerException - if componentType or componentClass is null
    • addDefaultValidatorId

      public void addDefaultValidatorId(String validatorId)
      Parameters:
      validatorId -
      Since:
      2.0
    • addELContextListener

      public void addELContextListener(jakarta.el.ELContextListener listener)

      Provide a way for Faces applications to register an ELContextListener that will be notified on creation of ELContext instances.

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

      Since:
      1.2
    • addELResolver

      public void addELResolver(jakarta.el.ELResolver resolver)

      Cause an the argument resolver to be added to the resolver chain as specified in section 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. 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.

      Since:
      1.2
    • addValidator

      public abstract void addValidator(String validatorId, 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:
      NullPointerException - if validatorId or validatorClass is null
    • createBehavior

      public Behavior createBehavior(String behaviorId) throws FacesException
      Parameters:
      behaviorId -
      Returns:
      Throws:
      FacesException
      Since:
      2.0 FIXME: Notify EG, this should not be abstract and throw UnsupportedOperationException
    • createComponent

      public UIComponent createComponent(FacesContext context, Resource componentResource)
      ???
      Parameters:
      context -
      componentResource -
      Returns:
      Since:
      2.0
    • createComponent

      public UIComponent createComponent(FacesContext context, String componentType, String rendererType)
      Parameters:
      context -
      componentType -
      rendererType -
      Returns:
      Since:
      2.0
    • createComponent

      public abstract UIComponent createComponent(String componentType) throws FacesException

      Create a new UIComponent subclass, using the mappings defined by previous calls to the addComponent method of this class.

      Throws:
      FacesException - if there is no mapping defined for the specified componentType, or if an instance of the specified type could not be created for any reason.
    • createComponent

      public UIComponent createComponent(jakarta.el.ValueExpression componentExpression, FacesContext context, 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.

      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
      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(jakarta.el.ValueExpression componentExpression, FacesContext context, String componentType, String rendererType)
      Parameters:
      componentExpression -
      context -
      componentType -
      rendererType -
      Returns:
      Since:
      2.0
    • createConverter

      public abstract Converter createConverter(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.

      Parameters:
      targetClass - - Target class for which to return a Converter
      Throws:
      FacesException - if the Converter cannot be created
      NullPointerException - if targetClass is null
    • createConverter

      public abstract Converter createConverter(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
      NullPointerException - if converterId is null
    • createValidator

      public abstract Validator createValidator(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
      NullPointerException - if validatorId is null
    • evaluateExpressionGet

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

      Get a value by evaluating an expression.

      Call getExpressionFactory() then call ExpressionFactory.createValueExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class) passing the argument expression and expectedType. Call FacesContext.getELContext() and pass it to ValueExpression.getValue(jakarta.el.ELContext), returning the result.

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

      Throws:
      jakarta.el.ELException
    • 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 MethodExpression 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(jakarta.faces.context.FacesContext, java.lang.String, java.lang.String) passing:
      • the FacesContext for the current request
      • If there is a MethodExpression instance for the action property of this component, the result of calling Expression.getExpressionString() on it, null otherwise
      • the logical outcome as determined above

    • getBehaviorIds

      public Iterator<String> getBehaviorIds()
      Returns:
      Since:
      2.0 FIXME: Notify EG, this should not be abstract and throw UnsupportedOperationException
    • getComponentTypes

      public abstract Iterator<String> getComponentTypes()
      Return an Iterator over the set of currently defined component types for this Application.
    • getConverterIds

      public abstract Iterator<String> getConverterIds()
      Return an Iterator over the set of currently registered converter ids for this Application
      Returns:
    • getConverterTypes

      public abstract Iterator<Class<?>> getConverterTypes()
      Return an Iterator over the set of Class instances for which Converter classeshave been explicitly registered.
      Returns:
    • getDefaultLocale

      public abstract Locale getDefaultLocale()
      Return the default Locale for this application. If not explicitly set, null is returned.
      Returns:
    • getDefaultRenderKitId

      public abstract String getDefaultRenderKitId()
      Return the renderKitId to be used for rendering this application. If not explicitly set, null is returned.
      Returns:
    • getDefaultValidatorInfo

      public Map<String,String> getDefaultValidatorInfo()
      Returns:
      Since:
      2.0
    • getELContextListeners

      public jakarta.el.ELContextListener[] getELContextListeners()

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

      .

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

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

      Since:
      1.2
    • getELResolver

      public jakarta.el.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:
      • ELResolver instances declared using the <el-resolver> element in the application configuration resources.
      • An implementation that wraps the head of the legacy VariableResolver chain, as per section VariableResolver ChainWrapper in Chapter 5 in the spec document.
      • An implementation that wraps the head of the legacy PropertyResolver chain, as per section PropertyResolver ChainWrapper in Chapter 5 in the spec document.
      • Any ELResolver instances added by calls to addELResolver(jakarta.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
    • getExpressionFactory

      public jakarta.el.ExpressionFactory getExpressionFactory()

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

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

      Returns:
      Since:
      1.2
    • getMessageBundle

      public abstract 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.
    • 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.
    • 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 ProjectStage.PROJECT_STAGE_PARAM_NAME
      • If a value is found 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.
      Since:
      2.0
    • getResourceBundle

      public ResourceBundle getResourceBundle(FacesContext ctx, 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
      NullPointerException - if ctx == null || name == null
    • getResourceHandler

      public ResourceHandler getResourceHandler()

      Return the singleton, stateless, thread-safe ResourceHandler for this application. The Faces 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.
      • RELEASE_PENDING(edburns) It can also be declared via an annotation as specified in [287-ConfigAnnotations].

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

      Since:
      2.0
    • 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.
    • getSupportedLocales

      public abstract Iterator<Locale> getSupportedLocales()
      Return an Iterator over the supported Locales for this appication.
    • getValidatorIds

      public abstract Iterator<String> getValidatorIds()
      Return an Iterator over the set of currently registered validator ids for this Application.
    • getViewHandler

      public abstract ViewHandler getViewHandler()
      Set the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.
      Returns:
    • publishEvent

      public void publishEvent(FacesContext facesContext, Class<? extends SystemEvent> systemEventClass, Class<?> sourceBaseType, Object source)
      Parameters:
      facesContext -
      systemEventClass -
      sourceBaseType -
      source -
      Since:
      2.0
    • publishEvent

      public void publishEvent(FacesContext facesContext, Class<? extends SystemEvent> systemEventClass, Object source)

      If 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, jakarta.faces.event.SystemEventListener)

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

      If the act of invoking the processListener method causes an AbortProcessingException to be thrown, processing of the listeners must be aborted.

      Algorithm traverseListenerList: For each listener in the list,

      Parameters:
      systemEventClass - - The Class of event that is being published. Must be non-null.
      source - - The source for the event of type systemEventClass. Must be non- null, and must implement SystemEventListenerHolder.
      Since:
      2.0
    • removeELContextListener

      public void removeELContextListener(jakarta.el.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.

      Parameters:
      listener -
    • 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:
      NullPointerException - if listener is null
    • setDefaultLocale

      public abstract void setDefaultLocale(Locale locale)
      Set the default Locale for this application.
      Parameters:
      locale - - The new default Locale
      Throws:
      NullPointerException - if listener is null
    • setDefaultRenderKitId

      public abstract void setDefaultRenderKitId(String renderKitId)
      Return the renderKitId to be used for rendering this application. If not explicitly set, null is returned.
      Parameters:
      renderKitId -
    • setMessageBundle

      public abstract void setMessageBundle(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:
      NullPointerException - if bundle is null
    • 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
    • setResourceHandler

      public void setResourceHandler(ResourceHandler resourceHandler)
      Parameters:
      resourceHandler -
      Since:
      2.0
    • 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 StateManagerinstance
      Throws:
      IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.
      NullPointerException - if manager is null
    • setSupportedLocales

      public abstract void setSupportedLocales(Collection<Locale> locales)
      Set the Locale instances representing the supported Locales for this application.
      Parameters:
      locales - The set of supported Locales for this application
      Throws:
      NullPointerException - if the argument newLocales is null.
    • 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.
      NullPointerException - if handler is null
    • subscribeToEvent

      public void subscribeToEvent(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener)
      Parameters:
      systemEventClass -
      sourceClass -
      listener -
      Since:
      2.0
    • subscribeToEvent

      public void subscribeToEvent(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener)
      Parameters:
      systemEventClass -
      listener -
      Since:
      2.0
    • unsubscribeFromEvent

      public void unsubscribeFromEvent(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener)
      Parameters:
      systemEventClass -
      sourceClass -
      listener -
      Since:
      2.0
    • unsubscribeFromEvent

      public void unsubscribeFromEvent(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener)
      Parameters:
      systemEventClass -
      listener -
      Since:
      2.0
    • getFlowHandler

      public FlowHandler getFlowHandler()
      Returns:
      Since:
      2.2
    • setFlowHandler

      public void setFlowHandler(FlowHandler flowHandler)
      Parameters:
      flowHandler -
      Since:
      2.2
    • addSearchKeywordResolver

      public void addSearchKeywordResolver(SearchKeywordResolver resolver)
    • getSearchKeywordResolver

      public SearchKeywordResolver getSearchKeywordResolver()
    • getSearchExpressionHandler

      public SearchExpressionHandler getSearchExpressionHandler()
      Returns:
      Since:
      2.3
    • setSearchExpressionHandler

      public void setSearchExpressionHandler(SearchExpressionHandler searchExpressionHandler)
      Parameters:
      searchExpressionHandler -
      Since:
      2.3