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