1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. 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,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package javax.servlet;
21
22 import java.io.InputStream;
23 import java.net.MalformedURLException;
24 import java.net.URL;
25 import java.util.Enumeration;
26 import java.util.Set;
27
28
29 /**
30 *
31 * Defines a set of methods that a servlet uses to communicate with its
32 * servlet container, for example, to get the MIME type of a file, dispatch
33 * requests, or write to a log file.
34 *
35 * <p>There is one context per "web application" per Java Virtual Machine. (A
36 * "web application" is a collection of servlets and content installed under a
37 * specific subset of the server's URL namespace such as <code>/catalog</code>
38 * and possibly installed via a <code>.war</code> file.)
39 *
40 * <p>In the case of a web
41 * application marked "distributed" in its deployment descriptor, there will
42 * be one context instance for each virtual machine. In this situation, the
43 * context cannot be used as a location to share global information (because
44 * the information won't be truly global). Use an external resource like
45 * a database instead.
46 *
47 * <p>The <code>ServletContext</code> object is contained within
48 * the {@link ServletConfig} object, which the Web server provides the
49 * servlet when the servlet is initialized.
50 *
51 * @author Various
52 * @version $Version$
53 *
54 * @see Servlet#getServletConfig
55 * @see ServletConfig#getServletContext
56 *
57 */
58
59 public interface ServletContext {
60
61
62 /**
63 * Returns a <code>ServletContext</code> object that
64 * corresponds to a specified URL on the server.
65 *
66 * <p>This method allows servlets to gain
67 * access to the context for various parts of the server, and as
68 * needed obtain {@link RequestDispatcher} objects from the context.
69 * The given path must be begin with "/", is interpreted relative
70 * to the server's document root and is matched against the context roots of
71 * other web applications hosted on this container.
72 *
73 * <p>In a security conscious environment, the servlet container may
74 * return <code>null</code> for a given URL.
75 *
76 * @param uripath a <code>String</code> specifying the context path of
77 * another web application in the container.
78 * @return the <code>ServletContext</code> object that
79 * corresponds to the named URL, or null if either
80 none exists or the container wishes to restrict
81 * this access.
82 *
83 * @see RequestDispatcher
84 *
85 */
86
87 public ServletContext getContext(String uripath);
88
89
90 public String getContextPath();
91
92
93 /**
94 * Returns the major version of the Java Servlet API that this
95 * servlet container supports. All implementations that comply
96 * with Version 2.4 must have this method
97 * return the integer 2.
98 *
99 * @return 2
100 *
101 */
102
103 public int getMajorVersion();
104
105
106
107 /**
108 * Returns the minor version of the Servlet API that this
109 * servlet container supports. All implementations that comply
110 * with Version 2.4 must have this method
111 * return the integer 4.
112 *
113 * @return 4
114 *
115 */
116
117 public int getMinorVersion();
118
119
120
121 /**
122 * Returns the MIME type of the specified file, or <code>null</code> if
123 * the MIME type is not known. The MIME type is determined
124 * by the configuration of the servlet container, and may be specified
125 * in a web application deployment descriptor. Common MIME
126 * types are <code>"text/html"</code> and <code>"image/gif"</code>.
127 *
128 *
129 * @param file a <code>String</code> specifying the name
130 * of a file
131 *
132 * @return a <code>String</code> specifying the file's MIME type
133 *
134 */
135
136 public String getMimeType(String file);
137
138 /**
139 * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path
140 * matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all
141 * relative to the root of the web application and have a leading '/'. For example, for a web application
142 * containing<br><br>
143
144 * /welcome.html<br>
145 * /catalog/index.html<br>
146 * /catalog/products.html<br>
147 * /catalog/offers/books.html<br>
148 * /catalog/offers/music.html<br>
149 * /customer/login.jsp<br>
150 * /WEB-INF/web.xml<br>
151 * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br>
152 *
153 * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br>
154 * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br>
155
156
157
158 *@param path the partial path used to match the resources,
159 * which must start with a /
160 *@return a Set containing the directory listing, or null if there are no resources in the web application whose path
161 * begins with the supplied path.
162
163 * @since Servlet 2.3
164 */
165
166 public Set getResourcePaths(String path);
167
168
169
170 /**
171 * Returns a URL to the resource that is mapped to a specified
172 * path. The path must begin with a "/" and is interpreted
173 * as relative to the current context root.
174 *
175 * <p>This method allows the servlet container to make a resource
176 * available to servlets from any source. Resources
177 * can be located on a local or remote
178 * file system, in a database, or in a <code>.war</code> file.
179 *
180 * <p>The servlet container must implement the URL handlers
181 * and <code>URLConnection</code> objects that are necessary
182 * to access the resource.
183 *
184 * <p>This method returns <code>null</code>
185 * if no resource is mapped to the pathname.
186 *
187 * <p>Some containers may allow writing to the URL returned by
188 * this method using the methods of the URL class.
189 *
190 * <p>The resource content is returned directly, so be aware that
191 * requesting a <code>.jsp</code> page returns the JSP source code.
192 * Use a <code>RequestDispatcher</code> instead to include results of
193 * an execution.
194 *
195 * <p>This method has a different purpose than
196 * <code>java.lang.Class.getResource</code>,
197 * which looks up resources based on a class loader. This
198 * method does not use class loaders.
199 *
200 * @param path a <code>String</code> specifying
201 * the path to the resource
202 *
203 * @return the resource located at the named path,
204 * or <code>null</code> if there is no resource
205 * at that path
206 *
207 * @exception MalformedURLException if the pathname is not given in
208 * the correct form
209 *
210 */
211
212 public URL getResource(String path) throws MalformedURLException;
213
214
215
216 /**
217 * Returns the resource located at the named path as
218 * an <code>InputStream</code> object.
219 *
220 * <p>The data in the <code>InputStream</code> can be
221 * of any type or length. The path must be specified according
222 * to the rules given in <code>getResource</code>.
223 * This method returns <code>null</code> if no resource exists at
224 * the specified path.
225 *
226 * <p>Meta-information such as content length and content type
227 * that is available via <code>getResource</code>
228 * method is lost when using this method.
229 *
230 * <p>The servlet container must implement the URL handlers
231 * and <code>URLConnection</code> objects necessary to access
232 * the resource.
233 *
234 * <p>This method is different from
235 * <code>java.lang.Class.getResourceAsStream</code>,
236 * which uses a class loader. This method allows servlet containers
237 * to make a resource available
238 * to a servlet from any location, without using a class loader.
239 *
240 *
241 * @param path a <code>String</code> specifying the path
242 * to the resource
243 *
244 * @return the <code>InputStream</code> returned to the
245 * servlet, or <code>null</code> if no resource
246 * exists at the specified path
247 *
248 *
249 */
250
251 public InputStream getResourceAsStream(String path);
252
253
254
255
256 /**
257 *
258 * Returns a {@link RequestDispatcher} object that acts
259 * as a wrapper for the resource located at the given path.
260 * A <code>RequestDispatcher</code> object can be used to forward
261 * a request to the resource or to include the resource in a response.
262 * The resource can be dynamic or static.
263 *
264 * <p>The pathname must begin with a "/" and is interpreted as relative
265 * to the current context root. Use <code>getContext</code> to obtain
266 * a <code>RequestDispatcher</code> for resources in foreign contexts.
267 * This method returns <code>null</code> if the <code>ServletContext</code>
268 * cannot return a <code>RequestDispatcher</code>.
269 *
270 * @param path a <code>String</code> specifying the pathname
271 * to the resource
272 *
273 * @return a <code>RequestDispatcher</code> object
274 * that acts as a wrapper for the resource
275 * at the specified path, or <code>null</code> if
276 * the <code>ServletContext</code> cannot return
277 * a <code>RequestDispatcher</code>
278 *
279 * @see RequestDispatcher
280 * @see ServletContext#getContext
281 *
282 */
283
284 public RequestDispatcher getRequestDispatcher(String path);
285
286
287
288 /**
289 * Returns a {@link RequestDispatcher} object that acts
290 * as a wrapper for the named servlet.
291 *
292 * <p>Servlets (and JSP pages also) may be given names via server
293 * administration or via a web application deployment descriptor.
294 * A servlet instance can determine its name using
295 * {@link ServletConfig#getServletName}.
296 *
297 * <p>This method returns <code>null</code> if the
298 * <code>ServletContext</code>
299 * cannot return a <code>RequestDispatcher</code> for any reason.
300 *
301 * @param name a <code>String</code> specifying the name
302 * of a servlet to wrap
303 *
304 * @return a <code>RequestDispatcher</code> object
305 * that acts as a wrapper for the named servlet,
306 * or <code>null</code> if the <code>ServletContext</code>
307 * cannot return a <code>RequestDispatcher</code>
308 *
309 * @see RequestDispatcher
310 * @see ServletContext#getContext
311 * @see ServletConfig#getServletName
312 *
313 */
314
315 public RequestDispatcher getNamedDispatcher(String name);
316
317
318
319
320 /**
321 *
322 * @deprecated As of Java Servlet API 2.1, with no direct replacement.
323 *
324 * <p>This method was originally defined to retrieve a servlet
325 * from a <code>ServletContext</code>. In this version, this method
326 * always returns <code>null</code> and remains only to preserve
327 * binary compatibility. This method will be permanently removed
328 * in a future version of the Java Servlet API.
329 *
330 * <p>In lieu of this method, servlets can share information using the
331 * <code>ServletContext</code> class and can perform shared business logic
332 * by invoking methods on common non-servlet classes.
333 *
334 */
335
336 public Servlet getServlet(String name) throws ServletException;
337
338
339
340
341
342
343 /**
344 *
345 * @deprecated As of Java Servlet API 2.0, with no replacement.
346 *
347 * <p>This method was originally defined to return an <code>Enumeration</code>
348 * of all the servlets known to this servlet context. In this
349 * version, this method always returns an empty enumeration and
350 * remains only to preserve binary compatibility. This method
351 * will be permanently removed in a future version of the Java
352 * Servlet API.
353 *
354 */
355
356 public Enumeration getServlets();
357
358
359
360
361
362
363 /**
364 * @deprecated As of Java Servlet API 2.1, with no replacement.
365 *
366 * <p>This method was originally defined to return an
367 * <code>Enumeration</code>
368 * of all the servlet names known to this context. In this version,
369 * this method always returns an empty <code>Enumeration</code> and
370 * remains only to preserve binary compatibility. This method will
371 * be permanently removed in a future version of the Java Servlet API.
372 *
373 */
374
375 public Enumeration getServletNames();
376
377
378
379
380
381 /**
382 *
383 * Writes the specified message to a servlet log file, usually
384 * an event log. The name and type of the servlet log file is
385 * specific to the servlet container.
386 *
387 *
388 * @param msg a <code>String</code> specifying the
389 * message to be written to the log file
390 *
391 */
392
393 public void log(String msg);
394
395
396
397
398
399 /**
400 * @deprecated As of Java Servlet API 2.1, use
401 * {@link #log(String message, Throwable throwable)}
402 * instead.
403 *
404 * <p>This method was originally defined to write an
405 * exception's stack trace and an explanatory error message
406 * to the servlet log file.
407 *
408 */
409
410 public void log(Exception exception, String msg);
411
412
413
414
415
416 /**
417 * Writes an explanatory message and a stack trace
418 * for a given <code>Throwable</code> exception
419 * to the servlet log file. The name and type of the servlet log
420 * file is specific to the servlet container, usually an event log.
421 *
422 *
423 * @param message a <code>String</code> that
424 * describes the error or exception
425 *
426 * @param throwable the <code>Throwable</code> error
427 * or exception
428 *
429 */
430
431 public void log(String message, Throwable throwable);
432
433
434
435
436
437 /**
438 * Returns a <code>String</code> containing the real path
439 * for a given virtual path. For example, the path "/index.html"
440 * returns the absolute file path on the server's filesystem would be
441 * served by a request for "http://host/contextPath/index.html",
442 * where contextPath is the context path of this ServletContext..
443 *
444 * <p>The real path returned will be in a form
445 * appropriate to the computer and operating system on
446 * which the servlet container is running, including the
447 * proper path separators. This method returns <code>null</code>
448 * if the servlet container cannot translate the virtual path
449 * to a real path for any reason (such as when the content is
450 * being made available from a <code>.war</code> archive).
451 *
452 *
453 * @param path a <code>String</code> specifying a virtual path
454 *
455 *
456 * @return a <code>String</code> specifying the real path,
457 * or null if the translation cannot be performed
458 *
459 *
460 */
461
462 public String getRealPath(String path);
463
464
465
466
467 /**
468 * Returns the name and version of the servlet container on which
469 * the servlet is running.
470 *
471 * <p>The form of the returned string is
472 * <i>servername</i>/<i>versionnumber</i>.
473 * For example, the JavaServer Web Development Kit may return the string
474 * <code>JavaServer Web Dev Kit/1.0</code>.
475 *
476 * <p>The servlet container may return other optional information
477 * after the primary string in parentheses, for example,
478 * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
479 *
480 *
481 * @return a <code>String</code> containing at least the
482 * servlet container name and version number
483 *
484 */
485
486 public String getServerInfo();
487
488
489
490
491 /**
492 * Returns a <code>String</code> containing the value of the named
493 * context-wide initialization parameter, or <code>null</code> if the
494 * parameter does not exist.
495 *
496 * <p>This method can make available configuration information useful
497 * to an entire "web application". For example, it can provide a
498 * webmaster's email address or the name of a system that holds
499 * critical data.
500 *
501 * @param name a <code>String</code> containing the name of the
502 * parameter whose value is requested
503 *
504 * @return a <code>String</code> containing at least the
505 * servlet container name and version number
506 *
507 * @see ServletConfig#getInitParameter
508 */
509
510 public String getInitParameter(String name);
511
512
513
514
515 /**
516 * Returns the names of the context's initialization parameters as an
517 * <code>Enumeration</code> of <code>String</code> objects, or an
518 * empty <code>Enumeration</code> if the context has no initialization
519 * parameters.
520 *
521 * @return an <code>Enumeration</code> of <code>String</code>
522 * objects containing the names of the context's
523 * initialization parameters
524 *
525 * @see ServletConfig#getInitParameter
526 */
527
528 public Enumeration getInitParameterNames();
529
530
531
532 /**
533 * Returns the servlet container attribute with the given name,
534 * or <code>null</code> if there is no attribute by that name.
535 * An attribute allows a servlet container to give the
536 * servlet additional information not
537 * already provided by this interface. See your
538 * server documentation for information about its attributes.
539 * A list of supported attributes can be retrieved using
540 * <code>getAttributeNames</code>.
541 *
542 * <p>The attribute is returned as a <code>java.lang.Object</code>
543 * or some subclass.
544 * Attribute names should follow the same convention as package
545 * names. The Java Servlet API specification reserves names
546 * matching <code>java.*</code>, <code>javax.*</code>,
547 * and <code>sun.*</code>.
548 *
549 *
550 * @param name a <code>String</code> specifying the name
551 * of the attribute
552 *
553 * @return an <code>Object</code> containing the value
554 * of the attribute, or <code>null</code>
555 * if no attribute exists matching the given
556 * name
557 *
558 * @see ServletContext#getAttributeNames
559 *
560 */
561
562 public Object getAttribute(String name);
563
564
565
566
567 /**
568 * Returns an <code>Enumeration</code> containing the
569 * attribute names available
570 * within this servlet context. Use the
571 * {@link #getAttribute} method with an attribute name
572 * to get the value of an attribute.
573 *
574 * @return an <code>Enumeration</code> of attribute
575 * names
576 *
577 * @see #getAttribute
578 *
579 */
580
581 public Enumeration getAttributeNames();
582
583
584
585
586 /**
587 *
588 * Binds an object to a given attribute name in this servlet context. If
589 * the name specified is already used for an attribute, this
590 * method will replace the attribute with the new to the new attribute.
591 * <p>If listeners are configured on the <code>ServletContext</code> the
592 * container notifies them accordingly.
593 * <p>
594 * If a null value is passed, the effect is the same as calling
595 * <code>removeAttribute()</code>.
596 *
597 * <p>Attribute names should follow the same convention as package
598 * names. The Java Servlet API specification reserves names
599 * matching <code>java.*</code>, <code>javax.*</code>, and
600 * <code>sun.*</code>.
601 *
602 *
603 * @param name a <code>String</code> specifying the name
604 * of the attribute
605 *
606 * @param object an <code>Object</code> representing the
607 * attribute to be bound
608 *
609 *
610 *
611 */
612
613 public void setAttribute(String name, Object object);
614
615
616
617
618
619 /**
620 * Removes the attribute with the given name from
621 * the servlet context. After removal, subsequent calls to
622 * {@link #getAttribute} to retrieve the attribute's value
623 * will return <code>null</code>.
624
625 * <p>If listeners are configured on the <code>ServletContext</code> the
626 * container notifies them accordingly.
627
628 *
629 *
630 * @param name a <code>String</code> specifying the name
631 * of the attribute to be removed
632 *
633 */
634
635 public void removeAttribute(String name);
636
637 /**
638 * Returns the name of this web application corresponding to this ServletContext as specified in the deployment
639 * descriptor for this web application by the display-name element.
640 *
641 *
642 * @return The name of the web application or null if no name has been declared in the deployment descriptor.
643 * @since Servlet 2.3
644 */
645
646 public String getServletContextName();
647 }
648
649