StandardHost (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.catalina.core, class: StandardHost

# 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.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class ContainerBase

  `ContainerBase.ContainerBackgroundProcessor, ContainerBase.ContainerBackgroundProcessorMonitor`

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  ### Fields inherited from class ContainerBase

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

  ### Fields inherited from interface Container

  `ADD_CHILD_EVENT, ADD_VALVE_EVENT, REMOVE_CHILD_EVENT, REMOVE_VALVE_EVENT`

  ### Fields inherited from interface Host

  `ADD_ALIAS_EVENT, REMOVE_ALIAS_EVENT`

  ### Fields inherited from interface 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

  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 new child Container to those associated with this Container, if supported.
  `String[]`
  `findAliases()`
  Get the array of alias names for this Host.
  `String[]`
  `findReloadedContextMemoryLeaks()`
  Attempt to identify the contexts that have a class loader memory leak.
  `String[]`
  `getAliases()`
  Returns the array of aliases for this host.
  `String`
  `getAppBase()`
  Get the application root for this Host.
  `File`
  `getAppBaseFile()`
  Get an absolute `File` for the appBase of this Host.
  `boolean`
  `getAutoDeploy()`
  Get the value of the auto deploy flag.
  `File`
  `getConfigBaseFile()`
  Get the default configuration path of this Host.
  `String`
  `getConfigClass()`
  Get the Java class name of the context configuration class for new web applications.
  `String`
  `getContextClass()`
  Returns the Java class name of the Context implementation class for new web applications.
  `boolean`
  `getCreateDirs()`
  Returns `true` if the Host will attempt to create directories for appBase and xmlBase unless they already exist.
  `String`
  `getDeployIgnore()`
  Get the regular expression that defines the files and directories in the host's appBase that will be ignored by the automatic deployment process.
  `Pattern`
  `getDeployIgnorePattern()`
  Get the compiled regular expression that defines the files and directories in the host's appBase that will be ignored by the automatic deployment process.
  `boolean`
  `getDeployOnStartup()`
  Get the value of the deploy on startup flag.
  `String`
  `getErrorReportValveClass()`
  Returns the Java class name of the error report valve class for new web applications.
  `String`
  `getLegacyAppBase()`
  Get the legacy (Java EE) application root for this Host.
  `File`
  `getLegacyAppBaseFile()`
  Get an absolute `File` for the legacy (Java EE) appBase of this Host.
  `String`
  `getName()`
  Return a name string (suitable for use by humans) that describes this Container.
  `protected String`
  `getObjectNameKeyProperties()`
  Allow subclasses to specify the key properties component of the `ObjectName` that will be used to register this component.
  `ExecutorService`
  `getStartStopExecutor()`
  Get the executor that is used for starting and stopping contexts.
  `boolean`
  `getUndeployOldVersions()`
  Get whether the Host is configured to automatically undeploy old versions of applications deployed using parallel deployment.
  `String[]`
  `getValveNames()`
  Returns the MBean Names of the Valves associated with this Host.
  `String`
  `getWorkDir()`
  Returns the host work directory base.
  `String`
  `getXmlBase()`
  Get the XML root for this Host.
  `boolean`
  `isCopyXML()`
  Returns the copy XML config file flag for this component.
  `boolean`
  `isDeployXML()`
  Returns whether XML context descriptors should be deployed.
  `boolean`
  `isFailCtxIfServletStartFails()`
  Returns whether a webapp start should fail if a Servlet startup fails.
  `boolean`
  `isUnpackWARs()`
  Returns whether WARs should be unpacked on deployment.
  `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)`
  Should the Host 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 appBase 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 a name string (suitable for use by humans) that describes this Container.
  `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 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, logAccess, removeChild, removeContainerListener, removePropertyChangeListener, setBackgroundProcessorDelay, setCluster, setParent, setParentClassLoader, setRealm, setStartChildren, setStartStopThreads, stopInternal, threadStart, threadStop, toString`

  ### Methods inherited from class LifecycleMBeanBase

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

  ### Methods inherited from class LifecycleBase

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

  ### Methods inherited from class Object

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

  ### Methods inherited from interface 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 Lifecycle

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

- ## Constructor Details

  - ### StandardHost

    public StandardHost()
    Create a new StandardHost component with the default basic Valve.

- ## Method Details

  - ### getUndeployOldVersions

    public boolean getUndeployOldVersions()
    Description copied from interface: `Host`
    Get whether the Host is configured to automatically undeploy old versions of applications deployed using parallel deployment. This only takes effect if `Host.getAutoDeploy()` also returns `true`.
    Specified by:
      `getUndeployOldVersions` in interface `Host`
    Returns:
      the undeploy old versions flag

  - ### 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()
    Description copied from interface: `Host`
    Get 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 multithreaded manner.
    Specified by:
      `getStartStopExecutor` in interface `Host`
    Returns:
      the start/stop executor

  - ### getAppBase

    public String getAppBase()
    Description copied from interface: `Host`
    Get 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

  - ### getAppBaseFile

    public File getAppBaseFile()
    Description copied from interface: `Host`
    Get an absolute `File` for the appBase of this Host. The file will be canonical if possible. There is no guarantee that the appBase exists.
    Specified by:
      `getAppBaseFile` in interface `Host`
    Returns:
      the application base file

  - ### 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()
    Description copied from interface: `Host`
    Get the legacy (Java EE) application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
    Specified by:
      `getLegacyAppBase` in interface `Host`
    Returns:
      the legacy application root

  - ### getLegacyAppBaseFile

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

  - ### 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()
    Description copied from interface: `Host`
    Get 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:
      `getXmlBase` in interface `Host`
    Returns:
      the XML root

  - ### setXmlBase

    public void setXmlBase(String xmlBase)
    Description copied from interface: `Host`
    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()
    Description copied from interface: `Host`
    Get the default configuration path of this Host. The file will be canonical if possible.
    Specified by:
      `getConfigBaseFile` in interface `Host`
    Returns:
      the configuration base file

  - ### getCreateDirs

    public boolean getCreateDirs()
    Returns `true` if the Host will attempt to create directories for appBase and xmlBase unless they already exist.

    The default value for this implementation is `true`.

    Specified by:
      `getCreateDirs` in interface `Host`
    Returns:
      true if the Host will attempt to create directories

  - ### setCreateDirs

    public void setCreateDirs(boolean createDirs)
    Description copied from interface: `Host`
    Should the Host attempt to create directories for xmlBase and appBase upon startup.
    Specified by:
      `setCreateDirs` in interface `Host`
    Parameters:
      `createDirs` - The new value for this flag

  - ### getAutoDeploy

    public boolean getAutoDeploy()
    Get the value of the auto deploy flag. If true, it indicates that this host's child webapps should be discovered and automatically deployed dynamically.

    The default value for this implementation is `true`.

    Specified by:
      `getAutoDeploy` in interface `Host`
    Returns:
      the auto deploy flag

  - ### setAutoDeploy

    public void setAutoDeploy(boolean autoDeploy)
    Description copied from interface: `Host`
    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()
    Description copied from interface: `Host`
    Get the Java class name of the context configuration class for new web applications.
    Specified by:
      `getConfigClass` in interface `Host`
    Returns:
      the context configuration class name

  - ### setConfigClass

    public void setConfigClass(String configClass)
    Description copied from interface: `Host`
    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.
    Returns:
      the Java class name of the Context implementation class

  - ### 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()
    Get the value of the deploy on startup flag. If true, it indicates that this host's child webapps should be discovered and automatically deployed.

    The default value for this implementation is `true`.

    Specified by:
      `getDeployOnStartup` in interface `Host`
    Returns:
      the deploy on startup flag

  - ### setDeployOnStartup

    public void setDeployOnStartup(boolean deployOnStartup)
    Description copied from interface: `Host`
    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 whether XML context descriptors should be deployed.
    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.
    Returns:
      the copy XML config file flag

  - ### 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.
    Returns:
      the Java class name of the error report valve class

  - ### 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 interface: `Container`
    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 human readable name of this container.

  - ### setName

    public void setName(String name)
    Description copied from interface: `Container`
    Set 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:
      `setName` in interface `Container`
    Overrides:
      `setName` in class `ContainerBase`
    Parameters:
      `name` - New name of this container

  - ### isUnpackWARs

    public boolean isUnpackWARs()
    Returns whether WARs should be unpacked on deployment.
    Returns:
      `true` if WARs should be unpacked

  - ### setUnpackWARs

    public void setUnpackWARs(boolean unpackWARs)
    Unpack WARs flag mutator.
    Parameters:
      `unpackWARs` - `true` to unpack WARs on deployment

  - ### getWorkDir

    public String getWorkDir()
    Returns the host work directory base.
    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()
    Description copied from interface: `Host`
    Get the regular expression that defines the files and directories in the host's appBase that will be ignored by the automatic deployment process.
    Specified by:
      `getDeployIgnore` in interface `Host`
    Returns:
      the deploy ignore regular expression

  - ### getDeployIgnorePattern

    public Pattern getDeployIgnorePattern()
    Description copied from interface: `Host`
    Get the compiled regular expression that defines the files and directories in the host's appBase that will be ignored by the automatic deployment process.
    Specified by:
      `getDeployIgnorePattern` in interface `Host`
    Returns:
      the compiled deploy ignore pattern

  - ### setDeployIgnore

    public void setDeployIgnore(String deployIgnore)
    Description copied from interface: `Host`
    Set the regular expression that defines the files and directories in the host's appBase that will be ignored by the automatic deployment process.
    Specified by:
      `setDeployIgnore` in interface `Host`
    Parameters:
      `deployIgnore` - A regular expression matching file names

  - ### isFailCtxIfServletStartFails

    public boolean isFailCtxIfServletStartFails()
    Returns whether a webapp start should fail if a Servlet startup fails.
    Returns:
      `true` if a webapp start should fail on servlet startup failure

  - ### 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)
    Description copied from interface: `Host`
    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 new child Container to those associated with this Container, if supported. Prior to adding this Container to the set of children, the child's `setParent()` method must be called, with this Container as an argument. This method may throw an `IllegalArgumentException` if this Container chooses not to be attached to the specified Container, in which case it is not added

    The child must be an implementation of `Context`.

    Specified by:
      `addChild` in interface `Container`
    Overrides:
      `addChild` in class `ContainerBase`
    Parameters:
      `child` - New 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:
      an array of possibly leaking contexts

  - ### findAliases

    public String[] findAliases()
    Description copied from interface: `Host`
    Get the array of alias names for this Host. If none are defined, a zero length array is returned.
    Specified by:
      `findAliases` in interface `Host`
    Returns:
      the array of alias names

  - ### removeAlias

    public void removeAlias(String alias)
    Description copied from interface: `Host`
    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
    Description copied from class: `ContainerBase`
    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.
    Returns:
      the MBean Names of the Valves
    Throws:
      `Exception` - if an MBean cannot be created or registered

  - ### getAliases

    public String[] getAliases()
    Returns the array of aliases for this host.
    Returns:
      the array of aliases

  - ### getObjectNameKeyProperties

    protected String getObjectNameKeyProperties()
    Description copied from class: `LifecycleMBeanBase`
    Allow subclasses 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`