001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.servlet;
017
018 import java.io.InputStream;
019 import java.net.MalformedURLException;
020 import java.net.URL;
021 import java.util.Enumeration;
022 import java.util.Set;
023
024 /**
025 *
026 * Defines a set of methods that a servlet uses to communicate with its
027 * servlet container, for example, to get the MIME type of a file, dispatch
028 * requests, or write to a log file.
029 *
030 * <p>There is one context per "web application" per Java Virtual Machine. (A
031 * "web application" is a collection of servlets and content installed under a
032 * specific subset of the server's URL namespace such as <code>/catalog</code>
033 * and possibly installed via a <code>.war</code> file.)
034 *
035 * <p>In the case of a web
036 * application marked "distributed" in its deployment descriptor, there will
037 * be one context instance for each virtual machine. In this situation, the
038 * context cannot be used as a location to share global information (because
039 * the information won't be truly global). Use an external resource like
040 * a database instead.
041 *
042 * <p>The <code>ServletContext</code> object is contained within
043 * the {@link ServletConfig} object, which the Web server provides the
044 * servlet when the servlet is initialized.
045 *
046 * @author Various
047 * @version $Version$
048 *
049 * @see Servlet#getServletConfig
050 * @see ServletConfig#getServletContext
051 *
052 */
053
054 public interface ServletContext {
055
056 /**
057 * Returns a <code>ServletContext</code> object that
058 * corresponds to a specified URL on the server.
059 *
060 * <p>This method allows servlets to gain
061 * access to the context for various parts of the server, and as
062 * needed obtain {@link RequestDispatcher} objects from the context.
063 * The given path must be begin with "/", is interpreted relative
064 * to the server's document root and is matched against the context roots of
065 * other web applications hosted on this container.
066 *
067 * <p>In a security conscious environment, the servlet container may
068 * return <code>null</code> for a given URL.
069 *
070 * @param uripath a <code>String</code> specifying the context path of
071 * another web application in the container.
072 * @return the <code>ServletContext</code> object that
073 * corresponds to the named URL, or null if either
074 none exists or the container wishes to restrict
075 * this access.
076 *
077 * @see RequestDispatcher
078 *
079 */
080
081 public ServletContext getContext(String uripath);
082
083 /**
084 * Returns the major version of the Java Servlet API that this
085 * servlet container supports. All implementations that comply
086 * with Version 2.4 must have this method
087 * return the integer 2.
088 *
089 * @return 2
090 *
091 */
092
093 public int getMajorVersion();
094
095 /**
096 * Returns the minor version of the Servlet API that this
097 * servlet container supports. All implementations that comply
098 * with Version 2.4 must have this method
099 * return the integer 4.
100 *
101 * @return 4
102 *
103 */
104
105 public int getMinorVersion();
106
107 /**
108 * Returns the MIME type of the specified file, or <code>null</code> if
109 * the MIME type is not known. The MIME type is determined
110 * by the configuration of the servlet container, and may be specified
111 * in a web application deployment descriptor. Common MIME
112 * types are <code>"text/html"</code> and <code>"image/gif"</code>.
113 *
114 *
115 * @param file a <code>String</code> specifying the name
116 * of a file
117 *
118 * @return a <code>String</code> specifying the file's MIME type
119 *
120 */
121
122 public String getMimeType(String file);
123
124 /**
125 * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path
126 * matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all
127 * relative to the root of the web application and have a leading '/'. For example, for a web application
128 * containing<br><br>
129
130 * /welcome.html<br>
131 * /catalog/index.html<br>
132 * /catalog/products.html<br>
133 * /catalog/offers/books.html<br>
134 * /catalog/offers/music.html<br>
135 * /customer/login.jsp<br>
136 * /WEB-INF/web.xml<br>
137 * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br>
138 *
139 * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br>
140 * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br>
141
142
143
144 *@param path the partial path used to match the resources,
145 * which must start with a /
146 *@return a Set containing the directory listing, or null if there are no resources in the web application whose path
147 * begins with the supplied path.
148
149 * @since Servlet 2.3
150 */
151
152 public Set getResourcePaths(String path);
153
154 /**
155 * Returns a URL to the resource that is mapped to a specified
156 * path. The path must begin with a "/" and is interpreted
157 * as relative to the current context root.
158 *
159 * <p>This method allows the servlet container to make a resource
160 * available to servlets from any source. Resources
161 * can be located on a local or remote
162 * file system, in a database, or in a <code>.war</code> file.
163 *
164 * <p>The servlet container must implement the URL handlers
165 * and <code>URLConnection</code> objects that are necessary
166 * to access the resource.
167 *
168 * <p>This method returns <code>null</code>
169 * if no resource is mapped to the pathname.
170 *
171 * <p>Some containers may allow writing to the URL returned by
172 * this method using the methods of the URL class.
173 *
174 * <p>The resource content is returned directly, so be aware that
175 * requesting a <code>.jsp</code> page returns the JSP source code.
176 * Use a <code>RequestDispatcher</code> instead to include results of
177 * an execution.
178 *
179 * <p>This method has a different purpose than
180 * <code>java.lang.Class.getResource</code>,
181 * which looks up resources based on a class loader. This
182 * method does not use class loaders.
183 *
184 * @param path a <code>String</code> specifying
185 * the path to the resource
186 *
187 * @return the resource located at the named path,
188 * or <code>null</code> if there is no resource
189 * at that path
190 *
191 * @exception MalformedURLException if the pathname is not given in
192 * the correct form
193 *
194 */
195
196 public URL getResource(String path) throws MalformedURLException;
197
198 /**
199 * Returns the resource located at the named path as
200 * an <code>InputStream</code> object.
201 *
202 * <p>The data in the <code>InputStream</code> can be
203 * of any type or length. The path must be specified according
204 * to the rules given in <code>getResource</code>.
205 * This method returns <code>null</code> if no resource exists at
206 * the specified path.
207 *
208 * <p>Meta-information such as content length and content type
209 * that is available via <code>getResource</code>
210 * method is lost when using this method.
211 *
212 * <p>The servlet container must implement the URL handlers
213 * and <code>URLConnection</code> objects necessary to access
214 * the resource.
215 *
216 * <p>This method is different from
217 * <code>java.lang.Class.getResourceAsStream</code>,
218 * which uses a class loader. This method allows servlet containers
219 * to make a resource available
220 * to a servlet from any location, without using a class loader.
221 *
222 *
223 * @param path a <code>String</code> specifying the path
224 * to the resource
225 *
226 * @return the <code>InputStream</code> returned to the
227 * servlet, or <code>null</code> if no resource
228 * exists at the specified path
229 *
230 *
231 */
232
233 public InputStream getResourceAsStream(String path);
234
235 /**
236 *
237 * Returns a {@link RequestDispatcher} object that acts
238 * as a wrapper for the resource located at the given path.
239 * A <code>RequestDispatcher</code> object can be used to forward
240 * a request to the resource or to include the resource in a response.
241 * The resource can be dynamic or static.
242 *
243 * <p>The pathname must begin with a "/" and is interpreted as relative
244 * to the current context root. Use <code>getContext</code> to obtain
245 * a <code>RequestDispatcher</code> for resources in foreign contexts.
246 * This method returns <code>null</code> if the <code>ServletContext</code>
247 * cannot return a <code>RequestDispatcher</code>.
248 *
249 * @param path a <code>String</code> specifying the pathname
250 * to the resource
251 *
252 * @return a <code>RequestDispatcher</code> object
253 * that acts as a wrapper for the resource
254 * at the specified path, or <code>null</code> if
255 * the <code>ServletContext</code> cannot return
256 * a <code>RequestDispatcher</code>
257 *
258 * @see RequestDispatcher
259 * @see ServletContext#getContext
260 *
261 */
262
263 public RequestDispatcher getRequestDispatcher(String path);
264
265 /**
266 * Returns a {@link RequestDispatcher} object that acts
267 * as a wrapper for the named servlet.
268 *
269 * <p>Servlets (and JSP pages also) may be given names via server
270 * administration or via a web application deployment descriptor.
271 * A servlet instance can determine its name using
272 * {@link ServletConfig#getServletName}.
273 *
274 * <p>This method returns <code>null</code> if the
275 * <code>ServletContext</code>
276 * cannot return a <code>RequestDispatcher</code> for any reason.
277 *
278 * @param name a <code>String</code> specifying the name
279 * of a servlet to wrap
280 *
281 * @return a <code>RequestDispatcher</code> object
282 * that acts as a wrapper for the named servlet,
283 * or <code>null</code> if the <code>ServletContext</code>
284 * cannot return a <code>RequestDispatcher</code>
285 *
286 * @see RequestDispatcher
287 * @see ServletContext#getContext
288 * @see ServletConfig#getServletName
289 *
290 */
291
292 public RequestDispatcher getNamedDispatcher(String name);
293
294 /**
295 *
296 * @deprecated As of Java Servlet API 2.1, with no direct replacement.
297 *
298 * <p>This method was originally defined to retrieve a servlet
299 * from a <code>ServletContext</code>. In this version, this method
300 * always returns <code>null</code> and remains only to preserve
301 * binary compatibility. This method will be permanently removed
302 * in a future version of the Java Servlet API.
303 *
304 * <p>In lieu of this method, servlets can share information using the
305 * <code>ServletContext</code> class and can perform shared business logic
306 * by invoking methods on common non-servlet classes.
307 *
308 */
309
310 public Servlet getServlet(String name) throws ServletException;
311
312 /**
313 *
314 * @deprecated As of Java Servlet API 2.0, with no replacement.
315 *
316 * <p>This method was originally defined to return an <code>Enumeration</code>
317 * of all the servlets known to this servlet context. In this
318 * version, this method always returns an empty enumeration and
319 * remains only to preserve binary compatibility. This method
320 * will be permanently removed in a future version of the Java
321 * Servlet API.
322 *
323 */
324
325 public Enumeration getServlets();
326
327 /**
328 * @deprecated As of Java Servlet API 2.1, with no replacement.
329 *
330 * <p>This method was originally defined to return an
331 * <code>Enumeration</code>
332 * of all the servlet names known to this context. In this version,
333 * this method always returns an empty <code>Enumeration</code> and
334 * remains only to preserve binary compatibility. This method will
335 * be permanently removed in a future version of the Java Servlet API.
336 *
337 */
338
339 public Enumeration getServletNames();
340
341 /**
342 *
343 * Writes the specified message to a servlet log file, usually
344 * an event log. The name and type of the servlet log file is
345 * specific to the servlet container.
346 *
347 *
348 * @param msg a <code>String</code> specifying the
349 * message to be written to the log file
350 *
351 */
352
353 public void log(String msg);
354
355 /**
356 * @deprecated As of Java Servlet API 2.1, use
357 * {@link #log(String message, Throwable throwable)}
358 * instead.
359 *
360 * <p>This method was originally defined to write an
361 * exception's stack trace and an explanatory error message
362 * to the servlet log file.
363 *
364 */
365
366 public void log(Exception exception, String msg);
367
368 /**
369 * Writes an explanatory message and a stack trace
370 * for a given <code>Throwable</code> exception
371 * to the servlet log file. The name and type of the servlet log
372 * file is specific to the servlet container, usually an event log.
373 *
374 *
375 * @param message a <code>String</code> that
376 * describes the error or exception
377 *
378 * @param throwable the <code>Throwable</code> error
379 * or exception
380 *
381 */
382
383 public void log(String message, Throwable throwable);
384
385 /**
386 * Returns a <code>String</code> containing the real path
387 * for a given virtual path. For example, the path "/index.html"
388 * returns the absolute file path on the server's filesystem would be
389 * served by a request for "http://host/contextPath/index.html",
390 * where contextPath is the context path of this ServletContext..
391 *
392 * <p>The real path returned will be in a form
393 * appropriate to the computer and operating system on
394 * which the servlet container is running, including the
395 * proper path separators. This method returns <code>null</code>
396 * if the servlet container cannot translate the virtual path
397 * to a real path for any reason (such as when the content is
398 * being made available from a <code>.war</code> archive).
399 *
400 *
401 * @param path a <code>String</code> specifying a virtual path
402 *
403 *
404 * @return a <code>String</code> specifying the real path,
405 * or null if the translation cannot be performed
406 *
407 *
408 */
409
410 public String getRealPath(String path);
411
412 /**
413 * Returns the name and version of the servlet container on which
414 * the servlet is running.
415 *
416 * <p>The form of the returned string is
417 * <i>servername</i>/<i>versionnumber</i>.
418 * For example, the JavaServer Web Development Kit may return the string
419 * <code>JavaServer Web Dev Kit/1.0</code>.
420 *
421 * <p>The servlet container may return other optional information
422 * after the primary string in parentheses, for example,
423 * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
424 *
425 *
426 * @return a <code>String</code> containing at least the
427 * servlet container name and version number
428 *
429 */
430
431 public String getServerInfo();
432
433 /**
434 * Returns a <code>String</code> containing the value of the named
435 * context-wide initialization parameter, or <code>null</code> if the
436 * parameter does not exist.
437 *
438 * <p>This method can make available configuration information useful
439 * to an entire "web application". For example, it can provide a
440 * webmaster's email address or the name of a system that holds
441 * critical data.
442 *
443 * @param name a <code>String</code> containing the name of the
444 * parameter whose value is requested
445 *
446 * @return a <code>String</code> containing at least the
447 * servlet container name and version number
448 *
449 * @see ServletConfig#getInitParameter
450 */
451
452 public String getInitParameter(String name);
453
454 /**
455 * Returns the names of the context's initialization parameters as an
456 * <code>Enumeration</code> of <code>String</code> objects, or an
457 * empty <code>Enumeration</code> if the context has no initialization
458 * parameters.
459 *
460 * @return an <code>Enumeration</code> of <code>String</code>
461 * objects containing the names of the context's
462 * initialization parameters
463 *
464 * @see ServletConfig#getInitParameter
465 */
466
467 public Enumeration getInitParameterNames();
468
469 /**
470 * Returns the servlet container attribute with the given name,
471 * or <code>null</code> if there is no attribute by that name.
472 * An attribute allows a servlet container to give the
473 * servlet additional information not
474 * already provided by this interface. See your
475 * server documentation for information about its attributes.
476 * A list of supported attributes can be retrieved using
477 * <code>getAttributeNames</code>.
478 *
479 * <p>The attribute is returned as a <code>java.lang.Object</code>
480 * or some subclass.
481 * Attribute names should follow the same convention as package
482 * names. The Java Servlet API specification reserves names
483 * matching <code>java.*</code>, <code>javax.*</code>,
484 * and <code>sun.*</code>.
485 *
486 *
487 * @param name a <code>String</code> specifying the name
488 * of the attribute
489 *
490 * @return an <code>Object</code> containing the value
491 * of the attribute, or <code>null</code>
492 * if no attribute exists matching the given
493 * name
494 *
495 * @see ServletContext#getAttributeNames
496 *
497 */
498
499 public Object getAttribute(String name);
500
501 /**
502 * Returns an <code>Enumeration</code> containing the
503 * attribute names available
504 * within this servlet context. Use the
505 * {@link #getAttribute} method with an attribute name
506 * to get the value of an attribute.
507 *
508 * @return an <code>Enumeration</code> of attribute
509 * names
510 *
511 * @see #getAttribute
512 *
513 */
514
515 public Enumeration getAttributeNames();
516
517 /**
518 *
519 * Binds an object to a given attribute name in this servlet context. If
520 * the name specified is already used for an attribute, this
521 * method will replace the attribute with the new to the new attribute.
522 * <p>If listeners are configured on the <code>ServletContext</code> the
523 * container notifies them accordingly.
524 * <p>
525 * If a null value is passed, the effect is the same as calling
526 * <code>removeAttribute()</code>.
527 *
528 * <p>Attribute names should follow the same convention as package
529 * names. The Java Servlet API specification reserves names
530 * matching <code>java.*</code>, <code>javax.*</code>, and
531 * <code>sun.*</code>.
532 *
533 *
534 * @param name a <code>String</code> specifying the name
535 * of the attribute
536 *
537 * @param object an <code>Object</code> representing the
538 * attribute to be bound
539 *
540 *
541 *
542 */
543
544 public void setAttribute(String name, Object object);
545
546 /**
547 * Removes the attribute with the given name from
548 * the servlet context. After removal, subsequent calls to
549 * {@link #getAttribute} to retrieve the attribute's value
550 * will return <code>null</code>.
551
552 * <p>If listeners are configured on the <code>ServletContext</code> the
553 * container notifies them accordingly.
554
555 *
556 *
557 * @param name a <code>String</code> specifying the name
558 * of the attribute to be removed
559 *
560 */
561
562 public void removeAttribute(String name);
563
564 /**
565 * Returns the name of this web application corresponding to this ServletContext as specified in the deployment
566 * descriptor for this web application by the display-name element.
567 *
568 *
569 * @return The name of the web application or null if no name has been declared in the deployment descriptor.
570 * @since Servlet 2.3
571 */
572
573 public String getServletContextName();
574 }
|