URL of the article:

Building Digital Dashboards with JSP Tag Libraries
Managing Tomcat with the IO Tag Library
by Alan M Berg
Monitoring of a typical Enterprise environment may involve interaction with a complex series of protocols. Within this article I will describe a simplistic approach through the application of the Jakarta IO tag library to monitor and control one server type—Tomcat.

Introduction
Monitoring in a distributed, web enabled environment can be difficult. Tools such as Multi Router Traffic Grapher (MRTG) and Big Sister (see Resources & References section) are excellent for obtaining and viewing statistics generated from polling SNMP enabled devices. Within the Microsoft Windows realm, SNMP and WMI (read WBEM derivative) are the main standards of interest. Monitoring tools vary from software that simply pings a series of devices to complex agent based data collection structures. But the question for the builder of a typical Web based Java application is, `How do you plug into such an environment?'.

Java Management Extensions (JMX) is a standard part of Java 1.5. (Various aspects of JMX have been mentioned in JSRs 3, 70, 71, 77, 146, 160, 174.) The JMX standard allows for a uniform method of monitoring and controlling distributed systems. Tomcat and JBoss are among the many applications that are JMX enabled. In this article I will briefly outline JMX and explain how to directly or indirectly interact with Tomcats JMX features via the Jakarta IO tag library. From a few simple JSP pages, you will be able to manage and monitor various aspects of the Tomcat environment.

JMX Overview
JMX is a set of patterns and APIs that are a standard part of the Java 1.5 SDK. The details of JMX can be daunting at a first viewing. Avoiding unnecessary details: JMX separates responsibility for monitored applications into parts so that programmers can concentrate on application specific details. To enable remote control of any given application, the application builder creates MBeans. Depending on the type of MBean, the bean can return statistics, send notifications, and have methods evoked. For example, you may have a property named queueSize that once is varied, changes exactly that in the application. The MBean is hosted on an MServer that in turn may be connected through adapters to the outside world. JMX, as a standard, communicates via RMI. Tomcat 5 and onwards are enabled and Tomcat 4 can be enabled.

Figure 1 explains a slightly more complex situation. The MBean server interacts with the monitoring dashboard via adapters. (The adapters are for the Remote Method Invocation (RMI) and Simple Network Management Protocol (SNMP) protocols.) The Hyper Text Transfer Protocol (HTTP) adapter speaks with JSP pages via the Jakarta IO tag library. A significant advantage of the adapter pattern is easier plugin to your monitoring solutions. SNMP is particularly important for monitoring via standard programs. SNMP has been the staple diet of system administrators since the mid to late 80's. JMX Java libraries communicating through RMI are typical for a programmatic approach via standard libraries in Java 1.5. HTTP is the most interesting at a practical level if you wish to pass seamlessly through most firewall configurations. Avoiding or adding extra rules for firewalls was one of the motivations for the development of SOAP. Therefore HTML and SOAP adapters are the most efficient for distributed Internet services.


Figure 1: An Example JMX Infrastructure

In the following sections, we will explore one example of using HTML with JMX, which is the JMXproxy inbuilt in the manager application of Tomcat 5 and above. Through the use of example code, I will show you how to log onto the application and receive metrics over the system and modify parameters.

Preparing Tomcat
The JMX proxy works out of the box with Tomcat. However, the real trick with the proxy is to know the locations of the MBeans in the namespace of the MServer. In the next section, I will describe the use of JConsole to browse the namespace. But first we need to enable JMX through RMI. This is achieved via setting the JAVA_OPTS environment viable before running Tomcat, like this: 

-Dcom.sun.management.jmxremote

-Dcom.sun.management.jmxremote.port=9000

-Dcom.sun.management.jmxremote.authenticate=false

-Dcom.sun.management.jmxremote.ssl=false

The JAVA_OPTS settings tell Tomcat to enable Port 9000 to listen for JMX. Since no authentication is required to allow interaction, this is a potentially dangerous situation and should only be allowed in a secured test environment.

Windows users should look under the {tomcat_home}/bin directory for tomcat5w. Run the binary and add the same lines under the Java tag, as shown in Figure 2. If the Tomcat server fails to start (as was true in my efforts), change the account that the Tomcat server is running under, from local system to an administrator account.


Figure 2: Screen Grab of Configuration Settings in the tomcat5w Binary

JConsole and MC4JMX
JConsole is a standard tool contained within the bin directory of the SDK. Run the tool and make an anonymous connection to port 9000. The next step is to familiarize yourself with the namespace structure. As an exercise, see if you can change any values or run any methods. If you look further, you can even find passwords. In a production environment, therefore, you would need to separate the roles of administrators by defining read and write accountants.


Figure 3: A screen grab of the Jconsole in action with Tomcat 5.5

Tomcat HTML Management
Tomcat does not have any adapters other than an MServer that communicates via RMI. Rather, it has its own application that translates HTTP requests into JMX related actions. Tomcat also has other operations that are controlled via HTTP. I will step you through a brief review of this pragmatic methodology in this section. (In the next section, I will detail how to use the Jakarta IO tag library within this context.)

Note that the IO tag library can also speak with FTP servers and SOAP. So it has much more potential than is mentioned.

To perform an action requires logging on to the manager application via basic authentication and adding extra parts to the URL. For example, to list all web applications and their status, you will need to browse to a URL similar to the following: 

https://HOST:port/manager/list

To list the server info, use: 

http://Host:port/manager/serverinfo

which will return a response similar to this: 

OK - Server info

Tomcat Version: Apache Tomcat/5.5.12

OS Name: Windows XP

OS Version: 5.1

OS Architecture: x86

JVM Version: 1.5.0_06-b05

JVM Vendor: Sun Microsystems Inc.

To list the user roles, use: 

https://HOST:PORT/manager/roles

To obtain default session information, send a query with the path to the context whose session information you wish for. For example, the following query: 

http://localhost:8080/manager/sessions?path=/

produces a result similar to: 

OK - Session information for application at context path /

Default maximum session inactive interval 30 minutes

To list JNDI resources for example database, LDAP setting, and such, use the following query: 

http://Host:PORT/manager/resources

which will produce a result similar to: 

OK - Listed global resources of all types

UserDatabase:org.apache.catalina.users.MemoryUserDatabase

simpleValue:java.lang.Integer

The following is an example URL, for finding java.lang.Integer instances: 

http://localhost:8081/manager/resources?type=java.lang.Integer

To start or stop, or undeploy a web application, use: 

http://localhost:8080/manager/start?path={context_path}

http://localhost:8080/manager/stop?path={context_path}

http://localhost:8080/manager/undeploy?path={context_path}

Note: Undeployment may have unexpected side effects. For example, I sometimes found that specific JAR files under the webapps/lib directory failed to be removed.

The JMXproxy can query or set Bean properties. The syntax for querying is as follows: 

http(s)://host:port/manager/jmxproxy/?query=namespace name of bean ,name of attribute to return.

Following is an example: 

https://localhost:8080/manager/jmxproxy/?qry=

Catalina:type=Environment,resourcetype=Global,name=simpleValue

To set a value, follow the syntax: 

http://host:port/manager/jmxproxy?set=namespace url for bean,name of attribute,value of attribute

Following is an example: 

http://127.0.0.1:8080/manager/jmxproxy/?set=

Catalina:type=Environment,resourcetype=Global,name=simpleValue&att=value&val=5

The Jakarta IO Tag Library
In the last section we saw that after basic authentication we can monitor and manage the Tomcat server. In this section I will explain how to use the Jakarta IO tag library for such purposes. The idea, of course, is not to monitor one Tomcat server but multiple servers. Further, the tag library needs to be flexible enough to deal with SOAP, and perhaps FTP, for monitoring systems that may be protected via layered firewall infrastructures. The Jakarta IO tag library fulfils these requirements. To use the tag library, drop the downloaded JAR file in the WEB-INF/lib directory and add the tag lib as shown in line one of Listing 1.

Listing 1: Code Highlighting Basic IO Functionality 

1 <%@taglib uri="http://jakarta.apache.org/taglibs/io-1.0" prefix="io" %>

2 <%@page import="java.net.*" %>

3 <%@page import="java.io.*"%>

4 <%

5   URL inFile = pageContext.getServletContext().getResource(

6 "/data/monitor_file.txt" );

7   File file = File.createTempFile( "output-", ".html" );

8   FileWriter fWriter = new FileWriter( file );

9 %>

10 <io:request url='<%= inFile.toString() %>'

11 <io:http url="http://localhost:8080/ARTICLE2/data/monitor_http.txt"/>

12 <io:pipe writer="<%= fWriter %>">

13    <io:http url="http://localhost:8080/ARTICLE2/data/monitor_http.txt"/>

14 </io:pipe>

15 <%

16     fWriter.flush();

17     fWriter.close();

18 %>

Listing 1 does a couple of things. It reads a local file and displays that file in an HTML page. It also gets and displays a text file from the Internet. Lines 5 to 8 gets the local text file from a path relative to the web application. Line 10 is the first IO tag you have encountered—the ¬tag gets and displays the resource mentioned in the URL attribute. The resource may be one of the following types:
  • file system
  • FTP
  • HTTP
  • HTTPS
  • XML-RPC
  • SOAP
The HTTP tag of line 10 has an expanded syntax allowing for fine control of GET and POST requests. Lines 1-14 show you how to pipe output from an embedded HTTP tag to a writer. This is extra complexity, but is handy when you want to pipe from one set of tag libraries to some random piece of Java code.

Listing 2 posts information to the http_report.jsp page as mentioned in Listing 3, adding an arbitrary header TEST=Hello Word and Post data x=1&y=2&z=3 is equivalent to sending the parameters x,y,z. An HTML page is returned by http_report.jsp, displaying header and parameter information.

Listing 2: IO HTTP Example where the Sent Header is Modified 

1 <%@taglib uri="http://jakarta.apache.org/taglibs/io-1.0" prefix="io" %>

2 <io:http url="http://localhost:8081/ARTICLE2/http_report.jsp"/>

3 <io:http url="http://localhost:8081/ARTICLE2/http_report.jsp" action="POST">

4   <io:header name="TEST" value="Hello World"/>

5   <io:body>

6   x=1&y=2&z=3

7   </io:body>

8 </io:http>

Listing 3: A JSP page that Returns the Header and Parameter Information from a Request 

1 <%@page import="java.util.*"%>

2 <%

3    Enumeration headerNames = request.getHeaderNames();

4    while (headerNames.hasMoreElements()) {

5         String headerName = (String)headerNames.nextElement();

6         out.println("<li>"+headerName+":"+request.getHeader(headerName)+"\n");

7    }

8    Enumeration parameterNames = request.getParameterNames();

9   while (parameterNames.hasMoreElements()) {

10         String parameterName = (String)parameterNames.nextElement();

11         out.println("<li>"+parameterName+": "

12                       +request.getParameter(parameterName)+"\n");

13   }

14 %>

Before moving to the Tomcat manager application, we need to defend the manager a little better from the outside world. The easiest way to achieve this is via an IP restriction list. A valve (or a filter) is a piece of plumbing within Tomcat. If it is enabled, the filter will look at every incoming request for the context it is configured for. The Java pattern is known as the chain of responsibility as the filter may pipe into other filters. Tomcat has a filter for IP restrictions. By adding the valve to the manage context, you can force the context to work only for the local address. During testing I would recommend doing so. You will need to modify the conf/server.xml file, as shown: 

<Context path="/manager" debug="0" privileged="true"

docBase="/usr/local/tomcat/server/webapps/manager">

<Valve className="org.apache.catalina.valves.RemoteAddrValve"allow="127.0.0.1"/>

</Context>

Next we will need to work out how to achieve basic authentication via HTTP headers. The Apache SOAP project has a rather nice TCP Tunnel/Monitor. The monitor listens at a certain port number and displays the HTTP request, passing the request on to another port. If you have the SOAP library [as mentioned in the Resources & References section] in your CLASSPATH, you can run the library via the following command: 

java -cp soap.jar org.apache.soap.util.net.TcpTunnelGui 8079 localhost 808

At this point, the monitor waits for your browser to talk to port 8079 and passes the requests on to 8080. Therefore, typing the URL http://localhost:8079/manager/list, and typing in your username and password, will display something similar to Figure 4.


Figure 4: Screen grab of the Tunnel GUI contained in the Soap libraries from Apache.

As you can see in the screen grab, the basic authentication is achieved via a header of type Authorization: Basic base64 encoded username, password. So to login and perform actions is simply to add a header to the HTTP tag, like this: 

<io:http url="http://localhost:8081/manager/jmxproxy?" >

<io:header name="Authorization" value="Basic xxxxxxxxxxxxx

</io:http>

JSP Tags for JMX
HTTP, SOAP adapters or HTML proxies can be integrated into your personalized dashboard via the IO tag library. JConsole and other RMI adapter clients are also handy tools for browsing within the perimeter of a firewalled enclave. JSP tag libraries for this type of situation can be found in the open source WebJMX project or in the commercial product by Coldjava. It is recommended to stick to HTTP or SNMP [as much as possible] since it will simplify integration later.

Conclusions
The Jakarta IO tag library can provide additional glue to help with monitoring your distributed applications. However, if you want to directly interact with JMX you should decide between using a specific application such as MC4J, or create a customization yourself. For fast to build, rough and ready solutions one can imagine creating an almost pure JSP product.

Coming Next
In the concluding article in the series I will seek to find ways to make JSP pages as interactive as possible. I will look especially hard at JSP in combination with AJAX and JavaScript technologies.

Alan Berg, Bsc. MSc. MSc. PGCE, has been a lead developer at the Central Computer Services at the University of Amsterdam for the last seven years. In his spare time, he writes computer articles. He has a degree, two masters and a teaching qualification. In previous incarnations, he was a technical writer, an Internet/Linux course writer, and a science teacher. He likes to get his hands dirty with the building and gluing of systems. He remains agile by playing computer games with his kids who (sadly) consistently beat him.

Resources & References
© 2004 Software & Support Verlag GmbH. Reproduction has to be permitted by the publisher. Questions?