Package jakarta.faces.application

Class Application

  • Direct Known Subclasses:
    ApplicationWrapper
    public abstract class Application
extends Object

    Application represents a per-web-application singleton object where applications based on Jakarta Faces (or implementations wishing to provide extended functionality) can register application-wide singletons that provide functionality required by Jakarta 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), and createValidator(java.lang.String).

    • 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 application. If not explicitly set, a default implementation must be provided that performs the functions as specified in the section 7.1.1 "ActionListener Property" in the chapter 7 "Application Integration" of the Jakarta Faces Specification Document.

        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.

        Returns:
        the action listener.

      • getDefaultLocale

        public abstract Locale getDefaultLocale()

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

        Returns:
        the default Locale, or null.

      • setDefaultLocale

        public abstract void setDefaultLocale​(Locale locale)

        Set the default Locale for this application.

        Parameters:
        locale - The new default Locale
        Throws:
        NullPointerException - if locale is null

      • getDefaultRenderKitId

        public abstract String getDefaultRenderKitId()

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

        Returns:
        the default render kit id, or null.

      • setDefaultRenderKitId

        public abstract void setDefaultRenderKitId​(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.

        Parameters:
        renderKitId - the render kit id to set.

      • getMessageBundle

        public abstract String getMessageBundle()

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

        Returns:
        the message bundle class name, or null.

      • setMessageBundle

        public abstract void setMessageBundle​(String bundle)

        Set the fully qualified class name of the ResourceBundle to be used for Jakarta 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

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

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

        The runtime must employ the decorator pattern as for every other pluggable artifact in Jakarta Faces.

        Returns:
        the navigation handler.

      • getResourceHandler

        public ResourceHandler getResourceHandler()

        Return the singleton, stateless, thread-safe ResourceHandler for this application. The Jakarta 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.

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

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

        .
        Returns:
        the resource handler.
        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.
        NullPointerException - if resourceHandler is null
        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.

        Parameters:
        ctx - the Faces context.
        name - the name of the resource bundle.
        Returns:
        the resource bundle.
        Throws:
        FacesException - if a bundle was defined, but not resolvable
        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

        .
        Returns:
        the project stage.
        Since:
        2.0

      • addELResolver

        public void addELResolver​(ELResolver resolver)

        Cause an the argument resolver to be added to the resolver chain as specified in section 5.3.2 "ELResolver" of the Jakarta Faces Specification Document.

        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 Jakarta Server Pages 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.

        Parameters:
        resolver - the Jakarta Expression Language resolver to add.
        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 Jakarta Expression Language 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 5 in the spec document.

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

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

        Returns:
        the Jakarta Expression Language resolver.
        Since:
        1.2

      • getFlowHandler

        public FlowHandler getFlowHandler()

        Return the thread-safe singleton FlowHandler for this application. For implementations declaring compliance with version 2.2 of the specification, this method must never return null, even if the application has no flows. This is necessary to enable dynamic flow creation during the application's lifetime.

        All implementations that declare compliance with version 2.2 of the specification must implement this method. For the purpose of backward compatibility with environments that extend Application but do not override this method, an implementation is provided that returns null. Due to the decoratable nature of Application, code calling this method should always check for a null return.

        Returns:
        the flow handler.
        Since:
        2.2

      • setFlowHandler

        public void setFlowHandler​(FlowHandler newHandler)

        Set the FlowHandler instance used by the NavigationHandler to satisfy the requirements of the faces flows feature.

        Parameters:
        newHandler - the flow handler to set.
        Throws:
        NullPointerException - if newHandler is null
        IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.
        Since:
        2.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 Jakarta Faces Specification.

        Returns:
        the view handler.

      • 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

      • 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 Jakarta Faces Specification.

        Returns:
        the state manager.

      • 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.
        NullPointerException - if manager is null

      • addBehavior

        public void addBehavior​(String behaviorId,
                        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:
        NullPointerException - if behaviorId or behaviorClass is null
        Since:
        2.0

      • createBehavior

        public Behavior createBehavior​(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
        Returns:
        the behavior.
        Throws:
        FacesException - if the Behavior cannot be created
        NullPointerException - if behaviorId is null

      • getBehaviorIds

        public Iterator<String> getBehaviorIds()

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

        Returns:
        an iterator with behavior ids.

      • 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

      • getComponentTypes

        public abstract Iterator<String> getComponentTypes()

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

        Returns:
        an iterator with component types.

      • 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 converter id to be registered
        converterClass - The fully qualified class name of the corresponding Converter implementation
        Throws:
        NullPointerException - if converterId or converterClass 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

      • 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 the toLowerCase() of the String represenation of the value of the "jakarta.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
        Returns:
        the converter.
        Throws:
        FacesException - if the Converter cannot be created
        NullPointerException - if converterId is null

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

        If the toLowerCase() of the String represenation of the value of the "jakarta.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
        Returns:
        the converter.
        Throws:
        FacesException - if the Converter cannot be created
        NullPointerException - if targetClass is null

      • getConverterIds

        public abstract Iterator<String> getConverterIds()

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

        Returns:
        an iterator with converter ids.

      • getConverterTypes

        public abstract Iterator<Class<?>> getConverterTypes()

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

        Returns:
        an iterator with converter types.

      • addDefaultValidatorId

        public void addDefaultValidatorId​(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.

        Parameters:
        validatorId - the validator id.
        Since:
        2.0

      • getDefaultValidatorInfo

        public Map<String,​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.

        Returns:
        a map of default validator information.
        Since:
        2.0

      • getSupportedLocales

        public abstract Iterator<Locale> getSupportedLocales()

        Return an Iterator over the supported Locales for this appication.

        Returns:
        an iterator of the supported locales.

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

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

        Parameters:
        listener - the Jakarta Expression Language context listener to add.
        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.

        Parameters:
        listener - the Jakarta Expression Language context listener to remove.
        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

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

        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
        Returns:
        the validator.
        Throws:
        FacesException - if a Validator of the specified id cannot be created
        NullPointerException - if validatorId is null

      • getValidatorIds

        public abstract Iterator<String> getValidatorIds()

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

        Returns:
        an iterator of validator ids.

      • publishEvent

        public void publishEvent​(FacesContext context,
                         Class<? extends SystemEvent> systemEventClass,
                         Class<?> sourceBaseType,
                         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:
        NullPointerException - if any arguments except for sourceBaseType are null
        Since:
        2.0

      • addSearchKeywordResolver

        public void addSearchKeywordResolver​(SearchKeywordResolver resolver)

        Cause the argument resolver to be added to the head of the resolver chain.

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

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

        Parameters:
        resolver - the SearchKeywordResolver to add.
        Throws:
        IllegalStateException - if called after the first request to the FacesServlet has been serviced.
        NullPointerException - when resolver is null.
        Since:
        2.3

      • getSearchKeywordResolver

        public SearchKeywordResolver getSearchKeywordResolver()

        Return the singleton SearchKeywordResolver instance to be used for all search keyword resolution. This is actually an instance of a composite SearchKeywordResolver that must contain the following SearchKeywordResolver instances in the following order:

        1. SearchKeywordResolver instances declared using the <search-keyword-resolver> element in the application configuration resources.

        2. Any SearchKeywordResolver instances added by calls to addSearchKeywordResolver(jakarta.faces.component.search.SearchKeywordResolver).

        3. The SearchKeywordResolver implementations for @all, @child(n), @form, @id(...), @namingcontainer, @next, @none, @parent, @previous, @root and @this.

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

        Returns:
        the SearchKeywordResolver.
        Since:
        2.3