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