lib/servlet-api/javax/servlet/ServletContext.java

   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.EventListener;
  24 import java.util.Map;
  25 import java.util.Set;
  26
  27 import javax.servlet.descriptor.JspConfigDescriptor;
  28
  29 /**
  30  * Defines a set of methods that a servlet uses to communicate with its servlet
  31  * container, for example, to get the MIME type of a file, dispatch requests, or
  32  * write to a log file.
  33  * <p>
  34  * There is one context per "web application" per Java Virtual Machine. (A
  35  * "web application" is a collection of servlets and content installed under a
  36  * specific subset of the server's URL namespace such as <code>/catalog</code>
  37  * and possibly installed via a <code>.war</code> file.)
  38  * <p>
  39  * In the case of a web application marked "distributed" in its deployment
  40  * descriptor, there will be one context instance for each virtual machine. In
  41  * this situation, the context cannot be used as a location to share global
  42  * information (because the information won't be truly global). Use an external
  43  * resource like a database instead.
  44  * <p>
  45  * The <code>ServletContext</code> object is contained within the
  46  * {@link ServletConfig} object, which the Web server provides the servlet when
  47  * the servlet is initialized.
  48  *
  49  * @see Servlet#getServletConfig
  50  * @see ServletConfig#getServletContext
  51  */
  52 public interface ServletContext {
  53
  54     public static final String TEMPDIR = "javax.servlet.context.tempdir";
  55
  56     /**
  57      * @since Servlet 3.0
  58      */
  59     public static final String ORDERED_LIBS = "javax.servlet.context.orderedLibs";
  60
  61     public String getContextPath();
  62
  63     /**
  64      * Returns a <code>ServletContext</code> object that corresponds to a
  65      * specified URL on the server.
  66      * <p>
  67      * This method allows servlets to gain access to the context for various
  68      * parts of the server, and as needed obtain {@link RequestDispatcher}
  69      * objects from the context. The given path must be begin with "/", is
  70      * interpreted relative to the server's document root and is matched against
  71      * the context roots of other web applications hosted on this container.
  72      * <p>
  73      * In a security conscious environment, the servlet container may return
  74      * <code>null</code> for a given URL.
  75      *
  76      * @param uripath
  77      *            a <code>String</code> specifying the context path of another
  78      *            web application in the container.
  79      * @return the <code>ServletContext</code> object that corresponds to the
  80      *         named URL, or null if either none exists or the container wishes
  81      *         to restrict this access.
  82      * @see RequestDispatcher
  83      */
  84     public ServletContext getContext(String uripath);
  85
  86     /**
  87      * Returns the major version of the Java Servlet API that this servlet
  88      * container supports. All implementations that comply with Version 3.1 must
  89      * have this method return the integer 3.
  90      *
  91      * @return 3
  92      */
  93     public int getMajorVersion();
  94
  95     /**
  96      * Returns the minor version of the Servlet API that this servlet container
  97      * supports. All implementations that comply with Version 3.1 must have this
  98      * method return the integer 1.
  99      *
 100      * @return 1
 101      */
 102     public int getMinorVersion();
 103
 104     /**
 105      * @return TODO
 106      * @throws UnsupportedOperationException    If called from a
 107      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 108      *    method of a {@link ServletContextListener} that was not defined in a
 109      *    web.xml file, a web-fragment.xml file nor annotated with
 110      *    {@link javax.servlet.annotation.WebListener}. For example, a
 111      *    {@link ServletContextListener} defined in a TLD would not be able to
 112      *    use this method.
 113      *
 114      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 115      */
 116     public int getEffectiveMajorVersion();
 117
 118     /**
 119      * @return TODO
 120      * @throws UnsupportedOperationException    If called from a
 121      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 122      *    method of a {@link ServletContextListener} that was not defined in a
 123      *    web.xml file, a web-fragment.xml file nor annotated with
 124      *    {@link javax.servlet.annotation.WebListener}. For example, a
 125      *    {@link ServletContextListener} defined in a TLD would not be able to
 126      *    use this method.
 127      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 128      */
 129     public int getEffectiveMinorVersion();
 130
 131     /**
 132      * Returns the MIME type of the specified file, or <code>null</code> if the
 133      * MIME type is not known. The MIME type is determined by the configuration
 134      * of the servlet container, and may be specified in a web application
 135      * deployment descriptor. Common MIME types are <code>"text/html"</code> and
 136      * <code>"image/gif"</code>.
 137      *
 138      * @param file
 139      *            a <code>String</code> specifying the name of a file
 140      * @return a <code>String</code> specifying the file's MIME type
 141      */
 142     public String getMimeType(String file);
 143
 144     /**
 145      * Returns a directory-like listing of all the paths to resources within the
 146      * web application whose longest sub-path matches the supplied path
 147      * argument. Paths indicating subdirectory paths end with a '/'. The
 148      * returned paths are all relative to the root of the web application and
 149      * have a leading '/'. For example, for a web application containing<br>
 150      * <br>
 151      * /welcome.html<br>
 152      * /catalog/index.html<br>
 153      * /catalog/products.html<br>
 154      * /catalog/offers/books.html<br>
 155      * /catalog/offers/music.html<br>
 156      * /customer/login.jsp<br>
 157      * /WEB-INF/web.xml<br>
 158      * /WEB-INF/classes/com.acme.OrderServlet.class,<br>
 159      * <br>
 160      * getResourcePaths("/") returns {"/welcome.html", "/catalog/",
 161      * "/customer/", "/WEB-INF/"}<br>
 162      * getResourcePaths("/catalog/") returns {"/catalog/index.html",
 163      * "/catalog/products.html", "/catalog/offers/"}.<br>
 164      *
 165      * @param path
 166      *            the partial path used to match the resources, which must start
 167      *            with a /
 168      * @return a Set containing the directory listing, or null if there are no
 169      *         resources in the web application whose path begins with the
 170      *         supplied path.
 171      * @since Servlet 2.3
 172      */
 173     public Set<String> getResourcePaths(String path);
 174
 175     /**
 176      * Returns a URL to the resource that is mapped to a specified path. The
 177      * path must begin with a "/" and is interpreted as relative to the current
 178      * context root.
 179      * <p>
 180      * This method allows the servlet container to make a resource available to
 181      * servlets from any source. Resources can be located on a local or remote
 182      * file system, in a database, or in a <code>.war</code> file.
 183      * <p>
 184      * The servlet container must implement the URL handlers and
 185      * <code>URLConnection</code> objects that are necessary to access the
 186      * resource.
 187      * <p>
 188      * This method returns <code>null</code> if no resource is mapped to the
 189      * pathname.
 190      * <p>
 191      * Some containers may allow writing to the URL returned by this method
 192      * using the methods of the URL class.
 193      * <p>
 194      * The resource content is returned directly, so be aware that requesting a
 195      * <code>.jsp</code> page returns the JSP source code. Use a
 196      * <code>RequestDispatcher</code> instead to include results of an
 197      * execution.
 198      * <p>
 199      * This method has a different purpose than
 200      * <code>java.lang.Class.getResource</code>, which looks up resources based
 201      * on a class loader. This method does not use class loaders.
 202      *
 203      * @param path
 204      *            a <code>String</code> specifying the path to the resource
 205      * @return the resource located at the named path, or <code>null</code> if
 206      *         there is no resource at that path
 207      * @exception MalformedURLException
 208      *                if the pathname is not given in the correct form
 209      */
 210     public URL getResource(String path) throws MalformedURLException;
 211
 212     /**
 213      * Returns the resource located at the named path as an
 214      * <code>InputStream</code> object.
 215      * <p>
 216      * The data in the <code>InputStream</code> can be of any type or length.
 217      * The path must be specified according to the rules given in
 218      * <code>getResource</code>. This method returns <code>null</code> if no
 219      * resource exists at the specified path.
 220      * <p>
 221      * Meta-information such as content length and content type that is
 222      * available via <code>getResource</code> method is lost when using this
 223      * method.
 224      * <p>
 225      * The servlet container must implement the URL handlers and
 226      * <code>URLConnection</code> objects necessary to access the resource.
 227      * <p>
 228      * This method is different from
 229      * <code>java.lang.Class.getResourceAsStream</code>, which uses a class
 230      * loader. This method allows servlet containers to make a resource
 231      * available to a servlet from any location, without using a class loader.
 232      *
 233      * @param path
 234      *            a <code>String</code> specifying the path to the resource
 235      * @return the <code>InputStream</code> returned to the servlet, or
 236      *         <code>null</code> if no resource exists at the specified path
 237      */
 238     public InputStream getResourceAsStream(String path);
 239
 240     /**
 241      * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
 242      * resource located at the given path. A <code>RequestDispatcher</code>
 243      * object can be used to forward a request to the resource or to include the
 244      * resource in a response. The resource can be dynamic or static.
 245      * <p>
 246      * The pathname must begin with a "/" and is interpreted as relative to the
 247      * current context root. Use <code>getContext</code> to obtain a
 248      * <code>RequestDispatcher</code> for resources in foreign contexts. This
 249      * method returns <code>null</code> if the <code>ServletContext</code>
 250      * cannot return a <code>RequestDispatcher</code>.
 251      *
 252      * @param path
 253      *            a <code>String</code> specifying the pathname to the resource
 254      * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
 255      *         the resource at the specified path, or <code>null</code> if the
 256      *         <code>ServletContext</code> cannot return a
 257      *         <code>RequestDispatcher</code>
 258      * @see RequestDispatcher
 259      * @see ServletContext#getContext
 260      */
 261     public RequestDispatcher getRequestDispatcher(String path);
 262
 263     /**
 264      * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
 265      * named servlet.
 266      * <p>
 267      * Servlets (and JSP pages also) may be given names via server
 268      * administration or via a web application deployment descriptor. A servlet
 269      * instance can determine its name using
 270      * {@link ServletConfig#getServletName}.
 271      * <p>
 272      * This method returns <code>null</code> if the <code>ServletContext</code>
 273      * cannot return a <code>RequestDispatcher</code> for any reason.
 274      *
 275      * @param name
 276      *            a <code>String</code> specifying the name of a servlet to wrap
 277      * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
 278      *         the named servlet, or <code>null</code> if the
 279      *         <code>ServletContext</code> cannot return a
 280      *         <code>RequestDispatcher</code>
 281      * @see RequestDispatcher
 282      * @see ServletContext#getContext
 283      * @see ServletConfig#getServletName
 284      */
 285     public RequestDispatcher getNamedDispatcher(String name);
 286
 287     /**
 288      * @deprecated As of Java Servlet API 2.1, with no direct replacement.
 289      *             <p>
 290      *             This method was originally defined to retrieve a servlet from
 291      *             a <code>ServletContext</code>. In this version, this method
 292      *             always returns <code>null</code> and remains only to preserve
 293      *             binary compatibility. This method will be permanently removed
 294      *             in a future version of the Java Servlet API.
 295      *             <p>
 296      *             In lieu of this method, servlets can share information using
 297      *             the <code>ServletContext</code> class and can perform shared
 298      *             business logic by invoking methods on common non-servlet
 299      *             classes.
 300      */
 301     @SuppressWarnings("dep-ann")
 302     // Spec API does not use @Deprecated
 303     public Servlet getServlet(String name) throws ServletException;
 304
 305     /**
 306      * @deprecated As of Java Servlet API 2.0, with no replacement.
 307      *             <p>
 308      *             This method was originally defined to return an
 309      *             <code>Enumeration</code> of all the servlets known to this
 310      *             servlet context. In this version, this method always returns
 311      *             an empty enumeration and remains only to preserve binary
 312      *             compatibility. This method will be permanently removed in a
 313      *             future version of the Java Servlet API.
 314      */
 315     @SuppressWarnings("dep-ann")
 316     // Spec API does not use @Deprecated
 317     public Enumeration<Servlet> getServlets();
 318
 319     /**
 320      * @deprecated As of Java Servlet API 2.1, with no replacement.
 321      *             <p>
 322      *             This method was originally defined to return an
 323      *             <code>Enumeration</code> of all the servlet names known to
 324      *             this context. In this version, this method always returns an
 325      *             empty <code>Enumeration</code> and remains only to preserve
 326      *             binary compatibility. This method will be permanently removed
 327      *             in a future version of the Java Servlet API.
 328      */
 329     @SuppressWarnings("dep-ann")
 330     // Spec API does not use @Deprecated
 331     public Enumeration<String> getServletNames();
 332
 333     /**
 334      * Writes the specified message to a servlet log file, usually an event log.
 335      * The name and type of the servlet log file is specific to the servlet
 336      * container.
 337      *
 338      * @param msg
 339      *            a <code>String</code> specifying the message to be written to
 340      *            the log file
 341      */
 342     public void log(String msg);
 343
 344     /**
 345      * @deprecated As of Java Servlet API 2.1, use
 346      *             {@link #log(String message, Throwable throwable)} instead.
 347      *             <p>
 348      *             This method was originally defined to write an exception's
 349      *             stack trace and an explanatory error message to the servlet
 350      *             log file.
 351      */
 352     @SuppressWarnings("dep-ann")
 353     // Spec API does not use @Deprecated
 354     public void log(Exception exception, String msg);
 355
 356     /**
 357      * Writes an explanatory message and a stack trace for a given
 358      * <code>Throwable</code> exception to the servlet log file. The name and
 359      * type of the servlet log file is specific to the servlet container,
 360      * usually an event log.
 361      *
 362      * @param message
 363      *            a <code>String</code> that describes the error or exception
 364      * @param throwable
 365      *            the <code>Throwable</code> error or exception
 366      */
 367     public void log(String message, Throwable throwable);
 368
 369     /**
 370      * Returns a <code>String</code> containing the real path for a given
 371      * virtual path. For example, the path "/index.html" returns the absolute
 372      * file path on the server's filesystem would be served by a request for
 373      * "http://host/contextPath/index.html", where contextPath is the context
 374      * path of this ServletContext..
 375      * <p>
 376      * The real path returned will be in a form appropriate to the computer and
 377      * operating system on which the servlet container is running, including the
 378      * proper path separators. This method returns <code>null</code> if the
 379      * servlet container cannot translate the virtual path to a real path for
 380      * any reason (such as when the content is being made available from a
 381      * <code>.war</code> archive).
 382      *
 383      * @param path
 384      *            a <code>String</code> specifying a virtual path
 385      * @return a <code>String</code> specifying the real path, or null if the
 386      *         translation cannot be performed
 387      */
 388     public String getRealPath(String path);
 389
 390     /**
 391      * Returns the name and version of the servlet container on which the
 392      * servlet is running.
 393      * <p>
 394      * The form of the returned string is
 395      * <i>servername</i>/<i>versionnumber</i>. For example, the JavaServer Web
 396      * Development Kit may return the string
 397      * <code>JavaServer Web Dev Kit/1.0</code>.
 398      * <p>
 399      * The servlet container may return other optional information after the
 400      * primary string in parentheses, for example,
 401      * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
 402      *
 403      * @return a <code>String</code> containing at least the servlet container
 404      *         name and version number
 405      */
 406     public String getServerInfo();
 407
 408     /**
 409      * Returns a <code>String</code> containing the value of the named
 410      * context-wide initialization parameter, or <code>null</code> if the
 411      * parameter does not exist.
 412      * <p>
 413      * This method can make available configuration information useful to an
 414      * entire "web application". For example, it can provide a webmaster's email
 415      * address or the name of a system that holds critical data.
 416      *
 417      * @param name
 418      *            a <code>String</code> containing the name of the parameter
 419      *            whose value is requested
 420      * @return a <code>String</code> containing the value of the initialization
 421      *         parameter
 422      * @see ServletConfig#getInitParameter
 423      */
 424     public String getInitParameter(String name);
 425
 426     /**
 427      * Returns the names of the context's initialization parameters as an
 428      * <code>Enumeration</code> of <code>String</code> objects, or an empty
 429      * <code>Enumeration</code> if the context has no initialization parameters.
 430      *
 431      * @return an <code>Enumeration</code> of <code>String</code> objects
 432      *         containing the names of the context's initialization parameters
 433      * @see ServletConfig#getInitParameter
 434      */
 435
 436     public Enumeration<String> getInitParameterNames();
 437
 438     /**
 439      * @param name
 440      * @param value
 441      * @return TODO
 442      * @throws IllegalStateException
 443      * @throws UnsupportedOperationException    If called from a
 444      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 445      *    method of a {@link ServletContextListener} that was not defined in a
 446      *    web.xml file, a web-fragment.xml file nor annotated with
 447      *    {@link javax.servlet.annotation.WebListener}. For example, a
 448      *    {@link ServletContextListener} defined in a TLD would not be able to
 449      *    use this method.
 450      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 451      */
 452     public boolean setInitParameter(String name, String value);
 453
 454     /**
 455      * Returns the servlet container attribute with the given name, or
 456      * <code>null</code> if there is no attribute by that name. An attribute
 457      * allows a servlet container to give the servlet additional information not
 458      * already provided by this interface. See your server documentation for
 459      * information about its attributes. A list of supported attributes can be
 460      * retrieved using <code>getAttributeNames</code>.
 461      * <p>
 462      * The attribute is returned as a <code>java.lang.Object</code> or some
 463      * subclass. Attribute names should follow the same convention as package
 464      * names. The Java Servlet API specification reserves names matching
 465      * <code>java.*</code>, <code>javax.*</code>, and <code>sun.*</code>.
 466      *
 467      * @param name
 468      *            a <code>String</code> specifying the name of the attribute
 469      * @return an <code>Object</code> containing the value of the attribute, or
 470      *         <code>null</code> if no attribute exists matching the given name
 471      * @see ServletContext#getAttributeNames
 472      */
 473     public Object getAttribute(String name);
 474
 475     /**
 476      * Returns an <code>Enumeration</code> containing the attribute names
 477      * available within this servlet context. Use the {@link #getAttribute}
 478      * method with an attribute name to get the value of an attribute.
 479      *
 480      * @return an <code>Enumeration</code> of attribute names
 481      * @see #getAttribute
 482      */
 483     public Enumeration<String> getAttributeNames();
 484
 485     /**
 486      * Binds an object to a given attribute name in this servlet context. If the
 487      * name specified is already used for an attribute, this method will replace
 488      * the attribute with the new to the new attribute.
 489      * <p>
 490      * If listeners are configured on the <code>ServletContext</code> the
 491      * container notifies them accordingly.
 492      * <p>
 493      * If a null value is passed, the effect is the same as calling
 494      * <code>removeAttribute()</code>.
 495      * <p>
 496      * Attribute names should follow the same convention as package names. The
 497      * Java Servlet API specification reserves names matching
 498      * <code>java.*</code>, <code>javax.*</code>, and <code>sun.*</code>.
 499      *
 500      * @param name
 501      *            a <code>String</code> specifying the name of the attribute
 502      * @param object
 503      *            an <code>Object</code> representing the attribute to be bound
 504      */
 505     public void setAttribute(String name, Object object);
 506
 507     /**
 508      * Removes the attribute with the given name from the servlet context. After
 509      * removal, subsequent calls to {@link #getAttribute} to retrieve the
 510      * attribute's value will return <code>null</code>.
 511      * <p>
 512      * If listeners are configured on the <code>ServletContext</code> the
 513      * container notifies them accordingly.
 514      *
 515      * @param name
 516      *            a <code>String</code> specifying the name of the attribute to
 517      *            be removed
 518      */
 519     public void removeAttribute(String name);
 520
 521     /**
 522      * Returns the name of this web application corresponding to this
 523      * ServletContext as specified in the deployment descriptor for this web
 524      * application by the display-name element.
 525      *
 526      * @return The name of the web application or null if no name has been
 527      *         declared in the deployment descriptor.
 528      * @since Servlet 2.3
 529      */
 530     public String getServletContextName();
 531
 532     /**
 533      * @param servletName
 534      * @param className
 535      * @return TODO
 536      * @throws IllegalStateException
 537      *             If the context has already been initialised
 538      * @throws UnsupportedOperationException    If called from a
 539      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 540      *    method of a {@link ServletContextListener} that was not defined in a
 541      *    web.xml file, a web-fragment.xml file nor annotated with
 542      *    {@link javax.servlet.annotation.WebListener}. For example, a
 543      *    {@link ServletContextListener} defined in a TLD would not be able to
 544      *    use this method.
 545      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 546      */
 547     public ServletRegistration.Dynamic addServlet(String servletName,
 548             String className);
 549
 550     /**
 551      * @param servletName
 552      * @param servlet
 553      * @return TODO
 554      * @throws IllegalStateException
 555      *             If the context has already been initialised
 556      * @throws UnsupportedOperationException    If called from a
 557      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 558      *    method of a {@link ServletContextListener} that was not defined in a
 559      *    web.xml file, a web-fragment.xml file nor annotated with
 560      *    {@link javax.servlet.annotation.WebListener}. For example, a
 561      *    {@link ServletContextListener} defined in a TLD would not be able to
 562      *    use this method.
 563      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 564      */
 565     public ServletRegistration.Dynamic addServlet(String servletName,
 566             Servlet servlet);
 567
 568     /**
 569      * @param servletName
 570      * @param servletClass
 571      * @return TODO
 572      * @throws IllegalStateException
 573      *             If the context has already been initialised
 574      * @throws UnsupportedOperationException    If called from a
 575      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 576      *    method of a {@link ServletContextListener} that was not defined in a
 577      *    web.xml file, a web-fragment.xml file nor annotated with
 578      *    {@link javax.servlet.annotation.WebListener}. For example, a
 579      *    {@link ServletContextListener} defined in a TLD would not be able to
 580      *    use this method.
 581      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 582      */
 583     public ServletRegistration.Dynamic addServlet(String servletName,
 584             Class<? extends Servlet> servletClass);
 585
 586     /**
 587      * @param c
 588      * @return TODO
 589      * @throws ServletException
 590      * @throws UnsupportedOperationException    If called from a
 591      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 592      *    method of a {@link ServletContextListener} that was not defined in a
 593      *    web.xml file, a web-fragment.xml file nor annotated with
 594      *    {@link javax.servlet.annotation.WebListener}. For example, a
 595      *    {@link ServletContextListener} defined in a TLD would not be able to
 596      *    use this method.
 597      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 598      */
 599     public <T extends Servlet> T createServlet(Class<T> c)
 600             throws ServletException;
 601
 602     /**
 603      * Obtain the details of the named servlet.
 604      *
 605      * @param servletName   The name of the Servlet of interest
 606      *
 607      * @return  The registration details for the named Servlet or
 608      *          <code>null</code> if no Servlet has been registered with the
 609      *          given name
 610      *
 611      * @throws UnsupportedOperationException    If called from a
 612      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 613      *    method of a {@link ServletContextListener} that was not defined in a
 614      *    web.xml file, a web-fragment.xml file nor annotated with
 615      *    {@link javax.servlet.annotation.WebListener}. For example, a
 616      *    {@link ServletContextListener} defined in a TLD would not be able to
 617      *    use this method.
 618      *
 619      * @since Servlet 3.0
 620      */
 621     public ServletRegistration getServletRegistration(String servletName);
 622
 623     /**
 624      * @return TODO
 625      * @throws UnsupportedOperationException    If called from a
 626      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 627      *    method of a {@link ServletContextListener} that was not defined in a
 628      *    web.xml file, a web-fragment.xml file nor annotated with
 629      *    {@link javax.servlet.annotation.WebListener}. For example, a
 630      *    {@link ServletContextListener} defined in a TLD would not be able to
 631      *    use this method.
 632      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 633      */
 634     public Map<String, ? extends ServletRegistration> getServletRegistrations();
 635
 636     /**
 637      * @param filterName
 638      * @param className
 639      * @return TODO
 640      * @throws UnsupportedOperationException    If called from a
 641      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 642      *    method of a {@link ServletContextListener} that was not defined in a
 643      *    web.xml file, a web-fragment.xml file nor annotated with
 644      *    {@link javax.servlet.annotation.WebListener}. For example, a
 645      *    {@link ServletContextListener} defined in a TLD would not be able to
 646      *    use this method.
 647      * @throws IllegalStateException
 648      *             If the context has already been initialised
 649      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 650      */
 651     public FilterRegistration.Dynamic addFilter(String filterName,
 652             String className);
 653
 654     /**
 655      * @param filterName
 656      * @param filter
 657      * @return TODO
 658      * @throws UnsupportedOperationException    If called from a
 659      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 660      *    method of a {@link ServletContextListener} that was not defined in a
 661      *    web.xml file, a web-fragment.xml file nor annotated with
 662      *    {@link javax.servlet.annotation.WebListener}. For example, a
 663      *    {@link ServletContextListener} defined in a TLD would not be able to
 664      *    use this method.
 665      * @throws IllegalStateException
 666      *             If the context has already been initialised
 667      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 668      */
 669     public FilterRegistration.Dynamic addFilter(String filterName, Filter filter);
 670
 671     /**
 672      * @param filterName
 673      * @param filterClass
 674      * @return TODO
 675      * @throws UnsupportedOperationException    If called from a
 676      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 677      *    method of a {@link ServletContextListener} that was not defined in a
 678      *    web.xml file, a web-fragment.xml file nor annotated with
 679      *    {@link javax.servlet.annotation.WebListener}. For example, a
 680      *    {@link ServletContextListener} defined in a TLD would not be able to
 681      *    use this method.
 682      * @throws IllegalStateException
 683      *             If the context has already been initialised
 684      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 685      */
 686     public FilterRegistration.Dynamic addFilter(String filterName,
 687             Class<? extends Filter> filterClass);
 688
 689     /**
 690      * @param c
 691      * @return TODO
 692      * @throws UnsupportedOperationException    If called from a
 693      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 694      *    method of a {@link ServletContextListener} that was not defined in a
 695      *    web.xml file, a web-fragment.xml file nor annotated with
 696      *    {@link javax.servlet.annotation.WebListener}. For example, a
 697      *    {@link ServletContextListener} defined in a TLD would not be able to
 698      *    use this method.
 699      * @throws ServletException
 700      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 701      */
 702     public <T extends Filter> T createFilter(Class<T> c)
 703             throws ServletException;
 704
 705     /**
 706      * @param filterName
 707      * @return TODO
 708      * @throws UnsupportedOperationException    If called from a
 709      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 710      *    method of a {@link ServletContextListener} that was not defined in a
 711      *    web.xml file, a web-fragment.xml file nor annotated with
 712      *    {@link javax.servlet.annotation.WebListener}. For example, a
 713      *    {@link ServletContextListener} defined in a TLD would not be able to
 714      *    use this method.
 715      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 716      */
 717     public FilterRegistration getFilterRegistration(String filterName);
 718
 719     /**
 720      * @return TODO
 721      * @throws UnsupportedOperationException    If called from a
 722      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 723      *    method of a {@link ServletContextListener} that was not defined in a
 724      *    web.xml file, a web-fragment.xml file nor annotated with
 725      *    {@link javax.servlet.annotation.WebListener}. For example, a
 726      *    {@link ServletContextListener} defined in a TLD would not be able to
 727      *    use this method.
 728      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 729      */
 730     public Map<String, ? extends FilterRegistration> getFilterRegistrations();
 731
 732     /**
 733      * @return TODO
 734      * @throws UnsupportedOperationException    If called from a
 735      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 736      *    method of a {@link ServletContextListener} that was not defined in a
 737      *    web.xml file, a web-fragment.xml file nor annotated with
 738      *    {@link javax.servlet.annotation.WebListener}. For example, a
 739      *    {@link ServletContextListener} defined in a TLD would not be able to
 740      *    use this method.
 741      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 742      */
 743     public SessionCookieConfig getSessionCookieConfig();
 744
 745     /**
 746      * @param sessionTrackingModes
 747      * @throws IllegalArgumentException
 748      *             If sessionTrackingModes specifies
 749      *             {@link SessionTrackingMode#SSL} in combination with any other
 750      *             {@link SessionTrackingMode}
 751      * @throws IllegalStateException
 752      *             If the context has already been initialised
 753      * @throws UnsupportedOperationException    If called from a
 754      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 755      *    method of a {@link ServletContextListener} that was not defined in a
 756      *    web.xml file, a web-fragment.xml file nor annotated with
 757      *    {@link javax.servlet.annotation.WebListener}. For example, a
 758      *    {@link ServletContextListener} defined in a TLD would not be able to
 759      *    use this method.
 760      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 761      */
 762     public void setSessionTrackingModes(
 763             Set<SessionTrackingMode> sessionTrackingModes);
 764
 765     /**
 766      * @return TODO
 767      * @throws UnsupportedOperationException    If called from a
 768      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 769      *    method of a {@link ServletContextListener} that was not defined in a
 770      *    web.xml file, a web-fragment.xml file nor annotated with
 771      *    {@link javax.servlet.annotation.WebListener}. For example, a
 772      *    {@link ServletContextListener} defined in a TLD would not be able to
 773      *    use this method.
 774      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 775      */
 776     public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
 777
 778     /**
 779      * @return TODO
 780      * @throws UnsupportedOperationException    If called from a
 781      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 782      *    method of a {@link ServletContextListener} that was not defined in a
 783      *    web.xml file, a web-fragment.xml file nor annotated with
 784      *    {@link javax.servlet.annotation.WebListener}. For example, a
 785      *    {@link ServletContextListener} defined in a TLD would not be able to
 786      *    use this method.
 787      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 788      */
 789     public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
 790
 791     /**
 792      * @param className
 793      * @throws UnsupportedOperationException    If called from a
 794      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 795      *    method of a {@link ServletContextListener} that was not defined in a
 796      *    web.xml file, a web-fragment.xml file nor annotated with
 797      *    {@link javax.servlet.annotation.WebListener}. For example, a
 798      *    {@link ServletContextListener} defined in a TLD would not be able to
 799      *    use this method.
 800      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 801      */
 802     public void addListener(String className);
 803
 804     /**
 805      * @param <T>
 806      * @param t
 807      * @throws UnsupportedOperationException    If called from a
 808      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 809      *    method of a {@link ServletContextListener} that was not defined in a
 810      *    web.xml file, a web-fragment.xml file nor annotated with
 811      *    {@link javax.servlet.annotation.WebListener}. For example, a
 812      *    {@link ServletContextListener} defined in a TLD would not be able to
 813      *    use this method.
 814      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 815      */
 816     public <T extends EventListener> void addListener(T t);
 817
 818     /**
 819      * @param listenerClass
 820      * @throws UnsupportedOperationException    If called from a
 821      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 822      *    method of a {@link ServletContextListener} that was not defined in a
 823      *    web.xml file, a web-fragment.xml file nor annotated with
 824      *    {@link javax.servlet.annotation.WebListener}. For example, a
 825      *    {@link ServletContextListener} defined in a TLD would not be able to
 826      *    use this method.
 827      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 828      */
 829     public void addListener(Class<? extends EventListener> listenerClass);
 830
 831     /**
 832      * @param <T>
 833      * @param c
 834      * @return TODO
 835      * @throws ServletException
 836      * @throws UnsupportedOperationException    If called from a
 837      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 838      *    method of a {@link ServletContextListener} that was not defined in a
 839      *    web.xml file, a web-fragment.xml file nor annotated with
 840      *    {@link javax.servlet.annotation.WebListener}. For example, a
 841      *    {@link ServletContextListener} defined in a TLD would not be able to
 842      *    use this method.
 843      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 844      */
 845     public <T extends EventListener> T createListener(Class<T> c)
 846             throws ServletException;
 847
 848     /**
 849      * @return TODO
 850      * @throws UnsupportedOperationException    If called from a
 851      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 852      *    method of a {@link ServletContextListener} that was not defined in a
 853      *    web.xml file, a web-fragment.xml file nor annotated with
 854      *    {@link javax.servlet.annotation.WebListener}. For example, a
 855      *    {@link ServletContextListener} defined in a TLD would not be able to
 856      *    use this method.
 857      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 858      */
 859     public JspConfigDescriptor getJspConfigDescriptor();
 860
 861     /**
 862      * @return TODO
 863      * @throws UnsupportedOperationException    If called from a
 864      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 865      *    method of a {@link ServletContextListener} that was not defined in a
 866      *    web.xml file, a web-fragment.xml file nor annotated with
 867      *    {@link javax.servlet.annotation.WebListener}. For example, a
 868      *    {@link ServletContextListener} defined in a TLD would not be able to
 869      *    use this method.
 870      * @throws SecurityException
 871      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 872      */
 873     public ClassLoader getClassLoader();
 874
 875     /**
 876      * @param roleNames
 877      * @throws UnsupportedOperationException    If called from a
 878      *    {@link ServletContextListener#contextInitialized(ServletContextEvent)}
 879      *    method of a {@link ServletContextListener} that was not defined in a
 880      *    web.xml file, a web-fragment.xml file nor annotated with
 881      *    {@link javax.servlet.annotation.WebListener}. For example, a
 882      *    {@link ServletContextListener} defined in a TLD would not be able to
 883      *    use this method.
 884      * @throws IllegalArgumentException
 885      * @throws IllegalStateException
 886      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 887      */
 888     public void declareRoles(String... roleNames);
 889
 890     /**
 891      * Returns the primary name of the virtual host on which this context is
 892      * deployed. The name may or may not be a valid host name.
 893      */
 894     public String getVirtualServerName();
 895 }