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 */ getContextPath()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 getContext(String uripath)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 getMajorVersion()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 getMinorVersion()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 getMimeType(String file)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 getResourcePaths(String path)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 getResource(String path)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 getResourceAsStream(String path)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 getRequestDispatcher(String path)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 getNamedDispatcher(String name)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 getServlet(String name)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 getServlets()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 getServletNames()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 log(String msg)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 log(Exception exception, String msg)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 log(String message, Throwable throwable)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 getRealPath(String path)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 getServerInfo()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 getInitParameter(String name)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 getInitParameterNames()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 getAttribute(String name)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 getAttributeNames()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 setAttribute(String name, Object object)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 removeAttribute(String name)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 getServletContextName()677 public String getServletContextName(); 678 } 679 680 681