Package: JspApplicationContext

JspApplicationContext

Coverage

1: /*
2: * Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: * Copyright 2004 The Apache Software Foundation
5: *
6: * Licensed under the Apache License, Version 2.0 (the "License");
7: * you may not use this file except in compliance with the License.
8: * You may obtain a copy of the License at
9: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing, software
13: * distributed under the License is distributed on an "AS IS" BASIS,
14: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: * See the License for the specific language governing permissions and
16: * limitations under the License.
17: */
18:
19: package jakarta.servlet.jsp;
20:
21: import jakarta.el.ELResolver;
22: import jakarta.el.ExpressionFactory;
23: import jakarta.el.ELContextListener;
24:
25: /**
26: * Stores application-scoped information relevant to JSP containers.
27: *
28: * <p>
29: * The JSP container must create a single instance of <code>JspApplicationContext</code> for each
30: * <code>ServletContext</code> instance.
31: * </p>
32: *
33: * <p>
34: * An instance of <code>JspApplicationContext</code> is obtained by invoking the static
35: * {@link JspFactory#getJspApplicationContext} method, passing the <code>ServletContext</code> of the corresponding web
36: * application.
37: * </p>
38: *
39: * <p>
40: * The <code>JspApplicationContext</code> provides the following services to JSP applications:
41: * </p>
42: * <ul>
43: * <li>Allows registration of <code>ELResolver</code>s, which are used to resolve variables in EL expressions contained
44: * in JSP pages and tag files.</li>
45: * <li>Provides an instance of <code>ExpressionFactory</code> for those applications or frameworks that need to perform
46: * programmatic evaluation of EL expressions instead of allowing the JSP container to do it for them.</li>
47: * <li>Allows the attachment of <code>ELContextListener</code> instances for notification whenever a new
48: * <code>ELContext</code> is created. This is necessary when an application wishes to make custom context objects
49: * available to their pluggable <code>ELResolver</code>s.</li>
50: * </ul>
51: *
52: * @see jakarta.servlet.ServletContext
53: * @see JspFactory
54: * @see jakarta.el.ELResolver
55: * @see jakarta.el.ExpressionFactory
56: * @see jakarta.el.ELContextListener
57: * @since JSP 2.1
58: */
59: public interface JspApplicationContext {
60:
61: /**
62: * Adds an <code>ELResolver</code> to affect the way EL variables and properties are resolved for EL expressions
63: * appearing in JSP pages and tag files.
64: *
65: * <p>
66: * For example, in the EL expression ${employee.lastName}, an <code>ELResolver</code> determines what object
67: * "employee" references and how to find its "lastName" property.
68: * </p>
69: *
70: * <p>
71: * When evaluating an expression, the JSP container will consult a set of standard resolvers as well as any
72: * resolvers registered via this method. The set of resolvers are consulted in the following order:
73: * </p>
74: * <ul>
75: * <li>{@link jakarta.servlet.jsp.el.ImplicitObjectELResolver}</li>
76: * <li><code>ELResolver</code>s registered via this method, in the order in which they are registered.</li>
77: * <li>{@link jakarta.el.MapELResolver}</li>
78: * <li>{@link jakarta.el.ListELResolver}</li>
79: * <li>{@link jakarta.el.ArrayELResolver}</li>
80: * <li>{@link jakarta.el.BeanELResolver}</li>
81: * <li>{@link jakarta.servlet.jsp.el.ScopedAttributeELResolver}</li>
82: * </ul>
83: *
84: * <p>
85: * It is illegal to register an <code>ELResolver</code> after the application has received any request from the
86: * client. If an attempt is made to register an <code>ELResolver</code> after that time, an
87: * <code>IllegalStateException</code> is thrown.
88: * </p>
89: * <p>
90: * This restriction is in place to allow the JSP container to optimize for the common case where no additional
91: * <code>ELResolver</code>s are in the chain, aside from the standard ones. It is permissible to add
92: * <code>ELResolver</code>s before or after initialization to a <code>CompositeELResolver</code> that is already in
93: * the chain.
94: * </p>
95: *
96: * <p>
97: * It is not possible to remove an <code>ELResolver</code> registered with this method, once it has been registered.
98: * </p>
99: *
100: * @param resolver The new <code>ELResolver</code>
101: * @throws IllegalStateException if an attempt is made to call this method after all
102: * <code>ServletContextListener</code>s have had their <code>contextInitialized</code>
103: * methods invoked.
104: */
105: public void addELResolver(ELResolver resolver);
106:
107: /**
108: * Returns a factory used to create <code>ValueExpression</code>s and <code>MethodExpression</code>s so that EL
109: * expressions can be parsed and evaluated.
110: *
111: * @return A concrete implementation of the an <code>ExpressionFactory</code>.
112: */
113: public ExpressionFactory getExpressionFactory();
114:
115: /**
116: * Registers a <code>ELContextListener</code>s so that context objects can be added whenever a new
117: * <code>ELContext</code> is created.
118: *
119: * <p>
120: * At a minimum, the <code>ELContext</code> objects created will contain a reference to the <code>JspContext</code>
121: * for this request, which is added by the JSP container. This is sufficient for all the default
122: * <code>ELResolver</code>s listed in {@link #addELResolver}. Note that <code>JspContext.class</code> is used as the
123: * key to ELContext.putContext() for the <code>JspContext</code> object reference.
124: * </p>
125: *
126: * <p>
127: * This method is generally used by frameworks and applications that register their own <code>ELResolver</code> that
128: * needs context other than <code>JspContext</code>. The listener will typically add the necessary context to the
129: * <code>ELContext</code> provided in the event object. Registering a listener that adds context allows the
130: * <code>ELResolver</code>s in the stack to access the context they need when they do a resolution.
131: * </p>
132: *
133: * @param listener The listener to be notified when a new <code>ELContext</code> is created.
134: */
135: public void addELContextListener(ELContextListener listener);
136: }