/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.servlet; import java.io.InputStream; import java.net.MalformedURLException; import java.net.URL; import java.util.Enumeration; import java.util.EventListener; import java.util.Map; import java.util.Set; import javax.servlet.descriptor.JspConfigDescriptor; /** * Defines a set of methods that a servlet uses to communicate with its servlet * container, for example, to get the MIME type of a file, dispatch requests, or * write to a log file. *

* There is one context per "web application" per Java Virtual Machine. (A * "web application" is a collection of servlets and content installed under a * specific subset of the server's URL namespace such as /catalog * and possibly installed via a .war file.) *

* In the case of a web application marked "distributed" in its deployment * descriptor, there will be one context instance for each virtual machine. In * this situation, the context cannot be used as a location to share global * information (because the information won't be truly global). Use an external * resource like a database instead. *

* The ServletContext object is contained within the * {@link ServletConfig} object, which the Web server provides the servlet when * the servlet is initialized. * * @see Servlet#getServletConfig * @see ServletConfig#getServletContext */ public interface ServletContext { public static final String TEMPDIR = "javax.servlet.context.tempdir"; /** * @since Servlet 3.0 */ public static final String ORDERED_LIBS = "javax.servlet.context.orderedLibs"; /** * Return the main path associated with this context. * * @return The main context path * * @since Servlet 2.5 */ public String getContextPath(); /** * Returns a ServletContext object that corresponds to a * specified URL on the server. *

* This method allows servlets to gain access to the context for various * parts of the server, and as needed obtain {@link RequestDispatcher} * objects from the context. The given path must be begin with "/", is * interpreted relative to the server's document root and is matched against * the context roots of other web applications hosted on this container. *

* In a security conscious environment, the servlet container may return * null for a given URL. * * @param uripath * a String specifying the context path of another * web application in the container. * @return the ServletContext object that corresponds to the * named URL, or null if either none exists or the container wishes * to restrict this access. * @see RequestDispatcher */ public ServletContext getContext(String uripath); /** * Returns the major version of the Java Servlet API that this servlet * container supports. All implementations that comply with Version 3.1 must * have this method return the integer 3. * * @return 3 */ public int getMajorVersion(); /** * Returns the minor version of the Servlet API that this servlet container * supports. All implementations that comply with Version 3.1 must have this * method return the integer 1. * * @return 1 */ public int getMinorVersion(); /** * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public int getEffectiveMajorVersion(); /** * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public int getEffectiveMinorVersion(); /** * Returns the MIME type of the specified file, or null if the * MIME type is not known. The MIME type is determined by the configuration * of the servlet container, and may be specified in a web application * deployment descriptor. Common MIME types are "text/html" and * "image/gif". * * @param file * a String specifying the name of a file * @return a String specifying the file's MIME type */ public String getMimeType(String file); /** * Returns a directory-like listing of all the paths to resources within the * web application whose longest sub-path matches the supplied path * argument. Paths indicating subdirectory paths end with a '/'. The * returned paths are all relative to the root of the web application and * have a leading '/'. For example, for a web application containing
*
* /welcome.html
* /catalog/index.html
* /catalog/products.html
* /catalog/offers/books.html
* /catalog/offers/music.html
* /customer/login.jsp
* /WEB-INF/web.xml
* /WEB-INF/classes/com.acme.OrderServlet.class,
*
* getResourcePaths("/") returns {"/welcome.html", "/catalog/", * "/customer/", "/WEB-INF/"}
* getResourcePaths("/catalog/") returns {"/catalog/index.html", * "/catalog/products.html", "/catalog/offers/"}.
* * @param path * the partial path used to match the resources, which must start * with a / * @return a Set containing the directory listing, or null if there are no * resources in the web application whose path begins with the * supplied path. * @since Servlet 2.3 */ public Set getResourcePaths(String path); /** * Returns a URL to the resource that is mapped to a specified path. The * path must begin with a "/" and is interpreted as relative to the current * context root. *

* This method allows the servlet container to make a resource available to * servlets from any source. Resources can be located on a local or remote * file system, in a database, or in a .war file. *

* The servlet container must implement the URL handlers and * URLConnection objects that are necessary to access the * resource. *

* This method returns null if no resource is mapped to the * pathname. *

* Some containers may allow writing to the URL returned by this method * using the methods of the URL class. *

* The resource content is returned directly, so be aware that requesting a * .jsp page returns the JSP source code. Use a * RequestDispatcher instead to include results of an * execution. *

* This method has a different purpose than * java.lang.Class.getResource, which looks up resources based * on a class loader. This method does not use class loaders. * * @param path * a String specifying the path to the resource * @return the resource located at the named path, or null if * there is no resource at that path * @exception MalformedURLException * if the pathname is not given in the correct form */ public URL getResource(String path) throws MalformedURLException; /** * Returns the resource located at the named path as an * InputStream object. *

* The data in the InputStream can be of any type or length. * The path must be specified according to the rules given in * getResource. This method returns null if no * resource exists at the specified path. *

* Meta-information such as content length and content type that is * available via getResource method is lost when using this * method. *

* The servlet container must implement the URL handlers and * URLConnection objects necessary to access the resource. *

* This method is different from * java.lang.Class.getResourceAsStream, which uses a class * loader. This method allows servlet containers to make a resource * available to a servlet from any location, without using a class loader. * * @param path * a String specifying the path to the resource * @return the InputStream returned to the servlet, or * null if no resource exists at the specified path */ public InputStream getResourceAsStream(String path); /** * Returns a {@link RequestDispatcher} object that acts as a wrapper for the * resource located at the given path. A RequestDispatcher * object can be used to forward a request to the resource or to include the * resource in a response. The resource can be dynamic or static. *

* The pathname must begin with a "/" and is interpreted as relative to the * current context root. Use getContext to obtain a * RequestDispatcher for resources in foreign contexts. This * method returns null if the ServletContext * cannot return a RequestDispatcher. * * @param path * a String specifying the pathname to the resource * @return a RequestDispatcher object that acts as a wrapper for * the resource at the specified path, or null if the * ServletContext cannot return a * RequestDispatcher * @see RequestDispatcher * @see ServletContext#getContext */ public RequestDispatcher getRequestDispatcher(String path); /** * Returns a {@link RequestDispatcher} object that acts as a wrapper for the * named servlet. *

* Servlets (and JSP pages also) may be given names via server * administration or via a web application deployment descriptor. A servlet * instance can determine its name using * {@link ServletConfig#getServletName}. *

* This method returns null if the ServletContext * cannot return a RequestDispatcher for any reason. * * @param name * a String specifying the name of a servlet to wrap * @return a RequestDispatcher object that acts as a wrapper for * the named servlet, or null if the * ServletContext cannot return a * RequestDispatcher * @see RequestDispatcher * @see ServletContext#getContext * @see ServletConfig#getServletName */ public RequestDispatcher getNamedDispatcher(String name); /** * Do not use. This method was originally defined to retrieve a servlet from * a ServletContext. In this version, this method always * returns null and remains only to preserve binary * compatibility. This method will be permanently removed in a future * version of the Java Servlet API. *

* In lieu of this method, servlets can share information using the * ServletContext class and can perform shared business logic * by invoking methods on common non-servlet classes. * * @param name Not used * * @return Always null * * @throws ServletException never * * @deprecated As of Java Servlet API 2.1, with no direct replacement. */ @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated public Servlet getServlet(String name) throws ServletException; /** * Do not use. This method was originally defined to return an * Enumeration of all the servlets known to this servlet * context. In this version, this method always returns an empty enumeration * and remains only to preserve binary compatibility. This method will be * permanently removed in a future version of the Java Servlet API. * * @return Always and empty Enumeration * * @deprecated As of Java Servlet API 2.0, with no replacement. */ @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated public Enumeration getServlets(); /** * Do not use. This method was originally defined to return an * Enumeration of all the servlet names known to this context. * In this version, this method always returns an empty * Enumeration and remains only to preserve binary * compatibility. This method will be permanently removed in a future * version of the Java Servlet API. * * @return Always and empty Enumeration * * @deprecated As of Java Servlet API 2.1, with no replacement. */ @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated public Enumeration getServletNames(); /** * Writes the specified message to a servlet log file, usually an event log. * The name and type of the servlet log file is specific to the servlet * container. * * @param msg * a String specifying the message to be written to * the log file */ public void log(String msg); /** * Do not use. * @param exception The exception to log * @param msg The message to log with the exception * @deprecated As of Java Servlet API 2.1, use * {@link #log(String message, Throwable throwable)} instead. *

* This method was originally defined to write an exception's * stack trace and an explanatory error message to the servlet * log file. */ @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated public void log(Exception exception, String msg); /** * Writes an explanatory message and a stack trace for a given * Throwable exception to the servlet log file. The name and * type of the servlet log file is specific to the servlet container, * usually an event log. * * @param message * a String that describes the error or exception * @param throwable * the Throwable error or exception */ public void log(String message, Throwable throwable); /** * Returns a String containing the real path for a given * virtual path. For example, the path "/index.html" returns the absolute * file path on the server's filesystem would be served by a request for * "http://host/contextPath/index.html", where contextPath is the context * path of this ServletContext.. *

* The real path returned will be in a form appropriate to the computer and * operating system on which the servlet container is running, including the * proper path separators. This method returns null if the * servlet container cannot translate the virtual path to a real path for * any reason (such as when the content is being made available from a * .war archive). * * @param path * a String specifying a virtual path * @return a String specifying the real path, or null if the * translation cannot be performed */ public String getRealPath(String path); /** * Returns the name and version of the servlet container on which the * servlet is running. *

* The form of the returned string is * servername/versionnumber. For example, the JavaServer Web * Development Kit may return the string * JavaServer Web Dev Kit/1.0. *

* The servlet container may return other optional information after the * primary string in parentheses, for example, * JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86). * * @return a String containing at least the servlet container * name and version number */ public String getServerInfo(); /** * Returns a String containing the value of the named * context-wide initialization parameter, or null if the * parameter does not exist. *

* This method can make available configuration information useful to an * entire "web application". For example, it can provide a webmaster's email * address or the name of a system that holds critical data. * * @param name * a String containing the name of the parameter * whose value is requested * @return a String containing the value of the initialization * parameter * @see ServletConfig#getInitParameter */ public String getInitParameter(String name); /** * Returns the names of the context's initialization parameters as an * Enumeration of String objects, or an empty * Enumeration if the context has no initialization parameters. * * @return an Enumeration of String objects * containing the names of the context's initialization parameters * @see ServletConfig#getInitParameter */ public Enumeration getInitParameterNames(); /** * Set the given initialisation parameter to the given value. * @param name Name of initialisation parameter * @param value Value for initialisation parameter * @return true if the call succeeds or false if * the call fails because an initialisation parameter with the same * name has already been set * @throws IllegalStateException If initialisation of this ServletContext * has already completed * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public boolean setInitParameter(String name, String value); /** * Returns the servlet container attribute with the given name, or * null if there is no attribute by that name. An attribute * allows a servlet container to give the servlet additional information not * already provided by this interface. See your server documentation for * information about its attributes. A list of supported attributes can be * retrieved using getAttributeNames. *

* The attribute is returned as a java.lang.Object or some * subclass. Attribute names should follow the same convention as package * names. The Java Servlet API specification reserves names matching * java.*, javax.*, and sun.*. * * @param name * a String specifying the name of the attribute * @return an Object containing the value of the attribute, or * null if no attribute exists matching the given name * @see ServletContext#getAttributeNames */ public Object getAttribute(String name); /** * Returns an Enumeration containing the attribute names * available within this servlet context. Use the {@link #getAttribute} * method with an attribute name to get the value of an attribute. * * @return an Enumeration of attribute names * @see #getAttribute */ public Enumeration getAttributeNames(); /** * Binds an object to a given attribute name in this servlet context. If the * name specified is already used for an attribute, this method will replace * the attribute with the new to the new attribute. *

* If listeners are configured on the ServletContext the * container notifies them accordingly. *

* If a null value is passed, the effect is the same as calling * removeAttribute(). *

* Attribute names should follow the same convention as package names. The * Java Servlet API specification reserves names matching * java.*, javax.*, and sun.*. * * @param name * a String specifying the name of the attribute * @param object * an Object representing the attribute to be bound */ public void setAttribute(String name, Object object); /** * Removes the attribute with the given name from the servlet context. After * removal, subsequent calls to {@link #getAttribute} to retrieve the * attribute's value will return null. *

* If listeners are configured on the ServletContext the * container notifies them accordingly. * * @param name * a String specifying the name of the attribute to * be removed */ public void removeAttribute(String name); /** * Returns the name of this web application corresponding to this * ServletContext as specified in the deployment descriptor for this web * application by the display-name element. * * @return The name of the web application or null if no name has been * declared in the deployment descriptor. * @since Servlet 2.3 */ public String getServletContextName(); /** * Register a servlet implementation for use in this ServletContext. * @param servletName The name of the servlet to register * @param className The implementation class for the servlet * @return The registration object that enables further configuration * @throws IllegalStateException * If the context has already been initialised * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public ServletRegistration.Dynamic addServlet(String servletName, String className); /** * Register a servlet instance for use in this ServletContext. * @param servletName The name of the servlet to register * @param servlet The Servlet instance to register * @return The registration object that enables further configuration * @throws IllegalStateException * If the context has already been initialised * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public ServletRegistration.Dynamic addServlet(String servletName, Servlet servlet); /** * Add servlet to context. * @param servletName Name of servlet to add * @param servletClass Class of servlet to add * @return null if the servlet has already been fully defined, * else a {@link javax.servlet.ServletRegistration.Dynamic} object * that can be used to further configure the servlet * @throws IllegalStateException * If the context has already been initialised * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public ServletRegistration.Dynamic addServlet(String servletName, Class servletClass); /** * TODO SERVLET3 - Add comments * @param TODO * @param c TODO * @return TODO * @throws ServletException TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public T createServlet(Class c) throws ServletException; /** * Obtain the details of the named servlet. * * @param servletName The name of the Servlet of interest * * @return The registration details for the named Servlet or * null if no Servlet has been registered with the * given name * * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * * @since Servlet 3.0 */ public ServletRegistration getServletRegistration(String servletName); /** * TODO SERVLET3 - Add comments * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public Map getServletRegistrations(); /** * Add filter to context. * @param filterName Name of filter to add * @param className Name of filter class * @return null if the filter has already been fully defined, * else a {@link javax.servlet.FilterRegistration.Dynamic} object * that can be used to further configure the filter * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws IllegalStateException * If the context has already been initialised * @since Servlet 3.0 */ public FilterRegistration.Dynamic addFilter(String filterName, String className); /** * Add filter to context. * @param filterName Name of filter to add * @param filter Filter to add * @return null if the filter has already been fully defined, * else a {@link javax.servlet.FilterRegistration.Dynamic} object * that can be used to further configure the filter * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws IllegalStateException * If the context has already been initialised * @since Servlet 3.0 */ public FilterRegistration.Dynamic addFilter(String filterName, Filter filter); /** * Add filter to context. * @param filterName Name of filter to add * @param filterClass Class of filter to add * @return null if the filter has already been fully defined, * else a {@link javax.servlet.FilterRegistration.Dynamic} object * that can be used to further configure the filter * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws IllegalStateException * If the context has already been initialised * @since Servlet 3.0 */ public FilterRegistration.Dynamic addFilter(String filterName, Class filterClass); /** * TODO SERVLET3 - Add comments * @param TODO * @param c TODO * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws ServletException TODO * @since Servlet 3. */ public T createFilter(Class c) throws ServletException; /** * TODO SERVLET3 - Add comments * @param filterName TODO * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public FilterRegistration getFilterRegistration(String filterName); /** * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public Map getFilterRegistrations(); /** * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public SessionCookieConfig getSessionCookieConfig(); /** * Configures the available session tracking modes for this web application. * @param sessionTrackingModes The session tracking modes to use for this * web application * @throws IllegalArgumentException * If sessionTrackingModes specifies * {@link SessionTrackingMode#SSL} in combination with any other * {@link SessionTrackingMode} * @throws IllegalStateException * If the context has already been initialised * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public void setSessionTrackingModes( Set sessionTrackingModes); /** * Obtains the default session tracking modes for this web application. * By default {@link SessionTrackingMode#URL} is always supported, {@link * SessionTrackingMode#COOKIE} is supported unless the cookies * attribute has been set to false for the context and {@link * SessionTrackingMode#SSL} is supported if at least one of the connectors * used by this context has the attribute secure set to * true. * @return The set of default session tracking modes for this web * application * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public Set getDefaultSessionTrackingModes(); /** * Obtains the currently enabled session tracking modes for this web * application. * @return The value supplied via {@link #setSessionTrackingModes(Set)} if * one was previously set, else return the defaults * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public Set getEffectiveSessionTrackingModes(); /** * TODO SERVLET3 - Add comments * @param className TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public void addListener(String className); /** * TODO SERVLET3 - Add comments * @param TODO * @param t TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public void addListener(T t); /** * TODO SERVLET3 - Add comments * @param listenerClass TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public void addListener(Class listenerClass); /** * TODO SERVLET3 - Add comments * @param TODO * @param c TODO * @return TODO * @throws ServletException TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 */ public T createListener(Class c) throws ServletException; /** * @return TODO * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public JspConfigDescriptor getJspConfigDescriptor(); /** * Get the web application class loader associated with this ServletContext. * * @return The associated web application class loader * * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws SecurityException if access to the class loader is prevented by a * SecurityManager * @since Servlet 3.0 */ public ClassLoader getClassLoader(); /** * Add to the declared roles for this ServletContext. * @param roleNames The roles to add * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a * web.xml file, a web-fragment.xml file nor annotated with * {@link javax.servlet.annotation.WebListener}. For example, a * {@link ServletContextListener} defined in a TLD would not be able to * use this method. * @throws IllegalArgumentException If the list of roleNames is null or * empty * @throws IllegalStateException If the ServletContext has already been * initialised * @since Servlet 3.0 */ public void declareRoles(String... roleNames); /** * Get the primary name of the virtual host on which this context is * deployed. The name may or may not be a valid host name. * * @return The primary name of the virtual host on which this context is * deployed * @since Servlet 3.1 */ public String getVirtualServerName(); }