javax.faces.application.Application Maven / Gradle / Ivy
/*
* $Id: Application.java,v 1.47 2007/01/29 06:44:05 rlubke Exp $
*/
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* https://javaserverfaces.dev.java.net/CDDL.html or
* legal/CDDLv1.0.txt.
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* [Name of File] [ver.__] [Date]
*
* Copyright 2005 Sun Microsystems Inc. All Rights Reserved
*/
package javax.faces.application;
import java.util.Iterator;
import java.util.Collection;
import java.util.Locale;
import java.util.ResourceBundle;
import javax.faces.FacesException;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.convert.Converter;
import javax.faces.el.MethodBinding;
import javax.faces.el.PropertyResolver;
import javax.faces.el.ReferenceSyntaxException;
import javax.faces.el.ValueBinding;
import javax.faces.el.VariableResolver;
import javax.faces.event.ActionListener;
import javax.faces.validator.Validator;
import javax.el.ELContextListener;
import javax.el.ExpressionFactory;
import javax.el.ValueExpression;
import javax.el.ELException;
import javax.el.ELResolver;
/**
* 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 {@link Application} is created by calling the
* getApplication() method of {@link 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 {@link
* Application#createComponent}, {@link Application#createConverter},
* and {@link Application#createValidator}.
*/
public abstract class Application {
// ------------------------------------------------------------- Properties
/**
* Return the default {@link ActionListener} to be registered for
* all {@link javax.faces.component.ActionSource} components in this
* appication. If not explicitly set, a default implementation must
* be provided that performs the
*
* following functions:
*
* - The
processAction() method must first call
* FacesContext.renderResponse() in order to bypass
* any intervening lifecycle phases, once the method returns.
* - The
processAction() method must next determine
* the logical outcome of this event, as follows:
*
* - If the originating component has a non-
null
* action property, retrieve the {@link
* MethodBinding} from the property, and call
* invoke() on it. Convert the returned value (if
* any) to a String, and use it as the logical outcome.
* - Otherwise, the logical outcome is
null.
*
* - The
processAction() method must finally retrieve
* the NavigationHandler instance for this
* application and call {@link
* NavigationHandler#handleNavigation} passing:
*
*
* - the {@link FacesContext} for the current request
* - If there is a
MethodBinding instance for the
* action property of this component, the result of
* calling {@link MethodBinding#getExpressionString} on it, null
* otherwise
*
* - the logical outcome as determined above
*
*
*
*
*
*
* Note that the specification for the default
* ActionListener contiues to call for the use of a
* deprecated property (action) and
* class (MethodBinding). Unfortunately, this is
* necessary because the default ActionListener must
* continue to work with components that do not implement {@link
* javax.faces.component.ActionSource2}, and only implement {@link
* javax.faces.component.ActionSource}.
*/
public abstract ActionListener getActionListener();
/**
* Set the default {@link ActionListener} to be registered for all
* {@link javax.faces.component.ActionSource} components.
*
*
* @param listener The new default {@link ActionListener}
*
* @throws NullPointerException if listener
* is null
*/
public abstract void setActionListener(ActionListener listener);
/**
* Return the default Locale for this application. If
* not explicitly set, null is returned.
*/
public abstract Locale getDefaultLocale();
/**
* Set the default Locale for this application.
*
* @param locale The new default Locale
*
* @throws NullPointerException if locale
* is null
*/
public abstract void setDefaultLocale(Locale locale);
/**
* Return the renderKitId to be used for rendering
* this application. If not explicitly set, null is
* returned.
*/
public abstract String getDefaultRenderKitId();
/**
* Set the renderKitId to be used to render this
* application. Unless the client has provided a custom {@link ViewHandler}
* that supports the use of multiple {@link javax.faces.render.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 void setDefaultRenderKitId(String renderKitId);
/**
* 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 String getMessageBundle();
/**
* 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.
*
* @param bundle Base name of the resource bundle to be used
*
* @throws NullPointerException if bundle
* is null
*/
public abstract void setMessageBundle(String bundle);
/**
* Return the {@link 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
* {@link NavigationHandler} class description.
*/
public abstract NavigationHandler getNavigationHandler();
/**
* Set the {@link NavigationHandler} instance that will be passed
* the outcome returned by any invoked application action for this
* web application.
*
* @param handler The new {@link NavigationHandler} instance
*
* @throws NullPointerException if handler
* is null
*/
public abstract void setNavigationHandler(NavigationHandler handler);
/**
* Return a {@link PropertyResolver} instance that wraps the
* {@link 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.
*
* @deprecated This has been replaced by {@link #getELResolver}.
*/
public abstract PropertyResolver getPropertyResolver();
/**
* Set the {@link 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.
*
* @param resolver The new {@link PropertyResolver} instance
*
* @throws NullPointerException if resolver
* is null
*
* @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 {@link ELResolver} and
* exposed to the EL resolution system as if the user had called
* {@link #addELResolver}.
*
* @throws IllegalStateException if called after the first
* request to the {@link javax.faces.webapp.FacesServlet} has been
* serviced.
*/
public abstract void setPropertyResolver(PropertyResolver resolver);
/**
* 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 {@link
* javax.faces.component.UIViewRoot}.
*
* The default implementation throws
* UnsupportedOperationException and is provided
* for the sole purpose of not breaking existing applications that extend
* this class.
*
* @return ResourceBundle for the current UIViewRoot,
* otherwise null
*
* @throws FacesException if a bundle was defined, but not resolvable
*
* @throws NullPointerException if ctx == null || name == null
*
* @since 1.2
*/
public ResourceBundle getResourceBundle(FacesContext ctx, String name) {
Application impl;
if (null != (impl = (Application) ctx.getExternalContext().getApplicationMap().
get("com.sun.faces.ApplicationImpl"))) {
//noinspection TailRecursion
return impl.getResourceBundle(ctx, name);
}
throw new UnsupportedOperationException();
}
/**
* Return the {@link VariableResolver} that wraps the {@link
* 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.
*
* @deprecated This has been replaced by {@link #getELResolver}.
*/
public abstract VariableResolver getVariableResolver();
/**
* Set the {@link 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.
*
* @param resolver The new {@link VariableResolver} instance
*
* @throws NullPointerException if resolver
* is null
*
* @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 {@link ELResolver} and
* exposed to the EL resolution system as if the user had called
* {@link #addELResolver}.
*
* @throws IllegalStateException if called after the first
* request to the {@link javax.faces.webapp.FacesServlet} has been
* serviced.
*/
public abstract void setVariableResolver(VariableResolver resolver);
/**
* Cause an the argument resolver to be added to the
* resolver chain as specified in section 5.5.1 of the JavaServer
* Faces Specification.
*
* It is not possible to remove an ELResolver
* registered with this method, once it has been registered.
*
* It is illegal to register an ELResolver after
* the application has received any requests from the client. If an
* attempt is made to register a listener after that time, an
* IllegalStateException must be thrown. 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
* {@link Application}.
*
* @since 1.2
*/
public void addELResolver(ELResolver resolver) {
throw new UnsupportedOperationException();
}
/**
* Return the singleton {@link ELResolver} instance to be used
* for all EL resolution. This is actually an instance of {@link
* javax.el.CompositeELResolver} that must contain the following
* ELResolver instances in the following order:
*
*
*
* ELResolver instances declared using the
* <el-resolver> element in the application configuration
* resources.
An implementation that wraps the head of
* the legacy VariableResolver chain, as per section
* VariableResolver ChainWrapper in Chapter 5 in the spec
* document.
An implementation that wraps the head of
* the legacy PropertyResolver chain, as per section
* PropertyResolver ChainWrapper in Chapter 5 in the spec
* document.
Any ELResolver instances added by calls to
* {@link #addELResolver}.
*
* The default implementation throws UnsupportedOperationException
* and is provided for the sole purpose of not breaking existing applications
* that extend {@link Application}.
*
* @since 1.2
*/
public ELResolver getELResolver() {
throw new UnsupportedOperationException();
}
/**
* Return the {@link 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 {@link ViewHandler} description in the
* JavaServer Faces Specification.
*/
public abstract ViewHandler getViewHandler();
/**
* Set the {@link ViewHandler} instance that will be utilized
* during the Restore View and Render Response
* phases of the request processing lifecycle.
*
* @param handler The new {@link ViewHandler} instance
*
* @throws IllegalStateException if this method is called after
* at least one request has been processed by the
* Lifecycle instance for this application.
* @throws NullPointerException if handler
* is null
*/
public abstract void setViewHandler(ViewHandler handler);
/**
* Return the {@link 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 {@link StateManager} description
* in the JavaServer Faces Specification.
*/
public abstract StateManager getStateManager();
/**
* Set the {@link StateManager} instance that will be utilized
* during the Restore View and Render Response
* phases of the request processing lifecycle.
*
* @param manager The new {@link StateManager} instance
*
* @throws IllegalStateException if this method is called after
* at least one request has been processed by the
* Lifecycle instance for this application.
* @throws NullPointerException if manager
* is null
*/
public abstract void setStateManager(StateManager manager);
// ------------------------------------------------------- Object Factories
/**
* Register a new mapping of component type to the name of the
* corresponding {@link UIComponent} class. This allows subsequent calls
* to createComponent() to serve as a factory for
* {@link UIComponent} instances.
*
* @param componentType The component type to be registered
* @param componentClass The fully qualified class name of the
* corresponding {@link UIComponent} implementation
*
* @throws NullPointerException if componentType or
* componentClass is null
*/
public abstract void addComponent(String componentType,
String componentClass);
/**
* Instantiate and return a new {@link UIComponent} instance of the
* class specified by a previous call to addComponent() for
* the specified component type.
*
* @param componentType The component type for which to create and
* return a new {@link UIComponent} instance
*
* @throws FacesException if a {@link UIComponent} of the
* specified type cannot be created
* @throws NullPointerException if componentType
* is null
*/
public abstract UIComponent createComponent(String componentType)
throws FacesException;
/**
* Wrap the argument componentBinding in an
* implementation of {@link ValueExpression} and call through to
* {@link
* #createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String)}.
*
* @param componentBinding {@link ValueBinding} representing a
* component value binding expression (typically specified by the
* component attribute of a custom tag)
* @param context {@link FacesContext} for the current request
* @param componentType Component type to create if the {@link ValueBinding}
* does not return a component instance
*
* @throws FacesException if a {@link UIComponent} cannot be created
* @throws NullPointerException if any parameter is null
*
*
* @deprecated This has been replaced by {@link
* #createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String)}.
*/
public abstract UIComponent createComponent(ValueBinding componentBinding,
FacesContext context,
String componentType)
throws FacesException;
/**
* Call the getValue() method on the specified
* {@link ValueExpression}. If it returns a {@link
* UIComponent} instance, return it as the value of this method. If
* it does not, instantiate a new {@link UIComponent} instance of
* the specified component type, pass the new component to the
* setValue() method of the specified {@link
* ValueExpression}, and return it.
*
* @param componentExpression {@link ValueExpression} representing a
* component value expression (typically specified by the
* component attribute of a custom tag)
* @param context {@link FacesContext} for the current request
* @param componentType Component type to create if the {@link
* ValueExpression} does not return a component instance
*
* @throws FacesException if a {@link UIComponent} cannot be created
* @throws NullPointerException if any parameter is null
*
* A default implementation is provided that throws
* UnsupportedOperationException so that users
* that decorate Application can continue to function
.
*
* @since 1.2
*/
public UIComponent createComponent(ValueExpression componentExpression,
FacesContext context,
String componentType)
throws FacesException {
if (null == componentExpression || null == context ||
null == componentType) {
// PENDING - i18n
StringBuilder builder = new StringBuilder(64);
builder.append("null parameters - ");
builder.append("componentExpression: ").append(componentExpression);
builder.append(", context: ").append(context);
builder.append(", componentType: ").append(componentType);
throw new NullPointerException(builder.toString());
}
Object result;
boolean createOne = false;
try {
if (null != (result =
componentExpression.getValue(context.getELContext()))) {
// if the result is not an instance of UIComponent
createOne = (!(result instanceof UIComponent));
// we have to create one.
}
if (null == result || createOne) {
result = this.createComponent(componentType);
componentExpression.setValue((context.getELContext()), result);
}
} catch (ELException elex) {
throw new FacesException(elex);
}
return (UIComponent) result;
}
/**
* Return an Iterator over the set of currently defined
* component types for this Application.
*/
public abstract Iterator getComponentTypes();
/**
* Register a new mapping of converter id to the name of the
* corresponding {@link Converter} class. This allows subsequent calls
* to createConverter() to serve as a factory for
* {@link Converter} instances.
*
* @param converterId The converter id to be registered
* @param converterClass The fully qualified class name of the
* corresponding {@link Converter} implementation
*
* @throws NullPointerException if converterId
* or converterClass is null
*/
public abstract void addConverter(String converterId,
String converterClass);
/**
* Register a new converter class that is capable of performing
* conversions for the specified target class.
*
* @param targetClass The class for which this converter is registered
* @param converterClass The fully qualified class name of the
* corresponding {@link Converter} implementation
*
* @throws NullPointerException if targetClass
* or converterClass is null
*/
public abstract void addConverter(Class targetClass,
String converterClass);
/**
* Instantiate and return a new {@link Converter} instance of the
* class specified by a previous call to addConverter()
* for the specified converter id. If there is no such registration
* for this converter id, return null.
*
* @param converterId The converter id for which to create and
* return a new {@link Converter} instance
*
* @throws FacesException if the {@link Converter} cannot be
* created
* @throws NullPointerException if converterId
* is null
*/
public abstract Converter createConverter(String converterId);
/**
* Instantiate and return a new {@link Converter} instance of the
* class that has registered itself as capable of performing conversions
* for objects of the specified type. If no such {@link Converter} class
* can be identified, return null.
*
* To locate an appropriate {@link Converter} class, the following
* algorithm is performed, stopping as soon as an appropriate {@link
* Converter} class is found:
*
* - Locate a {@link Converter} registered for the target class itself.
*
* - Locate a {@link Converter} registered for interfaces that are
* implemented by the target class (directly or indirectly).
* - Locate a {@link 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.
*
*
* @param targetClass Target class for which to return a {@link Converter}
*
* @throws FacesException if the {@link Converter} cannot be
* created
* @throws NullPointerException if targetClass
* is null
*/
public abstract Converter createConverter(Class targetClass);
/**
* Return an Iterator over the set of currently registered
* converter ids for this Application.
*/
public abstract Iterator getConverterIds();
/**
* Return an Iterator over the set of Class
* instances for which {@link Converter} classes have been explicitly
* registered.
*/
public abstract Iterator getConverterTypes();
/**
* Return the {@link ExpressionFactory} instance for this
* application. This instance is used by the convenience method
* {@link #evaluateExpressionGet}.
*
* The implementation must return the
* ExpressionFactory from the JSP container by calling
* JspFactory.getDefaultFactory().getJspApplicationContext(servletContext).getExpressionFactory().
*
* An implementation is provided that throws
* UnsupportedOperationException so that users that decorate
* the Application continue to work.
*
* @since 1.2
*/
public ExpressionFactory getExpressionFactory() {
throw new UnsupportedOperationException();
}
/**
*
Get a value by evaluating an expression.
*
* Call {@link #getExpressionFactory} then call {@link
* ExpressionFactory#createValueExpression} passing the argument
* expression and expectedType. Call
* {@link FacesContext#getELContext} and pass it to {@link
* ValueExpression#getValue}, returning the result.
*
* An implementation is provided that throws
* UnsupportedOperationException so that users that decorate
* the Application continue to work.
*
*/
public Object evaluateExpressionGet(FacesContext context,
String expression,
Class expectedType) throws ELException {
throw new UnsupportedOperationException();
}
/**
*
Call {@link #getExpressionFactory} then call {@link
* ExpressionFactory#createMethodExpression}, passing the given
* arguments, and wrap the result in a MethodBinding
* implementation, returning it.
*
* @param ref Method binding expression for which to return a
* {@link MethodBinding} instance
* @param params Parameter signatures that must be compatible with those
* of the method to be invoked, or a zero-length array or null
* for a method that takes no parameters
*
* @throws NullPointerException if ref
* is null
* @throws ReferenceSyntaxException if the specified ref
* has invalid syntax
*
* @deprecated This has been replaced by calling {@link
* #getExpressionFactory} then {@link
* ExpressionFactory#createMethodExpression}.
*/
public abstract MethodBinding createMethodBinding(String ref,
Class params[])
throws ReferenceSyntaxException;
/**
* Return an Iterator over the supported
* Locales for this appication.
*/
public abstract Iterator getSupportedLocales();
/**
* Set the Locale instances representing the supported
* Locales for this application.
*
* @param locales The set of supported Locales
* for this application
*
* @throws NullPointerException if the argument
* newLocales is null.
*
*/
public abstract void setSupportedLocales(Collection locales);
/**
* Provide a way for Faces applications to register an
* ELContextListener that will be notified on creation
* of ELContext instances. This listener will be
* called once per request.
*
* An implementation is provided that throws
* UnsupportedOperationException so that users that decorate
* the Application continue to work.
*
* @since 1.2
*/
public void addELContextListener(ELContextListener listener) {
throw new UnsupportedOperationException();
}
/**
*
Remove the argument listener from the list of
* {@link ELContextListener}s. If listener is null, no
* exception is thrown and no action is performed. If
* listener is not in the list, no exception is thrown
* and no action is performed.
*
* An implementation is provided that throws
* UnsupportedOperationException so that users that decorate
* the Application continue to work.
*
* @since 1.2
*/
public void removeELContextListener(ELContextListener listener) {
throw new UnsupportedOperationException();
}
/**
*
If no calls have been made to {@link #addELContextListener},
* this method must return an empty array.
*
* Otherwise, return an array representing the list of listeners
* added by calls to {@link #addELContextListener}.
*
* An implementation is provided that throws
* UnsupportedOperationException so that users that decorate
* the Application continue to work.
*
* @since 1.2
*/
public ELContextListener [] getELContextListeners() {
throw new UnsupportedOperationException();
}
/**
*
Register a new mapping of validator id to the name of the
* corresponding {@link Validator} class. This allows subsequent calls
* to createValidator() to serve as a factory for
* {@link Validator} instances.
*
* @param validatorId The validator id to be registered
* @param validatorClass The fully qualified class name of the
* corresponding {@link Validator} implementation
*
* @throws NullPointerException if validatorId
* or validatorClass is null
*/
public abstract void addValidator(String validatorId,
String validatorClass);
/**
* Instantiate and return a new {@link Validator} instance of the
* class specified by a previous call to addValidator()
* for the specified validator id.
*
* @param validatorId The validator id for which to create and
* return a new {@link Validator} instance
*
* @throws FacesException if a {@link Validator} of the
* specified id cannot be created
* @throws NullPointerException if validatorId
* is null
*/
public abstract Validator createValidator(String validatorId)
throws FacesException;
/**
* Return an Iterator over the set of currently registered
* validator ids for this Application.
*/
public abstract Iterator getValidatorIds();
/**
* Call {@link #getExpressionFactory} then call {@link
* ExpressionFactory#createValueExpression}, passing the argument
* ref, Object.class for the expectedType,
* and null, for the fnMapper.
*
*
* @param ref Value binding expression for which to return a
* {@link ValueBinding} instance
*
* @throws NullPointerException if ref
* is null
* @throws ReferenceSyntaxException if the specified ref
* has invalid syntax
*
* @deprecated This has been replaced by calling {@link
* #getExpressionFactory} then {@link
* ExpressionFactory#createValueExpression}.
*/
public abstract ValueBinding createValueBinding(String ref)
throws ReferenceSyntaxException;
}