001: /*
002: * HttpScriptContext.java
003: *
004: * @author Mike Grogan
005: * @version 1.0
006: * @Created on December 18, 2003, 9:26 PM
007: */
008:
009: package javax.script.http;
010:
011: import javax.servlet.http.*;
012: import javax.servlet.*;
013: import java.io.Reader;
014: import java.io.IOException;
015: import javax.script.*;
016:
017: /**
018: * Classes implementing the <code>HttpScriptContext</code> interface connect a
019: * <code>ScriptEngine</code> with the implicit objects from a Servlet Container.
020: * <br><br>
021: * The interface contains methods that allow a <code>HttpScriptServlet</code> to initialize the
022: * <code>HttpScriptContext</code> with the implicit objects for each request,
023: * and methods that allow a <code>ScriptEngine</code> to access them.
024: * <p>The objects may be used by internal constructs related to the web environment in
025: * the scripting languages, and are also generally exposed in the namespaces
026: * of scripts executing in the engines.
027: *
028: */
029:
030: public interface HttpScriptContext extends ScriptContext {
031:
032: /**
033: * RequestScope attributes are visible during the processing
034: * of a single request.
035: */
036: public static final int REQUEST_SCOPE = 0;
037:
038: /**
039: * SessionScope attributes are visible during the processing
040: * of all requests belonging to a single <code>HttpSession</code>
041: * during the lifetime of the session.
042: */
043: public static final int SESSION_SCOPE = 150;
044:
045: /**
046: * ApplicationScope attributes are visible during the processing
047: * of all requests belonging to a single Web Application.
048: */
049: public static final int APPLICATION_SCOPE = 175;
050:
051: /**
052: * Initializes this <code>HttpScriptContext</code> for processing of a single
053: * request. Implementations must initialize attributes in <code>REQUEST_SCOPE</code>,
054: * <code>SESSION_SCOPE</code> and <code>APPLICATION_SCOPE</code>
055: * and store servlet, request and response references for use by the <code>ScriptEngine</code>
056: * executing the request.
057: * @param servlet The <code>HttpScriptServlet</code> executing the request
058: * @param req The current request.
059: * @param res The current response.
060: * @throws ServletException If a <code>ScriptExcepton</code> is thrown by the <code>ScriptEngine</code>
061: * during the processing of a request.
062: */
063: public void initialize(Servlet servlet, HttpServletRequest req,
064: HttpServletResponse res) throws ServletException;
065:
066: /**
067: * Clears any state stored in this <code>HttpScriptContext</code>, allowing its
068: * reuse by other requests.
069: */
070: public void release();
071:
072: /**
073: * Gets the value of the attribute in the specified scope. Initially, the
074: * <code>REQUEST_SCOPE</code>, <code>SESSION_SCOPE</code> and
075: * <code>APPLICATION_SCOPE</code> should be initialized using the values of the
076: * request attributes, session attributes and context attributes associated
077: * with the current request. Also, the following mappings should
078: * be included in the initial values of the <code>REQUEST_SCOPE</code> attributes:
079: *<br><br>
080: * <center>
081: * <table border="1">
082: * <tr><td><b>Name</b></td><td><b>Value</b></td></tr>
083: * <tr><td>Request</td><td>return value of <code>getRequest</code></td></tr>
084: * <tr><td>Response</td><td>return value of <code>getResponse</code></td></tr>
085: * <tr><td>Servlet</td><td>return value of <code>getServlet</code></td></tr>
086: * </table>
087: * </center>
088: * <br><br>
089: * Attempts to access <code>SESSION_SCOPE</code>
090: * attributes should return <code>null</code> if <code>useSession</code>
091: * returns <code>false</code> or if the current session is invalid.
092: * @param name The name of the attribute to get
093: * @param scope The scope used to find the attribute
094: * @return the value of the attribute.
095: * @throws IllegalArgumentException if scope is invalid.
096: */
097: public Object getAttribute(String name, int scope);
098:
099: /**
100: * Returns the value of the attribute in the lowest scope for which
101: * the attribute is defined. Return <code>null</code> if an attribute
102: * with the given name is not defined in any scope.
103: */
104:
105: public Object getAttribute(String name);
106:
107: /**
108: * Sets the value of the named attribute in the specified scope.
109: * Calls using <code>REQUEST_SCOPE</code>, <code>SESSION_SCOPE</code>
110: * and <code>APPLICATION_SCOPE</code> should set the corresponding
111: * request attribute, session attribute or context attribute for the current request.
112: * @param name The name of the attribute to set.
113: * @param value The value of the attribute to set.
114: * @param scope The scope in which to set the attribute.
115: * @throws IllegalArgumentException if scope is invalid.
116: * @throws IllegalStateException if scope is <code>SESSION_SCOPE</code>
117: * and session is either invalid or disabled according to the return
118: * value of <code>useSession</code>.
119: */
120: public void setAttribute(String name, Object value, int scope);
121:
122: /**
123: * Returns a Reader from which the source of the script used to execute the
124: * current request can be read. This may be obtained from a resource in the current
125: * Web Application whose name is derived from the URI of the current request, a
126: * script directory in the filesystem specified in the configuration of the
127: * Web Application or in some implementation-defined way.
128: */
129: public Reader getScriptSource();
130:
131: /**
132: * Returns the <code>HttpServoetRequest</code> for the current request. If the
133: * use of session state is disabled using the <tt>script-use-session</tt>
134: * initialization parameter, an adapter whose <code>getSession</code> method
135: * returns <code>null</code> must be returned.
136: *
137: * @return The current request
138: */
139: public HttpServletRequest getRequest();
140:
141: /**
142: * Returns the <code>HttpServletResponse</code> for the current request.
143: *
144: * @return The current response
145: */
146: public HttpServletResponse getResponse();
147:
148: /**
149: * Returns the <code>HttpScriptServlet</code> using the <code>HttpScriptContext</code>.
150: *
151: * @return The current servlet
152: */
153: public Servlet getServlet();
154:
155: /**
156: * Forward the request to the resource identified by the specified
157: * relative path.
158: * @param relativePath The URI to process the request. The path
159: * is resolved according to the rules specified in the <code>forward</code>
160: * method of <code>javax.servlet.jsp.PageContext</code>.
161: * @throws ServletException
162: */
163: public void forward(String relativePath) throws ServletException,
164: IOException;
165:
166: /**
167: * Includes the resource identified by the specified
168: * relative path.
169: * @param relativePath The URI to process the request. The path
170: * is resolved according to the rules specified in the <code>include</code>
171: * method of <code>javax.servlet.jsp.PageContext</code>.
172: * @throws ServletException
173: */
174: public void include(String relativePath) throws ServletException,
175: IOException;
176:
177: /**
178: * Return value indicates whether script execution has been
179: * disabled in the Web Application. This is determined by the value
180: * of the application's initialization parameter <tt>script-disable</tt>.
181: * @return <code>false</code> unless the value of that parameter is "true".
182: * Returns <code>true</code> in that case.
183: */
184: public boolean disableScript();
185:
186: /**
187: * Return value indicates whether the <code>HttpSession</code> associated
188: * with the current request is exposed in the SESSION_SCOPE attributes and
189: * in the <code>HttpScriptRequest</code> returned by <code>getRequest</code>.
190: * This is determined by the value of the <tt>script-use-session</tt> Web Application
191: * initialization parameter.
192: * @return <code>true</code> unless the value of the <tt>script-use-session</tt>
193: * parameter is "false". Returns <code>false</code> in that case.
194: *
195: */
196: public boolean useSession();
197:
198: /**
199: * Return value indicates whether a <code>HttpScriptServlet</code> executing in this context
200: * should display the results of script evaluations.<p> If <code>true</code>, the
201: * servlet should display the <code>toString</code> of the value returned by script execution using the
202: * Writer returned by the <code>getWriter</code> method.
203: * <p>
204: * The value is determined by the <tt>script-display-results</tt> initialization parameter.
205: * @return <code>true</code> unless the value of the <tt>script-display-results</tt>
206: * initialization parameter is "false". Returns <code>false</code> in that case.
207: */
208: public boolean displayResults();
209:
210: /**
211: * An array of Strings describing the HTTP request methods handled by
212: * <code>HttpScriptServlets</code> executing in this context. The value is determined
213: * by the value of the <tt>script-methods</tt> Web Application initialization parameter.
214: * @return An array of (case-insensitive) method names. The elements of the array are
215: * determined by the <tt>script-methods</tt> initialization parameter, which is a comma-delimited
216: * list of the names.
217: */
218: public String[] getMethods();
219:
220: /**
221: * An array of Strings naming the languages that may be used by scripts running
222: * in this <code>HttpScriptContext</code>. The value is obtained from the
223: * <tt>allow-languages</tt> initialization parameter. A return value of <code>null</code>
224: * indicates that there is no restriction on script language.
225: * @return An array of allowed script languages.
226: */
227: public String[] getAllowedLanguages();
228: }
|