[Jakarta HiveMind Wiki] New: JmxDoc

[hi...@jakarta.apache.org]

   Date: 2005-02-26T15:29:28
   Editor: AchimHuegen
   Wiki: Jakarta HiveMind Wiki
   Page: JmxDoc
   URL: http://wiki.apache.org/jakarta-hivemind/JmxDoc

   no comment

New Page:

AchimHuegen, Feb 26 2005

This page describes HiveMinds support for the Java Management Extension (JMX).
JMX support is not currently available in the official 1.1 release but hopefully
will be include soon.

= How to get started =

Ok, you want to build in jmx support in your HiveMind application.
Actually there are two topics to talk about now:
 * How to connect to the application?
 * What to manage?

But for the impatient ones, that just want to get up anything to play with 
here are some quick start instructions:

== J2SE 1.4 / Tomcat 5.0.x - Quickstart ==

Add these lines to your (web) application's hivemind descriptor:

{{{
  <contribution configuration-id="hivemind.EagerLoad">
    <load service-id="hivemind.management.MBeanRegistry"/>
  </contribution>

  <contribution configuration-id="hivemind.management.MBeans">
	<mbean service-id="hivemind.management.connector.HttpAdaptorMBean" start-method="start" />
	<mbean service-id="hivemind.management.log4j.LogManagementMBean" />
  </contribution>

  <contribution configuration-id="hivemind.management.log4j.ManagedLog4jLoggers">
  	<logger name="hivemind.*" />
  </contribution>	  

}}}

Ensure that mx4j.jar and mx-tools.jar (mx4j 2.0.1) and log4j.jar are include in the classpath of your application. Start your application/tomcat and enter http://localhost:9000 in your browser. Read on [#QuickStartResults here]

== J2SE 1.5 - Quickstart ==

Add these lines to your application's hivemind descriptor:

{{{
  <contribution configuration-id="hivemind.EagerLoad">
    <load service-id="hivemind.management.MBeanRegistry"/>
  </contribution>

  <contribution configuration-id="hivemind.management.MBeans">
	<mbean service-id="hivemind.management.log4j.LogManagementMBean" />
  </contribution>

  <contribution configuration-id="hivemind.management.log4j.ManagedLog4jLoggers">
  	<logger name="hivemind.*" />
  </contribution>	  

}}}

Ensure that mx4j.jar (mx4j 2.0.1) and log4j.jar are include in the classpath of your application. Start the application (it should run some time), start jconsole
and connect to the local application.

[[Anchor(QuickStartResults)]]
== Quick start results ==

What you get from the quick start is the ability to manage the Log4j loggers used by the hivemind framework. Look for MBeans in the "hivemind" domain of type "logger". 
For example: hivemind:module=hivemind,type=logger,id=BuilderFactory.

You can change the log level (priority) and add appenders without restarting 
the application.

= Details =

== Export services as MBeans ==

Services can be registered as MBean very easily by a contribution to "mbeans":
{{{
<contribution configuration-id="hivemind.management.mbeans" >
    <mbean service-id="test.management.Calculator" />
</contribution>
}}}

Now the complete service interface is available via jmx.
(There are some datatype constraints and the servicemodel should be primitive or singleton)

Have a look at the Calculator MBean (test.management.service.Calculator). You can do some calculations on the jconsole operations tab.
Double click on the 'sum' attribute to get a graph of the sum over time.
This is the corresponding service interface :

{{{public interface Calculator
{
    public int getSum();
    
    public void add(int value);
    
    public void subtract(int value);
    
    public void multiply(int value);
    
    public void clear();
}
}}}

== Performance interceptor ==

The interceptor PerformanceMonitor collects statistical data about calls to the intercepted service.
The results are sent to a newly created mbean. For each service method it displays: number of calls,
maximum, minimum, average and last execution duration.

The mbean test.management.service.Calculator.PerformanceCollector displays these values for the Calculator service.
So just execute some calculations and watch the statistical data changing. 
Double clicking the attribute values displays a graph.

== Monitor ==

Though creation of jmx monitors is not automated a monitor can easily defining as service point using the standard builderfactory functionality.
Such a monitor can watch the attribute of another mbean (for example the average execution time of a service method) and 
send notifications, if a treshold is crossed.

The mbean test.management.service.CalculatorSumMonitor monitors the sum attribute of the calculator service (attribute DerivedGauge). Click the subscribe button on the notification tab to get notified when the calculator sum gets above 100.

= Implementation details =

== Dependencies ==

The implementation uses JMX 1.2 and supports JSR 160 for remote management (via jconsole, mc4j etc.)
It is depending on MX4J but is working fine with Sun RI and J2SE 1.5 too.
The dependency could be broken up, but there is no standardized way for creating an HTMLAdaptor.

= Remarks =

== Services as MBeans ==

It doesn't always make sense to use the service interface as MBean interface like in the calculator example. It would be nice to separate between service and management interface. Problem: As soon as an service model other that primitive is used or the service is intercepted, the management interface is no longer accessible. 
The reason is, that interceptors and proxies are limited to a single interface. This is already a problem for standard MBeans, that implement MBean lifecycle events.
There are two possible solutions:
 * Interceptors and proxies populate multiple/all interfaces of a service. This was already discussed on the mailing list
 * There must be a way to access the core service instance 

















---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-cvs-help@jakarta.apache.org