jakarta.servlet.jsp.JspApplicationContext Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
* All rights reserved.
* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jakarta.servlet.jsp;
import jakarta.el.ELResolver;
import jakarta.el.ExpressionFactory;
import jakarta.el.ELContextListener;
/**
* Stores application-scoped information relevant to JSP containers.
*
*
* The JSP container must create a single instance of JspApplicationContext for each
* ServletContext instance.
*
*
*
* An instance of JspApplicationContext is obtained by invoking the static
* {@link JspFactory#getJspApplicationContext} method, passing the ServletContext of the corresponding web
* application.
*
*
*
* The JspApplicationContext provides the following services to JSP applications:
*
*
* - Allows registration of
ELResolvers, which are used to resolve variables in EL expressions contained
* in JSP pages and tag files.
* - Provides an instance of
ExpressionFactory for those applications or frameworks that need to perform
* programmatic evaluation of EL expressions instead of allowing the JSP container to do it for them.
* - Allows the attachment of
ELContextListener instances for notification whenever a new
* ELContext is created. This is necessary when an application wishes to make custom context objects
* available to their pluggable ELResolvers.
*
*
* @see jakarta.servlet.ServletContext
* @see JspFactory
* @see jakarta.el.ELResolver
* @see jakarta.el.ExpressionFactory
* @see jakarta.el.ELContextListener
* @since JSP 2.1
*/
public interface JspApplicationContext {
/**
* Adds an ELResolver to affect the way EL variables and properties are resolved for EL expressions
* appearing in JSP pages and tag files.
*
*
* For example, in the EL expression ${employee.lastName}, an ELResolver determines what object
* "employee" references and how to find its "lastName" property.
*
*
*
* When evaluating an expression, the JSP container will consult a set of standard resolvers as well as any
* resolvers registered via this method. The set of resolvers are consulted in the following order:
*
*
* - {@link jakarta.servlet.jsp.el.ImplicitObjectELResolver}
* ELResolvers registered via this method, in the order in which they are registered.- {@link jakarta.el.MapELResolver}
* - {@link jakarta.el.ListELResolver}
* - {@link jakarta.el.ArrayELResolver}
* - {@link jakarta.el.BeanELResolver}
* - {@link jakarta.servlet.jsp.el.ScopedAttributeELResolver}
*
*
*
* It is illegal to register an ELResolver after the application has received any request from the
* client. If an attempt is made to register an ELResolver after that time, an
* IllegalStateException is 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.
*
*
*
* It is not possible to remove an ELResolver registered with this method, once it has been registered.
*
*
* @param resolver The new ELResolver
* @throws IllegalStateException if an attempt is made to call this method after all
* ServletContextListeners have had their contextInitialized
* methods invoked.
*/
public void addELResolver(ELResolver resolver);
/**
* Returns a factory used to create ValueExpressions and MethodExpressions so that EL
* expressions can be parsed and evaluated.
*
* @return A concrete implementation of the an ExpressionFactory.
*/
public ExpressionFactory getExpressionFactory();
/**
* Registers a ELContextListeners so that context objects can be added whenever a new
* ELContext is created.
*
*
* At a minimum, the ELContext objects created will contain a reference to the JspContext
* for this request, which is added by the JSP container. This is sufficient for all the default
* ELResolvers listed in {@link #addELResolver}. Note that JspContext.class is used as the
* key to ELContext.putContext() for the JspContext object reference.
*
*
*
* This method is generally used by frameworks and applications that register their own ELResolver that
* needs context other than JspContext. The listener will typically add the necessary context to the
* ELContext provided in the event object. Registering a listener that adds context allows the
* ELResolvers in the stack to access the context they need when they do a resolution.
*
*
* @param listener The listener to be notified when a new ELContext is created.
*/
public void addELContextListener(ELContextListener listener);
}