You may have seen that the Tomcat project participated in the Google Summer of Code (GSOC) this year. This year, Chamith Buddhika has been working on improving the JMX support. In particular the aims were:

  • Aligning the attributes and methods exposed via JMX with reality. The JMX descriptions and the actual code had diverged over time and there were many missing entries as well as entries that no longer worked.
  • Making it possible to fully configure a Tomcat instance over JMX.

It is this second objective that I am writing about today. With the most recent changes to Tomcat 7 trunk (you'll need to build from svn or wait until 7.0.3 to use these features) it is now possible to start an absolute bare minimum Tomcat instance and perform all the configuration via JMX.

To try this out for yourself, you'll need to start with a standard Tomcat install (if building from trunk the contents of output/build will be fine) and reduce server.xml to the bare minimum. Something like this:

Then start Tomcat along with JConsole and connect JConsole to your newly started Tomcat instance. In the MBean tab in JConsole, you should see a number of Tomcat MBeans including one named "Catalina:type=MBeanFactory". Navigate to this MBean and use the "createStandardServiceEngine" method to create a Service and an Engine. There is a one-to-one mapping between Service and Engine so they are created together. For domain and defaultHost I use the standard values "Catalina" and "localhost" respectively. You can change these if you wish. baseDir must be the full path to CATALINA_BASE.

The next step is to add a Host to the Engine, configure the Host and start it. To add the Host, navigate to the Engine you just created and use the addChild operation. The type should be "org.apache.catalina.core.StandardHost" and the name must match the name you used for the defaultHost attribute when creating the Engine. The default configuration for the Host should allow you to start it, so navigate to the new Host element and use the start operation. You should see all the Contexts found in webapps being automatically deployed.

Finally, you need to add a Connector so you can test your configuration. Navigate to the Service element you created earlier and select the addConnector operation. If you don't specify an address, the Connector will listen on all IP addresses assigned to the machine where Tomcat is running. You must specify a port (I used the standard value of 8080) and you'll want to set isAjp and isSSL to false.

With this complete, you should be able to point your browser at localhost:8080 and see the standard Tomcat ROOT application.

The main purpose of improving the JMX features was to allow management tools better visibility and control over Tomcat instances. For example, a management tool could keep track of the current required configuration and dynamically configure the Tomcat instance via JMX both while the instance is running and when the instance is restarted. This would allow a management tool to have full control over a Tomcat instance's configuration without having to keep the management tool's view of the Tomcat configuration and the instance's server.xml file in sync.

The JMX improvements are still a work in progress. There are still a number of operations and attributes that don't work correctly. As always patches to improve the situation are very welcome. If you'd like to get involved in this effort - or any other aspect of Tomcat development - please subscribe to the Tomcat dev list and drop the developer community a note.