|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjavax.faces.application.Application
public abstract class Application
Application represents a per-web-application singleton object where applications based on JavaServer Faces (or implementations wishing to provide extended functionality) can register application-wide singletons that provide functionality required by JavaServer Faces. Default implementations of each object are provided for cases where the application does not choose to customize the behavior.
The instance of Application is created by calling the
getApplication() method of ApplicationFactory.
Because this instance is shared, it must be implemented in a
thread-safe manner.
The application also acts as a factory for several types of
Objects specified in the Faces Configuration file. Please see Application#createComponent, Application#createConverter,
and Application#createValidator.
| Constructor Summary | |
|---|---|
Application()
|
|
| Method Summary | ||
|---|---|---|
void |
addBehavior(java.lang.String behaviorId,
java.lang.String behaviorClass)
Register a new mapping of behavior id to the name of the corresponding Behavior class. |
|
abstract void |
addComponent(java.lang.String componentType,
java.lang.String componentClass)
Register a new mapping of component type to the name of the corresponding UIComponent class. |
|
abstract void |
addConverter(java.lang.Class<?> targetClass,
java.lang.String converterClass)
Register a new converter class that is capable of performing conversions for the specified target class. |
|
abstract void |
addConverter(java.lang.String converterId,
java.lang.String converterClass)
Register a new mapping of converter id to the name of the corresponding Converter class. |
|
void |
addDefaultValidatorId(java.lang.String validatorId)
Register a validator by its id that
is applied to all |
|
void |
addELContextListener(ELContextListener listener)
Provide a way for Faces applications to register an ELContextListener that will be notified on creation
of ELContext instances. |
|
void |
addELResolver(ELResolver resolver)
Cause an the argument resolver to be added to the
resolver chain as specified in section JSF.5.5.1 of the JavaServer
Faces Specification. |
|
abstract void |
addValidator(java.lang.String validatorId,
java.lang.String validatorClass)
Register a new mapping of validator id to the name of the corresponding Validator class. |
|
Behavior |
createBehavior(java.lang.String behaviorId)
Instantiate and return a new Behavior instance of the class specified by
a previous call to addBehavior() for the specified
behavior id. |
|
UIComponent |
createComponent(FacesContext context,
Resource componentResource)
Instantiate and return a new |
|
UIComponent |
createComponent(FacesContext context,
java.lang.String componentType,
java.lang.String rendererType)
Like |
|
abstract UIComponent |
createComponent(java.lang.String componentType)
Instantiate and return a new UIComponent instance of the class specified
by a previous call to addComponent() for the
specified component type. |
|
abstract UIComponent |
createComponent(ValueBinding componentBinding,
FacesContext context,
java.lang.String componentType)
Deprecated. This has been replaced by createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String). |
|
UIComponent |
createComponent(ValueExpression componentExpression,
FacesContext context,
java.lang.String componentType)
Call the getValue() method on the specified ValueExpression. |
|
UIComponent |
createComponent(ValueExpression componentExpression,
FacesContext context,
java.lang.String componentType,
java.lang.String rendererType)
Like |
|
abstract Converter |
createConverter(java.lang.Class<?> targetClass)
Instantiate and return a new Converter instance of the class that has registered
itself as capable of performing conversions for objects of the
specified type. |
|
abstract Converter |
createConverter(java.lang.String converterId)
Instantiate and return a new Converter instance of the class specified by
a previous call to addConverter() for the specified
converter id. |
|
abstract MethodBinding |
createMethodBinding(java.lang.String ref,
java.lang.Class<?>[] params)
Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createMethodExpression. |
|
abstract Validator |
createValidator(java.lang.String validatorId)
Instantiate and return a new Validator instance of the class specified by
a previous call to addValidator() for the specified
validator id. |
|
abstract ValueBinding |
createValueBinding(java.lang.String ref)
Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory#createValueExpression. |
|
|
evaluateExpressionGet(FacesContext context,
java.lang.String expression,
java.lang.Class<? extends T> expectedType)
Get a value by evaluating an expression. |
|
abstract ActionListener |
getActionListener()
Return the default ActionListener to be registered for
all ActionSource components in this
appication. |
|
java.util.Iterator<java.lang.String> |
getBehaviorIds()
Return an Iterator over the set of currently registered
behavior ids for this Application. |
|
abstract java.util.Iterator<java.lang.String> |
getComponentTypes()
Return an Iterator over the set of currently defined
component types for this Application. |
|
abstract java.util.Iterator<java.lang.String> |
getConverterIds()
Return an Iterator over the set of currently registered
converter ids for this Application. |
|
abstract java.util.Iterator<java.lang.Class<?>> |
getConverterTypes()
Return an Iterator over the set of Class
instances for which Converter classes have been explicitly
registered. |
|
abstract java.util.Locale |
getDefaultLocale()
Return the default Locale for this application. |
|
abstract java.lang.String |
getDefaultRenderKitId()
Return the renderKitId to be used for rendering
this application. |
|
java.util.Map<java.lang.String,java.lang.String> |
getDefaultValidatorInfo()
Return an immutable |
|
ELContextListener[] |
getELContextListeners()
If no calls have been made to addELContextListener(javax.el.ELContextListener),
this method must return an empty array. |
|
ELResolver |
getELResolver()
Return the singleton ELResolver instance to be used
for all EL resolution. |
|
ExpressionFactory |
getExpressionFactory()
Return the ExpressionFactory instance for this
application. |
|
abstract java.lang.String |
getMessageBundle()
Return the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages
for this application. |
|
abstract NavigationHandler |
getNavigationHandler()
Return the NavigationHandler instance that will be passed
the outcome returned by any invoked application action for this
web application. |
|
ProjectStage |
getProjectStage()
Return the project stage for the currently running application instance. |
|
abstract PropertyResolver |
getPropertyResolver()
Deprecated. This has been replaced by getELResolver(). |
|
java.util.ResourceBundle |
getResourceBundle(FacesContext ctx,
java.lang.String name)
Find a ResourceBundle as defined in the
application configuration resources under the specified name. |
|
ResourceHandler |
getResourceHandler()
Return the singleton, stateless, thread-safe |
|
abstract StateManager |
getStateManager()
Return the StateManager instance that will be utilized
during the Restore View and Render Response
phases of the request processing lifecycle. |
|
abstract java.util.Iterator<java.util.Locale> |
getSupportedLocales()
Return an Iterator over the supported
Locales for this appication. |
|
abstract java.util.Iterator<java.lang.String> |
getValidatorIds()
Return an Iterator over the set of currently registered
validator ids for this Application. |
|
abstract VariableResolver |
getVariableResolver()
Deprecated. This has been replaced by getELResolver(). |
|
abstract ViewHandler |
getViewHandler()
Return the ViewHandler instance that will be utilized
during the Restore View and Render Response
phases of the request processing lifecycle. |
|
void |
publishEvent(FacesContext context,
java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceBaseType,
java.lang.Object source)
This method functions exactly like
|
|
void |
publishEvent(FacesContext context,
java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Object source)
If |
|
void |
removeELContextListener(ELContextListener listener)
Remove the argument listener from the list of
ELContextListeners. |
|
abstract void |
setActionListener(ActionListener listener)
Set the default ActionListener to be registered for all
ActionSource components. |
|
abstract void |
setDefaultLocale(java.util.Locale locale)
Set the default Locale for this application. |
|
abstract void |
setDefaultRenderKitId(java.lang.String renderKitId)
Set the renderKitId to be used to render this
application. |
|
abstract void |
setMessageBundle(java.lang.String bundle)
Set the fully qualified class name of the ResourceBundle
to be used for JavaServer Faces messages for this application. |
|
abstract void |
setNavigationHandler(NavigationHandler handler)
Set the NavigationHandler instance that will be passed
the outcome returned by any invoked application action for this
web application. |
|
abstract void |
setPropertyResolver(PropertyResolver resolver)
Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the
right place in the application configuration resources which will
be considered in the normal course of expression evaluation.
This method now will cause the argument resolver to
be wrapped inside an implementation of ELResolver and
exposed to the EL resolution system as if the user had called
addELResolver(javax.el.ELResolver). |
|
void |
setResourceHandler(ResourceHandler resourceHandler)
Set the |
|
abstract void |
setStateManager(StateManager manager)
Set the StateManager instance that will be utilized
during the Restore View and Render Response
phases of the request processing lifecycle. |
|
abstract void |
setSupportedLocales(java.util.Collection<java.util.Locale> locales)
Set the Locale instances representing the supported
Locales for this application. |
|
abstract void |
setVariableResolver(VariableResolver resolver)
Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the
right place in the application configuration resources which will
be considered in the normal course of expression evaluation.
This method now will cause the argument resolver to
be wrapped inside an implementation of ELResolver and
exposed to the EL resolution system as if the user had called
addELResolver(javax.el.ELResolver). |
|
abstract void |
setViewHandler(ViewHandler handler)
Set the ViewHandler instance that will be utilized
during the Restore View and Render Response
phases of the request processing lifecycle. |
|
void |
subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceClass,
SystemEventListener listener)
Install the listener instance
referenced by argument |
|
void |
subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
SystemEventListener listener)
Install the listener instance
referenced by argument |
|
void |
unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceClass,
SystemEventListener listener)
Remove the listener instance
referenced by argument |
|
void |
unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
SystemEventListener listener)
Remove the listener instance
referenced by argument |
|
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public Application()
| Method Detail |
|---|
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:
processAction() method must first call
FacesContext.renderResponse() in order to bypass
any intervening lifecycle phases, once the method returns.processAction() method must next determine
the logical outcome of this event, as follows:
null
action property, retrieve the MethodBinding from the property, and call
invoke() on it. Convert the returned value (if
any) to a String, and use it as the logical outcome.null.processAction() method must finally retrieve
the NavigationHandler instance for this
application and call NavigationHandler#handleNavigation passing:
FacesContext for the current requestMethodBinding instance for the
action property of this component, the result of
calling MethodBinding#getExpressionString on it, null
otherwiseNote 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.
public abstract void setActionListener(ActionListener listener)
Set the default ActionListener to be registered for all
ActionSource components.
listener - The new default ActionListener
java.lang.NullPointerException - if listener
is nullpublic abstract java.util.Locale getDefaultLocale()
Return the default Locale for this application. If
not explicitly set, null is returned.
public abstract void setDefaultLocale(java.util.Locale locale)
Set the default Locale for this application.
locale - The new default Locale
java.lang.NullPointerException - if locale
is nullpublic abstract java.lang.String getDefaultRenderKitId()
Return the renderKitId to be used for rendering
this application. If not explicitly set, null is
returned.
public abstract void setDefaultRenderKitId(java.lang.String renderKitId)
Set the renderKitId to be used to render this
application. Unless the client has provided a custom ViewHandler
that supports the use of multiple RenderKit
instances in the same application, this method must only be called at
application startup, before any Faces requests have been processed.
This is a limitation of the current Specification, and may be lifted in
a future release.
public abstract java.lang.String getMessageBundle()
Return the fully qualified class name of the
ResourceBundle to be used for JavaServer Faces messages
for this application. If not explicitly set, null
is returned.
public abstract void setMessageBundle(java.lang.String bundle)
Set the fully qualified class name of the ResourceBundle
to be used for JavaServer Faces messages for this application. See the
JavaDocs for the java.util.ResourceBundle class for more
information about the syntax for resource bundle names.
bundle - Base name of the resource bundle to be used
java.lang.NullPointerException - if bundle
is nullpublic 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.
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.
handler - The new NavigationHandler instance
java.lang.NullPointerException - if handler
is nullpublic ResourceHandler getResourceHandler()
Return the singleton, stateless, thread-safe ResourceHandler for this application. The JSF implementation
must support the following techniques for declaring an alternate
implementation of ResourceHandler.
The ResourceHandler implementation is
declared in the application configuration resources by giving
the fully qualified class name as the value of the
<resource-handler> element within the
<application> element.
In all of the above cases, the runtime must employ the decorator pattern as for every other pluggable artifact in JSF.
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function
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.
resourceHandler - The new ResourceHandler instance
IllegalStateException - if this method is called after
at least one request has been processed by the
Lifecycle instance for this application.
java.lang.NullPointerException - if resourceHandler
is null
public abstract PropertyResolver getPropertyResolver()
getELResolver().
Return a PropertyResolver instance that wraps the
ELResolver instance that Faces provides to the unified EL
for the resolution of expressions that appear programmatically in
an application.
Note that this no longer returns the default
PropertyResolver since that class is now a no-op
that aids in allowing custom PropertyResolvers to
affect the EL resolution process.
public abstract void setPropertyResolver(PropertyResolver resolver)
<el-resolver> element at the
right place in the application configuration resources which will
be considered in the normal course of expression evaluation.
This method now will cause the argument resolver to
be wrapped inside an implementation of ELResolver and
exposed to the EL resolution system as if the user had called
addELResolver(javax.el.ELResolver).
Set the PropertyResolver instance that will be utilized
to resolve method and value bindings.
This method is now deprecated but the implementation must
cause the argument to be set as the head of the legacy
PropertyResolver chain, replacing any existing value
that was set from the application configuration resources.
It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.
resolver - The new PropertyResolver instance
java.lang.NullPointerException - if resolver
is null
IllegalStateException - if called after the first
request to the FacesServlet has been
serviced.
public java.util.ResourceBundle getResourceBundle(FacesContext ctx,
java.lang.String name)
Find a ResourceBundle as defined in the
application configuration resources under the specified name. If
a ResourceBundle was defined for the name, return an
instance that uses the locale of the current UIViewRoot.
The default implementation throws
UnsupportedOperationException and is provided
for the sole purpose of not breaking existing applications that extend
this class.
ResourceBundle for the current UIViewRoot,
otherwise null
FacesException - if a bundle was defined, but not resolvable
java.lang.NullPointerException - if ctx == null || name == nullpublic 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
public abstract VariableResolver getVariableResolver()
getELResolver().
Return the VariableResolver that wraps the ELResolver instance that Faces provides to the unified EL for
the resolution of expressions that appear programmatically in an
application. The implementation of the
VariableResolvermust pass null as the
base argument for any methods invoked on the underlying
ELResolver.
Note that this method no longer returns the default
VariableResolver, since that class now is a no-op
that aids in allowing custom VariableResolvers to
affect the EL resolution process.
public abstract void setVariableResolver(VariableResolver resolver)
<el-resolver> element at the
right place in the application configuration resources which will
be considered in the normal course of expression evaluation.
This method now will cause the argument resolver to
be wrapped inside an implementation of ELResolver and
exposed to the EL resolution system as if the user had called
addELResolver(javax.el.ELResolver).
Set the VariableResolver instance that will be consulted
to resolve method and value bindings.
This method is now deprecated but the implementation must
cause the argument to be set as the head of the legacy
VariableResolver chain, replacing any existing value
that was set from the application configuration resources.
It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.
resolver - The new VariableResolver instance
java.lang.NullPointerException - if resolver
is null
IllegalStateException - if called after the first
request to the FacesServlet has been
serviced.public void addELResolver(ELResolver resolver)
Cause an the argument resolver to be added to the
resolver chain as specified in section JSF.5.5.1 of the JavaServer
Faces Specification.
It is not possible to remove an ELResolver
registered with this method, once it has been registered.
It is illegal to register an ELResolver after
the application has received any requests from the client. If an
attempt is made to register a listener after that time, an
IllegalStateException must be thrown. This restriction is
in place to allow the JSP container to optimize for the common
case where no additional ELResolvers are in the
chain, aside from the standard ones. It is permissible to add
ELResolvers before or after initialization to a
CompositeELResolver that is already in the
chain.
The default implementation throws
UnsupportedOperationException and is provided
for the sole purpose of not breaking existing applications that extend
Application.
IllegalStateException - if called after the first
request to the FacesServlet has been
serviced.public ELResolver getELResolver()
Return the singleton ELResolver instance to be used
for all EL resolution. This is actually an instance of CompositeELResolver that must contain the following
ELResolver instances in the following order:
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 JSF.5 in the spec
document.
An implementation that wraps the head of
the legacy PropertyResolver chain, as per section
PropertyResolver ChainWrapper in Chapter JSF.5 in the spec
document.
Any ELResolver instances added by calls to
addELResolver(javax.el.ELResolver).
The default implementation throws UnsupportedOperationException
and is provided for the sole purpose of not breaking existing applications
that extend Application.
public abstract ViewHandler getViewHandler()
Return the ViewHandler instance that will be utilized
during the Restore View and Render Response
phases of the request processing lifecycle. If not explicitly set,
a default implementation must be provided that performs the functions
described in the ViewHandler description in the
JavaServer Faces Specification.
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.
handler - The new ViewHandler instance
IllegalStateException - if this method is called after
at least one request has been processed by the
Lifecycle instance for this application.
java.lang.NullPointerException - if handler
is nullpublic 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.
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.
manager - The new StateManager instance
IllegalStateException - if this method is called after
at least one request has been processed by the
Lifecycle instance for this application.
java.lang.NullPointerException - if manager
is null
public void addBehavior(java.lang.String behaviorId,
java.lang.String behaviorClass)
Register a new mapping
of behavior id to the name of the corresponding
Behavior class. This allows subsequent calls
to createBehavior() to serve as a factory for
Behavior instances.
behaviorId - The behavior id to be registeredbehaviorClass - The fully qualified class name of the
corresponding Behavior implementation
java.lang.NullPointerException - if behaviorId
or behaviorClass is null
public Behavior createBehavior(java.lang.String behaviorId)
throws FacesException
Instantiate and
return a new Behavior instance of the class specified by
a previous call to addBehavior() for the specified
behavior id.
behaviorId - The behavior id for which to create and
return a new Behavior instance
FacesException - if the Behavior cannot be
created
java.lang.NullPointerException - if behaviorId
is nullpublic java.util.Iterator<java.lang.String> getBehaviorIds()
Return an Iterator over the set of currently registered
behavior ids for this Application.
public abstract void addComponent(java.lang.String componentType,
java.lang.String componentClass)
Register a new mapping of component type to the name of the
corresponding UIComponent class. This allows subsequent calls
to createComponent() to serve as a factory for
UIComponent instances.
componentType - The component type to be registeredcomponentClass - The fully qualified class name of the
corresponding UIComponent implementation
java.lang.NullPointerException - if componentType or
componentClass is null
public abstract UIComponent createComponent(java.lang.String componentType)
throws FacesException
Instantiate and
return a new UIComponent instance of the class specified
by a previous call to addComponent() for the
specified component type.
Before the component instance is
returned, it must be inspected for the presence of a ListenerFor (or ListenersFor) or ResourceDependency
(or ResourceDependencies) annotation. If any of these
annotations are present, the action listed in ListenerFor or ResourceDependency must
be taken on the component, before it is returned from this
method. This variant of createComponent must
not inspect the Renderer for the component to be returned for
any of the afore mentioned annotations. Such inspection is the
province of createComponent(ValueExpression,
FacesContext, String, String) or createComponent(FacesContext, String, String).
componentType - The component type for which to create and
return a new UIComponent instance
FacesException - if a UIComponent of the
specified type cannot be created
java.lang.NullPointerException - if componentType
is null
public abstract UIComponent createComponent(ValueBinding componentBinding,
FacesContext context,
java.lang.String componentType)
throws FacesException
createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).
Wrap the argument componentBinding in an
implementation of ValueExpression and call through to
createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).
componentBinding - ValueBinding representing a
component value binding expression (typically specified by the
component attribute of a custom tag)context - FacesContext for the current requestcomponentType - Component type to create if the ValueBinding
does not return a component instance
FacesException - if a UIComponent cannot be created
java.lang.NullPointerException - if any parameter is null
public UIComponent createComponent(ValueExpression componentExpression,
FacesContext context,
java.lang.String componentType)
throws FacesException
Call the
getValue() method on the specified ValueExpression. If it returns a UIComponent instance,
return it as the value of this method. If it does not,
instantiate a new UIComponent instance of the specified
component type, pass the new component to the
setValue() method of the specified ValueExpression, and return it.
Before the component instance is
returned, it must be inspected for the presence of a ListenerFor (or ListenersFor) or ResourceDependency
(or ResourceDependencies) annotation. If any of these
annotations are present, the action listed in ListenerFor or ResourceDependency must
be taken on the component, before it is returned from this
method. This variant of createComponent must
not inspect the Renderer for the component to be returned for
any of the afore mentioned annotations. Such inspection is the
province of createComponent(ValueExpression,
FacesContext, String, String) or createComponent(FacesContext, String, String).
componentExpression - ValueExpression representing a
component value expression (typically specified by the
component attribute of a custom tag)context - FacesContext for the current requestcomponentType - Component type to create if the ValueExpression does not return a component instance
FacesException - if a UIComponent cannot be created
java.lang.NullPointerException - if any parameter is null
A default implementation is provided that throws
UnsupportedOperationException so that users
that decorate Application can continue to function.
public UIComponent createComponent(ValueExpression componentExpression,
FacesContext context,
java.lang.String componentType,
java.lang.String rendererType)
Like createComponent(ValueExpression, FacesContext, String) except
the Renderer for the component to be returned must
be inspected for the annotations mentioned in createComponent(ValueExpression, FacesContext, String) as
specified in the documentation for that method. The
Renderer instance to inspect must be obtained by
calling FacesContext#getRenderKit and calling RenderKit.getRenderer(java.lang.String, java.lang.String) on the result, passing
the argument componentType as the first argument and
the result of calling UIComponent#getFamily on the newly
created component as the second argument. If no such
Renderer can be found, a message must be logged with
a helpful error message. Otherwise, UIComponent#setRendererType must be called on the newly created
UIComponent instance, passing the argument
rendererType as the argument.
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function.
componentExpression - ValueExpression representing a
component value expression (typically specified by the
component attribute of a custom tag)context - FacesContext for the current requestcomponentType - Component type to create if the ValueExpression does not return a component instancerendererType - The renderer-type of the
Renderer that will render this component. A
null value must be accepted for this parameter.
FacesException - if a UIComponent cannot be created
java.lang.NullPointerException - if any of the parameters
componentExpression, context, or
componentType are null
public UIComponent createComponent(FacesContext context,
java.lang.String componentType,
java.lang.String rendererType)
Like createComponent(String) except the Renderer for
the component to be returned must be inspected for the
annotations mentioned in createComponent(ValueExpression,
FacesContext, String) as specified in the documentation for that
method. The Renderer instance to inspect must be
obtained by calling FacesContext#getRenderKit and calling
RenderKit.getRenderer(java.lang.String, java.lang.String) on the result,
passing the argument componentType as the first
argument and the result of calling UIComponent#getFamily
on the newly created component as the second argument. If no
such Renderer can be found, a message must be logged
with a helpful error message. Otherwise, UIComponent#setRendererType must be called on the newly created
UIComponent instance, passing the argument
rendererType as the argument.
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function
context - FacesContext for the current requestcomponentType - Component type to createrendererType - The renderer-type of the
Renderer that will render this component. A
null value must be accepted for this parameter.
FacesException - if a UIComponent cannot be created
java.lang.NullPointerException - if any of the parameters
context, or componentType are
null
public UIComponent createComponent(FacesContext context,
Resource componentResource)
Instantiate and return a new UIComponent instance from the argument Resource. An
algorithm semantically equivalent to the following must be
followed to instantiate the UIComponent to
return.
Obtain a reference to the ViewDeclarationLanguage for this Application
instance by calling ViewHandler#getViewDeclarationLanguage,
passing the viewId found by calling
UIViewRoot.getViewId() on the
UIViewRoot in the argument
FacesContext.
Obtain a reference to the composite component
metadata for this composite component by calling ViewDeclarationLanguage#getComponentMetadata, passing the
facesContext and componentResource
arguments to this method. This version of JSF specification
uses JavaBeans as the API to the component metadata.
Determine if the component author declared a
component-type for this component instance by
obtaining the BeanDescriptor from the component
metadata and calling its getValue() method,
passing UIComponent#COMPOSITE_COMPONENT_TYPE_KEY as
the argument. If non-null, the result must be a
ValueExpression whose value is the
component-type of the UIComponent to
be created for this Resource component. Call
through to createComponent(java.lang.String) to
create the component.
Otherwise, determine if a script based component for
this Resource can be found by calling ViewDeclarationLanguage#getScriptComponentResource. If the
result is non-null, and is a script written in
one of the languages listed in JSF.4.3 of the specification prose
document, create a UIComponent instance from the
script resource.
Otherwise, let library-name be the return from
calling Resource#getLibraryName on the argument
componentResource and resource-name be
the return from calling Resource#getResourceName on
the argument componentResource. Create a fully
qualified Java class name by removing any file extension from
resource-name and let fqcn be
library-name + "." +
resource-name. If a class with the name of
fqcn cannot be found, take no action and continue to
the next step. If any of InstantiationException,
IllegalAccessException, or
ClassCastException are thrown, wrap the exception
in a FacesException and re-throw it. If any
other exception is thrown, log the exception and
continue to the next step.
If none of the previous steps have yielded a
UIComponent instance, call createComponent(java.lang.String) passing
"javax.faces.NamingContainer" as the
argument.
Call UIComponent#setRendererType on the
UIComponent instance, passing
"javax.faces.Composite" as the argument.
Store the argument Resource in the
attributes Map of the UIComponent
under the key, Resource#COMPONENT_RESOURCE_KEY.
Store composite component metadata in the
attributes Map of the UIComponent
under the key, UIComponent#BEANINFO_KEY.
Before the component instance is returned, it must be
inspected for the presence of a ListenerFor annotation. If this annotation is
present, the action listed in ListenerFor must be taken on the component,
before it is returned from this method.
A default implementation is provided that throws
UnsupportedOperationException so that users
that decorate Application can continue to function.
context - FacesContext for the current requestcomponentResource - A Resource that points to a
source file that provides an implementation of a component.
FacesException - if a UIComponent from the Resource cannot be created
NullPointerException - if any parameter is
null
java.lang.NullPointerException - if unable, for any reason, to obtain a
ViewDeclarationLanguage instance as described above.public abstract java.util.Iterator<java.lang.String> getComponentTypes()
Return an Iterator over the set of currently defined
component types for this Application.
public abstract void addConverter(java.lang.String converterId,
java.lang.String converterClass)
Register a new mapping of converter id to the name of the
corresponding Converter class. This allows subsequent calls
to createConverter() to serve as a factory for
Converter instances.
converterId - The converter id to be registeredconverterClass - The fully qualified class name of the
corresponding Converter implementation
java.lang.NullPointerException - if converterId
or converterClass is null
public abstract void addConverter(java.lang.Class<?> targetClass,
java.lang.String converterClass)
Register a new converter class that is capable of performing conversions for the specified target class.
targetClass - The class for which this converter is registeredconverterClass - The fully qualified class name of the
corresponding Converter implementation
java.lang.NullPointerException - if targetClass
or converterClass is nullpublic abstract Converter createConverter(java.lang.String converterId)
Instantiate and
return a new Converter instance of the class specified by
a previous call to addConverter() for the specified
converter id.
If the toLowerCase() of
the String represenation of the value of the
"javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE"
application configuration parameter is "true"
(without the quotes) and the Converter instance to
be returned is an instance of DateTimeConverter, DateTimeConverter.setTimeZone(java.util.TimeZone) must be
called, passing the return from
TimeZone.getDefault().
The argument
converter must be inspected for the presence of the
ResourceDependency annotation.
If the ResourceDependency annotation is present,
the action described in ResourceDependency must
be taken. If the ResourceDependency annotation is
not present, the argument converter must be inspected
for the presence of the ResourceDependencies annotation.
If the ResourceDependencies annotation
is present, the action described in ResourceDependencies
must be taken.
converterId - The converter id for which to create and
return a new Converter instance
FacesException - if the Converter cannot be
created
java.lang.NullPointerException - if converterId
is nullpublic abstract Converter createConverter(java.lang.Class<?> targetClass)
Instantiate and return
a new Converter instance of the class that has registered
itself as capable of performing conversions for objects of the
specified type. If no such Converter class can be
identified, return null.
To locate an appropriate Converter class, the following
algorithm is performed, stopping as soon as an appropriate Converter class is found:
Converter registered for the target class itself.
Converter registered for interfaces that are
implemented by the target class (directly or indirectly).Converter registered for the superclass (if any)
of the target class, recursively working up the inheritance
hierarchy.If the Converter has a single argument constructor that
accepts a Class, instantiate the Converter
using that constructor, passing the argument targetClass as
the sole argument. Otherwise, simply use the zero-argument constructor.
If the toLowerCase() of
the String represenation of the value of the
"javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE"
application configuration parameter is "true"
(without the quotes) and the Converter instance to
be returned is an instance of DateTimeConverter, DateTimeConverter.setTimeZone(java.util.TimeZone) must be
called, passing the return from
TimeZone.getDefault().
targetClass - Target class for which to return a Converter
FacesException - if the Converter cannot be
created
java.lang.NullPointerException - if targetClass
is nullpublic abstract java.util.Iterator<java.lang.String> getConverterIds()
Return an Iterator over the set of currently registered
converter ids for this Application.
public abstract java.util.Iterator<java.lang.Class<?>> getConverterTypes()
Return an Iterator over the set of Class
instances for which Converter classes have been explicitly
registered.
public void addDefaultValidatorId(java.lang.String validatorId)
Register a validator by its id that
is applied to all UIInput components in a view. The
validator to most often serve this role is the
BeanValidator. The usage contract for this method
assumes that the validator has been registered using the normal
“by-id” registration mechanism.
An implementation is provided that takes no action
so that users that decorate
the Application continue to work.
public java.util.Map<java.lang.String,java.lang.String> getDefaultValidatorInfo()
Return an immutable Map over
the set of currently registered default validator IDs and their class
name for this Application.
An implementation is provided that returns Collections.emptyMap
so that users that decorate
the Application continue to work.
public ExpressionFactory getExpressionFactory()
Return the ExpressionFactory instance for this
application. This instance is used by the convenience method
evaluateExpressionGet(javax.faces.context.FacesContext, java.lang.String, java.lang.Class extends T>).
The implementation must return the
ExpressionFactory from the JSP container by calling
JspFactory.getDefaultFactory().getJspApplicationContext(servletContext).getExpressionFactory().
An implementation is provided that throws
UnsupportedOperationException so that users that decorate
the Application continue to work.
public <T> T evaluateExpressionGet(FacesContext context,
java.lang.String expression,
java.lang.Class<? extends T> expectedType)
throws ELException
Get a value by evaluating an expression.
Call getExpressionFactory() then call ExpressionFactory#createValueExpression passing the argument
expression and expectedType. Call
FacesContext#getELContext and pass it to ValueExpression#getValue, returning the result.
An implementation is provided that throws
UnsupportedOperationException so that users that decorate
the Application continue to work.
ELException
public abstract MethodBinding createMethodBinding(java.lang.String ref,
java.lang.Class<?>[] params)
throws ReferenceSyntaxException
getExpressionFactory() then ExpressionFactory#createMethodExpression.
Call getExpressionFactory() then call ExpressionFactory#createMethodExpression, passing the given
arguments, and wrap the result in a MethodBinding
implementation, returning it.
ref - Method binding expression for which to return a
MethodBinding instanceparams - Parameter signatures that must be compatible with those
of the method to be invoked, or a zero-length array or null
for a method that takes no parameters
java.lang.NullPointerException - if ref
is null
ReferenceSyntaxException - if the specified ref
has invalid syntaxpublic abstract java.util.Iterator<java.util.Locale> getSupportedLocales()
Return an Iterator over the supported
Locales for this appication.
public abstract void setSupportedLocales(java.util.Collection<java.util.Locale> locales)
Set the Locale instances representing the supported
Locales for this application.
locales - The set of supported Locales
for this application
java.lang.NullPointerException - if the argument
newLocales is null.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.
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.
public ELContextListener[] getELContextListeners()
If no calls have been made to addELContextListener(javax.el.ELContextListener),
this method must return an empty array.
Otherwise, return an array representing the list of listeners
added by calls to addELContextListener(javax.el.ELContextListener).
An implementation is provided that throws
UnsupportedOperationException so that users that decorate
the Application continue to work.
public abstract void addValidator(java.lang.String validatorId,
java.lang.String validatorClass)
Register a new mapping of validator id to the name of the
corresponding Validator class. This allows subsequent calls
to createValidator() to serve as a factory for
Validator instances.
validatorId - The validator id to be registeredvalidatorClass - The fully qualified class name of the
corresponding Validator implementation
java.lang.NullPointerException - if validatorId
or validatorClass is null
public abstract Validator createValidator(java.lang.String validatorId)
throws FacesException
Instantiate and
return a new Validator instance of the class specified by
a previous call to addValidator() for the specified
validator id.
The argument
validator must be inspected for the presence of the
ResourceDependency annotation.
If the ResourceDependency annotation is present,
the action described in ResourceDependency must
be taken. If the ResourceDependency annotation is
not present, the argument validator must be inspected
for the presence of the ResourceDependencies annotation.
If the ResourceDependencies annotation
is present, the action described in ResourceDependencies
must be taken.
validatorId - The validator id for which to create and
return a new Validator instance
FacesException - if a Validator of the
specified id cannot be created
java.lang.NullPointerException - if validatorId
is nullpublic abstract java.util.Iterator<java.lang.String> getValidatorIds()
Return an Iterator over the set of currently registered
validator ids for this Application.
public abstract ValueBinding createValueBinding(java.lang.String ref)
throws ReferenceSyntaxException
getExpressionFactory() then ExpressionFactory#createValueExpression.
Call getExpressionFactory() then call ExpressionFactory#createValueExpression, passing the argument
ref, Object.class for the expectedType,
and null, for the fnMapper.
ref - Value binding expression for which to return a
ValueBinding instance
java.lang.NullPointerException - if ref
is null
ReferenceSyntaxException - if the specified ref
has invalid syntax
public void publishEvent(FacesContext context,
java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Object source)
If FacesContext.isProcessingEvents() is
true and there are one or more listeners
for events of the type represented by
systemEventClass, call those listeners, passing
source as the source of the event. The
implementation should be as fast as possible in determining
whether or not a listener for the given
systemEventClass and source has been
installed, and should return immediately once such a
determination has been made. The implementation of
publishEvent must honor the requirements stated in
subscribeToEvent(java.lang.Class extends javax.faces.event.SystemEvent>, java.lang.Class>, javax.faces.event.SystemEventListener) regarding the storage and retrieval of
listener instances. Specifically, if subscribeToEvent(Class,Class,SystemEventListener) was called,
the sourceClass argument must match exactly the
Class of the source argument in the
call to publishEvent(). The implementation must not
do any inheritance hierarachy inspection when looking for a match
between the sourceClass passed to subscribeToEvent(Class,Class,SystemEventListener) and the
sourceClass passed to publishEvent() in
order to find any listeners to which the event should be
published. In the case where the Class of the
source argument does not match the
Class of the sourceClass used when the
listener was subscribed using subscribeToEvent(),
publishEvent(FacesContext,Class,Class,Object) can be used to
provide the Class used to perform the listener lookup and
match.
The default implementation must implement an algorithm semantically equivalent to the following to locate listener instances and to invoke them.
If the source argument implements SystemEventListenerHolder, call SystemEventListenerHolder.getListenersForEventClass(java.lang.Class extends javax.faces.event.SystemEvent>)
on it, passing the systemEventClass argument. If
the list is not empty, perform algorithm
traverseListenerList on the list.
If any view level listeners have been installed
by previous calls to subscribeToEvent(Class, Class,
javax.faces.event.SystemEventListener) on the UIViewRoot, perform algorithm
traverseListenerList on the list of listeners for that
event installed on the UIViewRoot.
If any Application level listeners have
been installed by previous calls to subscribeToEvent(Class, Class,
javax.faces.event.SystemEventListener), perform algorithm
traverseListenerList on the list.
If any Application level listeners have
been installed by previous calls to subscribeToEvent(Class, javax.faces.event.SystemEventListener),
perform algorithm traverseListenerList on the
list.
If the act of invoking the processListener method
causes an AbortProcessingException to
be thrown, processing of the listeners must be aborted, no
further processing of the listeners for this event must take
place, and the exception must be logged with
Level.SEVERE.
Algorithm traverseListenerList: For each listener in the list,
Call SystemEventListener.isListenerForSource(java.lang.Object), passing the
source argument. If this returns
false, take no action on the listener.
Otherwise, if the event to be passed to the listener
instances has not yet been constructed, construct the event,
passing source as the argument to the
one-argument constructor that takes an Object.
This same event instance must be passed to all listener
instances.
Call SystemEvent.isAppropriateListener(javax.faces.event.FacesListener),
passing the listener instance as the argument. If this
returns false, take no action on the
listener.
Call SystemEvent.processListener(javax.faces.event.FacesListener),
passing the listener instance.
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function
context - the FacesContext for the current requestsystemEventClass - The Class of event that is
being published.source - The source for the event of type
systemEventClass.
java.lang.NullPointerException - if either context,
systemEventClass or source is null
public void publishEvent(FacesContext context,
java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceBaseType,
java.lang.Object source)
This method functions exactly like
publishEvent(FacesContext,Class,Object), except the run-time
must use the argument sourceBaseType to find the matching
listener instead of using the Class of the
source argument.
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function
context - the FacesContext for the current requestsystemEventClass - 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.
java.lang.NullPointerException - if any arguments are null
public void subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceClass,
SystemEventListener listener)
Install the listener instance
referenced by argument listener into the
application as a listener for events of type
systemEventClass that originate from objects of type
sourceClass.
If argument sourceClass is non-null,
sourceClass and systemEventClass must be
used to store the argument listener in the application in
such a way that the listener can be quickly looked
up by the implementation of publishEvent(javax.faces.context.FacesContext, java.lang.Class extends javax.faces.event.SystemEvent>, java.lang.Object) given
systemEventClass and an instance of the
Class referenced by sourceClass. If
argument sourceClass is null, the
listener must be discoverable by the implementation
of publishEvent(javax.faces.context.FacesContext, java.lang.Class extends javax.faces.event.SystemEvent>, java.lang.Object) given only systemEventClass.
systemEventClass - the Class of event for which
listener must be fired.sourceClass - the Class of the instance which
causes events of type systemEventClass to be fired.
May be null.listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(javax.faces.event.SystemEvent) method must be called when
events of type systemEventClass are fired.
NullPointerException - if any combination of
systemEventClass, or listener are
null.
public void subscribeToEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
SystemEventListener listener)
Install the listener instance
referenced by argument listener into application as
a listener for events of type systemEventClass. The
default implementation simply calls through to subscribeToEvent(Class, Class,
javax.faces.event.SystemEventListener) passing null
as the sourceClass argument
A default implementation is provided
that throws UnsupportedOperationException so that
users that decorate Application can continue to
function
systemEventClass - the Class of event for which
listener must be fired.listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(javax.faces.event.SystemEvent) method must
be called when events of type systemEventClass are
fired.
NullPointerException - if any combination of
systemEventClass, or listener are
null.
public void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
java.lang.Class<?> sourceClass,
SystemEventListener listener)
Remove the listener instance
referenced by argument listener from the application
as a listener for events of type
systemEventClass that originate from objects of type
sourceClass. See subscribeToEvent(Class, Class,
javax.faces.event.SystemEventListener) for the specification
of how the listener is stored, and therefore, how it must be
removed.
systemEventClass - the Class of event for which
listener must be fired.sourceClass - the Class of the instance which
causes events of type systemEventClass to be fired.
May be null.listener - the implementation of SystemEventListener to remove from the internal data
structure.
NullPointerException - if any combination of
context,
systemEventClass, or listener are
null.
public void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> systemEventClass,
SystemEventListener listener)
Remove the listener instance
referenced by argument listener from the application
as a listener for events of type systemEventClass. The
default implementation simply calls through to unsubscribeFromEvent(Class, javax.faces.event.SystemEventListener)
passing null as the sourceClass argument
systemEventClass - the Class of event for which
listener must be fired.listener - the implementation of SystemEventListener to remove from the internal data
structure.
NullPointerException - if any combination of
context, systemEventClass, or
listener are
null. http://java.sun.com/javaee/javaserverfaces/reference/api/index.html
|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.
Generated on 24-November-2009 03:24