StandardHost (Apache Tomcat 8.5.57 API Documentation)

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.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, children, cluster, listeners, logger, logName, name, parent, parentClassLoader, pipeline, sm, startChildren, startStopExecutor, support`

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

      `mserver`

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

      `ADD_ALIAS_EVENT, REMOVE_ALIAS_EVENT`

    - ### 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.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 and Description
    `StandardHost()` Create a new StandardHost component with the default basic Valve.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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()` Return the application root for this Host.
    `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` | `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` | `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`

    - ### 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()

      Return the application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
      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)

      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

    - #### getXmlBase

          public String getXmlBase()

      (
      Specified by:
        `getXmlBase` in interface `Host`
      Returns:
        the XML root for this Host. This can be an absolute pathname, a relative pathname, or a URL. 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, a relative pathname, or a URL. 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`

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.