A full description of the RelationService, what it does and why it does it can be found in the JMX Specifications.

The example java source files can be found in the examples directory under services/relation, they include:

Before any relations can be defined the RelationService must be registered in the MBeanServer.

import javax.management.relation.RelationService;

MBeanServer server = MBeanServerFactory.createMBeanServer();
String className = "javax.management.relation.RelationService";
ObjectName objectName = new ObjectName("Relations:name=RelationService");

// The boolean value is to enable a purge of relations to determine invalid relations when an unregistration occurs of MBeans
Object[] params = {new Boolean(true)};
String[] signature = {"boolean"};
server.createMBean(className, objectName, null, params, signature);
               

Once we have the RelationService registered we can then create in the server our MBeans that will be playing the roles in our use-case scenarios. This being done we can proceed to adding our RelationType SimplePersonalLibrary which must extend javax.management.relation.RelationTypeSupport. This class is not registered in the MBeanServer, it is merely a simple way of providing the definitions of our Roles in the RelationService, an example of adding a RelationType in the RelationService follows:

// SimplePersonalLibrary is our RelationTypeSupport class
String relationTypeName = "my_library";
SimplePersonalLibrary library = new SimplePersonalLibrary(relationTypeName);

Object[] params = {library};
String[] signature = {"javax.management.relation.RelationType"};

server.invoke(objectName, "addRelationType", params, signature);
               

Our next step will be to start filling the roles we defined in our support class and adding the MBeans up to the maximum number we defined our SimplePersonalLibrary class. This means registering the MBeans first with MBeanServer. Once registered. we can add them within our Roles...

// building the owner Role
ArrayList ownerList = new ArrayList();
ownerList.add(ownerName1);  // can only add owner to an owner role cardinality defined as 1
Role ownerRole = new Role("owner", ownerList);

// building the book role
ArrayList bookList = new ArrayList();
// we can have between 1 and 4 books more than 4 invalidates out relation and less than 1 invalidates it
bookList.add(bookName1);
bookList.add(bookName2);
bookList.add(bookName3);
Role bookRole = new Role("books", bookList);

// add our roles to the RoleList
RoleList libraryList = new RoleList();
libraryList.add(ownerRole);
libraryList.add(bookRole);

// now create the relation
Object[] params = {personalLibraryId, libraryTypeName, libraryList};
String[] signature = {"java.lang.String", "java.lang.String", "javax.management.relation.RoleList"};
m_server.invoke(m_relationObjectName, "createRelation", params, signature);
               

We are done a note about the alternate scenarios: Once Role cardinality has been invalidated the relation is removed from the RelationService and can no longer be accessed via the RelationService though any MBeans registered in the MBeanServer can still be accessed individually.

The RelationService examples which can be downloaded from the JMX website will run in the MX4J implementation. The few changes required are due to the fact that MX4J implements the accessors of MBeans as server.getAttribute(..) and server.setAttribute(...) whereas the JMX implements all as method calls using server.invoke(..)

To be able to use the Examples from the JMX download. A list of the few changes required for the RelationAgent follows: