ContextConfig (Apache Tomcat 11.0.23 API Documentation)
Description: declaration: package: org.apache.catalina.startup, class: ContextConfig

# Class ContextConfig

java.lang.Object
org.apache.catalina.startup.ContextConfig

All Implemented Interfaces:
  `LifecycleListener`

public class ContextConfig extends Object implements LifecycleListener
Startup event listener for a Context that configures the properties of that Context, and the associated defined servlets.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `ContextConfig.ContextXml`
  Interface for loading context XML configuration into a Context.
  `protected static class`
  `ContextConfig.DefaultWebXmlCacheEntry`
  Cache entry for the default web.xml fragment associated with a Host.
  `protected static class`
  `ContextConfig.JavaClassCacheEntry`
  Cache entry for a Java class used during annotation scanning.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final Properties`
  `authenticators`
  The set of Authenticators that we know how to configure.
  `protected Context`
  `context`
  The Context we are associated with.
  `protected Map<String, Authenticator>`
  `customAuthenticators`
  Custom mappings of login methods to authenticators
  `protected String`
  `defaultWebXml`
  The default web application's deployment descriptor location.
  `protected static long`
  `deploymentCount`
  Deployment count.
  `protected static final LoginConfig`
  `DUMMY_LOGIN_CONFIG`
  Dummy login configuration used when no login config is defined but an authenticator is needed to support programmatic login.
  `protected boolean`
  `handlesTypesAnnotations`
  Flag that indicates if at least one `HandlesTypes` entry is present that represents an annotation.
  `protected boolean`
  `handlesTypesNonAnnotations`
  Flag that indicates if at least one `HandlesTypes` entry is present that represents a non-annotation.
  `protected static final Map<Host, ContextConfig.DefaultWebXmlCacheEntry>`
  `hostWebXmlCache`
  Cache of default web.xml fragments per Host
  `protected final Map<ServletContainerInitializer, Set<Class<?>>>`
  `initializerClassMap`
  Map of ServletContainerInitializer to classes they expressed interest in.
  `protected boolean`
  `ok`
  Track any fatal errors during startup configuration processing.
  `protected String`
  `originalDocBase`
  Original docBase.
  `protected static final StringManager`
  `sm`
  The string resources for this package.
  `protected final Map<Class<?>, Set<ServletContainerInitializer>>`
  `typeInitializerMap`
  Map of Types to ServletContainerInitializer that are interested in those types.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ContextConfig()`
  Constructs a new ContextConfig instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `antiLocking()`
  Handles anti-locking by copying the docBase to a temporary location to prevent file locking issues on Windows.
  `protected void`
  `applicationAnnotationsConfig()`
  Process the application classes annotations, if it exists.
  `protected void`
  `authenticatorConfig()`
  Set up an Authenticator automatically if required, and one has not already been configured.
  `protected void`
  `beforeStart()`
  Process a "before start" event for this Context.
  `protected void`
  `checkHandlesTypes(JavaClass javaClass, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  For classes packaged with the web application, the class and each super class needs to be checked for a match with `HandlesTypes` or for an annotation that matches `HandlesTypes`.
  `protected void`
  `configureStart()`
  Process a "contextConfig" event for this Context.
  `protected void`
  `configureStop()`
  Process a "stop" event for this Context.
  `protected void`
  `contextConfig(Digester digester)`
  Process the default configuration file, if it exists.
  `protected Digester`
  `createContextDigester()`
  Create (if necessary) and return a Digester configured to process the context configuration descriptor for an application.
  `protected WebXml`
  `createWebXml()`
  Creates a new WebXml instance.
  `protected void`
  `destroy()`
  Process a "destroy" event for this Context.
  `protected void`
  `fixDocBase()`
  Adjust docBase.
  `protected void`
  `generateClassFooter(Digester digester)`
  Generates the footer of the Java class for context XML code generation.
  `protected void`
  `generateClassHeader(Digester digester, String packageName, String resourceName)`
  Generates the header of the Java class for context XML code generation.
  `String`
  `getConfigBasePath()`
  Returns the configuration base path for the Host that contains this Context.
  `protected InputSource`
  `getContextWebXmlSource()`
  Identify the application web.xml to be used and obtain an input source for it.
  `protected File`
  `getContextXmlJavaSource(String contextXmlPackageName, String contextXmlSimpleClassName)`
  Returns the Java source file path for the given context XML class.
  `protected static String`
  `getContextXmlPackageName(String generatedCodePackage, Container container)`
  Builds the package name for context XML generated code based on the container hierarchy.
  `String`
  `getDefaultWebXml()`
  Obtain the location of the default deployment descriptor.
  `protected boolean`
  `getGenerateCode()`
  Returns whether code generation is enabled for this context.
  `protected File`
  `getGeneratedCodeLocation()`
  Returns the location where generated code is stored.
  `protected String`
  `getGeneratedCodePackage()`
  Returns the package name for generated code.
  `protected InputSource`
  `getGlobalWebXmlSource()`
  Identify the default web.xml to be used and obtain an input source for it.
  `protected File`
  `getHostConfigBase()`
  Returns the configuration base directory for the Host that contains this Context.
  `protected InputSource`
  `getHostWebXmlSource()`
  Identify the host web.xml to be used and obtain an input source for it.
  `protected boolean`
  `getUseGeneratedCode()`
  Returns whether the use of generated code is enabled for this context.
  `protected InputSource`
  `getWebXmlSource(String filename, boolean global)`
  Utility method to create an input source from the specified XML file.
  `protected void`
  `init()`
  Process an "init" event for this Context.
  `void`
  `lifecycleEvent(LifecycleEvent event)`
  Process events for an associated Context.
  `protected void`
  `processAnnotations(Set<WebXml> fragments, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Processes annotations for the given set of web fragments.
  `protected void`
  `processAnnotationsFile(File file, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Processes annotations for a file or directory, recursing into subdirectories.
  `protected void`
  `processAnnotationsInParallel(Set<WebXml> fragments, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Parallelized version of processAnnotationsInParallel().
  `protected void`
  `processAnnotationsJar(URL url, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Processes annotations for all .class files within a JAR.
  `protected void`
  `processAnnotationsStream(InputStream is, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Processes annotations from a class file input stream.
  `protected String[]`
  `processAnnotationsStringArray(ElementValue ev)`
  Processes an element value that represents a string array from an annotation.
  `protected void`
  `processAnnotationsUrl(URL url, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Dispatches annotation processing based on the URL protocol.
  `protected void`
  `processAnnotationsWebResource(WebResource webResource, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)`
  Processes annotations for a web resource, recursing into directories.
  `protected void`
  `processAnnotationWebFilter(String className, AnnotationEntry ae, WebXml fragment)`
  Process filter annotation and merge with existing one
  `protected Map<String,String>`
  `processAnnotationWebInitParams(ElementValue ev)`
  Processes init parameters from an annotation element value.
  `protected void`
  `processAnnotationWebServlet(String className, AnnotationEntry ae, WebXml fragment)`
  Processes a @WebServlet annotation and merges it into the web fragment.
  `protected void`
  `processClass(WebXml fragment, JavaClass clazz)`
  Processes servlet annotations from a parsed Java class.
  `protected void`
  `processClasses(WebXml webXml, Set<WebXml> orderedFragments)`
  Processes /WEB-INF/classes and JARs for annotations and @HandlesTypes matches.
  `protected void`
  `processContextConfig(Digester digester, URL contextXml, InputStream stream)`
  Process a context.xml.
  `protected Map<String,WebXml>`
  `processJarsForWebFragments(WebXml application, WebXmlParser webXmlParser)`
  Scan /WEB-INF/lib for JARs and for each one found add it and any /META-INF/web-fragment.xml to the resulting Map. web-fragment.xml files will be parsed before being added to the map.
  `protected void`
  `processResourceJARs(Set<WebXml> fragments)`
  Scan JARs that contain web-fragment.xml files that will be used to configure this application to see if they also contain static resources.
  `protected void`
  `processServletContainerInitializers()`
  Scan JARs for ServletContainerInitializer implementations.
  `void`
  `setCustomAuthenticators(Map<String, Authenticator> customAuthenticators)`
  Sets custom mappings of login methods to authenticators.
  `void`
  `setDefaultWebXml(String path)`
  Set the location of the default deployment descriptor.
  `protected void`
  `validateSecurityRoles()`
  Validate the usage of security role names in the web application deployment descriptor.
  `protected void`
  `webConfig()`
  Scan the web.xml files that apply to the web application and merge them using the rules defined in the spec.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### sm

    protected static final StringManager sm
    The string resources for this package.

  - ### DUMMY_LOGIN_CONFIG

    protected static final LoginConfig DUMMY_LOGIN_CONFIG
    Dummy login configuration used when no login config is defined but an authenticator is needed to support programmatic login.

  - ### authenticators

    protected static final Properties authenticators
    The set of Authenticators that we know how to configure. The key is the name of the implemented authentication method, and the value is the fully qualified Java class name of the corresponding Valve.

  - ### deploymentCount

    protected static long deploymentCount
    Deployment count.

  - ### hostWebXmlCache

    protected static final Map<Host, ContextConfig.DefaultWebXmlCacheEntry> hostWebXmlCache
    Cache of default web.xml fragments per Host

  - ### customAuthenticators

    protected Map<String, Authenticator> customAuthenticators
    Custom mappings of login methods to authenticators

  - ### context

    protected volatile Context context
    The Context we are associated with.

  - ### defaultWebXml

    protected String defaultWebXml
    The default web application's deployment descriptor location.

  - ### ok

    protected boolean ok
    Track any fatal errors during startup configuration processing.

  - ### originalDocBase

    protected String originalDocBase
    Original docBase.

  - ### initializerClassMap

    protected final Map<ServletContainerInitializer, Set<Class<?>>> initializerClassMap
    Map of ServletContainerInitializer to classes they expressed interest in.

  - ### typeInitializerMap

    protected final Map<Class<?>, Set<ServletContainerInitializer>> typeInitializerMap
    Map of Types to ServletContainerInitializer that are interested in those types.

  - ### handlesTypesAnnotations

    protected boolean handlesTypesAnnotations
    Flag that indicates if at least one `HandlesTypes` entry is present that represents an annotation.

  - ### handlesTypesNonAnnotations

    protected boolean handlesTypesNonAnnotations
    Flag that indicates if at least one `HandlesTypes` entry is present that represents a non-annotation.

- ## Constructor Details

  - ### ContextConfig

    public ContextConfig()
    Constructs a new ContextConfig instance.

- ## Method Details

  - ### getDefaultWebXml

    public String getDefaultWebXml()
    Obtain the location of the default deployment descriptor.
    Returns:
      The path to the default web.xml. If not absolute, it is relative to CATALINA_BASE.

  - ### setDefaultWebXml

    public void setDefaultWebXml(String path)
    Set the location of the default deployment descriptor.
    Parameters:
      `path` - The path to the default web.xml. If not absolute, it is relative to CATALINA_BASE.

  - ### setCustomAuthenticators

    public void setCustomAuthenticators(Map<String, Authenticator> customAuthenticators)
    Sets custom mappings of login methods to authenticators.
    Parameters:
      `customAuthenticators` - Custom mappings of login methods to authenticators

  - ### lifecycleEvent

    public void lifecycleEvent(LifecycleEvent event)
    Process events for an associated Context.
    Specified by:
      `lifecycleEvent` in interface `LifecycleListener`
    Parameters:
      `event` - The lifecycle event that has occurred

  - ### applicationAnnotationsConfig

    protected void applicationAnnotationsConfig()
    Process the application classes annotations, if it exists.

  - ### authenticatorConfig

    protected void authenticatorConfig()
    Set up an Authenticator automatically if required, and one has not already been configured.

  - ### createContextDigester

    protected Digester createContextDigester()
    Create (if necessary) and return a Digester configured to process the context configuration descriptor for an application.
    Returns:
      the digester for context.xml files

  - ### getGenerateCode

    protected boolean getGenerateCode()
    Returns whether code generation is enabled for this context.
    Returns:
      `true` if code generation is enabled

  - ### getUseGeneratedCode

    protected boolean getUseGeneratedCode()
    Returns whether the use of generated code is enabled for this context.
    Returns:
      `true` if the use of generated code is enabled

  - ### getGeneratedCodeLocation

    protected File getGeneratedCodeLocation()
    Returns the location where generated code is stored.
    Returns:
      the location where generated code is stored

  - ### getGeneratedCodePackage

    protected String getGeneratedCodePackage()
    Returns the package name for generated code.
    Returns:
      the package name for generated code

  - ### getContextXmlPackageName

    protected static String getContextXmlPackageName(String generatedCodePackage, Container container)
    Builds the package name for context XML generated code based on the container hierarchy.
    Parameters:
      `generatedCodePackage` - the base package name for generated code
      `container` - the container from which to derive the package name
    Returns:
      the fully qualified package name for the context XML generated code

  - ### getContextXmlJavaSource

    protected File getContextXmlJavaSource(String contextXmlPackageName, String contextXmlSimpleClassName)
    Returns the Java source file path for the given context XML class.
    Parameters:
      `contextXmlPackageName` - the package name for the context XML class
      `contextXmlSimpleClassName` - the simple class name
    Returns:
      the source file path, or `null` if the directory cannot be created

  - ### generateClassHeader

    protected void generateClassHeader(Digester digester, String packageName, String resourceName)
    Generates the header of the Java class for context XML code generation.
    Parameters:
      `digester` - the digester instance
      `packageName` - the package name for the generated class
      `resourceName` - the simple class name

  - ### generateClassFooter

    protected void generateClassFooter(Digester digester)
    Generates the footer of the Java class for context XML code generation.
    Parameters:
      `digester` - the digester instance

  - ### contextConfig

    protected void contextConfig(Digester digester)
    Process the default configuration file, if it exists.
    Parameters:
      `digester` - The digester that will be used for XML parsing

  - ### processContextConfig

    protected void processContextConfig(Digester digester, URL contextXml, InputStream stream)
    Process a context.xml.
    Parameters:
      `digester` - The digester that will be used for XML parsing
      `contextXml` - The URL to the context.xml configuration
      `stream` - The XML resource stream

  - ### fixDocBase

    protected void fixDocBase() throws IOException
    Adjust docBase.
    Throws:
      `IOException` - cannot access the context base path

  - ### antiLocking

    protected void antiLocking()
    Handles anti-locking by copying the docBase to a temporary location to prevent file locking issues on Windows.

  - ### init

    protected void init()
    Process an "init" event for this Context.

  - ### beforeStart

    protected void beforeStart()
    Process a "before start" event for this Context.

  - ### configureStart

    protected void configureStart()
    Process a "contextConfig" event for this Context.

  - ### configureStop

    protected void configureStop()
    Process a "stop" event for this Context.

  - ### destroy

    protected void destroy()
    Process a "destroy" event for this Context.

  - ### validateSecurityRoles

    protected void validateSecurityRoles()
    Validate the usage of security role names in the web application deployment descriptor. If any problems are found, issue warning messages (for backwards compatibility) and add the missing roles. (To make these problems fatal instead, simply set the `ok` instance variable to `false` as well).

  - ### getHostConfigBase

    protected File getHostConfigBase()
    Returns the configuration base directory for the Host that contains this Context.
    Returns:
      the configuration base directory, or `null` if the parent is not a Host

  - ### webConfig

    protected void webConfig()
    Scan the web.xml files that apply to the web application and merge them using the rules defined in the spec. For the global web.xml files, where there is duplicate configuration, the most specific level wins. ie an application's web.xml takes precedence over the host level or global web.xml file.

  - ### processClasses

    protected void processClasses(WebXml webXml, Set<WebXml> orderedFragments)
    Processes /WEB-INF/classes and JARs for annotations and @HandlesTypes matches.
    Parameters:
      `webXml` - the main web.xml metadata
      `orderedFragments` - the ordered set of web fragments

  - ### createWebXml

    protected WebXml createWebXml()
    Creates a new WebXml instance.
    Returns:
      a new WebXml instance

  - ### processServletContainerInitializers

    protected void processServletContainerInitializers()
    Scan JARs for ServletContainerInitializer implementations.

  - ### processResourceJARs

    protected void processResourceJARs(Set<WebXml> fragments)
    Scan JARs that contain web-fragment.xml files that will be used to configure this application to see if they also contain static resources. If static resources are found, add them to the context. Resources are added in web-fragment.xml priority order.
    Parameters:
      `fragments` - The set of fragments that will be scanned for static resources

  - ### getGlobalWebXmlSource

    protected InputSource getGlobalWebXmlSource()
    Identify the default web.xml to be used and obtain an input source for it.
    Returns:
      an input source to the default web.xml

  - ### getHostWebXmlSource

    protected InputSource getHostWebXmlSource()
    Identify the host web.xml to be used and obtain an input source for it.
    Returns:
      an input source to the default per host web.xml

  - ### getContextWebXmlSource

    protected InputSource getContextWebXmlSource()
    Identify the application web.xml to be used and obtain an input source for it.
    Returns:
      an input source to the context web.xml

  - ### getConfigBasePath

    public String getConfigBasePath()
    Returns the configuration base path for the Host that contains this Context.
    Returns:
      the configuration base path, or `null` if the parent is not a Host

  - ### getWebXmlSource

    protected InputSource getWebXmlSource(String filename, boolean global)
    Utility method to create an input source from the specified XML file.
    Parameters:
      `filename` - Name of the file (possibly with one or more leading path segments) to read
      `global` - true if processing a shared resource, false if processing a host based resource
    Returns:
      the input source

  - ### processJarsForWebFragments

    protected Map<String,WebXml> processJarsForWebFragments(WebXml application, WebXmlParser webXmlParser)
    Scan /WEB-INF/lib for JARs and for each one found add it and any /META-INF/web-fragment.xml to the resulting Map. web-fragment.xml files will be parsed before being added to the map. Every JAR will be added and `null` will be used if no web-fragment.xml was found. Any JARs known not contain fragments will be skipped.
    Parameters:
      `application` - The main web.xml metadata
      `webXmlParser` - The parser to use to process the web.xml file
    Returns:
      A map of JAR name to processed web fragment (if any)

  - ### processAnnotations

    protected void processAnnotations(Set<WebXml> fragments, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Processes annotations for the given set of web fragments.
    Parameters:
      `fragments` - the web fragments to scan
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes

  - ### processAnnotationsInParallel

    protected void processAnnotationsInParallel(Set<WebXml> fragments, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Parallelized version of processAnnotationsInParallel(). Constructs tasks, submits them as they're created, then waits for completion.
    Parameters:
      `fragments` - Set of parallelizable scans
      `handlesTypesOnly` - Important parameter for the underlying scan
      `javaClassCache` - The class cache

  - ### processAnnotationsWebResource

    protected void processAnnotationsWebResource(WebResource webResource, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Processes annotations for a web resource, recursing into directories.
    Parameters:
      `webResource` - the web resource to process
      `fragment` - the web fragment to merge annotations into
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes

  - ### processAnnotationsUrl

    protected void processAnnotationsUrl(URL url, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Dispatches annotation processing based on the URL protocol.
    Parameters:
      `url` - the URL to process
      `fragment` - the web fragment to merge annotations into
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes

  - ### processAnnotationsJar

    protected void processAnnotationsJar(URL url, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Processes annotations for all .class files within a JAR.
    Parameters:
      `url` - the URL of the JAR
      `fragment` - the web fragment to merge annotations into
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes

  - ### processAnnotationsFile

    protected void processAnnotationsFile(File file, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    Processes annotations for a file or directory, recursing into subdirectories.
    Parameters:
      `file` - the file or directory to process
      `fragment` - the web fragment to merge annotations into
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes

  - ### processAnnotationsStream

    protected void processAnnotationsStream(InputStream is, WebXml fragment, boolean handlesTypesOnly, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache) throws ClassFormatException, IOException
    Processes annotations from a class file input stream.
    Parameters:
      `is` - the input stream for the class file
      `fragment` - the web fragment to merge annotations into
      `handlesTypesOnly` - whether to only process @HandlesTypes matches
      `javaClassCache` - the class cache for tracking processed classes
    Throws:
      `ClassFormatException` - if the class file is malformed
      `IOException` - if an I/O error occurs

  - ### processClass

    protected void processClass(WebXml fragment, JavaClass clazz)
    Processes servlet annotations from a parsed Java class.
    Parameters:
      `fragment` - the web fragment to merge annotations into
      `clazz` - the parsed Java class

  - ### checkHandlesTypes

    protected void checkHandlesTypes(JavaClass javaClass, Map<String, ContextConfig.JavaClassCacheEntry> javaClassCache)
    For classes packaged with the web application, the class and each super class needs to be checked for a match with `HandlesTypes` or for an annotation that matches `HandlesTypes`.
    Parameters:
      `javaClass` - the class to check
      `javaClassCache` - a class cache

  - ### processAnnotationWebServlet

    protected void processAnnotationWebServlet(String className, AnnotationEntry ae, WebXml fragment)
    Processes a @WebServlet annotation and merges it into the web fragment.
    Parameters:
      `className` - the class name containing the annotation
      `ae` - the annotation entry
      `fragment` - the web fragment to merge the servlet definition into

  - ### processAnnotationWebFilter

    protected void processAnnotationWebFilter(String className, AnnotationEntry ae, WebXml fragment)
    Process filter annotation and merge with existing one
    Parameters:
      `className` - The filter class name
      `ae` - The filter annotation
      `fragment` - The corresponding fragment

  - ### processAnnotationsStringArray

    protected String[] processAnnotationsStringArray(ElementValue ev)
    Processes an element value that represents a string array from an annotation.
    Parameters:
      `ev` - the element value to process
    Returns:
      the resulting string array

  - ### processAnnotationWebInitParams

    protected Map<String,String> processAnnotationWebInitParams(ElementValue ev)
    Processes init parameters from an annotation element value.
    Parameters:
      `ev` - the element value containing init parameters
    Returns:
      a map of init parameter names to values