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