001: /*
002: * Copyright (c) 1998-2008 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: *
023: * Free Software Foundation, Inc.
024: * 59 Temple Place, Suite 330
025: * Boston, MA 02111-1307 USA
026: *
027: * @author Scott Ferguson
028: */
029:
030: package javax.servlet;
031:
032: import java.io.InputStream;
033: import java.util.Enumeration;
034: import java.util.Set;
035:
036: /**
037: * ServletContexts encapsulate applications. Applications are generalized
038: * virtual hosts; a URL prefix defines a distinct application.
039: * So /myapp and /yourapp could define different applications. As a
040: * degenerate case, each virtual host has its own ServletContext.
041: *
042: * <p>Each application is entirely distinct. Each has its own:
043: * <ul>
044: * <li>Class loader -- each application gets its own beans and servlets.
045: * <li>ServletContext attributes
046: * <li>Servlets and servlet mappings (e.g. *.jsp could map to different
047: * servlets in different applications.)
048: * <li>File root
049: * <li>Mime mapping
050: * <li>Real-path mapping (aliases)
051: * </ul>
052: *
053: * <p>URIs are relative to the application root (e.g. /myapp) for
054: * most ServletContext methods. So you can define user workspaces with
055: * identical JSP files and servlets in different applications.
056: *
057: * <h4>Including and forwarding</h4>
058: *
059: * <p>Forwarding and including files, the Servlet equivalent of SSI are
060: * handled by the RequestDispatcher methods.
061: *
062: * <h4>Global initialization</h4>
063: *
064: * <p>There is no direct equivalent of a global.jsa. To initialize
065: * and cleanup shared classes on start and stop, use a load-on-startup
066: * servlet. The init() method will be called when the application starts
067: * and the destroy() method will be called when the application finishes.
068: *
069: * <pre><code>
070: * <servlet servlet-name='global'
071: * servlet-class='test.InitServlet'
072: * load-on-startup/>
073: * </code></pre>
074: *
075: * <h4>Basic configuration</h4>
076: *
077: * In the resin.conf, to define the /myapp application with a document
078: * root in /www/myweb, add the following to the resin.conf.
079: *
080: * <pre><code>
081: * <web-app id='/myapp' app-dir='/www/myweb'/>
082: * </code></pre>
083: *
084: * <h4>Servlet and Bean locations (class loaders)</h4>
085: *
086: * Each application has its own directories to load application servlets
087: * and beans. By default these are WEB-APP/classes and WEB-APP/lib.
088: * To add a servlet test.MyServlet, create the java file:
089: * <center>/www/myweb/WEB-APP/classes/test/MyServlet.java</center>
090: *
091: * <h4>Load balancing</h4>
092: *
093: * When using load balancing with a web server, each JVM will have its own
094: * application object. The attributes are not shared. In contrast,
095: * sessions are always sent to the same JVM.
096: *
097: * <p>So the application object is best used as a cache rather than
098: * as a way for servlets to communicate.
099: */
100: public interface ServletContext {
101: /**
102: * Returns the URL prefix for the ServletContext.
103: */
104: public String getServletContextName();
105:
106: /**
107: * Returns a server-specific string identifying the servlet engine.
108: */
109: public String getServerInfo();
110:
111: /**
112: * Returns the major version of the servlet API.
113: */
114: public int getMajorVersion();
115:
116: /**
117: * Returns the minor version of the servlet API.
118: */
119: public int getMinorVersion();
120:
121: /**
122: * Returns the value of an initialization parameter from the configuration
123: * file.
124: *
125: * The Resin configuration looks something like:
126: * <pre><code>
127: * <web-app id='/myapp' app-dir='/www/myapp'>
128: * <context-param name1='value1'/>
129: * <context-param name2='value2'/>
130: * </web-app>
131: * </code></pre>
132: *
133: * @param name init parameter name
134: * @return init parameter value
135: */
136: public String getInitParameter(String name);
137:
138: /**
139: * Returns an enumeration of all init parameter names.
140: */
141: public Enumeration getInitParameterNames();
142:
143: /**
144: * Returns the ServletContext for the uri.
145: * Note: the uri is <em>not</em> relative to the application.
146: *
147: * @param uri path relative to the root
148: * @return the ServletContext responsible for the given uri.
149: */
150: public ServletContext getContext(String uri);
151:
152: /**
153: * Returns the context-path for the web-application.
154: */
155: public String getContextPath();
156:
157: /**
158: * Returns the real file path for the given uri. The file path will
159: * be in native path format (with native path separators.)
160: *
161: * <p>See ServletRequest to return the real path relative to the
162: * request uri.
163: *
164: * @param uri path relative to the application root to be translated.
165: * @return native file path for the uri.
166: */
167: public String getRealPath(String uri);
168:
169: /**
170: * Returns a request dispatcher for later inclusion or forwarding. This
171: * is the servlet API equivalent to SSI includes. The uri is relative
172: * to the application root.
173: *
174: * <p>The following example includes the result of executing inc.jsp
175: * into the output stream. If the context path is /myapp, the equivalent
176: * uri is /myapp/inc.jsp
177: *
178: * <code><pre>
179: * RequestDispatcher disp;
180: * disp = getRequestDispatcher("/inc.jsp?a=b");
181: * disp.include(request, response);
182: * </pre></code>
183: *
184: * <p>See ServletRequest to return a request dispatcher relative to the
185: * request uri.
186: *
187: * @param uri path relative to the app root (including query string)
188: * for the included file.
189: * @return RequestDispatcher for later inclusion or forwarding.
190: */
191: public RequestDispatcher getRequestDispatcher(String uri);
192:
193: /**
194: * Returns a request dispatcher based on a servlet name.
195: *
196: * @param servletName the servlet name to include or forward to.
197: * @return RequestDispatcher for later inclusion or forwarding.
198: */
199: public RequestDispatcher getNamedDispatcher(String servletName);
200:
201: /**
202: * Returns the mime type for the given uri.
203: *
204: * @param uri path relative to the application root.
205: */
206: public String getMimeType(String uri);
207:
208: /**
209: * Returns an attribute value.
210: *
211: * @param name of the attribute.
212: * @return stored value
213: */
214: public Object getAttribute(String name);
215:
216: /**
217: * Returns an enumeration of all the attribute names.
218: */
219: public Enumeration getAttributeNames();
220:
221: /**
222: * Sets an attribute value. Because servlets are multithreaded,
223: * setting ServletContext attributes will generally need synchronization.
224: *
225: * <p>A typical initialization of an application attribute will look like:
226: * <code><pre>
227: * ServletContext app = getServletContext();
228: * Object value;
229: * synchronized (app) {
230: * value = app.getAttribute("cache");
231: * if (value == null) {
232: * value = new Cache();
233: * app.setAttribute("cache", value);
234: * }
235: * }
236: * </pre></code>
237: *
238: * @param name of the attribute.
239: * @param value value to store
240: */
241: public void setAttribute(String name, Object value);
242:
243: /**
244: * Removes an attribute. Because servlets are multithreaded,
245: * removing ServletContext attributes will generally need synchronization.
246: *
247: * @param name of the attribute.
248: */
249: public void removeAttribute(String name);
250:
251: /**
252: * Logs a message.
253: */
254: public void log(String msg);
255:
256: /**
257: * Logs a message and a stack trace.
258: */
259: public void log(String message, Throwable throwable);
260:
261: /**
262: * Returns the resource for the given uri. In general, the
263: * RequestDispatcher routines are more useful.
264: *
265: * @param uri path relative to the application root.
266: */
267: public java.net.URL getResource(String uri)
268: throws java.net.MalformedURLException;
269:
270: /**
271: * Returns the set all resources held by the application.
272: */
273: public Set getResourcePaths(String prefix);
274:
275: /**
276: * Returns the resource as a stream. In general, the
277: * RequestDispatcher routines are more useful.
278: *
279: * @param uri path relative to the application root.
280: * @return InputStream to the resource.
281: */
282: public InputStream getResourceAsStream(String path);
283:
284: /**
285: * @deprecated
286: */
287: public Servlet getServlet(String name) throws ServletException;
288:
289: /**
290: * @deprecated
291: */
292: public Enumeration getServlets();
293:
294: /**
295: * @deprecated
296: */
297: public Enumeration getServletNames();
298:
299: /**
300: * @deprecated
301: */
302: public void log(Exception exception, String msg);
303:
304: }
|