Class Application
- Direct Known Subclasses:
ApplicationImpl
,ApplicationWrapper
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 Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addBehavior
(String behaviorId, String behaviorClass) Register a new mapping of behavior id to the name of the correspondingBehavior
class.abstract void
addComponent
(String componentType, String componentClass) Register a new mapping of component type to the name of the correspondingUIComponent
class.abstract void
addConverter
(Class<?> targetClass, String converterClass) Register a new converter class that is capable of performing conversions for the specified target class.abstract void
addConverter
(String converterId, String converterClass) Register a new mapping of converter id to the name of the correspondingConverter
class.void
addDefaultValidatorId
(String validatorId) Register a validator by its id that is applied to allUIInput
components in a view.void
addELContextListener
(jakarta.el.ELContextListener listener) Provide a way for Faces applications to register anELContextListener
that will be notified on creation ofELContext
instances.void
addELResolver
(jakarta.el.ELResolver resolver) Cause an the argumentresolver
to be added to the resolver chain as specified in section 5.3.2 "ELResolver" of the Jakarta Faces Specification Document.void
Cause the argumentresolver
to be added to the head of the resolver chain.abstract void
addValidator
(String validatorId, String validatorClass) Register a new mapping of validator id to the name of the correspondingValidator
class.createBehavior
(String behaviorId) Instantiate and return a newBehavior
instance of the class specified by a previous call toaddBehavior()
for the specified behavior id.createComponent
(jakarta.el.ValueExpression componentExpression, FacesContext context, String componentType) Call thegetValue()
method on the specifiedValueExpression
.createComponent
(jakarta.el.ValueExpression componentExpression, FacesContext context, String componentType, String rendererType) LikecreateComponent(ValueExpression, FacesContext, String)
except theRenderer
for the component to be returned must be inspected for the annotations mentioned increateComponent(ValueExpression, FacesContext, String)
as specified in the documentation for that method.createComponent
(FacesContext context, Resource componentResource) createComponent
(FacesContext context, String componentType, String rendererType) LikecreateComponent(String)
except theRenderer
for the component to be returned must be inspected for the annotations mentioned increateComponent(ValueExpression, FacesContext, String)
as specified in the documentation for that method.abstract UIComponent
createComponent
(String componentType) Instantiate and return a newUIComponent
instance of the class specified by a previous call toaddComponent()
for the specified component type.abstract Converter
createConverter
(Class<?> targetClass) Instantiate and return a newConverter
instance of the class that has registered itself as capable of performing conversions for objects of the specified type.abstract Converter
createConverter
(String converterId) Instantiate and return a newConverter
instance of the class specified by a previous call toaddConverter()
for the specified converter id.abstract Validator
createValidator
(String validatorId) Instantiate and return a newValidator
instance of the class specified by a previous call toaddValidator()
for the specified validator id.<T> T
evaluateExpressionGet
(FacesContext context, String expression, Class<? extends T> expectedType) Get a value by evaluating an expression.abstract ActionListener
Return the defaultActionListener
to be registered for allActionSource
components in this application.Return anIterator
over the set of currently registered behavior ids for thisApplication
.Return anIterator
over the set of currently defined component types for thisApplication
.Return anIterator
over the set of currently registered converter ids for thisApplication
.Return anIterator
over the set ofClass
instances for whichConverter
classes have been explicitly registered.abstract Locale
Return the defaultLocale
for this application.abstract String
Return therenderKitId
to be used for rendering this application.Return an immutableMap
over the set of currently registered default validator IDs and their class name for thisApplication
.jakarta.el.ELContextListener[]
If no calls have been made toaddELContextListener(jakarta.el.ELContextListener)
, this method must return an empty array.jakarta.el.ELResolver
Return the singletonELResolver
instance to be used for all Jakarta Expression Language resolution.jakarta.el.ExpressionFactory
Return theExpressionFactory
instance for this application.Return the thread-safe singletonFlowHandler
for this application.abstract String
Return the fully qualified class name of theResourceBundle
to be used for Jakarta Faces messages for this application.abstract NavigationHandler
Return theNavigationHandler
instance that will be passed the outcome returned by any invoked application action for this web application.Return the project stage for the currently running application instance.getResourceBundle
(FacesContext ctx, String name) Find aResourceBundle
as defined in the application configuration resources under the specified name.Return the singleton, stateless, thread-safeResourceHandler
for this application.Return the thread-safe singletonSearchExpressionHandler
for this application.Return the singletonSearchKeywordResolver
instance to be used for all search keyword resolution.abstract StateManager
Return theStateManager
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.Return anIterator
over the supportedLocale
s for this appication.Return anIterator
over the set of currently registered validator ids for thisApplication
.abstract ViewHandler
Return theViewHandler
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.void
publishEvent
(FacesContext context, Class<? extends SystemEvent> systemEventClass, Class<?> sourceBaseType, Object source) This method functions exactly likepublishEvent(FacesContext,Class,Object)
, except the run-time must use the argumentsourceBaseType
to find the matching listener instead of using theClass
of thesource
argument.void
publishEvent
(FacesContext context, Class<? extends SystemEvent> systemEventClass, Object source) IfFacesContext.isProcessingEvents()
istrue
and there are one or more listeners for events of the type represented bysystemEventClass
, call those listeners, passingsource
as the source of the event.void
removeELContextListener
(jakarta.el.ELContextListener listener) Remove the argumentlistener
from the list ofELContextListener
s.abstract void
setActionListener
(ActionListener listener) Set the defaultActionListener
to be registered for allActionSource
components.abstract void
setDefaultLocale
(Locale locale) Set the defaultLocale
for this application.abstract void
setDefaultRenderKitId
(String renderKitId) Set therenderKitId
to be used to render this application.void
setFlowHandler
(FlowHandler newHandler) Set theFlowHandler
instance used by theNavigationHandler
to satisfy the requirements of the faces flows feature.abstract void
setMessageBundle
(String bundle) Set the fully qualified class name of theResourceBundle
to be used for Jakarta Faces messages for this application.abstract void
setNavigationHandler
(NavigationHandler handler) Set theNavigationHandler
instance that will be passed the outcome returned by any invoked application action for this web application.void
setResourceHandler
(ResourceHandler resourceHandler) Set theResourceHandler
instance that will be utilized for rendering the markup for resources, and for satisfying client requests to serve up resources.void
setSearchExpressionHandler
(SearchExpressionHandler searchExpressionHandler) Set theSearchExpressionHandler
instance used by the application.abstract void
setStateManager
(StateManager manager) Set theStateManager
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.abstract void
setSupportedLocales
(Collection<Locale> locales) Set theLocale
instances representing the supportedLocale
s for this application.abstract void
setViewHandler
(ViewHandler handler) Set theViewHandler
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.void
subscribeToEvent
(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Install the listener instance referenced by argumentlistener
into application as a listener for events of typesystemEventClass
.void
subscribeToEvent
(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener) Install the listener instance referenced by argumentlistener
into the application as a listener for events of typesystemEventClass
that originate from objects of typesourceClass
.void
unsubscribeFromEvent
(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Remove the listener instance referenced by argumentlistener
from the application as a listener for events of typesystemEventClass
.void
unsubscribeFromEvent
(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener) Remove the listener instance referenced by argumentlistener
from the application as a listener for events of typesystemEventClass
that originate from objects of typesourceClass
.
-
Constructor Details
-
Application
public Application()
-
-
Method Details
-
getActionListener
Return the default
ActionListener
to be registered for allActionSource
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 defaultActionListener
must continue to work with components that do not implementActionSource2
, and only implementActionSource
.- Returns:
- the action listener.
-
setActionListener
Set the default
ActionListener
to be registered for allActionSource
components.- Parameters:
listener
- The new defaultActionListener
- Throws:
NullPointerException
- iflistener
isnull
-
getDefaultLocale
Return the default
Locale
for this application. If not explicitly set,null
is returned.- Returns:
- the default Locale, or
null
.
-
setDefaultLocale
Set the default
Locale
for this application.- Parameters:
locale
- The new defaultLocale
- Throws:
NullPointerException
- iflocale
isnull
-
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
Set the
renderKitId
to be used to render this application. Unless the client has provided a customViewHandler
that supports the use of multipleRenderKit
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
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
Set the fully qualified class name of the
ResourceBundle
to be used for Jakarta Faces messages for this application. See the JavaDocs for thejava.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
- ifbundle
isnull
-
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 ofResourceHandler
.-
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 decorateApplication
can continue to function- Returns:
- the resource handler.
- Since:
- 2.0
-
-
setResourceHandler
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 newResourceHandler
instance- Throws:
IllegalStateException
- if this method is called after at least one request has been processed by theLifecycle
instance for this application.NullPointerException
- ifresourceHandler
isnull
- Since:
- 2.0
-
getResourceBundle
Find a
ResourceBundle
as defined in the application configuration resources under the specified name. If aResourceBundle
was defined for the name, return an instance that uses the locale of the currentUIViewRoot
.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 resolvableNullPointerException
- if ctx == null || name == null- Since:
- 1.2
-
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 ofProjectStage.PROJECT_STAGE_JNDI_NAME
(return type ofjava.lang.String
). If found, continue with the algorithm below, otherwise, look for an entry in theinitParamMap
of theExternalContext
from the currentFacesContext
with the key given by the value ofProjectStage.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 theinitParamMap
. 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 decorateApplication
can continue to function- Returns:
- the project stage.
- Since:
- 2.0
-
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.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, anIllegalStateException
must be thrown. This restriction is in place to allow the Jakarta Server Pages container to optimize for the common case where no additionalELResolver
s are in the chain, aside from the standard ones. It is permissible to addELResolver
s before or after initialization to aCompositeELResolver
that is already in the chain.The default implementation throws
UnsupportedOperationException
and is provided for the sole purpose of not breaking existing applications that extendApplication
.- Parameters:
resolver
- the Jakarta Expression Language resolver to add.- Throws:
IllegalStateException
- if called after the first request to theFacesServlet
has been serviced.- Since:
- 1.2
-
getELResolver
public jakarta.el.ELResolver getELResolver()Return the singleton
ELResolver
instance to be used for all Jakarta Expression Language resolution. This is actually an instance ofCompositeELResolver
that must contain the followingELResolver
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 legacyVariableResolver
chain, as per section VariableResolver ChainWrapper in Chapter 5 in the spec document. -
An
implementation
that wraps the head of the legacyPropertyResolver
chain, as per section PropertyResolver ChainWrapper in Chapter 5 in the spec document. -
Any
ELResolver
instances added by calls toaddELResolver(jakarta.el.ELResolver)
.
The default implementation throws
UnsupportedOperationException
and is provided for the sole purpose of not breaking existing applications that extendApplication
.- Returns:
- the Jakarta Expression Language resolver.
- Since:
- 1.2
-
-
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 returnnull
, 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 returnsnull
. Due to the decoratable nature ofApplication
, code calling this method should always check for anull
return.- Returns:
- the flow handler.
- Since:
- 2.2
-
setFlowHandler
Set the
FlowHandler
instance used by theNavigationHandler
to satisfy the requirements of the faces flows feature.- Parameters:
newHandler
- the flow handler to set.- Throws:
NullPointerException
- if newHandler isnull
IllegalStateException
- if this method is called after at least one request has been processed by theLifecycle
instance for this application.- Since:
- 2.2
-
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 theViewHandler
description in the Jakarta Faces Specification.- Returns:
- the view handler.
-
setViewHandler
Set the
ViewHandler
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.- Parameters:
handler
- The newViewHandler
instance- Throws:
IllegalStateException
- if this method is called after at least one request has been processed by theLifecycle
instance for this application.NullPointerException
- ifhandler
isnull
-
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 theStateManager
description in the Jakarta Faces Specification.- Returns:
- the state manager.
-
setStateManager
Set the
StateManager
instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.- Parameters:
manager
- The newStateManager
instance- Throws:
IllegalStateException
- if this method is called after at least one request has been processed by theLifecycle
instance for this application.NullPointerException
- ifmanager
isnull
-
addBehavior
Register a new mapping of behavior id to the name of the corresponding
Behavior
class. This allows subsequent calls tocreateBehavior()
to serve as a factory forBehavior
instances.- Parameters:
behaviorId
- The behavior id to be registeredbehaviorClass
- The fully qualified class name of the correspondingBehavior
implementation- Throws:
NullPointerException
- ifbehaviorId
orbehaviorClass
isnull
- Since:
- 2.0
-
createBehavior
Instantiate and return a new
Behavior
instance of the class specified by a previous call toaddBehavior()
for the specified behavior id.- Parameters:
behaviorId
- The behavior id for which to create and return a newBehavior
instance- Returns:
- the behavior.
- Throws:
FacesException
- if theBehavior
cannot be createdNullPointerException
- ifbehaviorId
isnull
-
getBehaviorIds
Return an
Iterator
over the set of currently registered behavior ids for thisApplication
.- Returns:
- an iterator with behavior ids.
-
addComponent
Register a new mapping of component type to the name of the corresponding
UIComponent
class. This allows subsequent calls tocreateComponent()
to serve as a factory forUIComponent
instances.- Parameters:
componentType
- The component type to be registeredcomponentClass
- The fully qualified class name of the correspondingUIComponent
implementation- Throws:
NullPointerException
- ifcomponentType
orcomponentClass
isnull
-
createComponent
Instantiate and return a new
UIComponent
instance of the class specified by a previous call toaddComponent()
for the specified component type.Before the component instance is returned, it must be inspected for the presence of a
ListenerFor
(orListenersFor
) orResourceDependency
(orResourceDependencies
) annotation. If any of these annotations are present, the action listed inListenerFor
orResourceDependency
must be taken on the component, before it is returned from this method. This variant ofcreateComponent
must not inspect theRenderer
for the component to be returned for any of the afore mentioned annotations. Such inspection is the province ofcreateComponent(ValueExpression, FacesContext, String, String)
orcreateComponent(FacesContext, String, String)
.- Parameters:
componentType
- The component type for which to create and return a newUIComponent
instance- Returns:
- the UI component.
- Throws:
FacesException
- if aUIComponent
of the specified type cannot be createdNullPointerException
- ifcomponentType
isnull
-
createComponent
public UIComponent createComponent(jakarta.el.ValueExpression componentExpression, FacesContext context, String componentType) throws FacesException Call the
getValue()
method on the specifiedValueExpression
. If it returns aUIComponent
instance, return it as the value of this method. If it does not, instantiate a newUIComponent
instance of the specified component type, pass the new component to thesetValue()
method of the specifiedValueExpression
, and return it.Before the component instance is returned, it must be inspected for the presence of a
ListenerFor
(orListenersFor
) orResourceDependency
(orResourceDependencies
) annotation. If any of these annotations are present, the action listed inListenerFor
orResourceDependency
must be taken on the component, before it is returned from this method. This variant ofcreateComponent
must not inspect theRenderer
for the component to be returned for any of the afore mentioned annotations. Such inspection is the province ofcreateComponent(ValueExpression, FacesContext, String, String)
orcreateComponent(FacesContext, String, String)
.A default implementation is provided that throws
UnsupportedOperationException
so that users that decorateApplication
can continue to function.- Parameters:
componentExpression
-ValueExpression
representing a component value expression (typically specified by thecomponent
attribute of a custom tag)context
-FacesContext
for the current requestcomponentType
- Component type to create if theValueExpression
does not return a component instance- Returns:
- the UI component.
- Throws:
FacesException
- if aUIComponent
cannot be createdNullPointerException
- if any parameter isnull
- Since:
- 1.2
-
createComponent
public UIComponent createComponent(jakarta.el.ValueExpression componentExpression, FacesContext context, String componentType, String rendererType) Like
createComponent(ValueExpression, FacesContext, String)
except theRenderer
for the component to be returned must be inspected for the annotations mentioned increateComponent(ValueExpression, FacesContext, String)
as specified in the documentation for that method. TheRenderer
instance to inspect must be obtained by callingFacesContext.getRenderKit()
and callingRenderKit.getRenderer(java.lang.String, java.lang.String)
on the result, passing the argumentcomponentType
as the first argument and the result of callingUIComponent.getFamily()
on the newly created component as the second argument. If no suchRenderer
can be found, a message must be logged with a helpful error message. Otherwise,UIComponent.setRendererType(java.lang.String)
must be called on the newly createdUIComponent
instance, passing the argumentrendererType
as the argument.A default implementation is provided that throws
UnsupportedOperationException
so that users that decorateApplication
can continue to function.- Parameters:
componentExpression
-ValueExpression
representing a component value expression (typically specified by thecomponent
attribute of a custom tag)context
-FacesContext
for the current requestcomponentType
- Component type to create if theValueExpression
does not return a component instancerendererType
- The renderer-type of theRenderer
that will render this component. Anull
value must be accepted for this parameter.- Returns:
- the UI component.
- Throws:
FacesException
- if aUIComponent
cannot be createdNullPointerException
- if any of the parameterscomponentExpression
,context
, orcomponentType
arenull
- Since:
- 2.0
-
createComponent
Like
createComponent(String)
except theRenderer
for the component to be returned must be inspected for the annotations mentioned increateComponent(ValueExpression, FacesContext, String)
as specified in the documentation for that method. TheRenderer
instance to inspect must be obtained by callingFacesContext.getRenderKit()
and callingRenderKit.getRenderer(java.lang.String, java.lang.String)
on the result, passing the argumentcomponentType
as the first argument and the result of callingUIComponent.getFamily()
on the newly created component as the second argument. If no suchRenderer
can be found, a message must be logged with a helpful error message. Otherwise,UIComponent.setRendererType(java.lang.String)
must be called on the newly createdUIComponent
instance, passing the argumentrendererType
as the argument.A default implementation is provided that throws
.UnsupportedOperationException
so that users that decorateApplication
can continue to function- Parameters:
context
-FacesContext
for the current requestcomponentType
- Component type to createrendererType
- The renderer-type of theRenderer
that will render this component. Anull
value must be accepted for this parameter.- Returns:
- the UI component.
- Throws:
FacesException
- if aUIComponent
cannot be createdNullPointerException
- if any of the parameterscontext
, orcomponentType
arenull
- Since:
- 2.0
-
createComponent
Instantiate and return a new
UIComponent
instance from the argumentResource
. An algorithm semantically equivalent to the following must be followed to instantiate theUIComponent
to return.-
Obtain a reference to the
ViewDeclarationLanguage
for thisApplication
instance by callingViewHandler.getViewDeclarationLanguage(jakarta.faces.context.FacesContext, java.lang.String)
, passing theviewId
found by callingUIViewRoot.getViewId()
on theUIViewRoot
in the argumentFacesContext
. -
Obtain a reference to the composite component metadata for this composite component by calling
ViewDeclarationLanguage.getComponentMetadata(jakarta.faces.context.FacesContext, jakarta.faces.application.Resource)
, passing thefacesContext
andcomponentResource
arguments to this method. This version of the Jakarta Faces Specification uses JavaBeans as the API to the component metadata. -
Determine if the component author declared a
componentType
for this component instance by obtaining theBeanDescriptor
from the component metadata and calling itsgetValue()
method, passingUIComponent.COMPOSITE_COMPONENT_TYPE_KEY
as the argument. If non-null
, the result must be aValueExpression
whose value is thecomponent-type
of theUIComponent
to be created for thisResource
component. Call through tocreateComponent(java.lang.String)
to create the component. -
Otherwise, determine if a script based component for this
Resource
can be found by callingViewDeclarationLanguage.getScriptComponentResource(jakarta.faces.context.FacesContext, jakarta.faces.application.Resource)
. If the result is non-null
, and is a script written in a language satisfying the content typetext/javascript
, create aUIComponent
instance from the script resource. -
Otherwise, let library-name be the return from calling
Resource.getLibraryName()
on the argumentcomponentResource
and resource-name be the return from callingResource.getResourceName()
on the argumentcomponentResource
. Create a fully qualified Java class name by removing any file extension from resource-name and let fqcn belibrary-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 ofInstantiationException
,IllegalAccessException
, orClassCastException
are thrown, wrap the exception in aFacesException
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, callcreateComponent(java.lang.String)
passing "jakarta.faces.NamingContainer
" as the argument. -
Call
UIComponent.setRendererType(java.lang.String)
on theUIComponent
instance, passing "jakarta.faces.Composite
" as the argument. -
Store the argument
Resource
in the attributesMap
of theUIComponent
under the key,Resource.COMPONENT_RESOURCE_KEY
. -
Store composite component metadata in the attributes
Map
of theUIComponent
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 inListenerFor
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 decorateApplication
can continue to function.- Parameters:
context
-FacesContext
for the current requestcomponentResource
- AResource
that points to a source file that provides an implementation of a component.- Returns:
- the UI component.
- Throws:
FacesException
- if aUIComponent
from theResource
cannot be createdNullPointerException
- if any parameter isnull
NullPointerException
- if unable, for any reason, to obtain aViewDeclarationLanguage
instance as described above.- Since:
- 2.0
-
-
getComponentTypes
Return an
Iterator
over the set of currently defined component types for thisApplication
.- Returns:
- an iterator with component types.
-
addConverter
Register a new mapping of converter id to the name of the corresponding
Converter
class. This allows subsequent calls tocreateConverter()
to serve as a factory forConverter
instances.- Parameters:
converterId
- The converter id to be registeredconverterClass
- The fully qualified class name of the correspondingConverter
implementation- Throws:
NullPointerException
- ifconverterId
orconverterClass
isnull
-
addConverter
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 registeredconverterClass
- The fully qualified class name of the correspondingConverter
implementation- Throws:
NullPointerException
- iftargetClass
orconverterClass
isnull
-
createConverter
Instantiate and return a new
Converter
instance of the class specified by a previous call toaddConverter()
for the specified converter id.If the
toLowerCase()
of theString
represenation of the value of the "jakarta.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE
" application configuration parameter is "true
" (without the quotes) and theConverter
instance to be returned is an instance ofDateTimeConverter
,DateTimeConverter.setTimeZone(java.util.TimeZone)
must be called, passing the return fromTimeZone.getDefault()
.The argument
converter
must be inspected for the presence of theResourceDependency
annotation. If theResourceDependency
annotation is present, the action described inResourceDependency
must be taken. If theResourceDependency
annotation is not present, the argumentconverter
must be inspected for the presence of theResourceDependencies
annotation. If theResourceDependencies
annotation is present, the action described inResourceDependencies
must be taken.- Parameters:
converterId
- The converter id for which to create and return a newConverter
instance- Returns:
- the converter.
- Throws:
FacesException
- if theConverter
cannot be createdNullPointerException
- ifconverterId
isnull
-
createConverter
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 suchConverter
class can be identified, returnnull
.To locate an appropriate
Converter
class, the following algorithm is performed, stopping as soon as an appropriateConverter
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 aClass
, instantiate theConverter
using that constructor, passing the argumenttargetClass
as the sole argument. Otherwise, simply use the zero-argument constructor.If the
toLowerCase()
of theString
represenation of the value of the "jakarta.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE
" application configuration parameter is "true
" (without the quotes) and theConverter
instance to be returned is an instance ofDateTimeConverter
,DateTimeConverter.setTimeZone(java.util.TimeZone)
must be called, passing the return fromTimeZone.getDefault()
.- Parameters:
targetClass
- Target class for which to return aConverter
- Returns:
- the converter.
- Throws:
FacesException
- if theConverter
cannot be createdNullPointerException
- iftargetClass
isnull
- Locate a
-
getConverterIds
Return an
Iterator
over the set of currently registered converter ids for thisApplication
.- Returns:
- an iterator with converter ids.
-
getConverterTypes
Return an
Iterator
over the set ofClass
instances for whichConverter
classes have been explicitly registered.- Returns:
- an iterator with converter types.
-
addDefaultValidatorId
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 theBeanValidator
. 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
Return an immutable
Map
over the set of currently registered default validator IDs and their class name for thisApplication
.An implementation is provided that returns
Collections.emptyMap
so that users that decorate theApplication
continue to work.- Returns:
- a map of default validator information.
- Since:
- 2.0
-
getExpressionFactory
public jakarta.el.ExpressionFactory getExpressionFactory()Return the
ExpressionFactory
instance for this application. This instance is used by the convenience methodevaluateExpressionGet(jakarta.faces.context.FacesContext, java.lang.String, java.lang.Class<? extends T>)
.The implementation must return the
ExpressionFactory
from the Expression Language container by callingjakarta.el.ELManager.getExpressionFactory()
.An implementation is provided that throws
UnsupportedOperationException
so that users that decorate theApplication
continue to work.- Returns:
- the expression factory.
- Since:
- 1.2
-
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 callExpressionFactory.createValueExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class<?>)
passing the argumentexpression
andexpectedType
. CallFacesContext.getELContext()
and pass it toValueExpression.getValue(jakarta.el.ELContext)
, returning the result.An implementation is provided that throws
UnsupportedOperationException
so that users that decorate theApplication
continue to work.- Type Parameters:
T
- the return type.- Parameters:
context
- the Faces context.expression
- the expression.expectedType
- the expected type.- Returns:
- the result of the evaluation.
- Throws:
jakarta.el.ELException
-
getSupportedLocales
Return an
Iterator
over the supportedLocale
s for this appication.- Returns:
- an iterator of the supported locales.
-
setSupportedLocales
Set the
Locale
instances representing the supportedLocale
s for this application.- Parameters:
locales
- The set of supportedLocale
s for this application- Throws:
NullPointerException
- if the argumentnewLocales
isnull
.
-
addELContextListener
public void addELContextListener(jakarta.el.ELContextListener listener) Provide a way for Faces applications to register an
ELContextListener
that will be notified on creation ofELContext
instances. This listener will be called once per request.An implementation is provided that throws
UnsupportedOperationException
so that users that decorate theApplication
continue to work.- Parameters:
listener
- the Jakarta Expression Language context listener to add.- Since:
- 1.2
-
removeELContextListener
public void removeELContextListener(jakarta.el.ELContextListener listener) Remove the argument
listener
from the list ofELContextListener
s. Iflistener
is null, no exception is thrown and no action is performed. Iflistener
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 theApplication
continue to work.- Parameters:
listener
- the Jakarta Expression Language context listener to remove.- Since:
- 1.2
-
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 theApplication
continue to work.- Returns:
- an array of Jakarta Expression Language context listeners.
- Since:
- 1.2
-
addValidator
Register a new mapping of validator id to the name of the corresponding
Validator
class. This allows subsequent calls tocreateValidator()
to serve as a factory forValidator
instances.- Parameters:
validatorId
- The validator id to be registeredvalidatorClass
- The fully qualified class name of the correspondingValidator
implementation- Throws:
NullPointerException
- ifvalidatorId
orvalidatorClass
isnull
-
createValidator
Instantiate and return a new
Validator
instance of the class specified by a previous call toaddValidator()
for the specified validator id.The argument
validator
must be inspected for the presence of theResourceDependency
annotation. If theResourceDependency
annotation is present, the action described inResourceDependency
must be taken. If theResourceDependency
annotation is not present, the argumentvalidator
must be inspected for the presence of theResourceDependencies
annotation. If theResourceDependencies
annotation is present, the action described inResourceDependencies
must be taken.- Parameters:
validatorId
- The validator id for which to create and return a newValidator
instance- Returns:
- the validator.
- Throws:
FacesException
- if aValidator
of the specified id cannot be createdNullPointerException
- ifvalidatorId
isnull
-
getValidatorIds
Return an
Iterator
over the set of currently registered validator ids for thisApplication
.- Returns:
- an iterator of validator ids.
-
publishEvent
public void publishEvent(FacesContext context, Class<? extends SystemEvent> systemEventClass, Object source) If
FacesContext.isProcessingEvents()
istrue
and there are one or more listeners for events of the type represented bysystemEventClass
, call those listeners, passingsource
as the source of the event. The implementation should be as fast as possible in determining whether or not a listener for the givensystemEventClass
andsource
has been installed, and should return immediately once such a determination has been made. The implementation ofpublishEvent
must honor the requirements stated insubscribeToEvent(java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Class<?>, jakarta.faces.event.SystemEventListener)
regarding the storage and retrieval of listener instances. Specifically, ifsubscribeToEvent(Class,Class,SystemEventListener)
was called, thesourceClass
argument must match exactly theClass
of thesource
argument in the call topublishEvent()
. The implementation must not do any inheritance hierarachy inspection when looking for a match between thesourceClass
passed tosubscribeToEvent(Class,Class,SystemEventListener)
and thesourceClass
passed topublishEvent()
in order to find any listeners to which the event should be published. In the case where theClass
of thesource
argument does not match theClass
of thesourceClass
used when the listener was subscribed usingsubscribeToEvent()
,publishEvent(FacesContext,Class,Class,Object)
can be used to provide theClass
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 implementsSystemEventListenerHolder
, callSystemEventListenerHolder.getListenersForEventClass(java.lang.Class<? extends jakarta.faces.event.SystemEvent>)
on it, passing thesystemEventClass
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, jakarta.faces.event.SystemEventListener)
on theUIViewRoot
, perform algorithm traverseListenerList on the list of listeners for that event installed on theUIViewRoot
. -
If any
Application
level listeners have been installed by previous calls tosubscribeToEvent(Class, Class, jakarta.faces.event.SystemEventListener)
, perform algorithm traverseListenerList on the list. -
If any
Application
level listeners have been installed by previous calls tosubscribeToEvent(Class, jakarta.faces.event.SystemEventListener)
, perform algorithm traverseListenerList on the list.
If the act of invoking the
processListener
method causes anAbortProcessingException
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 withLevel.SEVERE
.Algorithm traverseListenerList: For each listener in the list,
-
Call
SystemEventListener.isListenerForSource(java.lang.Object)
, passing thesource
argument. If this returnsfalse
, 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 anObject
. This same event instance must be passed to all listener instances. -
Call
SystemEvent.isAppropriateListener(jakarta.faces.event.FacesListener)
, passing the listener instance as the argument. If this returnsfalse
, take no action on the listener. -
Call
SystemEvent.processListener(jakarta.faces.event.FacesListener)
, passing the listener instance.
A default implementation is provided that throws
.UnsupportedOperationException
so that users that decorateApplication
can continue to function- Parameters:
context
- theFacesContext
for the current requestsystemEventClass
- TheClass
of event that is being published.source
- The source for the event of typesystemEventClass
.- Throws:
NullPointerException
- if eithercontext
,systemEventClass
orsource
isnull
- Since:
- 2.0
-
-
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 argumentsourceBaseType
to find the matching listener instead of using theClass
of thesource
argument.A default implementation is provided that throws
.UnsupportedOperationException
so that users that decorateApplication
can continue to function- Parameters:
context
- theFacesContext
for the current requestsystemEventClass
- TheClass
of event that is being published.sourceBaseType
- TheClass
of the source event that must be used to lookup the listener to which this event must be published. If this argument isnull
the return fromsource.getClass()
must be used as thesourceBaseType
.source
- The source for the event of typesystemEventClass
.- Throws:
NullPointerException
- if any arguments except forsourceBaseType
arenull
- Since:
- 2.0
-
subscribeToEvent
public void subscribeToEvent(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener) Install the listener instance referenced by argument
listener
into the application as a listener for events of typesystemEventClass
that originate from objects of typesourceClass
.If argument
sourceClass
is non-null
,sourceClass
andsystemEventClass
must be used to store the argumentlistener
in the application in such a way that thelistener
can be quickly looked up by the implementation ofpublishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object)
givensystemEventClass
and an instance of theClass
referenced bysourceClass
. If argumentsourceClass
isnull
, thelistener
must be discoverable by the implementation ofpublishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object)
given onlysystemEventClass
.It is valid to call this method during the processing of an event which was subscribed to by a previous call to this method.
- Parameters:
systemEventClass
- theClass
of event for whichlistener
must be fired.sourceClass
- theClass
of the instance which causes events of typesystemEventClass
to be fired. May benull
.listener
- the implementation ofSystemEventListener
whoseSystemEventListener.processEvent(jakarta.faces.event.SystemEvent)
method must be called when events of typesystemEventClass
are fired.- Throws:
NullPointerException
- if any combination ofsystemEventClass
, orlistener
arenull
.- Since:
- 2.0
-
subscribeToEvent
public void subscribeToEvent(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Install the listener instance referenced by argument
listener
into application as a listener for events of typesystemEventClass
. The default implementation simply calls through tosubscribeToEvent(Class, Class, jakarta.faces.event.SystemEventListener)
passingnull
as thesourceClass
argumentA default implementation is provided that throws
.UnsupportedOperationException
so that users that decorateApplication
can continue to function- Parameters:
systemEventClass
- theClass
of event for whichlistener
must be fired.listener
- the implementation ofSystemEventListener
whoseSystemEventListener.processEvent(jakarta.faces.event.SystemEvent)
method must be called when events of typesystemEventClass
are fired.See
subscribeToEvent(java.lang.Class,java.lang.Class,jakarta.faces.event.SystemEventListener)
for an additional requirement regarding when it is valid to call this method.- Throws:
NullPointerException
- if any combination ofsystemEventClass
, orlistener
arenull
.- Since:
- 2.0
-
unsubscribeFromEvent
public void unsubscribeFromEvent(Class<? extends SystemEvent> systemEventClass, Class<?> sourceClass, SystemEventListener listener) Remove the listener instance referenced by argument
listener
from the application as a listener for events of typesystemEventClass
that originate from objects of typesourceClass
. SeesubscribeToEvent(Class, Class, jakarta.faces.event.SystemEventListener)
for the specification of how the listener is stored, and therefore, how it must be removed.See
subscribeToEvent(java.lang.Class,java.lang.Class,jakarta.faces.event.SystemEventListener)
for an additional requirement regarding when it is valid to call this method.- Parameters:
systemEventClass
- theClass
of event for whichlistener
must be fired.sourceClass
- theClass
of the instance which causes events of typesystemEventClass
to be fired. May benull
.listener
- the implementation ofSystemEventListener
to remove from the internal data structure.- Throws:
NullPointerException
- if any combination ofcontext
,systemEventClass
, orlistener
arenull
.- Since:
- 2.0
-
unsubscribeFromEvent
public void unsubscribeFromEvent(Class<? extends SystemEvent> systemEventClass, SystemEventListener listener) Remove the listener instance referenced by argument
listener
from the application as a listener for events of typesystemEventClass
. The default implementation simply calls through tounsubscribeFromEvent(Class, jakarta.faces.event.SystemEventListener)
passingnull
as thesourceClass
argumentSee
subscribeToEvent(java.lang.Class,java.lang.Class,jakarta.faces.event.SystemEventListener)
for an additional requirement regarding when it is valid to call this method.- Parameters:
systemEventClass
- theClass
of event for whichlistener
must be fired.listener
- the implementation ofSystemEventListener
to remove from the internal data structure.- Throws:
NullPointerException
- if any combination ofcontext
,systemEventClass
, orlistener
arenull
.- Since:
- 2.0
-
getSearchExpressionHandler
Return the thread-safe singleton
SearchExpressionHandler
for this application.- Returns:
- the
SearchExpressionHandler
. - Since:
- 2.3
-
setSearchExpressionHandler
Set the
SearchExpressionHandler
instance used by the application.- Parameters:
searchExpressionHandler
- theSearchExpressionHandler
.- Throws:
NullPointerException
- if searchExpressionHandler isnull
IllegalStateException
- if this method is called after at least one request has been processed by theLifecycle
instance for this application.- Since:
- 2.3
-
addSearchKeywordResolver
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 extendApplication
.- Parameters:
resolver
- the SearchKeywordResolver to add.- Throws:
IllegalStateException
- if called after the first request to theFacesServlet
has been serviced.NullPointerException
- when resolver is null.- Since:
- 2.3
-
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 followingSearchKeywordResolver
instances in the following order:-
SearchKeywordResolver
instances declared using the <search-keyword-resolver> element in the application configuration resources. -
Any
SearchKeywordResolver
instances added by calls toaddSearchKeywordResolver(jakarta.faces.component.search.SearchKeywordResolver)
. -
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 extendApplication
.- Returns:
- the
SearchKeywordResolver
. - Since:
- 2.3
-
-