net.sf.snmpadaptor4j
Class SnmpAdaptor

java.lang.Object
  javax.management.StandardMBean
      net.sf.snmpadaptor4j.SnmpAdaptor

All Implemented Interfaces:

DynamicMBean, MBeanRegistration, SnmpDaemonConfiguration, SnmpAdaptorMBean, SnmpAppContext, SnmpConfiguration

public class SnmpAdaptor
extends StandardMBean
implements SnmpConfiguration, SnmpAppContext, SnmpAdaptorMBean

snmpAdaptor4j is an adaptor for Java Management eXtensions (JMX) providing a simple access to MBeans via the SNMP protocol. Thus, this adapter you allow to connect most monitoring tools (like Nagios and Cacti) to your Java applications.

For each MBean, an XML mapping file allows to establish the relationships between attributes and the MIB of the SNMP adapter. No additional code is necessary to integrate the MBeans in the SNMP protocol.

This adapter can work in a multi-applications environment (such as application servers).

Building of the mapping files

For each MBean of your project, create the mapping file in the same package as the MBean. For example:

<?xml version="1.0" encoding="utf-8"?>
<snmpAdaptor4j-mapping
xmlns="http://www.sf.net/snmpAdaptor4j/mapping/1.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.sf.net/snmpAdaptor4j/mapping/1.1
http://snmpAdaptor4j.sourceforge.net/xsd/snmpAdaptor4j-mapping-1.1.xsd">

<attributes>
<attribute name="attributA" type="integer32" node="1" writable="true"/>
<attribute name="attributB" type="counter64" node="2" writable="false"/>
<attribute name="attributC" type="gauge32" node="3" writable="false"/>
</attributes>

</snmpAdaptor4j-mapping>

Here, we map only MBean attributes by indicating the SNMP data type and the node constituting the OID (Object IDentifier). The mapping of MBean instances, is generally put in the configuration file (see next chapter).

Building of the configuration file

Create the configuration file (one by application) like this:

<?xml version="1.0" encoding="utf-8"?>
<snmpAdaptor4j-config
xmlns="http://www.sf.net/snmpAdaptor4j/config/1.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.sf.net/snmpAdaptor4j/config/1.1
http://snmpAdaptor4j.sourceforge.net/xsd/snmpAdaptor4j-config-1.1.xsd">

<daemon address="127.0.0.1" port="161" version="2">
<readCommunity>public</readCommunity>
<writeCommunity>private</writeCommunity>
</daemon>

<roots default="1.3.6.1.4.1.99.12.8.1"/>

<mbeans>
<mbean name="fr.mydomain.myAppli:type=MyClass,name=objA" oid="1.1"/>
<mbean name="fr.mydomain.myAppli:type=MyClass,name=objB" oid="1.2"/>
</mbeans>

</snmpAdaptor4j-config>

Here, we define the OID for each instance of MBeans. The OID of an attribute, is built as follows:

${root}.${mbean oid}.${attribute node}.0

For example, the attributB OID of first MBean will be 1.3.6.1.4.1.99.12.8.1.1.1.2.0.

Registration and start of adaptor

Insert the following code to install the adapter inside JMX:

URL url = getClass().getResource("/snmp.xml");
SnmpAdaptor adaptor = new SnmpAdaptor(url, true);
ObjectName name = new ObjectName("net.sf.snmpadaptor4j:adaptor=SnmpAdaptor");
ManagementFactory.getPlatformMBeanServer().registerMBean(adaptor, name);

snmp.xml is the configuration file previously built.

Update the information about your system:

adaptor.getSystemInfo().setSysName("MyApp");
adaptor.getSystemInfo().setSysDescr("This is a java application");
adaptor.getSystemInfo().setSysLocation("Web server at Montpellier (France)");
adaptor.getSystemInfo().setSysContact("root@mydomain.fr");

Start the adaptor:

snmpAdaptor.start();

Test

Install the Net-SNMP commands and type:

snmpwalk -v2c -Os -c public 127.0.0.1 .1

You should see the attribute values of your MBean.

Author:

Jean-Philippe MINETTI

Field Summary

protected Map<ClassLoader,SnmpAppContext>

appContextMap Application context map.

Constructor Summary

	SnmpAdaptor(boolean classLoaderScope) Constructor with a minimum of parameters.
	SnmpAdaptor(SnmpAppContext appContext, boolean classLoaderScope) Constructor with an application context.
	SnmpAdaptor(SnmpConfiguration configuration, SnmpAppContext appContext, SystemInfo systemInfo, boolean classLoaderScope) Constructor with all parameters.
protected	SnmpAdaptor(String defaultRootOid, SnmpConfiguration configuration, boolean classLoaderScope, SystemSnmpMib systemMib, JvmSnmpMib jvmMib, JmxListener jmxListener, JmxNotificationManager jmxNotificationManager, SnmpDaemon daemon) Hidden constructor (used for tests only).
	SnmpAdaptor(URL url, boolean classLoaderScope) Constructor with an URL to SNMP configuration file (XML).
	SnmpAdaptor(URL url, SystemInfo systemInfo, boolean classLoaderScope) Constructor with an URL to SNMP configuration file (XML) and a SystemInfo.

Method Summary

void	addAppContext(ClassLoader classLoader, SnmpAppContext appContext) Adds a new application context.
protected static String	formatAttribute(String value) Formats an attribute value.
String	getDefaultRootOid() Returns the default root OID containing the attributes of the application.
String	getListenerAddress() Returns the listening IP address of SNMP daemon (127.0.0.1 by default).
Integer	getListenerPort() Returns the UDP port of SNMP daemon (161 by default).
String	getListenerReadCommunity() Returns the read community of SNMP daemon ("public" by default).
Integer	getListenerSnmpVersion() Returns the protocol version of SNMP daemon (SNMP v2 by default).
String	getListenerWriteCommunity() Returns the write community of SNMP daemon ("private" by default).
List<SnmpManagerConfiguration>	getManagerList() Returns the parameter list to connect to each manager where to send all notifications (SNMP traps).
Map<ObjectName,String>	getMBeanOidMap() Returns the map of MBean OIDs.
Map<String,String>	getRootOidMap() Returns the map of root OIDs where the attributes of the application will stay.
SystemInfo	getSystemInfo() Returns the informations on the system.
boolean	isStarted() Returns TRUE if the SNMP daemon is started.
void	preDeregister()
ObjectName	preRegister(MBeanServer server, ObjectName name)
void	removeAppContext(ClassLoader classLoader) Removes an application context.
void	setListenerAddress(String listenerAddress) Sets the listening IP address of SNMP daemon.
void	setListenerPort(Integer listenerPort) Sets the UDP port of SNMP daemon.
void	setListenerReadCommunity(String listenerReadCommunity) Sets the read community of SNMP daemon.
void	setListenerSnmpVersion(Integer listenerSnmpVersion) Sets the protocol version of SNMP daemon.
void	setListenerWriteCommunity(String listenerWriteCommunity) Sets the write community of SNMP daemon.
void	start() Starts the SNMP daemon.
void	stop() Stops the SNMP daemon.
String	toString()

Methods inherited from class javax.management.StandardMBean

cacheMBeanInfo, getAttribute, getAttributes, getCachedMBeanInfo, getClassName, getConstructors, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getImpact, getImplementation, getImplementationClass, getMBeanInfo, getMBeanInterface, getParameterName, getParameterName, invoke, postDeregister, postRegister, setAttribute, setAttributes, setImplementation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

appContextMap

protected final Map<ClassLoader,SnmpAppContext> appContextMap

Application context map.

Constructor Detail

SnmpAdaptor

public SnmpAdaptor(boolean classLoaderScope)
            throws Exception

Constructor with a minimum of parameters.

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

Throws:

Exception - Exception if an error has occurred.

SnmpAdaptor

public SnmpAdaptor(SnmpAppContext appContext,
                   boolean classLoaderScope)
            throws Exception

Constructor with an application context.

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

appContext - Application context.

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

Throws:

Exception - Exception if an error has occurred.

SnmpAdaptor

public SnmpAdaptor(URL url,
                   boolean classLoaderScope)
            throws Exception

Constructor with an URL to SNMP configuration file (XML).

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

url - URL of SNMP configuration file (XML).

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

Throws:

Exception - Exception if an error occurred.

SnmpAdaptor

public SnmpAdaptor(URL url,
                   SystemInfo systemInfo,
                   boolean classLoaderScope)
            throws Exception

Constructor with an URL to SNMP configuration file (XML) and a SystemInfo.

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

url - URL of SNMP configuration file (XML).

systemInfo - Informations on the system.

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

Throws:

Exception - Exception if an error occurred.

SnmpAdaptor

public SnmpAdaptor(SnmpConfiguration configuration,
                   SnmpAppContext appContext,
                   SystemInfo systemInfo,
                   boolean classLoaderScope)
            throws Exception

Constructor with all parameters.

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

configuration - SNMP configuration settings.

appContext - Application context.

systemInfo - Informations on the system.

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

Throws:

Exception - Exception if an error has occurred.

SnmpAdaptor

protected SnmpAdaptor(String defaultRootOid,
                      SnmpConfiguration configuration,
                      boolean classLoaderScope,
                      SystemSnmpMib systemMib,
                      JvmSnmpMib jvmMib,
                      JmxListener jmxListener,
                      JmxNotificationManager jmxNotificationManager,
                      SnmpDaemon daemon)
               throws Exception

Hidden constructor (used for tests only).

Set TRUE to classLoaderScope for web applications: this avoids to publish MBeans of other applications of application server.

Parameters:

defaultRootOid - Default root OID containing the attributes of the application.

configuration - SNMP configuration settings.

classLoaderScope - TRUE for handle only MBeans created by the same ClassLoader that the SNMP adapter. FALSE for handle all MBeans of the JVM.

systemMib - Management Information Base (MIB) for system attributes.

jvmMib - Management Information Base (MIB) for attributes of JVM.

jmxListener - Object designed to respond to each registration or deregistration of MBeans.

jmxNotificationManager - Manager of JMX notifications.

daemon - SNMP daemon.

Throws:

Exception - Exception if an error has occurred.

Method Detail

addAppContext

public void addAppContext(ClassLoader classLoader,
                          SnmpAppContext appContext)

Description copied from interface: SnmpAdaptorMBean

Adds a new application context.

SnmpAdaptor4j may be used by an application server. In this case you will inform the SNMP adapter to each deployment of a new application.

Specified by:

addAppContext in interface SnmpAdaptorMBean

Parameters:

classLoader - Class loader of application.

appContext - Application context.

removeAppContext

public void removeAppContext(ClassLoader classLoader)

Description copied from interface: SnmpAdaptorMBean

Removes an application context.

Specified by:

removeAppContext in interface SnmpAdaptorMBean

Parameters:

classLoader - Class loader of application.

getListenerAddress

public final String getListenerAddress()

Description copied from interface: SnmpDaemonConfiguration

Returns the listening IP address of SNMP daemon (127.0.0.1 by default).

Specified by:

getListenerAddress in interface SnmpDaemonConfiguration

Specified by:

getListenerAddress in interface SnmpAdaptorMBean

Returns:

Listening IP address.

setListenerAddress

public final void setListenerAddress(String listenerAddress)

Description copied from interface: SnmpAdaptorMBean

Sets the listening IP address of SNMP daemon.

Specified by:

setListenerAddress in interface SnmpAdaptorMBean

Parameters:

listenerAddress - Listening IP address.

getListenerPort

public final Integer getListenerPort()

Description copied from interface: SnmpDaemonConfiguration

Returns the UDP port of SNMP daemon (161 by default).

Specified by:

getListenerPort in interface SnmpDaemonConfiguration

Specified by:

getListenerPort in interface SnmpAdaptorMBean

Returns:

UDP port.

setListenerPort

public final void setListenerPort(Integer listenerPort)

Description copied from interface: SnmpAdaptorMBean

Sets the UDP port of SNMP daemon.

Specified by:

setListenerPort in interface SnmpAdaptorMBean

Parameters:

listenerPort - UDP port.

getListenerSnmpVersion

public final Integer getListenerSnmpVersion()

Description copied from interface: SnmpDaemonConfiguration

Returns the protocol version of SNMP daemon (SNMP v2 by default).

Specified by:

getListenerSnmpVersion in interface SnmpDaemonConfiguration

Specified by:

getListenerSnmpVersion in interface SnmpAdaptorMBean

Returns:

SNMP protocol version.

setListenerSnmpVersion

public final void setListenerSnmpVersion(Integer listenerSnmpVersion)

Description copied from interface: SnmpAdaptorMBean

Sets the protocol version of SNMP daemon.

Specified by:

setListenerSnmpVersion in interface SnmpAdaptorMBean

Parameters:

listenerSnmpVersion - SNMP protocol version.

getListenerReadCommunity

public final String getListenerReadCommunity()

Description copied from interface: SnmpDaemonConfiguration

Returns the read community of SNMP daemon ("public" by default).

Specified by:

getListenerReadCommunity in interface SnmpDaemonConfiguration

Specified by:

getListenerReadCommunity in interface SnmpAdaptorMBean

Returns:

Read community of SNMP daemon.

setListenerReadCommunity

public final void setListenerReadCommunity(String listenerReadCommunity)

Description copied from interface: SnmpAdaptorMBean

Sets the read community of SNMP daemon.

Specified by:

setListenerReadCommunity in interface SnmpAdaptorMBean

Parameters:

listenerReadCommunity - Read community of SNMP daemon.

getListenerWriteCommunity

public final String getListenerWriteCommunity()

Description copied from interface: SnmpDaemonConfiguration

Returns the write community of SNMP daemon ("private" by default).

Specified by:

getListenerWriteCommunity in interface SnmpDaemonConfiguration

Specified by:

getListenerWriteCommunity in interface SnmpAdaptorMBean

Returns:

Write community of SNMP daemon.

setListenerWriteCommunity

public final void setListenerWriteCommunity(String listenerWriteCommunity)

Description copied from interface: SnmpAdaptorMBean

Sets the write community of SNMP daemon.

Specified by:

setListenerWriteCommunity in interface SnmpAdaptorMBean

Parameters:

listenerWriteCommunity - Write community of SNMP daemon.

getManagerList

public final List<SnmpManagerConfiguration> getManagerList()

Description copied from interface: SnmpConfiguration

Returns the parameter list to connect to each manager where to send all notifications (SNMP traps).

Specified by:

getManagerList in interface SnmpAdaptorMBean

Specified by:

getManagerList in interface SnmpConfiguration

Returns:

Parameter list to connect to each manager.

getDefaultRootOid

public final String getDefaultRootOid()

Description copied from interface: SnmpAppContext

Returns the default root OID containing the attributes of the application.

Specified by:

getDefaultRootOid in interface SnmpAppContext

Returns:

Default root OID.

getRootOidMap

public final Map<String,String> getRootOidMap()

Description copied from interface: SnmpAppContext

Returns the map of root OIDs where the attributes of the application will stay.

Specified by:

getRootOidMap in interface SnmpAppContext

Returns:

Map of root OIDs (never NULL but can be empty).

getMBeanOidMap

public final Map<ObjectName,String> getMBeanOidMap()

Description copied from interface: SnmpAppContext

Returns the map of MBean OIDs.

Specified by:

getMBeanOidMap in interface SnmpAppContext

Returns:

Map of MBean OIDs (never NULL but can be empty).

start

public void start()
           throws Exception

Description copied from interface: SnmpAdaptorMBean

Starts the SNMP daemon.

Specified by:

start in interface SnmpAdaptorMBean

Throws:

Exception - Exception if an error has occurred.

stop

public void stop()
          throws Exception

Description copied from interface: SnmpAdaptorMBean

Stops the SNMP daemon.

Specified by:

stop in interface SnmpAdaptorMBean

Throws:

Exception - Exception if an error has occurred.

isStarted

public final boolean isStarted()

Description copied from interface: SnmpAdaptorMBean

Returns TRUE if the SNMP daemon is started.

Specified by:

isStarted in interface SnmpAdaptorMBean

Returns:

TRUE if the SNMP daemon is started.

getSystemInfo

public final SystemInfo getSystemInfo()

Returns the informations on the system.

The returned object is a MBean. It is possible to register it in JMX.

Returns:

Informations on the system.

formatAttribute

protected static final String formatAttribute(String value)

Formats an attribute value.

Parameters:

value - Value to format.

Returns:

Value formatted.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Specified by:

preRegister in interface MBeanRegistration

Overrides:

preRegister in class StandardMBean

Throws:

Exception

preDeregister

public void preDeregister()
                   throws Exception

Specified by:

preDeregister in interface MBeanRegistration

Overrides:

preDeregister in class StandardMBean

Throws:

Exception

toString

public String toString()

Overrides:

toString in class Object