Jmx

Professional Open Source™

Java Management Extension Using JMX in JBoss

© JBoss, Inc. 2003-2005.

8/2/2005

1

JMX in JBoss Professional Open Source™

Defines architecture and API for application management. – Specification defines a component called Managed Beans a.k.a MBeans – JBoss uses MBeans as service implementations

Agent – MBeanServer – JBoss uses MBean Server as an invocation bus in the microkernel

Distribution Layer (JSR-160) – Defines remote connectors and protocol adaptors – HTTP, RMI, SOAP, SNMP, JMS, ... – Used for connecting to the microkernel in JBoss – JBoss uses ‘invoker’ terminology

© JBoss, Inc. 2003-2005.

2

1

Why JMX ? Professional Open Source™

JMX decouples service implementations (via invocation bus). – Detaching the client from the resource allows the service to move or redeploy dynamically (24x7). – Detyping the invocation allows the management interface to evolve without affecting the client. – Ability to build generic management tools that will work on any JMX enabled J2EE platform.

3

© JBoss, Inc. 2003-2005.

JMX Architecture Professional Open Source™

MBeanServer is in the core (the agent). – MBeanServer is not distributed by default, it is local to the JVM. – You need to deploy connector services for remote access ability

Services can be plugged in as needed. – Dynamically at run-time – The services are implemented as MBeans.

Distribution achieved via connectors and protocol adaptors. – These are implemented as MBeans too.

© JBoss, Inc. 2003-2005.

4

2

JMX Architecture Professional Open Source™

Server JVM Service MBean

Browser Browser

Adaptor Adaptor

MBean Server Server MBean

Management Management Management Client Client Client

Connector Connector Proxy

Service MBean

Service MBean

5

© JBoss, Inc. 2003-2005.

JMX Architecture Professional Open Source™

The management client never has a direct Java reference to the managed resource. – Uses an ObjectName reference instead. – This allows the managed resources to move or redeploy dynamically.

lookup

MBean Server Server MBean

invoke(ObjectName,...)

Client

MBean MBean

invoke(...)

MBean MBean Repository Repository

© JBoss, Inc. 2003-2005.

6

3

JMX Architecture Professional Open Source™

Invocation is not statically typed. – The management interface may evolve without affecting the client.

class A {

class B implements M {

M reference; }

}

class A { MBeanServer srvr;

srvr.invoke(name, method,

Class MBeanServerImpl

args, signature);

implements MBeanServer {

ObjectName name; String method; Object[] args; String[] signature

}

}

7

© JBoss, Inc. 2003-2005.

JMX Object Naming (1/2) Professional Open Source™

MBeans are registered in the JMX bus with an ObjectName Any client can invoke operations on an MBean by using its ObjectName Each ObjectName is unique – The structure is <domain> : [ = ] { , = } Example: jboss:service=invoker,type=jrmp

© JBoss, Inc. 2003-2005.

8

4

JMX Object Naming (2/2) Professional Open Source™

The [ =] pairs can be used by clients to make queries on the MBeanServer and get a list of corresponding MBeans – Example: Querying JBossMX for “service=invoker” will return – JRMP – HTTP – IIOP – Local

Programmatic queries on MBean attribute names and values – Example: Querying for an MBean that has an attribute “Port” in value range >= 8000

9

© JBoss, Inc. 2003-2005.

Instrumentation: MBeans Professional Open Source™

MBean has a management interface – management attributes – management operations – management notifications

The MBean Server provides the meta data that describes the management interface for all of its registered MBeans. – Either uses inspection on the management interface, or invokes a specific method on the service implementation to retrieve the interface descriptions (meta-data)

© JBoss, Inc. 2003-2005.

10

5

Instrumentation: Standard MBeans Professional Open Source™

– Managed resource must implement a Java interface – The interface must be named after your class + “MBean” extension

public class MyClass implements MyClassMBean { // interface implementation goes here }

Interface declares attributes and operations – Attribute declaration follows the get/set method naming convention – Attribute can be read-only, write-only or read-write – All other methods are taken as operations

11

© JBoss, Inc. 2003-2005.

Instrumentation: Standard MBeans Professional Open Source™

public publicinterface interfaceMyClassMBean MyClassMBean{{ ////read-write read-writeattribute attribute‘State’ ‘State’of oftype typeString String String StringgetState(); getState(); void voidsetState(String setState(Stringstate); state); ////reset resetoperation operation reset(); reset(); }} public publicclass classMyClass MyClassimplements implementsMyClassMBean MyClassMBean{{ private privateString Stringstate state==“NOT_INITIALIZED”; “NOT_INITIALIZED”; public publicString StringgetState() getState() {{ return returnstate; state;}} public publicvoid voidsetState(String setState(Stringstate) state){{this.state this.state==state; state;}} public publicString StringgetHidden() getHidden(){{return return“All “Allgetters gettersare arenot notautomatically automaticallyMBean MBeanattributes.”; attributes.”;}} public publicvoid voidreset() reset(){{ ////implement implementreset resetoperation operationhere here }} }} © JBoss, Inc. 2003-2005.

12

6

Instrumentation: Standard MBeans Professional Open Source™

•

Attributes are accessed via getAttribute() and setAttribute() MBeanServer server = (MBeanServer)MBeanServerFactory.findMBeanServer(null).get(0); ObjectName oname = new ObjectName(“:name=MyClass”); server.registerMBean(new MyClass(), oname); ... server.setAttribute(oname, new Attribute(“State”, “INIT”); String state = (String)server.getAttribute(oname, “State”);

•

Operations are executed via invoke() MBeanServer server = (MBeanServer)MBeanServerFactory.findMBeanServer(nulll).get(0); ObjectName oname = new ObjectName(“:name=MyClass”); server.registerMBean(new MyClass(), oname); ... server.invoke(oname, “reset”, new Object[] {}, // empty argument list new String[] {}); // void signature

13

© JBoss, Inc. 2003-2005.

Instrumentation: Standard MBeans Professional Open Source™

Dynamic proxy for typed interface

MBean Interface

Invocation Invocation Handler Handler

public class JMXInvocationHandler implements InvocationHandler { Object invoke(Object proxy, Method method, Object[] args) { if (…) { server.setAttribute(…); } else if (…) { server.getAttribute(…); } else server.invoke(oname, method.getName(), …); }

import javax.management.MBeanServerInvocationHandler; MyClassMBean mbean = (MyClassMBean)MBeanProxy.get(MyClassMBean.class, oname, server); mbean.setState(“INIT”); mbean.reset(); © JBoss, Inc. 2003-2005.

14

7

Instrumentation: MBean Inheritance Professional Open Source™

The management interface may be inherited by subclasses.

MyClass

MyClassMBean

getState(); setState(Integer);

getState(); setState(Integer);

reset();

reset();

MySubClass The MySubClass automatically exposes the same management interface as its super class. There is no need to declare MySubClassMBean interface.

15

© JBoss, Inc. 2003-2005.

Instrumentation: MBean Inheritance Professional Open Source™

The subclass may override the existing management interface. – Here MySubClass does not have a State R/W attribute

MyClass

MyClassMBean

getState(); setState(Integer);

getState(); setState(Integer);

reset();

reset();

MySubClass

MySubClassMBean reset();

© JBoss, Inc. 2003-2005.

16

8

Notification Mechanism Professional Open Source™

Allows other MBeans and management applications to react to changes in a managed bean. Follows the design of JavaBean event mechanism. – Notification class is a subclass of java.util.EventObject – Observers implement the NotificationListener interface. – Introduces filters with NotificationFilter interface. – Broadcasting MBeans implement the NotificationBroadcaster interface.

Notifications are part of the MBean’s management interface.

17

© JBoss, Inc. 2003-2005.

Instrumentation: Dynamic MBeans Professional Open Source™

Dynamic MBeans implement the DynamicMBean interface. There is no statically typed Java interface which declares the management interface. – The management interface can be determined at run-time instead of compile time.

The MBean developer declares the management using the MBean meta data classes. – For standard MBeans this was done automatically via introspection by the MBean server.

The developer has more control over what management information is available in the meta data.

© JBoss, Inc. 2003-2005.

18

9

Instrumentation: Dynamic MBean Professional Open Source™

– Managed resource implements DynamicMBean interface – The implementation of attribute accessor methods, operation invoke and metadata structure is left to the developer

public interface DynamicMBean { public Object getAttribute(String attribute); public void setAttribute(Attribute attribute); public AttributeList getAttributes(String[] attributes); public AttributeList setAttributes(AttributeList attributes); public Object invoke(String actionName, Object[] params, String[] signature); public MBeanInfo getMBeanInfo(); }

19

© JBoss, Inc. 2003-2005.

MBean Meta Data Professional Open Source™

The agent discovers the management interface through the getMBeanInfo() method. The meta data consists of the following classes: – MBeanInfo • MBeanFeatureInfo – common name, description used by others Infos • MBeanAttributeInfo – attribute type, accessor info • MBeanOperationInfo – method info • MBeanConstructorInfo – MBean ctor info • MBeanNotificationInfo – Event notification info • MBeanParameterInfo – common name, type for ctor, method params

© JBoss, Inc. 2003-2005.

20

10

Dynamic MBean Implementation (1/2) Professional Open Source™

– The developer is responsible of mapping the management attributes and operations to their corresponding implementations – Developer responsible for checking the validity of invocations – Allows dynamic behavior public class MyClass implements DynamicMBean { private String state = “NOT_INITIALIZED”; public Object getAttribute(String attribute) { if (attribute.equals(“State”)) return state; } public void setAttribute(Attribute attribute) { … } public Object invoke(String actionName, Object[] params, String[] signature) { if (actionName.equals(“reset”) && params.length == 0) reset(); … }

21

© JBoss, Inc. 2003-2005.

Dynamic MBean Implementation (2/2) Professional Open Source™

public MBeanInfo getMBeanInfo() { boolean IS_READABLE = true; boolean IS_WRITABLE = true; return new MBeanInfo(“MyClass”, “This is my managed resource”, new MBeanAttributeInfo[] { new MBeanAttributeInfo(“State”, “java.lang.String”, “The state attribute describes the runtime state of the service.”, IS_READABLE, IS_WRITABLE, false); }, new MBeanConstructorInfo[] {}, new MBeanOperationInfo[] { new MBeanOperationInfo(“reset”, “The reset operation sets the service to NOT_INITIALIZED state.”, new MBeanParameterInfo[] {}, “void”, MBeanOperationInfo.ACTION) }, new MBeanNotificationInfo[] {} ); }

• You can retrieve the meta data from an external source © JBoss, Inc. 2003-2005.

22

11

Model MBeans: XMBeans in JBoss Professional Open Source™

Model MBeans – Take the pain out of Dynamic MBeans with template MBeans – The server provides the implementation you use it to define new MBeans easily. – Many services available to MMBeans through mandated interfaces PersistentMBean: Persistence of values in MBeans ModelMBeanNotificationBroadcaster: attribute change notification

23

© JBoss, Inc. 2003-2005.

XMBeans Professional Open Source™

XMBeans – JBossMX implementation of the ModelMBean from the specification – Use it when you want to create DynamicMBean with little work through an easy XML configuration

Persistence: ModelMBeans define persistence for the cached values in the MBean – load() and store() api calls from the PersistentMBean interface

– The decision to store: The persist policy never, OnUpdate, OnTimer, NoMoreOftenThan

JBossMX provides a simple serialized representation of the data – A DelegatingPersistenceManager with an external persistence service and a default XMLAttributePersistenceManager backend, also available.

© JBoss, Inc. 2003-2005.

24

12

XMBean DTD jboss_xmbean_1_1.dtd (Part 1) Professional Open Source™

25

© JBoss, Inc. 2003-2005.

XMBean DTD jboss_xmbean_1_1.dtd (Part 2) Professional Open Source™

© JBoss, Inc. 2003-2005.

26

13

Model MBean Example Professional Open Source™

Creating a standard JMX RequiredModelMBean instance will in fact be an XMBean with JBossMX implementation.

import javax.management.modelmbean.RequiredModelMBean; … RequiredModelMBean rmm = new RequiredModelMBean(); SomeObject myObject = new SomeObject(); // configure Model MBean instance with the managed // object reference rmm.setManagedResource(myObject); rmm.setModelMBeanInfo(getMetaData()); server.registerMBean(rmm, new ObjectName(“:name=MyModelMBean”);

27

© JBoss, Inc. 2003-2005.

XMBean Example Professional Open Source™

<mbean code="org.jboss.jmx.connector.invoker.InvokerAdaptorService" name="jboss.jmx:type=adaptor,name=Invoker“ xmbean-dd=""> <xmbean> <description>The JMX Detached Invoker Service org.jboss.jmx.connector.invoker.InvokerAdaptorService <description>The class name of the MBean Name java.lang.String <description>The status of the MBean State int <description>The status of the MBean in text form StateString java.lang.String

© JBoss, Inc. 2003-2005.

28

14

XMBean Example Professional Open Source™

<description>The interfaces the invoker proxy supports ExportedInterfaces [Ljava.lang.Class; <description>Map(Long hash, Method) of the proxy interface methods MethodMap java.util.Map <description>The start lifecycle operation start <description>The stop lifecycle operation stop

29

© JBoss, Inc. 2003-2005.

XMBean Example, jmx-invoker-adaptor-server.sar Professional Open Source™

… <description>The detached invoker entry point invoke <parameter> <description>The method invocation context invocation org.jboss.invocation.Invocation java.lang.Object org.jboss.jmx.adaptor.rmi.RMIAdaptor, org.jboss.jmx.adaptor.rmi.RMIAdaptorExt © JBoss, Inc. 2003-2005.

30

15

XMBean Persistence Professional Open Source™

Persistence Interceptor triggers store()

ModelMBeanAttribute Interceptor performs caching

MBeanServer

XMBean XMBean

Persistence Persistence Manager Manager

Target Resource (POJO)

Metadata & Descriptors (cached values, etc.)

Persists values “set” through the XMBean.

XMBean Lifecycle CTOR xmbean “value” sets load() once save() anytime (policy based) attribute overrides create() start() stop() destroy() GC

If POJO modifies attributes internally, XMBean does not know!

31

© JBoss, Inc. 2003-2005.

XMLAttributePersistenceManager Professional Open Source™

Default implementation providing simple, visible, file-based persistence Strategy – – – –

Null values will be marked as such XML Element will be saved as XML. A PropertyEditor for converting to Text will be used, if available. If the value is Serializable and serialization is succesful it will be saved as a hex encoded string (ala CORBA IOR) – If all fails, record an XML comment and log a warning

Default storage location – ./data/xmbean-attrs/

File name mangling E.g. jboss.jmx@[email protected] © JBoss, Inc. 2003-2005.

32

16

Example - docs/examples/jmx/persistent-service.sar Professional Open Source™

<xmbean> <description>PersistentServiceExample <descriptors> org.jboss.jmx.examples.persistence.PersistentServiceExample ...

33

© JBoss, Inc. 2003-2005.

Example - docs/examples/jmx/persistent-service.sar Professional Open Source™

Attribute Format: VALUE

Produced XML file: ./data/xmbean-attrs/jboss.jmx@[email protected]

31400000000000000 true <some-message>Welcome to the Athens 2004, Olympic Games! 666 888 I've got the devil inside me ACED0005737200126A6176612E73716C2E54696D657374616D7026 18D5C80153BF6 50200014900056E616E6F737872000E6A6176612E7574696C2E44617465686A81014B59 74190300007870770800 0000FE922D3F207808B3C880 © JBoss, Inc. 2003-2005.

34

17

Agent Layer: MBeanServer Interface Professional Open Source™

public interface MBeanServer { public ObjectInstance createMBean(String className, ObjectName name) throws ... ; public ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName) throws ... ; public ObjectInstance registerMBean(Object object, ObjectName name) throws ...; public void unregisterMBean(ObjectName name) throws ... ; ... public Object getAttribute(ObjectName name, String attribute) throws ... ; public AttributeList getAttributes(ObjectName name, String[] attributes) public void setAttribute(ObjectName name, Attribute attribute) throws ... ; public AttributeList setAttributes(ObjectName name, AttributeList attributes) ... public Object invoke(ObjectName name, String operation, Object params[], String signature[]) throws ... ; ... public void addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) throws ... ; public void removeNotificationListener(ObjectName name, NotificationListener listener) throws .. ... public MBeanInfo getMBeanInfo(ObjectName name) throws ... ; }

35

© JBoss, Inc. 2003-2005.

Conclusion Professional Open Source™

JMX decouples components from each other – No references are exposed outside MBean Server

MBean exposes its interface as metadata – Standard MBeans are introspected based on naming convention – Dynamic and Model MBeans are responsible of returning their own descriptions

Model MBean implementation in JBoss supports – Persistence – Interceptors – XML configuration and deployment

© JBoss, Inc. 2003-2005.

36

18