FileDocCategorySizeDatePackage
MBeanServerInvocationHandler.javaAPI DocJava SE 5 API10828Fri Aug 26 14:57:32 BST 2005javax.management

MBeanServerInvocationHandler

public class MBeanServerInvocationHandler extends Object implements InvocationHandler

{@link InvocationHandler} that forwards methods in an MBean's management interface through the MBean server to the MBean.

Given an {@link MBeanServerConnection}, the {@link ObjectName} of an MBean within that MBean server, and a Java interface Intf that describes the management interface of the MBean using the patterns for a Standard MBean, this class can be used to construct a proxy for the MBean. The proxy implements the interface Intf such that all of its methods are forwarded through the MBean server to the MBean.

If you have an MBean server mbs containing an MBean with {@link ObjectName} name, and if the MBean's management interface is described by the Java interface Intf, you can construct a proxy for the MBean like this:

Intf proxy = (Intf)
MBeanServerInvocationHandler.{@link #newProxyInstance newProxyInstance}(mbs,
name,
Intf.class,
false);

Suppose, for example, Intf looks like this:

public interface Intf {
public String getSomeAttribute();
public void setSomeAttribute(String value);
public void someOperation(String param1, int param2);
}

Then you can execute:

  • proxy.getSomeAttribute() which will result in a call to mbs.{@link MBeanServerConnection#getAttribute getAttribute}(name, "SomeAttribute").
  • proxy.setSomeAttribute("whatever") which will result in a call to mbs.{@link MBeanServerConnection#setAttribute setAttribute}(name, new Attribute("SomeAttribute", "whatever")).
  • proxy.someOperation("param1", 2) which will be translated into a call to mbs.{@link MBeanServerConnection#invoke invoke}(name, "someOperation", <etc>).

If the last parameter to {@link #newProxyInstance newProxyInstance} is true, then the MBean is assumed to be a {@link NotificationBroadcaster} or {@link NotificationEmitter} and the returned proxy will implement {@link NotificationEmitter}. A call to {@link NotificationBroadcaster#addNotificationListener} on the proxy will result in a call to {@link MBeanServerConnection#addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)}, and likewise for the other methods of {@link NotificationBroadcaster} and {@link NotificationEmitter}.

The methods {@link Object#toString()}, {@link Object#hashCode()}, and {@link Object#equals(Object)}, when invoked on a proxy using this invocation handler, are forwarded to the MBean server as methods on the proxied MBean. This will only work if the MBean declares those methods in its management interface.

since
1.5
since.unbundled
JMX 1.2

Fields Summary
private final MBeanServerConnection
connection
private final ObjectName
objectName
Constructors Summary
public MBeanServerInvocationHandler(MBeanServerConnection connection, ObjectName objectName)

Invocation handler that forwards methods through an MBean server. This constructor may be called instead of relying on {@link #newProxyInstance}, for instance if you need to supply a different {@link ClassLoader} to {@link Proxy#newProxyInstance Proxy.newProxyInstance}.

param
connection the MBean server connection through which all methods of a proxy using this handler will be forwarded.
param
objectName the name of the MBean within the MBean server to which methods will be forwarded.

	this.connection = connection;
	this.objectName = objectName;
	/* Could check here whether the MBean exists.  */
Methods Summary
public java.lang.Objectinvoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args)

	final Class methodClass = method.getDeclaringClass();

	if (methodClass.equals(NotificationBroadcaster.class)
	    || methodClass.equals(NotificationEmitter.class))
	    return invokeBroadcasterMethod(proxy, method, args);

	final String methodName = method.getName();
	final Class[] paramTypes = method.getParameterTypes();
	final Class returnType = method.getReturnType();

	/* Inexplicably, InvocationHandler specifies that args is null
	   when the method takes no arguments rather than a
	   zero-length array.  */
	final int nargs = (args == null) ? 0 : args.length;

	if (methodName.startsWith("get")
	    && methodName.length() > 3
	    && nargs == 0
	    && !returnType.equals(Void.TYPE)) {
	    return connection.getAttribute(objectName,
					   methodName.substring(3));
	}

	if (methodName.startsWith("is")
	    && methodName.length() > 2
	    && nargs == 0
	    && (returnType.equals(Boolean.TYPE)
		|| returnType.equals(Boolean.class))) {
	    return connection.getAttribute(objectName,
					   methodName.substring(2));
	}

	if (methodName.startsWith("set")
	    && methodName.length() > 3
	    && nargs == 1
	    && returnType.equals(Void.TYPE)) {
	    Attribute attr = new Attribute(methodName.substring(3), args[0]);
	    connection.setAttribute(objectName, attr);
	    return null;
	}

	final String[] signature = new String[paramTypes.length];
	for (int i = 0; i < paramTypes.length; i++)
	    signature[i] = paramTypes[i].getName();
	try {
	    return connection.invoke(objectName, methodName, args, signature);
	} catch (MBeanException e) {
	    throw e.getTargetException();
	}
	/* The invoke may fail because it can't get to the MBean, with
	   one of the these exceptions declared by
	   MBeanServerConnection.invoke:
	   - RemoteException: can't talk to MBeanServer;
	   - InstanceNotFoundException: objectName is not registered;
	   - ReflectionException: objectName is registered but does not
	     have the method being invoked.
	   In all of these cases, the exception will be wrapped by the
	   proxy mechanism in an UndeclaredThrowableException unless
	   it happens to be declared in the "throws" clause of the
	   method being invoked on the proxy.
	*/
private java.lang.ObjectinvokeBroadcasterMethod(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args)

	final String methodName = method.getName();
	final int nargs = (args == null) ? 0 : args.length;

	if (methodName.equals("addNotificationListener")) {
	    /* The various throws of IllegalArgumentException here
	       should not happen, since we know what the methods in
	       NotificationBroadcaster and NotificationEmitter
	       are.  */
	    if (nargs != 3) {
		final String msg =
		    "Bad arg count to addNotificationListener: " + nargs;
		throw new IllegalArgumentException(msg);
	    }
	    /* Other inconsistencies will produce ClassCastException
	       below.  */

	    NotificationListener listener = (NotificationListener) args[0];
	    NotificationFilter filter = (NotificationFilter) args[1];
	    Object handback = args[2];
	    connection.addNotificationListener(objectName,
					       listener,
					       filter,
					       handback);
	    return null;

	} else if (methodName.equals("removeNotificationListener")) {

	    /* NullPointerException if method with no args, but that
	       shouldn't happen because removeNL does have args.  */
	    NotificationListener listener = (NotificationListener) args[0];

	    switch (nargs) {
	    case 1:
		connection.removeNotificationListener(objectName, listener);
		return null;

	    case 3:
		NotificationFilter filter = (NotificationFilter) args[1];
		Object handback = args[2];
		connection.removeNotificationListener(objectName,
						      listener,
						      filter,
						      handback);
		return null;

	    default:
		final String msg =
		    "Bad arg count to removeNotificationListener: " + nargs;
		throw new IllegalArgumentException(msg);
	    }

	} else if (methodName.equals("getNotificationInfo")) {

	    if (args != null) {
		throw new IllegalArgumentException("getNotificationInfo has " +
						   "args");
	    }

	    MBeanInfo info = connection.getMBeanInfo(objectName);
	    return info.getNotifications();

	} else {
	    throw new IllegalArgumentException("Bad method name: " +
					       methodName);
	}
public static java.lang.ObjectnewProxyInstance(javax.management.MBeanServerConnection connection, javax.management.ObjectName objectName, java.lang.Class interfaceClass, boolean notificationBroadcaster)

Return a proxy that implements the given interface by forwarding its methods through the given MBean server to the named MBean.

This method is equivalent to {@link Proxy#newProxyInstance Proxy.newProxyInstance}(interfaceClass.getClassLoader(), interfaces, handler). Here handler is the result of {@link #MBeanServerInvocationHandler new MBeanServerInvocationHandler(connection, objectName)}, and interfaces is an array that has one element if notificationBroadcaster is false and two if it is true. The first element of interfaces is interfaceClass and the second, if present, is NotificationEmitter.class.

param
connection the MBean server to forward to.
param
objectName the name of the MBean within connection to forward to.
param
interfaceClass the management interface that the MBean exports, which will also be implemented by the returned proxy.
param
notificationBroadcaster make the returned proxy implement {@link NotificationEmitter} by forwarding its methods via connection.
return
the new proxy instance.

	final InvocationHandler handler =
	    new MBeanServerInvocationHandler(connection, objectName);
	final Class[] interfaces;
	if (notificationBroadcaster) {
	    interfaces =
		new Class[] {interfaceClass, NotificationEmitter.class};
	} else
	    interfaces = new Class[] {interfaceClass};
	return Proxy.newProxyInstance(interfaceClass.getClassLoader(),
				      interfaces,
				      handler);