/*

* 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 org.apache.catalina;

import java.net.URL;

import java.util.Locale;

import java.util.Map;

import java.util.Set;

import javax.servlet.ServletContainerInitializer;

import javax.servlet.ServletContext;

import javax.servlet.ServletRegistration;

import javax.servlet.ServletRequest;

import javax.servlet.ServletSecurityElement;

import javax.servlet.descriptor.JspConfigDescriptor;

import org.apache.catalina.deploy.NamingResourcesImpl;

import org.apache.tomcat.InstanceManager;

import org.apache.tomcat.JarScanner;

import org.apache.tomcat.util.descriptor.web.ApplicationParameter;

import org.apache.tomcat.util.descriptor.web.ErrorPage;

import org.apache.tomcat.util.descriptor.web.FilterDef;

import org.apache.tomcat.util.descriptor.web.FilterMap;

import org.apache.tomcat.util.descriptor.web.LoginConfig;

import org.apache.tomcat.util.descriptor.web.SecurityConstraint;

import org.apache.tomcat.util.http.CookieProcessor;

/**

* A <b>Context</b> is a Container that represents a servlet context, and

* therefore an individual web application, in the Catalina servlet engine.

* It is therefore useful in almost every deployment of Catalina (even if a

* Connector attached to a web server (such as Apache) uses the web server's

* facilities to identify the appropriate Wrapper to handle this request.

* It also provides a convenient mechanism to use Interceptors that see

* every request processed by this particular web application.

* <p>

* The parent Container attached to a Context is generally a Host, but may

* be some other implementation, or may be omitted if it is not necessary.

* <p>

* The child containers attached to a Context are generally implementations

* of Wrapper (representing individual servlet definitions).

* <p>

*

* @author Craig R. McClanahan

*/

public interface Context extends Container {

// ----------------------------------------------------- Manifest Constants

/**

* Container event for adding a welcome file.

*/

public static final String ADD_WELCOME_FILE_EVENT = "addWelcomeFile";

/**

* Container event for removing a wrapper.

*/

public static final String REMOVE_WELCOME_FILE_EVENT = "removeWelcomeFile";

/**

* Container event for clearing welcome files.

*/

public static final String CLEAR_WELCOME_FILES_EVENT = "clearWelcomeFiles";

/**

* Container event for changing the ID of a session.

*/

public static final String CHANGE_SESSION_ID_EVENT = "changeSessionId";

// ------------------------------------------------------------- Properties

/**

* Returns <code>true</code> if requests mapped to servlets without

* "multipart config" to parse multipart/form-data requests anyway.

*

* @return <code>true</code> if requests mapped to servlets without

* "multipart config" to parse multipart/form-data requests,

* <code>false</code> otherwise.

*/

public boolean getAllowCasualMultipartParsing();

/**

* Set to <code>true</code> to allow requests mapped to servlets that

* do not explicitly declare @MultipartConfig or have

* &lt;multipart-config&gt; specified in web.xml to parse

* multipart/form-data requests.

*

* @param allowCasualMultipartParsing <code>true</code> to allow such

* casual parsing, <code>false</code> otherwise.

*/

public void setAllowCasualMultipartParsing(boolean allowCasualMultipartParsing);

/**

* Obtain the registered application event listeners.

*

* @return An array containing the application event listener instances for

* this web application in the order they were specified in the web

* application deployment descriptor

*/

public Object[] getApplicationEventListeners();

/**

* Store the set of initialized application event listener objects,

* in the order they were specified in the web application deployment

* descriptor, for this application.

*

* @param listeners The set of instantiated listener objects.

*/

public void setApplicationEventListeners(Object listeners[]);

/**

* Obtain the registered application lifecycle listeners.

*

* @return An array containing the application lifecycle listener instances

* for this web application in the order they were specified in the

* web application deployment descriptor

*/

public Object[] getApplicationLifecycleListeners();

/**

* Store the set of initialized application lifecycle listener objects,

* in the order they were specified in the web application deployment

* descriptor, for this application.

*

* @param listeners The set of instantiated listener objects.

*/

public void setApplicationLifecycleListeners(Object listeners[]);

/**

* Obtain the character set name to use with the given Locale. Note that

* different Contexts may have different mappings of Locale to character

* set.

*

* @param locale The locale for which the mapped character set should be

* returned

*

* @return The name of the character set to use with the given Locale

*/

public String getCharset(Locale locale);

/**

* Return the URL of the XML descriptor for this context.

*

* @return The URL of the XML descriptor for this context

*/

public URL getConfigFile();

/**

* Set the URL of the XML descriptor for this context.

*

* @param configFile The URL of the XML descriptor for this context.

*/

public void setConfigFile(URL configFile);

/**

* Return the "correctly configured" flag for this Context.

*

* @return <code>true</code> if the Context has been correctly configured,

* otherwise <code>false</code>

*/

public boolean getConfigured();

/**

* Set the "correctly configured" flag for this Context. This can be

* set to false by startup listeners that detect a fatal configuration

* error to avoid the application from being made available.

*

* @param configured The new correctly configured flag

*/

public void setConfigured(boolean configured);

/**

* Return the "use cookies for session ids" flag.

*

* @return <code>true</code> if it is permitted to use cookies to track

* session IDs for this web application, otherwise

* <code>false</code>

*/

public boolean getCookies();

/**

* Set the "use cookies for session ids" flag.

*

* @param cookies The new flag

*/

public void setCookies(boolean cookies);

/**

* Gets the name to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @return The value of the default session cookie name or null if not

* specified

*/

public String getSessionCookieName();

/**

* Sets the name to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @param sessionCookieName The name to use

*/

public void setSessionCookieName(String sessionCookieName);

/**

* Gets the value of the use HttpOnly cookies for session cookies flag.

*

* @return <code>true</code> if the HttpOnly flag should be set on session

* cookies

*/

public boolean getUseHttpOnly();

/**

* Sets the use HttpOnly cookies for session cookies flag.

*

* @param useHttpOnly Set to <code>true</code> to use HttpOnly cookies

* for session cookies

*/

public void setUseHttpOnly(boolean useHttpOnly);

/**

* Gets the domain to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @return The value of the default session cookie domain or null if not

* specified

*/

public String getSessionCookieDomain();

/**

* Sets the domain to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @param sessionCookieDomain The domain to use

*/

public void setSessionCookieDomain(String sessionCookieDomain);

/**

* Gets the path to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @return The value of the default session cookie path or null if not

* specified

*/

public String getSessionCookiePath();

/**

* Sets the path to use for session cookies. Overrides any setting that

* may be specified by the application.

*

* @param sessionCookiePath The path to use

*/

public void setSessionCookiePath(String sessionCookiePath);

/**

* Is a / added to the end of the session cookie path to ensure browsers,

* particularly IE, don't send a session cookie for context /foo with

* requests intended for context /foobar.

*

* @return <code>true</code> if the slash is added, otherwise

* <code>false</code>

*/

public boolean getSessionCookiePathUsesTrailingSlash();

/**

* Configures if a / is added to the end of the session cookie path to

* ensure browsers, particularly IE, don't send a session cookie for context

* /foo with requests intended for context /foobar.

*

* @param sessionCookiePathUsesTrailingSlash <code>true</code> if the

* slash is should be added,

* otherwise <code>false</code>

*/

public void setSessionCookiePathUsesTrailingSlash(

boolean sessionCookiePathUsesTrailingSlash);

/**

* Return the "allow crossing servlet contexts" flag.

*

* @return <code>true</code> if cross-contest requests are allowed from this

* web applications, otherwise <code>false</code>

*/

public boolean getCrossContext();

/**

* Return the alternate Deployment Descriptor name.

*

* @return the name

*/

public String getAltDDName();

/**

* Set an alternate Deployment Descriptor name.

*

* @param altDDName The new name

*/

public void setAltDDName(String altDDName) ;

/**

* Set the "allow crossing servlet contexts" flag.

*

* @param crossContext The new cross contexts flag

*/

public void setCrossContext(boolean crossContext);

/**

* Return the deny-uncovered-http-methods flag for this web application.

*

* @return The current value of the flag

*/

public boolean getDenyUncoveredHttpMethods();

/**

* Set the deny-uncovered-http-methods flag for this web application.

*

* @param denyUncoveredHttpMethods The new deny-uncovered-http-methods flag

*/

public void setDenyUncoveredHttpMethods(boolean denyUncoveredHttpMethods);

/**

* Return the display name of this web application.

*

* @return The display name

*/

public String getDisplayName();

/**

* Set the display name of this web application.

*

* @param displayName The new display name

*/

public void setDisplayName(String displayName);

/**

* Return the distributable flag for this web application.

*/

public boolean getDistributable();

/**

* Set the distributable flag for this web application.

*

* @param distributable The new distributable flag

*/

public void setDistributable(boolean distributable);

/**

* Return the document root for this Context. This can be an absolute

* pathname, a relative pathname, or a URL.

*/

public String getDocBase();

/**

* Set the document root for this Context. This can be an absolute

* pathname, a relative pathname, or a URL.

*

* @param docBase The new document root

*/

public void setDocBase(String docBase);

/**

* Return the URL encoded context path, using UTF-8.

*/

public String getEncodedPath();

/**

* Return the boolean on the annotations parsing.

*/

public boolean getIgnoreAnnotations();

/**

* Set the boolean on the annotations parsing for this web

* application.

*

* @param ignoreAnnotations The boolean on the annotations parsing

*/

public void setIgnoreAnnotations(boolean ignoreAnnotations);

/**

* Return the login configuration descriptor for this web application.

*/

public LoginConfig getLoginConfig();

/**

* Set the login configuration descriptor for this web application.

*

* @param config The new login configuration

*/

public void setLoginConfig(LoginConfig config);

/**

* Return the naming resources associated with this web application.

*/

public NamingResourcesImpl getNamingResources();

/**

* Set the naming resources for this web application.

*

* @param namingResources The new naming resources

*/

public void setNamingResources(NamingResourcesImpl namingResources);

/**

* Return the context path for this web application.

*/

public String getPath();

/**

* Set the context path for this web application.

*

* @param path The new context path

*/

public void setPath(String path);

/**

* Return the public identifier of the deployment descriptor DTD that is

* currently being parsed.

*/

public String getPublicId();

/**

* Set the public identifier of the deployment descriptor DTD that is

* currently being parsed.

*

* @param publicId The public identifier

*/

public void setPublicId(String publicId);

/**

* Return the reloadable flag for this web application.

*/

public boolean getReloadable();

/**

* Set the reloadable flag for this web application.

*

* @param reloadable The new reloadable flag

*/

public void setReloadable(boolean reloadable);

/**

* Return the override flag for this web application.

*/

public boolean getOverride();

/**

* Set the override flag for this web application.

*

* @param override The new override flag

*/

public void setOverride(boolean override);

/**

* Return the privileged flag for this web application.

*/

public boolean getPrivileged();

/**

* Set the privileged flag for this web application.

*

* @param privileged The new privileged flag

*/

public void setPrivileged(boolean privileged);

/**

* Return the servlet context for which this Context is a facade.

*/

public ServletContext getServletContext();

/**

* Return the default session timeout (in minutes) for this

* web application.

*/

public int getSessionTimeout();

/**

* Set the default session timeout (in minutes) for this

* web application.

*

* @param timeout The new default session timeout

*/

public void setSessionTimeout(int timeout);

/**

* Returns <code>true</code> if remaining request data will be read

* (swallowed) even the request violates a data size constraint.

*

* @return <code>true</code> if data will be swallowed (default),

* <code>false</code> otherwise.

*/

public boolean getSwallowAbortedUploads();

/**

* Set to <code>false</code> to disable request data swallowing

* after an upload was aborted due to size constraints.

*

* @param swallowAbortedUploads <code>false</code> to disable

* swallowing, <code>true</code> otherwise (default).

*/

public void setSwallowAbortedUploads(boolean swallowAbortedUploads);

/**

* Return the value of the swallowOutput flag.

*/

public boolean getSwallowOutput();

/**

* Set the value of the swallowOutput flag. If set to true, the system.out

* and system.err will be redirected to the logger during a servlet

* execution.

*

* @param swallowOutput The new value

*/

public void setSwallowOutput(boolean swallowOutput);

/**

* Return the Java class name of the Wrapper implementation used

* for servlets registered in this Context.

*/

public String getWrapperClass();

/**

* Set the Java class name of the Wrapper implementation used

* for servlets registered in this Context.

*

* @param wrapperClass The new wrapper class

*/

public void setWrapperClass(String wrapperClass);

/**

* Will the parsing of web.xml and web-fragment.xml files for this Context

* be performed by a namespace aware parser?

*

* @return true if namespace awareness is enabled.

*/

public boolean getXmlNamespaceAware();

/**

* Controls whether the parsing of web.xml and web-fragment.xml files for

* this Context will be performed by a namespace aware parser.

*

* @param xmlNamespaceAware true to enable namespace awareness

*/

public void setXmlNamespaceAware(boolean xmlNamespaceAware);

/**

* Will the parsing of web.xml and web-fragment.xml files for this Context

* be performed by a validating parser?

*

* @return true if validation is enabled.

*/

public boolean getXmlValidation();

/**

* Controls whether the parsing of web.xml and web-fragment.xml files

* for this Context will be performed by a validating parser.

*

* @param xmlValidation true to enable xml validation

*/

public void setXmlValidation(boolean xmlValidation);

/**

* Will the parsing of web.xml, web-fragment.xml, *.tld, *.jspx, *.tagx and

* tagplugin.xml files for this Context block the use of external entities?

*

* @return true if access to external entities is blocked

*/

public boolean getXmlBlockExternal();

/**

* Controls whether the parsing of web.xml, web-fragment.xml, *.tld, *.jspx,

* *.tagx and tagplugin.xml files for this Context will block the use of

* external entities.

*

* @param xmlBlockExternal true to block external entities

*/

public void setXmlBlockExternal(boolean xmlBlockExternal);

/**

* Will the parsing of *.tld files for this Context be performed by a

* validating parser?

*

* @return true if validation is enabled.

*/

public boolean getTldValidation();

/**

* Controls whether the parsing of *.tld files for this Context will be

* performed by a validating parser.

*

* @param tldValidation true to enable xml validation

*/

public void setTldValidation(boolean tldValidation);

/**

* Get the Jar Scanner to be used to scan for JAR resources for this

* context.

* @return The Jar Scanner configured for this context.

*/

public JarScanner getJarScanner();

/**

* Set the Jar Scanner to be used to scan for JAR resources for this

* context.

* @param jarScanner The Jar Scanner to be used for this context.

*/

public void setJarScanner(JarScanner jarScanner);

/**

* Obtain the {@link Authenticator} that is used by this context or

* <code>null</code> if none is used.

*/

public Authenticator getAuthenticator();

/**

* Set whether or not the effective web.xml for this context should be

* logged on context start.

*/

public void setLogEffectiveWebXml(boolean logEffectiveWebXml);

/**

* Should the effective web.xml for this context be logged on context start?

*/

public boolean getLogEffectiveWebXml();

/**

* Get the instance manager associated with this context.

*/

public InstanceManager getInstanceManager();

/**

* Set the instance manager associated with this context.

*/

public void setInstanceManager(InstanceManager instanceManager);

/**

* Sets the regular expression that specifies which container provided SCIs

* should be filtered out and not used for this context. Matching uses

* {@link java.util.regex.Matcher#find()} so the regular expression only has

* to match a sub-string of the fully qualified class name of the container

* provided SCI for it to be filtered out.

*

* @param containerSciFilter The regular expression against which the fully

* qualified class name of each container provided

* SCI should be checked

*/

public void setContainerSciFilter(String containerSciFilter);

/**

* Obtains the regular expression that specifies which container provided

* SCIs should be filtered out and not used for this context. Matching uses

* {@link java.util.regex.Matcher#find()} so the regular expression only has

* to match a sub-string of the fully qualified class name of the container

* provided SCI for it to be filtered out.

*

* @return The regular expression against which the fully qualified class

* name of each container provided SCI will be checked

*/

public String getContainerSciFilter();

// --------------------------------------------------------- Public Methods

/**

* Add a new Listener class name to the set of Listeners

* configured for this application.

*

* @param listener Java class name of a listener class

*/

public void addApplicationListener(String listener);

/**

* Add a new application parameter for this application.

*

* @param parameter The new application parameter

*/

public void addApplicationParameter(ApplicationParameter parameter);

/**

* Add a security constraint to the set for this web application.

*/

public void addConstraint(SecurityConstraint constraint);

/**

* Add an error page for the specified error or Java exception.

*

* @param errorPage The error page definition to be added

*/

public void addErrorPage(ErrorPage errorPage);

/**

* Add a filter definition to this Context.

*

* @param filterDef The filter definition to be added

*/

public void addFilterDef(FilterDef filterDef);

/**

* Add a filter mapping to this Context.

*

* @param filterMap The filter mapping to be added

*/

public void addFilterMap(FilterMap filterMap);

/**

* Add a filter mapping to this Context before the mappings defined in the

* deployment descriptor but after any other mappings added via this method.

*

* @param filterMap The filter mapping to be added

*

* @exception IllegalArgumentException if the specified filter name

* does not match an existing filter definition, or the filter mapping

* is malformed

*/

public void addFilterMapBefore(FilterMap filterMap);

/**

* Add the classname of an InstanceListener to be added to each

* Wrapper appended to this Context.

*

* @param listener Java class name of an InstanceListener class

*/

public void addInstanceListener(String listener);

/**

* Add a Locale Encoding Mapping (see Sec 5.4 of Servlet spec 2.4)

*

* @param locale locale to map an encoding for

* @param encoding encoding to be used for a give locale

*/

public void addLocaleEncodingMappingParameter(String locale, String encoding);

/**

* Add a new MIME mapping, replacing any existing mapping for

* the specified extension.

*

* @param extension Filename extension being mapped

* @param mimeType Corresponding MIME type

*/

public void addMimeMapping(String extension, String mimeType);

/**

* Add a new context initialization parameter, replacing any existing

* value for the specified name.

*

* @param name Name of the new parameter

* @param value Value of the new parameter

*/

public void addParameter(String name, String value);

/**

* Add a security role reference for this web application.

*

* @param role Security role used in the application

* @param link Actual security role to check for

*/

public void addRoleMapping(String role, String link);

/**

* Add a new security role for this web application.

*

* @param role New security role

*/

public void addSecurityRole(String role);

/**

* Add a new servlet mapping, replacing any existing mapping for

* the specified pattern.

*

* @param pattern URL pattern to be mapped

* @param name Name of the corresponding servlet to execute

*/

public void addServletMapping(String pattern, String name);

/**

* Add a new servlet mapping, replacing any existing mapping for

* the specified pattern.

*

* @param pattern URL pattern to be mapped

* @param name Name of the corresponding servlet to execute

* @param jspWildcard true if name identifies the JspServlet

* and pattern contains a wildcard; false otherwise

*/

public void addServletMapping(String pattern, String name,

boolean jspWildcard);

/**

* Add a resource which will be watched for reloading by the host auto

* deployer. Note: this will not be used in embedded mode.

*

* @param name Path to the resource, relative to docBase

*/

public void addWatchedResource(String name);

/**

* Add a new welcome file to the set recognized by this Context.

*

* @param name New welcome file name

*/

public void addWelcomeFile(String name);

/**

* Add the classname of a LifecycleListener to be added to each

* Wrapper appended to this Context.

*

* @param listener Java class name of a LifecycleListener class

*/

public void addWrapperLifecycle(String listener);

/**

* Add the classname of a ContainerListener to be added to each

* Wrapper appended to this Context.

*

* @param listener Java class name of a ContainerListener class

*/

public void addWrapperListener(String listener);

/**

* Factory method to create and return a new Wrapper instance, of

* the Java implementation class appropriate for this Context

* implementation. The constructor of the instantiated Wrapper

* will have been called, but no properties will have been set.

*/

public Wrapper createWrapper();

/**

* Return the set of application listener class names configured

* for this application.

*/

public String[] findApplicationListeners();

/**

* Return the set of application parameters for this application.

*/

public ApplicationParameter[] findApplicationParameters();

/**

* Return the set of security constraints for this web application.

* If there are none, a zero-length array is returned.

*/

public SecurityConstraint[] findConstraints();

/**

* Return the error page entry for the specified HTTP error code,

* if any; otherwise return <code>null</code>.

*

* @param errorCode Error code to look up

*/

public ErrorPage findErrorPage(int errorCode);

/**

* Return the error page entry for the specified Java exception type,

* if any; otherwise return <code>null</code>.

*

* @param exceptionType Exception type to look up

*/

public ErrorPage findErrorPage(String exceptionType);

/**

* Return the set of defined error pages for all specified error codes

* and exception types.

*/

public ErrorPage[] findErrorPages();

/**

* Return the filter definition for the specified filter name, if any;

* otherwise return <code>null</code>.

*

* @param filterName Filter name to look up

*/

public FilterDef findFilterDef(String filterName);

/**

* Return the set of defined filters for this Context.

*/

public FilterDef[] findFilterDefs();

/**

* Return the set of filter mappings for this Context.

*/

public FilterMap[] findFilterMaps();

/**

* Return the set of InstanceListener classes that will be added to

* newly created Wrappers automatically.

*/

public String[] findInstanceListeners();