This page last changed on Feb 26, 2009 by agazzarini.

Object MBean

Description

QMan JMX representation of a Qpid domain object exposed for management / monitoring. Note that there will be an object MBean for each management object on Qpid.
This chapter refers to the abstract interface that object will have.

Object Name

Q-MAN:brokerId=<BROKER_ID>,type=Object,package=<PACKAGE_NAME>,class=<CLASS_NAME>,objectId=<OBJECT_ID>

where :

Name Description Example
Q-MAN QMan management domain. This is a fixed value. N.A.
BROKER_ID Broker identifier. This is a UUID assigned to each connected broker. Basically it indicates the (broker) owner of this object. 5004341d-7f3e-444a-b240-7d48030599f9
PACKAGE_NAME The package name. A package is a grouping of class definitions that are related to a single software component. The package concept is used to extend the management schema beyond just the QPID software components. org.apache.qpid.broker
CLASS_NAME The class name. A class is a type definition for a manageable object. queue, session, connection

Attributes

Object MBean attributes can be classifiled under two categories :

  • Properties : typed members of object (that is, of its class definition) which represent a configurable attribute of the class. In general, properties don't change frequently or may not change at all;
  • Statistics : typed members of object(that is, of its class definition) which represents an instrumentation attribute of the class. Statistics are always read-only in nature and tend to change rapidly.

The JMX interface of an object MBean lets you retrieve attributes metadata using the standard JMX API. The following example is showing that.

Example : retrieving attributes metadata
public class Example
{
	public static void main(String[] args) throws Exception
	{
		MBeanServer server = ManagementFactory.getPlatformMBeanServer();

		// Suppose the following is an object name associated with an existing managed domain instance.
		ObjectName objectName = ...;

		MBeanInfo mbeanMetadata = server.getMBeanInfo(objectName);

		// List all attributes (metadata, not values)
		for (MBeanAttributeInfo attribute : mbeanMetadata.getAttributes())
		{
			System.out.println("Name : "+attribute.getName());
			System.out.println("Description : "+attribute.getDescription());
			System.out.println("Type : "+attribute.getType());
			System.out.println("Is Readable : "+attribute.isReadable());
			System.out.println("Is Writable : "+attribute.isWritable());
		}
	}
}

Operations

Note that all operations that are part of the Object MBean interface are not exposed directly. According to JMX API specs, the invocation of those operations needs to be done using the MBeanServer Agent.

getAttribute

Operation Name Description Return Type
getAttribute This operation allows client to retrieve value of an mbean attribute (property or statistic). java.lang.Object
Argument Name Description Type Nullable Note
objectName This is the name of the target MBean. javax.management.ObjectName No N.A.
attributeName This is the name of the requested attribute. java.lang.String No N.A.
Example
public class Example
{
	public static void main(String[] args) throws Exception
	{
		MBeanServer server = ManagementFactory.getPlatformMBeanServer();

		// Suppose that this is an object name corresponding to a valid managed domain instance.
		ObjectName objectName = ...;

		// Suppose the mbean has an attribute (a statistic in this case) PendingMessagesCount
		Long attributeValue = (Long) server.getAttribute(objectName, "PendingMessagesCount");

		System.out.println("Attribute Value : "+attributeValue);
	}
}

setAttribute

Operation Name Description Return Type
setAttribute This operation allows client to set the value of an mbean attribute (property). Note that it will be possible only if the attribute is writable. You can get that information on the corresponding attribute metadata. void
Argument Name Description Type Nullable Note
objectName This is the name of the target MBean. javax.management.ObjectName No N.A.
attribute This is a data transfer object representing the attribute with the its new value. javax.management.Attribute Yes N.A.
Example
public class Example
{
	public static void main(String[] args) throws Exception
	{
		MBeanServer server = ManagementFactory.getPlatformMBeanServer();

		// Suppose that this is an object name corresponding to a valid managed domain instance.
		ObjectName objectName = ...;

		// Suppose we want to set a value of 30000 for "MgmtPubInterval" attribute.
                Attribute attribute = new Attribute("MgmtPubInterval",new Long(3000));
		server.setAttribute(objectName, attribute);
	}
}

invoke

Operation Name Description Return Type
invoke Invokes an operation on an object MBean org.apache.qpid.management.domain.handler.impl.InvocationResult
Argument Name Description Type Nullable Note
objectName The object name of the target object MBean javax.management.ObjectName No N.A.
operationName This is the operation to be invoked on the target MBean java.lang.String No N.A.
parameters These are the input parameters of the operation java.lang.Object[] No N.A.
signature The operation signature java.lang.String [] No N.A.

While mostly the interface follows the same rules of javax.management.MBeanServer.invoke() the only difference resides on return type.
The mentioned JMX interface generally returns java.lang.Object. While this is the type that the management client see, the underlying object that is returned as result of an operation invocation on QMan is ALWAYS one of the following :

  • org.apache.qpid.management.domain.handler.impl.InvocationResult : This is a simple data transfer object wrapping a java.util.Map<String, Object> that contains (optional) output parameters;
  • org.apache.qpid.management.domain.services.MethodInvocationException : An exception containing a status text and a status code that ndicate whether or not the method was successful and if not, what the error was.
Example
public class Example
{
	public static void main(String[] args) throws Exception
	{
		MBeanServer server = ManagementFactory.getPlatformMBeanServer();

		// Suppose that this is an object name corresponding to a valid managed domain instance.
		ObjectName objectName = new ObjectName("A:N=1");

		// Suppose the mbean has an operation
		// public int purge(int request)
		try
		{
			String outputParameterName = "result";

			String operationName = "purge";
			Object [] parameters = new Object[]{1235};
			String [] signature = new String[]{int.class.getName()};

			InvocationResult result =  (InvocationResultserver.invoke(
                                         objectName,
                                         operationName,
                                         parameters,
                                         signature);

			// Output parameters map
			Map<String,Object> outputSection = result.getOutputSection();

			// Output parameter
			Integer outputParameter = (Integer) outputSection.get(outputParameterName);

			System.out.println("Output parameter : "+outputParameter);

		} catch (MBeanException exception)
		{
                        Exception nested = exception.getTargetException();
                        if (nested instanceof MethodInvocationException)
			{
				MethodInvocationException invocationException = (MethodInvocationException) nested;
				System.out.println("Status Code : "+invocationException.getReturnCode());
				System.out.println("Status Text : "+invocationException.getStatusText());
			}
		}
	}
}

Notifications

N.A.

Document generated by Confluence on May 26, 2010 10:33