001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Portions Copyright Apache Software Foundation.
007: *
008: * The contents of this file are subject to the terms of either the GNU
009: * General Public License Version 2 only ("GPL") or the Common Development
010: * and Distribution License("CDDL") (collectively, the "License"). You
011: * may not use this file except in compliance with the License. You can obtain
012: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
013: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
014: * language governing permissions and limitations under the License.
015: *
016: * When distributing the software, include this License Header Notice in each
017: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
018: * Sun designates this particular file as subject to the "Classpath" exception
019: * as provided by Sun in the GPL Version 2 section of the License file that
020: * accompanied this code. If applicable, add the following below the License
021: * Header, with the fields enclosed by brackets [] replaced by your own
022: * identifying information: "Portions Copyrighted [year]
023: * [name of copyright owner]"
024: *
025: * Contributor(s):
026: *
027: * If you wish your version of this file to be governed by only the CDDL or
028: * only the GPL Version 2, indicate your decision by adding "[Contributor]
029: * elects to include this software in this distribution under the [CDDL or GPL
030: * Version 2] license." If you don't indicate a single choice of license, a
031: * recipient has the option to distribute your version of this file under
032: * either the CDDL, the GPL Version 2 or to extend the choice of license to
033: * its licensees as provided above. However, if you add GPL Version 2 code
034: * and therefore, elected the GPL Version 2 license, then the option applies
035: * only if the new code is made subject to such option by the copyright
036: * holder.
037: */
038:
039: package javax.servlet.jsp;
040:
041: import javax.el.ELResolver;
042: import javax.el.ExpressionFactory;
043: import javax.el.ELContextListener;
044:
045: /**
046: * Stores application-scoped information relevant to JSP containers.
047: *
048: * <p>The JSP container must create a single instance of
049: * <code>JspApplicationContext</code> for each
050: * <code>ServletContext</code> instance.</p>
051: *
052: * <p>An instance of <code>JspApplicationContext</code> is obtained by
053: * invoking the static {@link JspFactory#getJspApplicationContext} method,
054: * passing the <code>ServletContext</code> of the corresponding web
055: * application.</p>
056: *
057: * <p>The <code>JspApplicationContext</code> provides the following services
058: * to JSP applications:
059: * <ul>
060: * <li>Allows registration of <code>ELResolver</code>s, which are used to
061: * resolve variables in EL expressions contained in JSP pages and
062: * tag files.</li>
063: * <li>Provides an instance of <code>ExpressionFactory</code> for those
064: * applications or frameworks that need to perform programmatic
065: * evaluation of EL expressions instead of allowing the JSP
066: * container to do it for them.</li>
067: * <li>Allows the attachment of <code>ELContextListener</code> instances
068: * for notification whenever a new <code>ELContext</code> is created.
069: * This is necessary when an application wishes to make custom
070: * context objects available to their pluggable
071: * <code>ELResolver</code>s.</li>
072: * </ul>
073: * </p>
074: *
075: * @see javax.servlet.ServletContext
076: * @see JspFactory
077: * @see javax.el.ELResolver
078: * @see javax.el.ExpressionFactory
079: * @see javax.el.ELContextListener
080: * @since JSP 2.1
081: */
082: public interface JspApplicationContext {
083:
084: /**
085: * Adds an <code>ELResolver</code> to affect the way EL variables
086: * and properties are resolved for EL expressions appearing in JSP pages
087: * and tag files.
088: *
089: * <p>For example, in the EL expression ${employee.lastName}, an
090: * <code>ELResolver</code> determines what object "employee"
091: * references and how to find its "lastName" property.</p>
092: *
093: * <p>When evaluating an expression, the JSP container will consult a
094: * set of standard resolvers as well as any resolvers registered via
095: * this method. The set of resolvers are consulted in the following
096: * order:
097: * <ul>
098: * <li>{@link javax.servlet.jsp.el.ImplicitObjectELResolver}</li>
099: * <li><code>ELResolver</code>s registered via this method, in the
100: * order in which they are registered.</li>
101: * <li>{@link javax.el.MapELResolver}</li>
102: * <li>{@link javax.el.ListELResolver}</li>
103: * <li>{@link javax.el.ArrayELResolver}</li>
104: * <li>{@link javax.el.BeanELResolver}</li>
105: * <li>{@link javax.servlet.jsp.el.ScopedAttributeELResolver}</li>
106: * </ul></p>
107: *
108: * <p>It is illegal to register an <code>ELResolver</code> after the
109: * application has received any request from the client. If an
110: * attempt is made to register an <code>ELResolver</code> after that time,
111: * an <code>IllegalStateException</code> is thrown.</p>
112: * This restriction is
113: * in place to allow the JSP container to optimize for the common
114: * case where no additional <code>ELResolver</code>s are in the chain,
115: * aside from the standard ones. It is permissible to add
116: * <code>ELResolver</code>s before or after initialization to
117: * a <code>CompositeELResolver</code> that is already in the chain.</p>
118: *
119: * <p>It is not possible to remove an <code>ELResolver</code> registered
120: * with this method, once it has been registered.</p>
121: *
122: * @param resolver The new <code>ELResolver</code>
123: * @throws IllegalStateException if an attempt is made to
124: * call this method after all <code>ServletContextListener</code>s
125: * have had their <code>contextInitialized</code> methods invoked.
126: */
127: public void addELResolver(ELResolver resolver);
128:
129: /**
130: * Returns a factory used to create <code>ValueExpression</code>s and
131: * <code>MethodExpression</code>s so that EL expressions can be
132: * parsed and evaluated.
133: *
134: * @return A concrete implementation of the
135: * an <code>ExpressionFactory</code>.
136: */
137: public ExpressionFactory getExpressionFactory();
138:
139: /**
140: * Registers a <code>ELContextListener</code>s so that context objects
141: * can be added whenever a new <code>ELContext</code> is created.
142: *
143: * <p>At a minimum, the <code>ELContext</code> objects created will
144: * contain a reference to the <code>JspContext</code> for this request,
145: * which is added by the JSP container.
146: * This is sufficient for all the
147: * default <code>ELResolver</code>s listed in {@link #addELResolver}.
148: * Note that <code>JspContext.class</code> is used as the key to ELContext.putContext()
149: * for the <code>JspContext</code> object reference.</p>
150: *
151: * <p>This method is generally used by frameworks and applications that
152: * register their own <code>ELResolver</code> that needs context other
153: * than <code>JspContext</code>. The listener will typically add the
154: * necessary context to the <code>ELContext</code> provided in the
155: * event object. Registering a listener that adds context allows the
156: * <code>ELResolver</code>s in the stack to access the context they
157: * need when they do a resolution.</p>
158: *
159: * @param listener The listener to be notified when a new
160: * <code>ELContext</code> is created.
161: */
162: public void addELContextListener(ELContextListener listener);
163: }
|