StandardHost (Apache Tomcat 10.1.7 API Documentation)

Package org.apache.catalina.core

## Class StandardHost

- java.lang.Object
- - org.apache.catalina.util.LifecycleBase
  - - org.apache.catalina.util.LifecycleMBeanBase
    - - org.apache.catalina.core.ContainerBase
      - - org.apache.catalina.core.StandardHost

- All Implemented Interfaces:
    `MBeanRegistration`, `Container`, `Host`, `JmxEnabled`, `Lifecycle`

      public class StandardHost
      extends ContainerBase
      implements Host

  Standard implementation of the Host interface. Each child container must be a Context implementation to process the requests directed to a particular web application.
  Author:
    Craig R. McClanahan, Remy Maucherat

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.catalina.core.ContainerBase

      `ContainerBase.ContainerBackgroundProcessor, ContainerBase.ContainerBackgroundProcessorMonitor, ContainerBase.PrivilegedAddChild`

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    - ### Fields inherited from class org.apache.catalina.core.ContainerBase

      `accessLog, backgroundProcessorDelay, backgroundProcessorFuture, children, cluster, listeners, logger, logName, monitorFuture, name, parent, parentClassLoader, pipeline, sm, startChildren, startStopExecutor, support`

    - ### Fields inherited from interface org.apache.catalina.Container

      `ADD_CHILD_EVENT, ADD_VALVE_EVENT, REMOVE_CHILD_EVENT, REMOVE_VALVE_EVENT`

    - ### Fields inherited from interface org.apache.catalina.Host

      `ADD_ALIAS_EVENT, REMOVE_ALIAS_EVENT`

    - ### Fields inherited from interface org.apache.catalina.Lifecycle

      `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `StandardHost()` | Create a new StandardHost component with the default basic Valve.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addAlias​(String alias)` | Add an alias name that should be mapped to this same Host.
    `void` | `addChild​(Container child)` | Add a child Container, only if the proposed child is an implementation of Context.
    `String[]` | `findAliases()` |
    `String[]` | `findReloadedContextMemoryLeaks()` | Attempt to identify the contexts that have a class loader memory leak.
    `String[]` | `getAliases()` |
    `String` | `getAppBase()` |
    `File` | `getAppBaseFile()` |
    `boolean` | `getAutoDeploy()` |
    `File` | `getConfigBaseFile()` | (
    `String` | `getConfigClass()` |
    `String` | `getContextClass()` |
    `boolean` | `getCreateDirs()` | Returns `true` if the Host will attempt to create directories for appBase and xmlBase unless they already exist.
    `String` | `getDeployIgnore()` |
    `Pattern` | `getDeployIgnorePattern()` |
    `boolean` | `getDeployOnStartup()` |
    `String` | `getErrorReportValveClass()` |
    `String` | `getLegacyAppBase()` |
    `File` | `getLegacyAppBaseFile()` |
    `String` | `getName()` | Return a name string (suitable for use by humans) that describes this Container.
    `protected String` | `getObjectNameKeyProperties()` | Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
    `ExecutorService` | `getStartStopExecutor()` |
    `boolean` | `getUndeployOldVersions()` |
    `String[]` | `getValveNames()` |
    `String` | `getWorkDir()` |
    `String` | `getXmlBase()` | (
    `boolean` | `isCopyXML()` |
    `boolean` | `isDeployXML()` |
    `boolean` | `isFailCtxIfServletStartFails()` |
    `boolean` | `isUnpackWARs()` |
    `void` | `removeAlias​(String alias)` | Remove the specified alias name from the aliases for this Host.
    `void` | `setAppBase​(String appBase)` | Set the application root for this Host.
    `void` | `setAutoDeploy​(boolean autoDeploy)` | Set the auto deploy flag value for this host.
    `void` | `setConfigClass​(String configClass)` | Set the Java class name of the context configuration class for new web applications.
    `void` | `setContextClass​(String contextClass)` | Set the Java class name of the Context implementation class for new web applications.
    `void` | `setCopyXML​(boolean copyXML)` | Set the copy XML config file flag for this component.
    `void` | `setCreateDirs​(boolean createDirs)` | Set to `true` if the Host should attempt to create directories for xmlBase and appBase upon startup
    `void` | `setDeployIgnore​(String deployIgnore)` | Set the regular expression that defines the files and directories in the host's `getAppBase()` that will be ignored by the automatic deployment process.
    `void` | `setDeployOnStartup​(boolean deployOnStartup)` | Set the deploy on startup flag value for this host.
    `void` | `setDeployXML​(boolean deployXML)` | Deploy XML Context config files flag mutator.
    `void` | `setErrorReportValveClass​(String errorReportValveClass)` | Set the Java class name of the error report valve class for new web applications.
    `void` | `setFailCtxIfServletStartFails​(boolean failCtxIfServletStartFails)` | Change the behavior of Servlet startup errors on web application starts.
    `void` | `setLegacyAppBase​(String legacyAppBase)` | Set the legacy (Java EE) application root for this Host.
    `void` | `setName​(String name)` | Set the canonical, fully qualified, name of the virtual host this Container represents.
    `void` | `setUndeployOldVersions​(boolean undeployOldVersions)` | Set to `true` if the Host should automatically undeploy old versions of applications deployed using parallel deployment.
    `void` | `setUnpackWARs​(boolean unpackWARs)` | Unpack WARs flag mutator.
    `void` | `setWorkDir​(String workDir)` | Set host work directory base.
    `void` | `setXmlBase​(String xmlBase)` | (Set the Xml root for this Host.
    `protected void` | `startInternal()` | Start this component and implement the requirements of `LifecycleBase.startInternal()`.

    - ### Methods inherited from class org.apache.catalina.core.ContainerBase

      `addContainerListener, addPropertyChangeListener, addValve, backgroundProcess, destroyInternal, findChild, findChildren, findContainerListeners, fireContainerEvent, getAccessLog, getBackgroundProcessorDelay, getCatalinaBase, getCatalinaHome, getChildren, getCluster, getClusterInternal, getDomainInternal, getLogger, getLogName, getMBeanKeyProperties, getParent, getParentClassLoader, getPipeline, getRealm, getRealmInternal, getStartChildren, getStartStopThreads, initInternal, logAccess, removeChild, removeContainerListener, removePropertyChangeListener, setBackgroundProcessorDelay, setCluster, setParent, setParentClassLoader, setRealm, setStartChildren, setStartStopThreads, stopInternal, threadStart, threadStop, toString`

    - ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

    - ### Methods inherited from class org.apache.catalina.util.LifecycleBase

      `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.catalina.Container

      `addContainerListener, addPropertyChangeListener, backgroundProcess, findChild, findChildren, findContainerListeners, fireContainerEvent, getAccessLog, getBackgroundProcessorDelay, getCatalinaBase, getCatalinaHome, getCluster, getDomain, getLogger, getLogName, getMBeanKeyProperties, getObjectName, getParent, getParentClassLoader, getPipeline, getRealm, getStartStopThreads, logAccess, removeChild, removeContainerListener, removePropertyChangeListener, setBackgroundProcessorDelay, setCluster, setParent, setParentClassLoader, setRealm, setStartStopThreads`

    - ### Methods inherited from interface org.apache.catalina.Lifecycle

      `addLifecycleListener, destroy, findLifecycleListeners, getState, getStateName, init, removeLifecycleListener, start, stop`

- - ### Constructor Detail

    - #### StandardHost

          public StandardHost()

      Create a new StandardHost component with the default basic Valve.

  - ### Method Detail

    - #### getUndeployOldVersions

          public boolean getUndeployOldVersions()

      Specified by:
        `getUndeployOldVersions` in interface `Host`
      Returns:
        `true` of the Host is configured to automatically undeploy old versions of applications deployed using parallel deployment. This only takes effect is `Host.getAutoDeploy()` also returns `true`.

    - #### setUndeployOldVersions

          public void setUndeployOldVersions​(boolean undeployOldVersions)

      Description copied from interface: `Host`
      Set to `true` if the Host should automatically undeploy old versions of applications deployed using parallel deployment. This only takes effect if `Host.getAutoDeploy()` returns `true`.
      Specified by:
        `setUndeployOldVersions` in interface `Host`
      Parameters:
        `undeployOldVersions` - The new value for this flag

    - #### getStartStopExecutor

          public ExecutorService getStartStopExecutor()

      Specified by:
        `getStartStopExecutor` in interface `Host`
      Returns:
        the executor that is used for starting and stopping contexts. This is primarily for use by components deploying contexts that want to do this in a multi-threaded manner.

    - #### getAppBase

          public String getAppBase()

      Specified by:
        `getAppBase` in interface `Host`
      Returns:
        the application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.

    - #### getAppBaseFile

          public File getAppBaseFile()

      Specified by:
        `getAppBaseFile` in interface `Host`
      Returns:
        an absolute `File` for the appBase of this Host. The file will be canonical if possible. There is no guarantee that that the appBase exists.

    - #### setAppBase

          public void setAppBase​(String appBase)

      Description copied from interface: `Host`
      Set the application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
      Specified by:
        `setAppBase` in interface `Host`
      Parameters:
        `appBase` - The new application root

    - #### getLegacyAppBase

          public String getLegacyAppBase()

      Specified by:
        `getLegacyAppBase` in interface `Host`
      Returns:
        the legacy (Java EE) application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.

    - #### getLegacyAppBaseFile

          public File getLegacyAppBaseFile()

      Specified by:
        `getLegacyAppBaseFile` in interface `Host`
      Returns:
        an absolute `File` for the legacy (Java EE) appBase of this Host. The file will be canonical if possible. There is no guarantee that that the appBase exists.

    - #### setLegacyAppBase

          public void setLegacyAppBase​(String legacyAppBase)

      Description copied from interface: `Host`
      Set the legacy (Java EE) application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
      Specified by:
        `setLegacyAppBase` in interface `Host`
      Parameters:
        `legacyAppBase` - The new legacy application root

    - #### getXmlBase

          public String getXmlBase()

      (
      Specified by:
        `getXmlBase` in interface `Host`
      Returns:
        the XML root for this Host. This can be an absolute pathname or a relative pathname. If null, the base path defaults to ${catalina.base}/conf/<engine name>/<host name> directory

    - #### setXmlBase

          public void setXmlBase​(String xmlBase)

      (Set the Xml root for this Host. This can be an absolute pathname or a relative pathname. If null, the base path defaults to ${catalina.base}/conf/<engine name>/<host name> directory
      Specified by:
        `setXmlBase` in interface `Host`
      Parameters:
        `xmlBase` - The new XML root

    - #### getConfigBaseFile

          public File getConfigBaseFile()

      (
      Specified by:
        `getConfigBaseFile` in interface `Host`
      Returns:
        a default configuration path of this Host. The file will be canonical if possible.

    - #### getCreateDirs

          public boolean getCreateDirs()

      Description copied from interface: `Host`
      Returns `true` if the Host will attempt to create directories for appBase and xmlBase unless they already exist.
      Specified by:
        `getCreateDirs` in interface `Host`
      Returns:
        `true` if the Host will attempt to create directories for appBase and xmlBase unless they already exist.

    - #### setCreateDirs

          public void setCreateDirs​(boolean createDirs)

      Set to `true` if the Host should attempt to create directories for xmlBase and appBase upon startup
      Specified by:
        `setCreateDirs` in interface `Host`
      Parameters:
        `createDirs` - the new flag value

    - #### getAutoDeploy

          public boolean getAutoDeploy()

      Specified by:
        `getAutoDeploy` in interface `Host`
      Returns:
        the value of the auto deploy flag. If true, it indicates that this host's child webapps will be dynamically deployed.

    - #### setAutoDeploy

          public void setAutoDeploy​(boolean autoDeploy)

      Set the auto deploy flag value for this host.
      Specified by:
        `setAutoDeploy` in interface `Host`
      Parameters:
        `autoDeploy` - The new auto deploy flag

    - #### getConfigClass

          public String getConfigClass()

      Specified by:
        `getConfigClass` in interface `Host`
      Returns:
        the Java class name of the context configuration class for new web applications.

    - #### setConfigClass

          public void setConfigClass​(String configClass)

      Set the Java class name of the context configuration class for new web applications.
      Specified by:
        `setConfigClass` in interface `Host`
      Parameters:
        `configClass` - The new context configuration class

    - #### getContextClass

          public String getContextClass()

      Returns:
        the Java class name of the Context implementation class for new web applications.

    - #### setContextClass

          public void setContextClass​(String contextClass)

      Set the Java class name of the Context implementation class for new web applications.
      Parameters:
        `contextClass` - The new context implementation class

    - #### getDeployOnStartup

          public boolean getDeployOnStartup()

      Specified by:
        `getDeployOnStartup` in interface `Host`
      Returns:
        the value of the deploy on startup flag. If `true`, it indicates that this host's child webapps should be discovered and automatically deployed at startup time.

    - #### setDeployOnStartup

          public void setDeployOnStartup​(boolean deployOnStartup)

      Set the deploy on startup flag value for this host.
      Specified by:
        `setDeployOnStartup` in interface `Host`
      Parameters:
        `deployOnStartup` - The new deploy on startup flag

    - #### isDeployXML

          public boolean isDeployXML()

      Returns:
        `true` if XML context descriptors should be deployed.

    - #### setDeployXML

          public void setDeployXML​(boolean deployXML)

      Deploy XML Context config files flag mutator.
      Parameters:
        `deployXML` - `true` if context descriptors should be deployed

    - #### isCopyXML

          public boolean isCopyXML()

      Returns:
        the copy XML config file flag for this component.

    - #### setCopyXML

          public void setCopyXML​(boolean copyXML)

      Set the copy XML config file flag for this component.
      Parameters:
        `copyXML` - The new copy XML flag

    - #### getErrorReportValveClass

          public String getErrorReportValveClass()

      Returns:
        the Java class name of the error report valve class for new web applications.

    - #### setErrorReportValveClass

          public void setErrorReportValveClass​(String errorReportValveClass)

      Set the Java class name of the error report valve class for new web applications.
      Parameters:
        `errorReportValveClass` - The new error report valve class

    - #### getName

          public String getName()

      Description copied from class: `ContainerBase`
      Return a name string (suitable for use by humans) that describes this Container. Within the set of child containers belonging to a particular parent, Container names must be unique.
      Specified by:
        `getName` in interface `Container`
      Overrides:
        `getName` in class `ContainerBase`
      Returns:
        the canonical, fully qualified, name of the virtual host this Container represents.

    - #### setName

          public void setName​(String name)

      Set the canonical, fully qualified, name of the virtual host this Container represents.
      Specified by:
        `setName` in interface `Container`
      Overrides:
        `setName` in class `ContainerBase`
      Parameters:
        `name` - Virtual host name
      Throws:
        `IllegalArgumentException` - if name is null

    - #### isUnpackWARs

          public boolean isUnpackWARs()

      Returns:
        `true` if WARs should be unpacked on deployment.

    - #### setUnpackWARs

          public void setUnpackWARs​(boolean unpackWARs)

      Unpack WARs flag mutator.
      Parameters:
        `unpackWARs` - `true` to unpack WARs on deployment

    - #### getWorkDir

          public String getWorkDir()

      Returns:
        host work directory base.

    - #### setWorkDir

          public void setWorkDir​(String workDir)

      Set host work directory base.
      Parameters:
        `workDir` - the new base work folder for this host

    - #### getDeployIgnore

          public String getDeployIgnore()

      Specified by:
        `getDeployIgnore` in interface `Host`
      Returns:
        the regular expression that defines the files and directories in the host's `getAppBase()` that will be ignored by the automatic deployment process.

    - #### getDeployIgnorePattern

          public Pattern getDeployIgnorePattern()

      Specified by:
        `getDeployIgnorePattern` in interface `Host`
      Returns:
        the compiled regular expression that defines the files and directories in the host's `getAppBase()` that will be ignored by the automatic deployment process.

    - #### setDeployIgnore

          public void setDeployIgnore​(String deployIgnore)

      Set the regular expression that defines the files and directories in the host's `getAppBase()` that will be ignored by the automatic deployment process.
      Specified by:
        `setDeployIgnore` in interface `Host`
      Parameters:
        `deployIgnore` - the regexp

    - #### isFailCtxIfServletStartFails

          public boolean isFailCtxIfServletStartFails()

      Returns:
        `true` if a webapp start should fail if a Servlet startup fails

    - #### setFailCtxIfServletStartFails

          public void setFailCtxIfServletStartFails​(boolean failCtxIfServletStartFails)

      Change the behavior of Servlet startup errors on web application starts.
      Parameters:
        `failCtxIfServletStartFails` - `false` to ignore errors on Servlets which are stated when the web application starts

    - #### addAlias

          public void addAlias​(String alias)

      Add an alias name that should be mapped to this same Host.
      Specified by:
        `addAlias` in interface `Host`
      Parameters:
        `alias` - The alias to be added

    - #### addChild

          public void addChild​(Container child)

      Add a child Container, only if the proposed child is an implementation of Context.
      Specified by:
        `addChild` in interface `Container`
      Overrides:
        `addChild` in class `ContainerBase`
      Parameters:
        `child` - Child container to be added

    - #### findReloadedContextMemoryLeaks

          public String[] findReloadedContextMemoryLeaks()

      Attempt to identify the contexts that have a class loader memory leak. This is usually triggered on context reload. Note: This method attempts to force a full garbage collection. This should be used with extreme caution on a production system.
      Returns:
        a list of possibly leaking contexts

    - #### findAliases

          public String[] findAliases()

      Specified by:
        `findAliases` in interface `Host`
      Returns:
        the set of alias names for this Host. If none are defined, a zero length array is returned.

    - #### removeAlias

          public void removeAlias​(String alias)

      Remove the specified alias name from the aliases for this Host.
      Specified by:
        `removeAlias` in interface `Host`
      Parameters:
        `alias` - Alias name to be removed

    - #### startInternal

          protected void startInternal()
                                throws LifecycleException

      Start this component and implement the requirements of `LifecycleBase.startInternal()`.
      Overrides:
        `startInternal` in class `ContainerBase`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### getValveNames

          public String[] getValveNames()
                                 throws Exception

      Returns:
        the MBean Names of the Valves associated with this Host
      Throws:
        `Exception` - if an MBean cannot be created or registered

    - #### getAliases

          public String[] getAliases()

    - #### getObjectNameKeyProperties

          protected String getObjectNameKeyProperties()

      Description copied from class: `LifecycleMBeanBase`
      Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
      Specified by:
        `getObjectNameKeyProperties` in class `LifecycleMBeanBase`
      Returns:
        The string representation of the key properties component of the desired `ObjectName`