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);
}