ContextConfig (Apache Tomcat 9.0.68 API Documentation)

Package org.apache.catalina.startup

## Class ContextConfig

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

- All Implemented Interfaces:
    `LifecycleListener`

      public class ContextConfig
      extends java.lang.Object
      implements LifecycleListener

  Startup event listener for a Context that configures the properties of that Context, and the associated defined servlets.
  Author:
    Craig R. McClanahan

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `ContextConfig.ContextXml` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static java.util.Properties` | `authenticators` | The set of Authenticators that we know how to configure.
    `protected Context` | `context` | The Context we are associated with.
    `protected java.util.Map<java.lang.String,​Authenticator>` | `customAuthenticators` | Custom mappings of login methods to authenticators
    `protected java.lang.String` | `defaultWebXml` | The default web application's deployment descriptor location.
    `protected static long` | `deploymentCount` | Deployment count.
    `protected static LoginConfig` | `DUMMY_LOGIN_CONFIG` |
    `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 java.util.Map<Host,​org.apache.catalina.startup.ContextConfig.DefaultWebXmlCacheEntry>` | `hostWebXmlCache` | Cache of default web.xml fragments per Host
    `protected java.util.Map<ServletContainerInitializer,​java.util.Set<java.lang.Class<?>>>` | `initializerClassMap` | Map of ServletContainerInitializer to classes they expressed interest in.
    `protected boolean` | `ok` | Track any fatal errors during startup configuration processing.
    `protected java.lang.String` | `originalDocBase` | Original docBase.
    `protected static StringManager` | `sm` | The string resources for this package.
    `protected java.util.Map<java.lang.Class<?>,​java.util.Set<ServletContainerInitializer>>` | `typeInitializerMap` | Map of Types to ServletContainerInitializer that are interested in those types.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ContextConfig()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `antiLocking()` |
    `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, java.util.Map<java.lang.String,​org.apache.catalina.startup.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()` |
    `protected void` | `destroy()` | Process a "destroy" event for this Context.
    `protected void` | `fixDocBase()` | Adjust docBase.
    `protected void` | `generateClassFooter​(Digester digester)` |
    `protected void` | `generateClassHeader​(Digester digester, java.lang.String packageName, java.lang.String resourceName)` |
    `java.lang.String` | `getConfigBasePath()` |
    `protected org.xml.sax.InputSource` | `getContextWebXmlSource()` | Identify the application web.xml to be used and obtain an input source for it.
    `protected java.io.File` | `getContextXmlJavaSource​(java.lang.String contextXmlPackageName, java.lang.String contextXmlSimpleClassName)` |
    `protected static java.lang.String` | `getContextXmlPackageName​(java.lang.String generatedCodePackage, Container container)` |
    `java.lang.String` | `getDefaultWebXml()` | Obtain the location of the default deployment descriptor.
    `protected boolean` | `getGenerateCode()` |
    `protected java.io.File` | `getGeneratedCodeLocation()` |
    `protected java.lang.String` | `getGeneratedCodePackage()` |
    `protected org.xml.sax.InputSource` | `getGlobalWebXmlSource()` | Identify the default web.xml to be used and obtain an input source for it.
    `protected java.io.File` | `getHostConfigBase()` |
    `protected org.xml.sax.InputSource` | `getHostWebXmlSource()` | Identify the host web.xml to be used and obtain an input source for it.
    `protected boolean` | `getUseGeneratedCode()` |
    `protected org.xml.sax.InputSource` | `getWebXmlSource​(java.lang.String filename, boolean global)` | Utility method to create an input source from the specified XML file.
    `protected void` | `init()` | Process a "init" event for this Context.
    `void` | `lifecycleEvent​(LifecycleEvent event)` | Process events for an associated Context.
    `protected void` | `processAnnotations​(java.util.Set<WebXml> fragments, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected void` | `processAnnotationsFile​(java.io.File file, WebXml fragment, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected void` | `processAnnotationsInParallel​(java.util.Set<WebXml> fragments, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` | Parallelized version of processAnnotationsInParallel().
    `protected void` | `processAnnotationsJar​(java.net.URL url, WebXml fragment, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected void` | `processAnnotationsStream​(java.io.InputStream is, WebXml fragment, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected java.lang.String[]` | `processAnnotationsStringArray​(ElementValue ev)` |
    `protected void` | `processAnnotationsUrl​(java.net.URL url, WebXml fragment, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected void` | `processAnnotationsWebResource​(WebResource webResource, WebXml fragment, boolean handlesTypesOnly, java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)` |
    `protected void` | `processAnnotationWebFilter​(java.lang.String className, AnnotationEntry ae, WebXml fragment)` | process filter annotation and merge with existing one!
    `protected java.util.Map<java.lang.String,​java.lang.String>` | `processAnnotationWebInitParams​(ElementValue ev)` |
    `protected void` | `processAnnotationWebServlet​(java.lang.String className, AnnotationEntry ae, WebXml fragment)` |
    `protected void` | `processClass​(WebXml fragment, JavaClass clazz)` |
    `protected void` | `processClasses​(WebXml webXml, java.util.Set<WebXml> orderedFragments)` |
    `protected void` | `processContextConfig​(Digester digester, java.net.URL contextXml, java.io.InputStream stream)` | Process a context.xml.
    `protected java.util.Map<java.lang.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​(java.util.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​(java.util.Map<java.lang.String,​Authenticator> customAuthenticators)` | Sets custom mappings of login methods to authenticators.
    `void` | `setDefaultWebXml​(java.lang.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 java.lang.Object

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

- - ### Field Detail

    - #### sm

          protected static final StringManager sm

      The string resources for this package.

    - #### DUMMY_LOGIN_CONFIG

          protected static final LoginConfig DUMMY_LOGIN_CONFIG

    - #### authenticators

          protected static final java.util.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 java.util.Map<Host,​org.apache.catalina.startup.ContextConfig.DefaultWebXmlCacheEntry> hostWebXmlCache

      Cache of default web.xml fragments per Host

    - #### customAuthenticators

          protected java.util.Map<java.lang.String,​Authenticator> customAuthenticators

      Custom mappings of login methods to authenticators

    - #### context

          protected volatile Context context

      The Context we are associated with.

    - #### defaultWebXml

          protected java.lang.String defaultWebXml

      The default web application's deployment descriptor location.

    - #### ok

          protected boolean ok

      Track any fatal errors during startup configuration processing.

    - #### originalDocBase

          protected java.lang.String originalDocBase

      Original docBase.

    - #### initializerClassMap

          protected final java.util.Map<ServletContainerInitializer,​java.util.Set<java.lang.Class<?>>> initializerClassMap

      Map of ServletContainerInitializer to classes they expressed interest in.

    - #### typeInitializerMap

          protected final java.util.Map<java.lang.Class<?>,​java.util.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 Detail

    - #### ContextConfig

          public ContextConfig()

  - ### Method Detail

    - #### getDefaultWebXml

          public java.lang.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​(java.lang.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​(java.util.Map<java.lang.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()

    - #### getUseGeneratedCode

          protected boolean getUseGeneratedCode()

    - #### getGeneratedCodeLocation

          protected java.io.File getGeneratedCodeLocation()

    - #### getGeneratedCodePackage

          protected java.lang.String getGeneratedCodePackage()

    - #### getContextXmlPackageName

          protected static java.lang.String getContextXmlPackageName​(java.lang.String generatedCodePackage,
                                                                     Container container)

    - #### getContextXmlJavaSource

          protected java.io.File getContextXmlJavaSource​(java.lang.String contextXmlPackageName,
                                                         java.lang.String contextXmlSimpleClassName)

    - #### generateClassHeader

          protected void generateClassHeader​(Digester digester,
                                             java.lang.String packageName,
                                             java.lang.String resourceName)

    - #### generateClassFooter

          protected void generateClassFooter​(Digester digester)

    - #### 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,
                                              java.net.URL contextXml,
                                              java.io.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 java.io.IOException

      Adjust docBase.
      Throws:
        `java.io.IOException` - cannot access the context base path

    - #### antiLocking

          protected void antiLocking()

    - #### init

          protected void init()

      Process a "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 java.io.File getHostConfigBase()

    - #### 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,
                                        java.util.Set<WebXml> orderedFragments)

    - #### createWebXml

          protected WebXml createWebXml()

    - #### processServletContainerInitializers

          protected void processServletContainerInitializers()

      Scan JARs for ServletContainerInitializer implementations.

    - #### processResourceJARs

          protected void processResourceJARs​(java.util.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 org.xml.sax.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 org.xml.sax.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 org.xml.sax.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 java.lang.String getConfigBasePath()

    - #### getWebXmlSource

          protected org.xml.sax.InputSource getWebXmlSource​(java.lang.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 java.util.Map<java.lang.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​(java.util.Set<WebXml> fragments,
                                            boolean handlesTypesOnly,
                                            java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)

    - #### processAnnotationsInParallel

          protected void processAnnotationsInParallel​(java.util.Set<WebXml> fragments,
                                                      boolean handlesTypesOnly,
                                                      java.util.Map<java.lang.String,​org.apache.catalina.startup.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,
                                                       java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)

    - #### processAnnotationsUrl

          protected void processAnnotationsUrl​(java.net.URL url,
                                               WebXml fragment,
                                               boolean handlesTypesOnly,
                                               java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)

    - #### processAnnotationsJar

          protected void processAnnotationsJar​(java.net.URL url,
                                               WebXml fragment,
                                               boolean handlesTypesOnly,
                                               java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)

    - #### processAnnotationsFile

          protected void processAnnotationsFile​(java.io.File file,
                                                WebXml fragment,
                                                boolean handlesTypesOnly,
                                                java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)

    - #### processAnnotationsStream

          protected void processAnnotationsStream​(java.io.InputStream is,
                                                  WebXml fragment,
                                                  boolean handlesTypesOnly,
                                                  java.util.Map<java.lang.String,​org.apache.catalina.startup.ContextConfig.JavaClassCacheEntry> javaClassCache)
                                           throws ClassFormatException,
                                                  java.io.IOException

      Throws:
        `ClassFormatException`
        `java.io.IOException`

    - #### processClass

          protected void processClass​(WebXml fragment,
                                      JavaClass clazz)

    - #### checkHandlesTypes

          protected void checkHandlesTypes​(JavaClass javaClass,
                                           java.util.Map<java.lang.String,​org.apache.catalina.startup.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​(java.lang.String className,
                                                     AnnotationEntry ae,
                                                     WebXml fragment)

    - #### processAnnotationWebFilter

          protected void processAnnotationWebFilter​(java.lang.String className,
                                                    AnnotationEntry ae,
                                                    WebXml fragment)

      process filter annotation and merge with existing one! FIXME: refactoring method too long and has redundant subroutines with processAnnotationWebServlet!
      Parameters:
        `className` - The filter class name
        `ae` - The filter annotation
        `fragment` - The corresponding fragment

    - #### processAnnotationsStringArray

          protected java.lang.String[] processAnnotationsStringArray​(ElementValue ev)

    - #### processAnnotationWebInitParams

          protected java.util.Map<java.lang.String,​java.lang.String> processAnnotationWebInitParams​(ElementValue ev)