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

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: jakarta.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: jakarta.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(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