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

Package org.apache.catalina.manager.host

# Class HostManagerServlet

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

All Implemented Interfaces:
  `Servlet`, `ServletConfig`, `Serializable`, `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.

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.

Author:
  Craig R. McClanahan, Remy Maucherat
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.

  ### Fields inherited from class jakarta.servlet.http.HttpServlet

  `LEGACY_DO_HEAD`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HostManagerServlet()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `add(HttpServletRequest request, PrintWriter writer, String name, boolean htmlMode, StringManager smClient)`
  Add host with the given parameters.
  `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 boolean`
  `booleanParameter(HttpServletRequest request, String parameter, boolean theDefault, boolean htmlMode)`
  Extract boolean value from checkbox with default.
  `void`
  `destroy()`
  Finalize this servlet.
  `void`
  `doGet(HttpServletRequest request, HttpServletResponse response)`
  Process a GET request for the specified resource.
  `protected File`
  `getConfigBase(String hostName)`
  Get config base.
  `Wrapper`
  `getWrapper()`
  Return the Wrapper with which we are 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 we are 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 jakarta.servlet.http.HttpServlet

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

  ### Methods inherited from class jakarta.servlet.GenericServlet

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

  ### Methods inherited from class java.lang.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()

- ## Method Details

  - ### getWrapper

    public Wrapper getWrapper()
    Return the Wrapper with which we are associated.
    Specified by:
      `getWrapper` in interface `ContainerServlet`
    Returns:
      The Wrapper with which this Servlet is associated.

  - ### setWrapper

    public void setWrapper(Wrapper wrapper)
    Set the Wrapper with which we are associated.
    Specified by:
      `setWrapper` in interface `ContainerServlet`
    Parameters:
      `wrapper` - The new wrapper

  - ### destroy

    public void destroy()
    Finalize this servlet.
    Specified by:
      `destroy` in interface `Servlet`
    Overrides:
      `destroy` in class `GenericServlet`

  - ### doGet

    public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
    Process a GET request for the specified resource.
    Overrides:
      `doGet` in class `HttpServlet`
    Parameters:
      `request` - The servlet request we are processing
      `response` - The servlet response we are creating
    Throws:
      `IOException` - if an input/output error occurs
      `ServletException` - if a servlet-specified error occurs
    See Also:
      - `ServletResponse.setContentType(java.lang.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: `jakarta.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

    protected File getConfigBase(String hostName)
    Get config base.
    Parameters:
      `hostName` - The host name
    Returns:
      the config base for the host