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