<document>
<header>
<product>resin</product>
<title>Instrumenting Resources</title>
<description>
<p>
The facilities of JMX are a convenient way to provide an administration
interface to objects and components in web applications.  
</p>
</description>
</header>

<body>
<summary/>

<s1 title="Instrumenting Resources">

<p>Instrumenting resources so JMX can manage them consists
of the following steps:</p>

<ol>
<li>For a class <code>MyFoo</code>, create an interface <code>MyFooMBean</code> with
the management interface.
</li><li>Class <code>MyFoo</code> needs to <var>implement</var> the <code>MyFooMBean</code> interface.
</li><li>Register <code>MyFoo</code> with the JMX server.
</li></ol>

<s2 title="Instrumenting a servlet">

<p>Resin will automatically register any servlet which
implement an MBean interface.  By default, the JMX name will be:</p>

<def>
web-app:j2eeType=Servlet,name=<var>servlet-name</var>
</def>

<deftable title="ObjectName attributes">
<tr><th>Attribute</th><th>Value
</th></tr><tr><td>j2eeType</td><td>Servlet
</td></tr><tr><td>WebModule</td><td>the <var>contextPath</var>
</td></tr><tr><td>J2EEApplication</td><td>the host?
</td></tr><tr><td>J2EEServer</td><td>the server-id?
</td></tr></deftable>

<p>The domain is <var>web-app</var>, the type property
is javax.servlet.Servlet and the name property is the value
of &lt;servlet-name&gt;.</p>

<p>JMX clients will use the name to manage the servlet.  For example,
a client might use the pattern <var>web-app:type=javax.servlet.Servlet,*</var>
to retrieve all managed servlets.</p>

<example title="MyServletMBean.java">
package test;

public interface MyServletMBean {
  public int getCount();
}
</example>

<example title="MyServlet.java">
package test;

import java.io.*;
import javax.servlet.*;

public class MyServlet extends GenericServlet implements MyServletMBean {
  private int count;

  public int getCount()
  {
    return count;
  }

  public void service(ServletRequest request,
                      ServletResponse response)
    throws IOException
  {
    PrintWriter out = response.getWriter();

    count++;

    out.println("Hello, world");
  }
}
</example>

</s2>

</s1>

<s1 title="Managing Resources">

<p>Managing resources uses the JMX API, primarily using
the <code>MBeanServer</code> object.  In Resin, each web-app has
its own <code>MBeanServer</code>.</p>

<example title="Getting the Count attribute">
import javax.management.*;

...

MBeanServer server = MBeanServerFactory.createMBeanServer();

ObjectName name = new ObjectName("web-app:j2eeType=javax.servlet.Servlet," +
                                 "name=hello");

Object value = server.getAttribute(name, "Count");

out.println("Count: " + value);
</example>

<s2 title="/resin-status">

<p>The <a href="doc|jmx|servlet">resin-status servlet</a> has a
primitive generic JMX management view of JMX managed servlets.
By adding a MBean interface to your servlet, you'll automatically get
a view of your servlets from /resin-status.
</p>

</s2>

</s1>

  </body>
</document>