## org.apache.catalina.core
Class StandardHost

    java.lang.Object
      org.apache.catalina.core.ContainerBase
          org.apache.catalina.core.StandardHost

All Implemented Interfaces:
  Container, Deployer, Host, Lifecycle, javax.management.MBeanRegistration, Pipeline, java.io.Serializable

public class StandardHost
extends ContainerBase
implements Deployer, 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.

Version:
  $Revision: 1.31 $ $Date: 2004/05/26 15:41:07 $
Author:
  Craig R. McClanahan, Remy Maucherat
See Also:
  Serialized Form

Nested Class Summary

Nested classes inherited from class org.apache.catalina.core.ContainerBase
`ContainerBase.ContainerBackgroundProcessor, ContainerBase.PrivilegedAddChild`

Field Summary

Fields inherited from class org.apache.catalina.core.ContainerBase
`backgroundProcessorDelay, children, cluster, controller, debug, domain, lifecycle, listeners, loader, logger, manager, mserver, name, oname, parent, parentClassLoader, pipeline, realm, resources, sm, started, suffix, support, type`

Fields inherited from interface org.apache.catalina.Deployer
`INSTALL_EVENT, PRE_INSTALL_EVENT, REMOVE_EVENT`

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_MAPPER_EVENT, ADD_VALVE_EVENT, REMOVE_CHILD_EVENT, REMOVE_MAPPER_EVENT, REMOVE_VALVE_EVENT`

Fields inherited from interface org.apache.catalina.Lifecycle
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT`

Constructor Summary
`StandardHost()` Create a new StandardHost component with the default basic Valve.

Method Summary
`void` `addAlias(java.lang.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.
`void` `addDefaultContext(DefaultContext defaultContext)` Set the DefaultContext for new web applications.
`void` `backgroundProcess()` Execute a periodic task, such as reloading, etc.
`javax.management.ObjectName` `createObjectName(java.lang.String domain, javax.management.ObjectName parent)`
`java.lang.String[]` `findAliases()` Return the set of alias names for this Host.
`Context` `findDeployedApp(java.lang.String contextPath)` Return the Context for the deployed application that is associated with the specified context path (if any); otherwise return `null`.
`java.lang.String[]` `findDeployedApps()` Return the context paths of all deployed web applications in this Container.
`java.lang.String[]` `getAliases()`
`java.lang.String` `getAppBase()` Return the application root for this Host.
`boolean` `getAutoDeploy()` Return the value of the auto deploy flag.
`java.lang.String` `getConfigClass()` Return the Java class name of the context configuration class for new web applications.
`java.lang.String` `getContextClass()` Return the Java class name of the Context implementation class for new web applications.
`DefaultContext` `getDefaultContext()` Retrieve the DefaultContext for new web applications.
`Deployer` `getDeployer()`
`boolean` `getDeployOnStartup()` Return the value of the deploy on startup flag.
`java.lang.String` `getErrorReportValveClass()` Return the Java class name of the error report valve class for new web applications.
`java.lang.String` `getInfo()` Return descriptive information about this Container implementation and the corresponding version number, in the format `<description>/<version>`.
`boolean` `getLiveDeploy()` Return the value of the live deploy flag.
`java.lang.String` `getName()` Return the canonical, fully qualified, name of the virtual host this Container represents.
`java.lang.String[]` `getValveNames()` Return the MBean Names of the Valves assoicated with this Host
`java.lang.String` `getWorkDir()` Host work directory base.
`boolean` `getXmlNamespaceAware()` Get the server.xml <host> attribute's xmlNamespaceAware.
`boolean` `getXmlValidation()` Get the server.xml <host> attribute's xmlValidation.
`void` `importDefaultContext(Context context)` Import the DefaultContext config into a web application context.
`void` `init()` Init method, part of the MBean lifecycle.
`void` `install(java.lang.String contextPath, java.net.URL war)` Install a new web application, whose web application archive is at the specified URL, into this container with the specified context path.
`void` `install(java.net.URL war)` Installs a new web application from the web application archive at the specified URL, which must contain a META-INF/context.xml context configuration file (consisting of a `<Context>` element).
`void` `install(java.net.URL config, java.net.URL war)` Install a new web application, whose context configuration file (consisting of a `<Context>` element) and web application archive are at the specified URLs.
`void` `installDefaultContext(Context context)` Install the StandardContext portion of the DefaultContext configuration into current Context.
`boolean` `isDeployXML()` Deploy XML Context config files flag accessor.
`boolean` `isUnpackWARs()` Unpack WARs flag accessor.
`Context` `map(java.lang.String uri)` Return the Context that would be used to process the specified host-relative request URI, if any; otherwise return `null`.
`javax.management.ObjectName` `preRegister(javax.management.MBeanServer server, javax.management.ObjectName oname)`
`void` `remove(java.lang.String contextPath)` Remove an existing web application, attached to the specified context path.
`void` `remove(java.lang.String contextPath, boolean undeploy)` Remove an existing web application, attached to the specified context path.
`void` `removeAlias(java.lang.String alias)` Remove the specified alias name from the aliases for this Host.
`void` `setAppBase(java.lang.String appBase)` Set the application root for this Host.
`void` `setAutoDeploy(boolean autoDeploy)` Set the auto deploy flag value for this host.
`void` `setConfigClass(java.lang.String configClass)` Set the Java class name of the context configuration class for new web applications.
`void` `setContextClass(java.lang.String contextClass)` Set the Java class name of the Context implementation class for new web applications.
`void` `setDeployer(Deployer d)`
`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(java.lang.String errorReportValveClass)` Set the Java class name of the error report valve class for new web applications.
`void` `setLiveDeploy(boolean liveDeploy)` Set the live deploy flag value for this host.
`void` `setName(java.lang.String name)` Set the canonical, fully qualified, name of the virtual host this Container represents.
`void` `setUnpackWARs(boolean unpackWARs)` Unpack WARs flag mutator.
`void` `setWorkDir(java.lang.String workDir)` Host work directory base.
`void` `setXmlNamespaceAware(boolean xmlNamespaceAware)` Set the namespace aware feature of the XML parser used when parsing xml instances.
`void` `setXmlValidation(boolean xmlValidation)` Set the validation feature of the XML parser used when parsing xml instances.
`void` `start()` Start this host.
`void` `start(java.lang.String contextPath)` Start an existing web application, attached to the specified context path.
`void` `stop(java.lang.String contextPath)` Stop an existing web application, attached to the specified context path.
`java.lang.String` `toString()` Return a String representation of this component.

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

`addContainerListener, addLifecycleListener, addPropertyChangeListener, addValve, destroy, findChild, findChildren, findContainerListeners, findLifecycleListeners, fireContainerEvent, getBackgroundProcessorDelay, getBasic, getChildren, getCluster, getContainerSuffix, getDebug, getDomain, getJmxName, getJSR77Suffix, getLoader, getLogger, getManager, getMappingObject, getObjectName, getParent, getParentClassLoader, getParentName, getPipeline, getRealm, getResources, getType, getValveObjectNames, getValves, invoke, log, log, logName, postDeregister, postRegister, preDeregister, removeChild, removeContainerListener, removeLifecycleListener, removePropertyChangeListener, removeValve, setBackgroundProcessorDelay, setBasic, setCluster, setDebug, setDomain, setLoader, setLogger, setManager, setParent, setParentClassLoader, setRealm, setResources, stop, threadStart, threadStop`

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, findChild, findChildren, findContainerListeners, getBackgroundProcessorDelay, getCluster, getLoader, getLogger, getManager, getMappingObject, getParent, getParentClassLoader, getPipeline, getRealm, getResources, invoke, removeChild, removeContainerListener, removePropertyChangeListener, setBackgroundProcessorDelay, setCluster, setLoader, setLogger, setManager, setParent, setParentClassLoader, setRealm, setResources`

Constructor Detail

### StandardHost

    public StandardHost()

  Create a new StandardHost component with the default basic Valve.

Method Detail

### getAppBase

    public java.lang.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`

### setAppBase

    public void setAppBase(java.lang.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

### getAutoDeploy

    public boolean getAutoDeploy()

  Return the value of the auto deploy flag. If true, it indicates that this host's child webapps will be dynamically deployed.

  Specified by:
    `getAutoDeploy` in interface `Host`

### 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 java.lang.String getConfigClass()

  Return the Java class name of the context configuration class for new web applications.

### setConfigClass

    public void setConfigClass(java.lang.String configClass)

  Set the Java class name of the context configuration class for new web applications.

  Parameters:
    `configClass` - The new context configuration class

### addDefaultContext

    public void addDefaultContext(DefaultContext defaultContext)

  Set the DefaultContext for new web applications.

  Specified by:
    `addDefaultContext` in interface `Host`
  Parameters:
    `defaultContext` - The new DefaultContext

### getDefaultContext

    public DefaultContext getDefaultContext()

  Retrieve the DefaultContext for new web applications.

  Specified by:
    `getDefaultContext` in interface `Host`

### getContextClass

    public java.lang.String getContextClass()

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

### setContextClass

    public void setContextClass(java.lang.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()

  Return the value of the deploy on startup flag. If true, it indicates that this host's child webapps should be discovred and automatically deployed at startup time.

  Specified by:
    `getDeployOnStartup` in interface `Host`

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

  Deploy XML Context config files flag accessor.

  Specified by:
    `isDeployXML` in interface `Deployer`
  Returns:
    true of context.xml config files are supported, false otherwise

### setDeployXML

    public void setDeployXML(boolean deployXML)

  Deploy XML Context config files flag mutator.

### getLiveDeploy

    public boolean getLiveDeploy()

  Return the value of the live deploy flag. If true, it indicates that a background thread should be started that looks for web application context files, WAR files, or unpacked directories being dropped in to the `appBase` directory, and deploys new ones as they are encountered.

### setLiveDeploy

    public void setLiveDeploy(boolean liveDeploy)

  Set the live deploy flag value for this host.

  Parameters:
    `liveDeploy` - The new live deploy flag

### getErrorReportValveClass

    public java.lang.String getErrorReportValveClass()

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

### setErrorReportValveClass

    public void setErrorReportValveClass(java.lang.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 java.lang.String getName()

  Return the canonical, fully qualified, name of the virtual host this Container represents.

  Specified by:
    `getName` in interface `Deployer`
  Overrides:
    `getName` in class `ContainerBase`

### setName

    public void setName(java.lang.String name)

  Set the canonical, fully qualified, name of the virtual host this Container represents.

  Specified by:
    `setName` in interface `Host`
  Overrides:
    `setName` in class `ContainerBase`
  Parameters:
    `name` - Virtual host name
  Throws:
    `java.lang.IllegalArgumentException` - if name is null

### isUnpackWARs

    public boolean isUnpackWARs()

  Unpack WARs flag accessor.

### setUnpackWARs

    public void setUnpackWARs(boolean unpackWARs)

  Unpack WARs flag mutator.

### setXmlValidation

    public void setXmlValidation(boolean xmlValidation)

  Set the validation feature of the XML parser used when parsing xml instances.

  Specified by:
    `setXmlValidation` in interface `Host`
  Parameters:
    `xmlValidation` - true to enable xml instance validation

### getXmlValidation

    public boolean getXmlValidation()

  Get the server.xml <host> attribute's xmlValidation.

  Specified by:
    `getXmlValidation` in interface `Host`
  Returns:
    true if validation is enabled.

### getXmlNamespaceAware

    public boolean getXmlNamespaceAware()

  Get the server.xml <host> attribute's xmlNamespaceAware.

  Specified by:
    `getXmlNamespaceAware` in interface `Host`
  Returns:
    true if namespace awarenes is enabled.

### setXmlNamespaceAware

    public void setXmlNamespaceAware(boolean xmlNamespaceAware)

  Set the namespace aware feature of the XML parser used when parsing xml instances.

  Specified by:
    `setXmlNamespaceAware` in interface `Host`
  Parameters:
    `xmlNamespaceAware` - true to enable namespace awareness

### getWorkDir

    public java.lang.String getWorkDir()

  Host work directory base.

### setWorkDir

    public void setWorkDir(java.lang.String workDir)

  Host work directory base.

### installDefaultContext

    public void installDefaultContext(Context context)

  Install the StandardContext portion of the DefaultContext configuration into current Context.

  Parameters:
    `context` - current web application context

### importDefaultContext

    public void importDefaultContext(Context context)

  Import the DefaultContext config into a web application context.

  Specified by:
    `importDefaultContext` in interface `Host`
  Parameters:
    `context` - web application context to import default context

### addAlias

    public void addAlias(java.lang.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

### findAliases

    public java.lang.String[] findAliases()

  Return the set of alias names for this Host. If none are defined, a zero length array is returned.

  Specified by:
    `findAliases` in interface `Host`

### getInfo

    public java.lang.String getInfo()

  Return descriptive information about this Container implementation and the corresponding version number, in the format `<description>/<version>`.

  Specified by:
    `getInfo` in interface `Container`
  Overrides:
    `getInfo` in class `ContainerBase`

### map

    public Context map(java.lang.String uri)

  Return the Context that would be used to process the specified host-relative request URI, if any; otherwise return `null`.

  Specified by:
    `map` in interface `Host`
  Parameters:
    `uri` - Request URI to be mapped

### removeAlias

    public void removeAlias(java.lang.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

### toString

    public java.lang.String toString()

  Return a String representation of this component.

### start

    public void start()
               throws LifecycleException

  Start this host.

  Specified by:
    `start` in interface `Lifecycle`
  Overrides:
    `start` in class `ContainerBase`
  Throws:
    `LifecycleException` - if this component detects a fatal error that prevents it from being started

### backgroundProcess

    public void backgroundProcess()

  Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.

  Specified by:
    `backgroundProcess` in interface `Container`
  Overrides:
    `backgroundProcess` in class `ContainerBase`

### install

    public void install(java.lang.String contextPath,
                        java.net.URL war)
                 throws java.io.IOException

  Install a new web application, whose web application archive is at the specified URL, into this container with the specified context path. A context path of "" (the empty string) should be used for the root application for this container. Otherwise, the context path must start with a slash.

  If this application is successfully installed, a ContainerEvent of type `INSTALL_EVENT` will be sent to all registered listeners, with the newly created `Context` as an argument.

  Specified by:
    `install` in interface `Deployer`
  Parameters:
    `contextPath` - The context path to which this application should be installed (must be unique)
    `war` - A URL of type "jar:" that points to a WAR file, or type "file:" that points to an unpacked directory structure containing the web application to be installed
  Throws:
    `java.lang.IllegalArgumentException` - if the specified context path is malformed (it must be "" or start with a slash)
    `java.lang.IllegalStateException` - if the specified context path is already attached to an existing web application
    `java.io.IOException` - if an input/output error was encountered during install

### install

    public void install(java.net.URL config,
                        java.net.URL war)
                 throws java.io.IOException

  Install a new web application, whose context configuration file (consisting of a `<Context>` element) and web application archive are at the specified URLs.

  If this application is successfully installed, a ContainerEvent of type `INSTALL_EVENT` will be sent to all registered listeners, with the newly created `Context` as an argument.

  Specified by:
    `install` in interface `Deployer`
  Parameters:
    `config` - A URL that points to the context configuration file to be used for configuring the new Context
    `war` - A URL of type "jar:" that points to a WAR file, or type "file:" that points to an unpacked directory structure containing the web application to be installed
  Throws:
    `java.lang.IllegalArgumentException` - if one of the specified URLs is null
    `java.lang.IllegalStateException` - if the context path specified in the context configuration file is already attached to an existing web application
    `java.io.IOException` - if an input/output error was encountered during installation

### install

    public void install(java.net.URL war)
                 throws java.io.IOException

  Installs a new web application from the web application archive at the specified URL, which must contain a META-INF/context.xml context configuration file (consisting of a `<Context>` element).

  The web application is installed at the path specified inside the embedded META-INF/context.xml. The docBase (if any) specified inside the embedded META-INF/context.xml is overridden with the web application's location.

  If the installation succeeds, a ContainerEvent of type `INSTALL_EVENT` is sent to all registered listeners, with the newly created `Context` as its argument.

  Specified by:
    `install` in interface `Deployer`
  Parameters:
    `war` - URL pointing to web application location (WAR-packaged or unpacked directory)
  Throws:
    `java.lang.IllegalArgumentException` - if `war` is null, or if this StandardHost does not support any context.xml configuration files
    `java.lang.IllegalStateException` - if the context path specified in the context configuration file is already in use by an existing web application
    `java.io.IOException` - if an input/output error was encountered during installation

### findDeployedApp

    public Context findDeployedApp(java.lang.String contextPath)

  Return the Context for the deployed application that is associated with the specified context path (if any); otherwise return `null`.

  Specified by:
    `findDeployedApp` in interface `Deployer`
  Parameters:
    `contextPath` - The context path of the requested web application

### findDeployedApps

    public java.lang.String[] findDeployedApps()

  Return the context paths of all deployed web applications in this Container. If there are no deployed applications, a zero-length array is returned.

  Specified by:
    `findDeployedApps` in interface `Deployer`

### remove

    public void remove(java.lang.String contextPath)
                throws java.io.IOException

  Remove an existing web application, attached to the specified context path. If this application is successfully removed, a ContainerEvent of type `REMOVE_EVENT` will be sent to all registered listeners, with the removed `Context` as an argument.

  Specified by:
    `remove` in interface `Deployer`
  Parameters:
    `contextPath` - The context path of the application to be removed
  Throws:
    `java.lang.IllegalArgumentException` - if the specified context path is malformed (it must be "" or start with a slash)
    `java.lang.IllegalArgumentException` - if the specified context path does not identify a currently installed web application
    `java.io.IOException` - if an input/output error occurs during removal

### remove

    public void remove(java.lang.String contextPath,
                       boolean undeploy)
                throws java.io.IOException

  Remove an existing web application, attached to the specified context path. If this application is successfully removed, a ContainerEvent of type `REMOVE_EVENT` will be sent to all registered listeners, with the removed `Context` as an argument. Deletes the web application war file and/or directory if they exist in the Host's appBase.

  Specified by:
    `remove` in interface `Deployer`
  Parameters:
    `contextPath` - The context path of the application to be removed
    `undeploy` - boolean flag to remove web application from server
  Throws:
    `java.lang.IllegalArgumentException` - if the specified context path is malformed (it must be "" or start with a slash)
    `java.lang.IllegalArgumentException` - if the specified context path does not identify a currently installed web application
    `java.io.IOException` - if an input/output error occurs during removal

### start

    public void start(java.lang.String contextPath)
               throws java.io.IOException

  Start an existing web application, attached to the specified context path. Only starts a web application if it is not running.

  Specified by:
    `start` in interface `Deployer`
  Parameters:
    `contextPath` - The context path of the application to be started
  Throws:
    `java.lang.IllegalArgumentException` - if the specified context path is malformed (it must be "" or start with a slash)
    `java.lang.IllegalArgumentException` - if the specified context path does not identify a currently installed web application
    `java.io.IOException` - if an input/output error occurs during startup

### stop

    public void stop(java.lang.String contextPath)
              throws java.io.IOException

  Stop an existing web application, attached to the specified context path. Only stops a web application if it is running.

  Specified by:
    `stop` in interface `Deployer`
  Parameters:
    `contextPath` - The context path of the application to be stopped
  Throws:
    `java.lang.IllegalArgumentException` - if the specified context path is malformed (it must be "" or start with a slash)
    `java.lang.IllegalArgumentException` - if the specified context path does not identify a currently installed web application
    `java.io.IOException` - if an input/output error occurs while stopping the web application

### getDeployer

    public Deployer getDeployer()

### setDeployer

    public void setDeployer(Deployer d)

### getValveNames

    public java.lang.String[] getValveNames()
                                     throws java.lang.Exception

  Return the MBean Names of the Valves assoicated with this Host

  Throws:
    `java.lang.Exception` - if an MBean cannot be created or registered

### getAliases

    public java.lang.String[] getAliases()

### init

    public void init()

  Description copied from class: `ContainerBase`
  Init method, part of the MBean lifecycle. If the container was added via JMX, it'll register itself with the parent, using the ObjectName conventions to locate the parent. If the container was added directly and it doesn't have an ObjectName, it'll create a name and register itself with the JMX console. On destroy(), the object will unregister.

  Overrides:
    `init` in class `ContainerBase`

### preRegister

    public javax.management.ObjectName preRegister(javax.management.MBeanServer server,
                                                   javax.management.ObjectName oname)
                                            throws java.lang.Exception

  Specified by:
    `preRegister` in interface `javax.management.MBeanRegistration`
  Overrides:
    `preRegister` in class `ContainerBase`
  Throws:
    `java.lang.Exception`

### createObjectName

    public javax.management.ObjectName createObjectName(java.lang.String domain,
                                                        javax.management.ObjectName parent)
                                                 throws java.lang.Exception

  Overrides:
    `createObjectName` in class `ContainerBase`
  Throws:
    `java.lang.Exception`

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