4.2 Open Data Instances

All of the wrapper classes for the primitive types are defined and implemented in all Java virtual machines, as is java.lang.String. The ObjectName class is provided by the implementation of the JMX specification. You can use the CompositeData and TabularData interfaces to define aggregates of the open MBean data types and provide a mechanism for expressing complex data objects in a consistent manner.

All open data instances corresponding to the open MBean types defined in 4.1.1 Supported Data Types, except CompositeData and TabularData instances, are available through the classes of the Java 2 Platform, Standard Edition (J2SE) or JMX specification.

4.2.1 CompositeData and TabularData Instances

The CompositeData and TabularData interfaces represent complex data types. The JMX specification now includes a default implementation of these interfaces, using the CompositeDataSupport and TabularDataSupport classes respectively.

The CompositeData and TabularData interfaces and implementations provide some semantic structure to build aggregates from the open MBean data types. An implementation of the CompositeData interface is equivalent to a map with a predefined list of keys: values are retrieved by giving the name of the desired data item. Other terms commonly used for this sort of data type are record or struct.

An instance of a TabularData object contains a set of CompositeData instances. Each CompositeData instance in a TabularData instance is indexed by a unique key derived from its values, as described in 4.2.1.2 TabularDataSupport Class.

A CompositeData object is immutable once instantiated: you cannot add an item to it and you cannot change the value of an existing item. TabularData instances are modifiable: rows can be added or removed from existing instances.

4.2.1.1 CompositeDataSupport Class

A CompositeData object associates string keys with the values of each data item. The CompositeDataSupport class defines an immutable map with an arbitrary number of entries, called data items, which can be of any type. To comply with the design patterns for open MBeans, all data items must have a type among the set of open MBean data types, including other CompositeData types.

When instantiating the CompositeDataSupport class, you must provide the description of the composite data object in a CompositeType object (see 4.1.2 Type Descriptor Classes). All the items provided through the constructor must match this description. Because the composite object is immutable, all items must be provided at instantiation time, and therefore the constructor can verify that the items match the description. The getOpenType method returns this description so that other objects which interact with a CompositeData object can know its structure.

4.2.1.2 TabularDataSupport Class

The TabularDataSupport class defines a table structure with an arbitrary number of rows which can be indexed by any number of columns. Each row is a CompositeData object, and all rows must have the same composite data description. The columns of the table are headed by the names of the data items which make up the uniform CompositeData rows. The constructor and the methods for adding rows verify that all rows are described by equal CompositeData instances.

The index consists of a subset of the data items in the common composite data structure. This subset must be a key which uniquely identifies each row of the table. When the table is instantiated, or when a row is added, the methods of this class ensure that the index can uniquely identify all rows. Often the index will be a single column, for instance a column containing unique strings or integers.

Both the composite data description of all rows and the list of items which form the index are given by the table description returned by the getOpenType method. This method defined in the TabularData interface returns the TabularType object which describes the table (see 4.1.2 Type Descriptor Classes).

The access methods of the TabularData class take an array of objects representing a key value which indexes one row and returns the CompositeData instance which makes up the designated row. A row of the table can also be removed by providing its key value. All rows of the table can also be retrieved in an enumeration.