HostManagerServlet (Apache Tomcat 9.0.121 API Documentation)
Description: declaration: package: org.apache.catalina.manager.host, class: HostManagerServlet

# Class HostManagerServlet

java.lang.Object
javax.servlet.GenericServlet
javax.servlet.http.HttpServlet
org.apache.catalina.manager.host.HostManagerServlet

All Implemented Interfaces:
  `Serializable, Servlet, ServletConfig, ContainerServlet`

Direct Known Subclasses:
  `HTMLHostManagerServlet`

public class HostManagerServlet extends HttpServlet implements ContainerServlet
Servlet that enables remote management of the virtual hosts installed on the server. Normally, this functionality will be protected by a security constraint in the web application deployment descriptor. However, this requirement can be relaxed during testing.

This servlet examines the value returned by `getPathInfo()` and related query parameters to determine what action is being requested. The following actions and parameters (starting after the servlet path) are supported:

- /add?name={host-name}&aliases={host-aliases}&manager={manager} - Create and add a new virtual host. The `host-name` attribute indicates the name of the new host. The `host-aliases` attribute is a comma separated list of the host alias names. The `manager` attribute is a boolean value indicating if the webapp manager will be installed in the newly created host (optional, false by default).
- /remove?name={host-name} - Remove a virtual host. The `host-name` attribute indicates the name of the host.
- /list - List the virtual hosts installed on the server. Each host will be listed with the following format `host-name#host-aliases`.
- /start?name={host-name} - Start the virtual host.
- /stop?name={host-name} - Stop the virtual host.
- /persist - Persist the current server configuration to `server.xml`. Requires the `StoreConfigLifecycleListener` to be configured.

NOTE - Attempting to stop or remove the host containing this servlet itself will not succeed. Therefore, this servlet should generally be deployed in a separate virtual host.

The following servlet initialization parameters are recognized:

- debug - The debugging detail level that controls the amount of information that is logged by this servlet. Default is zero.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Context`
  `context`
  The Context container associated with our web application.
  `protected int`
  `debug`
  The debugging detail level for this servlet.
  `protected Engine`
  `engine`
  The associated engine.
  `protected Host`
  `installedHost`
  The associated host.
  `protected static final StringManager`
  `sm`
  The string manager for this package.
  `protected Wrapper`
  `wrapper`
  The Wrapper container associated with this servlet.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HostManagerServlet()`
  Constructs a new HostManagerServlet.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `add(PrintWriter writer, String name, String aliases, String appBase, boolean manager, boolean autoDeploy, boolean deployOnStartup, boolean deployXML, boolean unpackWARs, boolean copyXML, StringManager smClient)`
  Add a host using the specified parameters.
  `protected void`
  `add(HttpServletRequest request, PrintWriter writer, String name, boolean htmlMode, StringManager smClient)`
  Add host with the given parameters.
  `protected boolean`
  `booleanParameter(HttpServletRequest request, String parameter, boolean theDefault, boolean htmlMode)`
  Extract boolean value from checkbox with default.
  `void`
  `destroy()`
  Called by the servlet container to indicate to a servlet that the servlet is being taken out of service.
  `void`
  `doGet(HttpServletRequest request, HttpServletResponse response)`
  Called by the server (via the `service` method) to allow a servlet to handle a GET request.
  `protected File`
  `getConfigBase(String hostName)`
  Deprecated.
  Unused.
  `protected File`
  `getConfigBase(String hostName, PrintWriter writer, StringManager smClient)`
  Get config base.
  `Wrapper`
  `getWrapper()`
  Obtain the Wrapper with which this Servlet is associated.
  `void`
  `init()`
  A convenience method which can be overridden so that there's no need to call `super.init(config)`.
  `protected void`
  `list(PrintWriter writer, StringManager smClient)`
  Render a list of the currently active Contexts in our virtual host.
  `protected void`
  `persist(PrintWriter writer, StringManager smClient)`
  Persist the current configuration to server.xml.
  `protected void`
  `remove(PrintWriter writer, String name, StringManager smClient)`
  Remove the specified host.
  `void`
  `setWrapper(Wrapper wrapper)`
  Set the Wrapper with which this Servlet is associated.
  `protected void`
  `start(PrintWriter writer, String name, StringManager smClient)`
  Start the host with the specified name.
  `protected void`
  `stop(PrintWriter writer, String name, StringManager smClient)`
  Stop the host with the specified name.

  ### Methods inherited from class HttpServlet

  `doDelete, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service, service`

  ### Methods inherited from class GenericServlet

  `getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### context

    protected transient Context context
    The Context container associated with our web application.

  - ### debug

    protected int debug
    The debugging detail level for this servlet.

  - ### installedHost

    protected transient Host installedHost
    The associated host.

  - ### engine

    protected transient Engine engine
    The associated engine.

  - ### sm

    protected static final StringManager sm
    The string manager for this package.

  - ### wrapper

    protected transient Wrapper wrapper
    The Wrapper container associated with this servlet.

- ## Constructor Details

  - ### HostManagerServlet

    public HostManagerServlet()
    Constructs a new HostManagerServlet.

- ## Method Details

  - ### getWrapper

    public Wrapper getWrapper()
    Description copied from interface: `ContainerServlet`
    Obtain the Wrapper with which this Servlet is associated.
    Specified by:
      `getWrapper` in interface `ContainerServlet`
    Returns:
      The Wrapper with which this Servlet is associated.

  - ### setWrapper

    public void setWrapper(Wrapper wrapper)
    Description copied from interface: `ContainerServlet`
    Set the Wrapper with which this Servlet is associated.
    Specified by:
      `setWrapper` in interface `ContainerServlet`
    Parameters:
      `wrapper` - The new associated Wrapper

  - ### destroy

    public void destroy()
    Description copied from class: `javax.servlet.GenericServlet`
    Called by the servlet container to indicate to a servlet that the servlet is being taken out of service. See `Servlet.destroy()`.
    Specified by:
      `destroy` in interface `Servlet`
    Overrides:
      `destroy` in class `GenericServlet`

  - ### doGet

    public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
    Description copied from class: `javax.servlet.http.HttpServlet`
    Called by the server (via the `service` method) to allow a servlet to handle a GET request.

    Overriding this method to support a GET request also automatically supports an HTTP HEAD request. A HEAD request is a GET request that returns no body in the response, only the request header fields.

    When overriding this method, read the request data, write the response headers, get the response's Writer or output stream object, and finally, write the response data. It's best to include content type and encoding. When using a `PrintWriter` object to return the response, set the content type before accessing the `PrintWriter` object.

    The servlet container must write the headers before committing the response, because in HTTP the headers must be sent before the response body.

    Where possible, set the Content-Length header (with the `ServletResponse.setContentLength(int)` method), to allow the servlet container to use a persistent connection to return its response to the client, improving performance. The content length is automatically set if the entire response fits inside the response buffer.

    When using HTTP 1.1 chunked encoding (which means that the response has a Transfer-Encoding header), do not set the Content-Length header.

    The GET method should be safe, that is, without any side effects for which users are held responsible. For example, most form queries have no side effects. If a client request is intended to change stored data, the request should use some other HTTP method.

    The GET method should also be idempotent, meaning that it can be safely repeated. Sometimes making a method safe also makes it idempotent. For example, repeating queries is both safe and idempotent, but buying a product online or modifying data is neither safe nor idempotent.

    If the request is incorrectly formatted, `doGet` returns an HTTP "Bad Request" message.

    Overrides:
      `doGet` in class `HttpServlet`
    Parameters:
      `request` - an `HttpServletRequest` object that contains the request the client has made of the servlet
      `response` - an `HttpServletResponse` object that contains the response the servlet sends to the client
    Throws:
      `IOException` - if an input or output error is detected when the servlet handles the GET request
      `ServletException` - if the request for the GET could not be handled
    See Also:
      - `ServletResponse.setContentType(String)`

  - ### add

    protected void add(HttpServletRequest request, PrintWriter writer, String name, boolean htmlMode, StringManager smClient)
    Add host with the given parameters.
    Parameters:
      `request` - The request
      `writer` - The output writer
      `name` - The host name
      `htmlMode` - Flag value
      `smClient` - StringManager for the client's locale

  - ### booleanParameter

    protected boolean booleanParameter(HttpServletRequest request, String parameter, boolean theDefault, boolean htmlMode)
    Extract boolean value from checkbox with default.
    Parameters:
      `request` - The Servlet request
      `parameter` - The parameter name
      `theDefault` - Default value
      `htmlMode` - Flag value
    Returns:
      the boolean value for the parameter

  - ### init

    public void init() throws ServletException
    Description copied from class: `javax.servlet.GenericServlet`
    A convenience method which can be overridden so that there's no need to call `super.init(config)`.

    Instead of overriding `GenericServlet.init(ServletConfig)`, simply override this method and it will be called by `GenericServlet.init(ServletConfig config)`. The `ServletConfig` object can still be retrieved via `GenericServlet.getServletConfig()`.

    Overrides:
      `init` in class `GenericServlet`
    Throws:
      `ServletException` - if an exception occurs that interrupts the servlet's normal operation

  - ### add

    protected void add(PrintWriter writer, String name, String aliases, String appBase, boolean manager, boolean autoDeploy, boolean deployOnStartup, boolean deployXML, boolean unpackWARs, boolean copyXML, StringManager smClient)
    Add a host using the specified parameters.
    Parameters:
      `writer` - Writer to render results to
      `name` - host name
      `aliases` - comma separated alias list
      `appBase` - application base for the host
      `manager` - should the manager webapp be deployed to the new host ?
      `autoDeploy` - Flag value
      `deployOnStartup` - Flag value
      `deployXML` - Flag value
      `unpackWARs` - Flag value
      `copyXML` - Flag value
      `smClient` - StringManager for the client's locale

  - ### remove

    protected void remove(PrintWriter writer, String name, StringManager smClient)
    Remove the specified host.
    Parameters:
      `writer` - Writer to render results to
      `name` - host name
      `smClient` - StringManager for the client's locale

  - ### list

    protected void list(PrintWriter writer, StringManager smClient)
    Render a list of the currently active Contexts in our virtual host.
    Parameters:
      `writer` - Writer to render to
      `smClient` - StringManager for the client's locale

  - ### start

    protected void start(PrintWriter writer, String name, StringManager smClient)
    Start the host with the specified name.
    Parameters:
      `writer` - Writer to render to
      `name` - Host name
      `smClient` - StringManager for the client's locale

  - ### stop

    protected void stop(PrintWriter writer, String name, StringManager smClient)
    Stop the host with the specified name.
    Parameters:
      `writer` - Writer to render to
      `name` - Host name
      `smClient` - StringManager for the client's locale

  - ### persist

    protected void persist(PrintWriter writer, StringManager smClient)
    Persist the current configuration to server.xml.
    Parameters:
      `writer` - Writer to render to
      `smClient` - i18n resources localized for the client

  - ### getConfigBase

    @Deprecated protected File getConfigBase(String hostName)
    Deprecated.
    Unused. Will be removed in Tomcat 12. Use `getConfigBase(String, PrintWriter, StringManager)`
    Get config base.
    Parameters:
      `hostName` - The host name
    Returns:
      the config base for the host

  - ### getConfigBase

    protected File getConfigBase(String hostName, PrintWriter writer, StringManager smClient)
    Get config base.
    Parameters:
      `hostName` - The host name
      `writer` - Writer to render results to
      `smClient` - StringManager for the client's locale
    Returns:
      the config base for the host