// Author: Bela Ban
// $Id: JmxSupport.txt,v 1.2 2005/06/14 14:00:59 belaban Exp $



JMX support for JGroups
=======================

In 2.2.9, JMX support was added to JGroups. There were several design goals:

- No dependencies on JMX if JMX support is not required. It should be possible to ship a JGroups version without any
JMX support, and without jmxri.jar (for JDK 1.4.x). Therefore channels and protocols are not turned into MBeans, e.g.
FD doesn't implement FDMBean. Instead, a parallel MBean and MBeanImpl hierarchy was created, where the MBeanImpl
delegates to the real protocol. This hierarchy is located in package org.jgroups.jmx.
For a protocol org.jgroups.protocols.P, there is a corresponding org.jgroups.jmx.protocols.PMBean
MBean and an implementation org.jgroups.jmx.protocols.P

- No negative effect on performance, minimal effect on memory. JMX support can be disabled in the channel, and
all protocols (stats="false")

- Support for running in a pre-JMX JDK (1.4, for example), e.g. under JBoss. There is a jgroups-service target in
the ANT build which generates a jgroups-service.sar that can be deployed into JBoss. The channel defines in the
META-INF/jboss-service.xml file of the SAR defines a JGroups channel MBean, which will automatically create MBeans
for all protocols and register them with the MBeanServer

- Support for running in JDK 5 standalone. JDK 5 has JMX support built in. The jconsole tool can be used to inspect the
MBean hierarchy.
To programmatically create MBean support for JDK 5, the following code can be used:

JChannel channel;
channel.connect(groupname);
ArrayList servers=MBeanServerFactory.findMBeanServer(null);
if(servers == null || servers.size() == 0) {
    throw new Exception("No MBeanServers found;" +
                        "\nJmxTest needs to be run with an MBeanServer present, or inside JDK 5");
}
MBeanServer server=(MBeanServer)servers.get(0);
JmxConfigurator.registerChannel(channel, server, "JGroups:channel=" + channel.getChannelName() , true);

JmxConfigurator has a number of helper methods which register and de-register the channel and/or te protocols
attached to a given channel.


Provided information
--------------------
Some information provided includes (all info can be reset), besides configuration:
- UDP: messages sent/received, bytes sent/received (per member)
- Discovery: manual triggering of discovery
- NAKACK: retransmissions per member, last N retransmitted messages,
  lowest and highest sequence numbers per member
- GMS: membership, history of views
- FD/FD_SOCK: last N suspected members
- STATE_TRANSFER: number of state requests, total bytes transferred
- STABLE: manual triggering of STABLE protocol


Example
-------
The Draw program was modified to support JMX. The following steps describe how to configure and run a JDK 5 VM and
look at the resulting Draw application via jconsole.
- Run the Draw program (the JDK needs to be 5 !):
  java -Dcom.sun.management.jmxremote org.jgroups.demos.Draw -props c:\fc-fast.xml -jmx
  (the -jmx flag enables registering the Channel and protocols with the MBeanServer)
- Start jconsole and connect to the local Draw process
- Under 'MBeans', choose the JGroups channel and browse the channel and the protocols
- [optional] Add the STATS protocol to the top of the stack; it display information about messages sent
  and received