TomcatManager¶
-
class
tomcatmanager.tomcat_manager.
TomcatManager
¶ 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 = '', password: str = '') → tomcatmanager.models.TomcatManagerResponse¶ Connect to a Tomcat Manager server.
Parameters: url – url where the Tomcat Manager web application is deployed :param user: (optional) user to authenticate with :param password: (optional) password to authenticate with :return: TomcatManagerResponse()
objectYou don’t have to connect before using any other commands. If you initialized the object with credentials you can call any other method. This method:
- 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 make an HTTP request to the server and see if it returns successfully. 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
TomcatManager.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
objectRaises: 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
objectRaises: 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
objectRaises: 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
objectRaises: 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
objectRaises: 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
objectRaises: 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
objectRaises: 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 theresult
attribute and thesessions
attributeRaises: 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
object with the session summary in both theresult
attribute and thesessions
attributeRaises: 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 additionalapps
attribute which contains a list ofTomcatApplication
objectsUsage:
>>> 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 additionalserver_info
attributeThe
server_info
attribute contains aServerInfo
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 additionalstatus_xml
attributeUsage:
>>> 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 additionalvm_info
attribute
-
ssl_connector_ciphers
() → tomcatmanager.models.TomcatManagerResponse¶ Get SSL/TLS ciphers configured for each connector.
Returns: TomcatManagerResponse
object with an additionalssl_connector_ciphers
attribute
-
thread_dump
() → tomcatmanager.models.TomcatManagerResponse¶ Get a jvm thread dump.
Returns: TomcatManagerResponse
object with an additionalthread_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 additionalresources
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 additionalleakers
attributeThe
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
-