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

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

  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, 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, initInternal, 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 Details

  - ### StandardHost

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

- ## Method Details

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