TomcatManager¶

class tomcatmanager.tomcat_manager.TomcatManager¶

Bases: object

A class for interacting with the Tomcat Manager web application.

Here’s a summary of the recommended way to use this class with proper exception and error handling. For this example, we’ll use the server_info() method.

>>> import tomcatmanager as tm
>>> url = 'http://localhost:8080/manager'
>>> user = 'ace'
>>> password = 'newenglandclamchowder'
>>>
>>> tomcat = tm.TomcatManager()
>>> try:
...     r = tomcat.connect(url, user, password)
...     if r.ok:
...         r = tomcat.server_info()
...         if r.ok:
...             print(r.server_info)
...         else:
...             print('Error: {}'.format(r.status_message))
...     else:
...         print('Error: not connected')
... except Exception as err:
...     # handle exception
...     print('Error: not connected')
Error: not connected

connect(url: str, user: str = None, password: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Connect to a Tomcat Manager server.

Parameters:	url – url where the Tomcat Manager web application is deployed user – (optional) user to authenticate with password – (optional) password to authenticate with
Returns:	TomcatManagerResponse object

You don’t have to connect before using any other commands. If you initialized the object with credentials you can call any other method. The purpose of connect() is to:

give you a way to change the credentials on an existing object
provide a convenient mechanism to validate you can actually connect to the server
allow you to inspect the response so you can see why you can’t connect

Usage:

>>> import tomcatmanager as tm
>>> url = 'http://localhost:8080/manager'
>>> user = 'ace'
>>> password = 'newenglandclamchowder'
>>>
>>> tomcat = tm.TomcatManager()
>>> try:
...     r = tomcat.connect(url, user, password)
...     if r.ok:
...         print('connected')
...     else:
...         print('not connected')
... except Exception as err:
...     # handle exception
...     print('not connected')
not connected

The only way to validate whether we are connected is to actually get a url. Internally this method tries to retrieve /manager/text/serverinfo.

Requesting url’s via http can raise all kinds of exceptions. For example, if you give a URL where no web server is listening, you’ll get a requests.connections.ConnectionError. However, this method won’t raise exceptions for everything. If the credentials are incorrect, you won’t get an exception unless you ask for it.

Requesting url’s via http can also result in redirection to another url. If that occurs, the new url, not the one you passed, will be stored in the url attribute.

You can also use is_connected() to check if you are connected.

If you want to raise more exceptions see TomcatManagerResponse.raise_for_status().

is_connected¶

Does the url point to an actual tomcat server and are the credentials valid?

Returns:	True if connected to a tomcat server, otherwise, False.

deploy_localwar(path: str, warfile: str, version: str = None, update: bool = False) → tomcatmanager.models.TomcatManagerResponse¶

Deploy a warfile on the local file system to the Tomcat server.

Parameters:	path – The path on the server to deploy this war to, i.e. /sampleapp warfile – The path (specified using your local operating system convention) to a war file on the local file system. You can also pass a stream or file-like object. This will be sent to the server for deployment. version – (optional) For tomcat parallel deployments, the version string to associate with this deployment update – (optional) Whether to undeploy the existing path first (default False)
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is specified; if no warfile is specified

deploy_serverwar(path: str, warfile: str, version: str = None, update: bool = False) → tomcatmanager.models.TomcatManagerResponse¶

Deploy a warfile on the local file system to the Tomcat server.

Parameters:	path – The path on the server to deploy this war to, i.e. /sampleapp warfile – The java-style path (use slashes not backslashes) to the war file on the server. Don’t include `file:` at the beginning. version – (optional) For tomcat parallel deployments, the version string to associate with this deployment update – (optional) Whether to undeploy the existing path first (default False)
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is given; if no warfile is given

deploy_servercontext(path: str, contextfile: str, warfile: str = None, version: str = None, update: bool = False) → tomcatmanager.models.TomcatManagerResponse¶

Deploy a Tomcat application defined by a context file.

Parameters:	path – The path on the server to deploy this war to, i.e. /sampleapp contextfile – The java-style path (use slashes not backslashes) to the context file on the server. Don’t include `file:` at the beginning. warfile – (optional) The java-style path (use slashes not backslashes) to the war file on the server. Don’t include `file:` at the beginning. version – (optional) For tomcat parallel deployments, the version string to associate with this deployment update – (optional) Whether to undeploy the existing path first (default False)
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is given; if no contextfile is given

undeploy(path: str, version: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Undeploy the application at a given path.

Parameters:	path – The path of the application to undeploy version – (optional) The version string of the app to undeploy
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is specified

If the application was deployed with a version string, it must be specified in order to undeploy the application.

start(path: str, version: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Start the application at a given path.

Parameters:	path – The path of the application to start version – (optional) The version string of the app to start
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is specified

If the application was deployed with a version string, it must be specified in order to start the application.

stop(path: str, version: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Stop the application at a given path.

Parameters:	path – The path of the application to stop version – (optional) The version string of the app to stop
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is specified

If the application was deployed with a version string, it must be specified in order to stop the application.

reload(path: str, version: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Reload (stop and start) the application at a given path.

Parameters:	path – The path of the application to reload version – (optional) The version string of the app to reload
Returns:	TomcatManagerResponse object
Raises:	ValueError – if no path is specified

If the application was deployed with a version string, it must be specified in order to reload the application.

sessions(path: str, version: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Get the age of the sessions in an application.

Parameters:	path – The path of the application to get session information about version – (optional) The version string of the app to get session information about
Returns:	TomcatManagerResponse object with the session summary in both the `result` attribute and the `sessions` attribute
Raises:	ValueError – if no path is specified

Usage:

>>> tomcat = getfixture('tomcat')
>>> r = tomcat.sessions('/manager')
>>> if r.ok:
...     session_data = r.sessions

expire(path: str, version: str = None, idle: Any = None) → tomcatmanager.models.TomcatManagerResponse¶

Expire sessions idle for longer than idle minutes.

Parameters:	path – the path to the app on the server whose sessions you want to expire idle – sessions idle for more than this number of minutes will be expired. Use idle=0 to expire all sessions.
Returns:	TomcatManagerResponse with the session summary in the `result` attribute and in the `sessions` attribute
Raises:	ValueError – if no path is specified

Usage:

>>> tomcat = getfixture('tomcat')
>>> r = tomcat.expire('/manager', idle=15)
>>> if r.ok:
...     expiration_data = r.sessions

list() → tomcatmanager.models.TomcatManagerResponse¶

Get a list of all applications currently installed.

Returns:	TomcatManagerResponse object with an additional `apps` attribute which contains a list of TomcatApplication objects

Usage:

>>> import tomcatmanager as tm
>>> tomcat = getfixture('tomcat')
>>> r = tomcat.list()
>>> if r.ok:
...     running = filter(lambda app: app.state == tm.application_states.running, r.apps)

server_info() → tomcatmanager.models.TomcatManagerResponse¶

Get information about the Tomcat server.

Returns:	TomcatManagerResponse object with an additional `server_info` attribute

The server_info attribute contains a ServerInfo object, which is a dictionary with some added properties for well-known values returned from the Tomcat server.

Usage:

>>> tomcat = getfixture('tomcat')
>>> r = tomcat.server_info()
>>> if r.ok:
...     r.server_info['OS Name'] == r.server_info.os_name
True

status_xml() → tomcatmanager.models.TomcatManagerResponse¶

Get server status information in XML format.

Returns:	TomcatManagerResponse object with an additional `status_xml` attribute

Usage:

>>> import xml.etree.ElementTree as ET
>>> tomcat = getfixture('tomcat')
>>> r = tomcat.status_xml()
>>> if r.ok:
...     root = ET.fromstring(r.status_xml)
...     mem = root.find('jvm/memory')
...     print('Free Memory = {}'.format(mem.attrib['free'])) 
Free Memory ...

Tomcat 8.0 doesn’t include application info in the XML, even though the docs say it does.

vm_info() → tomcatmanager.models.TomcatManagerResponse¶

Get diagnostic information about the JVM.

Returns:	TomcatManagerResponse object with an additional `vm_info` attribute

ssl_connector_ciphers() → tomcatmanager.models.TomcatManagerResponse¶

Get SSL/TLS ciphers configured for each connector.

Returns:	TomcatManagerResponse object with an additional `ssl_connector_ciphers` attribute

thread_dump() → tomcatmanager.models.TomcatManagerResponse¶

Get a jvm thread dump.

Returns:	TomcatManagerResponse object with an additional `thread_dump` attribute

resources(type_: str = None) → tomcatmanager.models.TomcatManagerResponse¶

Get the global JNDI resources available for use in resource links for context config files

Parameters:	type – (optional) Fully qualified java class name of the resource type you are interested in. For example, pass `javax.sql.DataSource` to acquire the names of all available JDBC data sources.
Returns:	TomcatManagerResponse object with an additional `resources` attribute.

Usage:

>>> tomcat = getfixture('tomcat')
>>> r = tomcat.resources()
>>> if r.ok:
...     print(r.resources)
{'UserDatabase': 'org.apache.catalina.users.MemoryUserDatabase'}

resources is a dictionary with the resource name as the key and the class name as the value.

find_leakers() → tomcatmanager.models.TomcatManagerResponse¶

Get apps that leak memory.

Returns:	TomcatManagerResponse object with an additional `leakers` attribute

The leakers attribute contains a list of paths of applications which leak memory.

This command triggers a full garbage collection on the server. Use with extreme caution on production systems.

Explicity triggering a full garbage collection from code is documented to be unreliable. Furthermore, depending on the jvm, there are options to disable explicit GC triggering, like `-XX:+DisableExplicitGC`. If you want to make sure this command triggered a full GC, you will have to verify using something like GC logging or JConsole.

The Tomcat Manager documentation says the server can return duplicates in this list if the app has been reloaded and was leaking both before and after the reload. The list returned by the leakers attribute will have no duplicates in it.

Usage:

>>> tomcat = getfixture('tomcat')
>>> r = tomcat.find_leakers()
>>> if r.ok:
...     cnt = len(r.leakers)
... else:
...     cnt = 0