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