Chapter 5. Examples

Table of Contents

XDoclet: Automatic interface and description sources generation
Using The FilePersister



Bronwen Cassidy

Revision History
Revision $Revision: 1.2 $$Date: 2002/01/25 16:20:04 $


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:

  • RelationServiceExample (the main class)
  • SimpleBooks
  • SimpleOwner
  • SimplePersonalLibrary (which extends the javax.mangement.relation.RelationTypeSupport and provides the definitions of our roles)

Simple use-case for the example

  • 1)Adding Books Use-Case: Main Success Scenario:
A user adds 1 book to his personal library, he already has 3, a check is done and it is determined that he is allowed 4 books, there are no problems and he can add the book.
  • 2)Adding Books Use-Case: Alternate Scenarios:
Our user decides he would like to add another book, as he has defined the number of books to be minimum 1 and maximum 4, and he is now trying to add a fifth, he is not allowed to add the extra book..
  • 3)Removing Books Use-Case: Main Success Scenario:
A User decides to remove 3 old books from his personal-library. As he has defined the number of books he is allowed as to being between 1 and 4 there are no problems, the books are removed and he can no longer read or write to them, from the RelationService..
  • 4)Removing Books Use-Case: Alternate Scenario:
The book owner decides to remove all his books. The relation is invalidated and he can no longer access his records as they have been removed from the RelationService, including his role as Owner..

Code Usage

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

Example 5.1. Creating the RelationService


MBeanServer server = MBeanServerFactory.createMBeanServer();
String className = "";
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 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:

Example 5.2. Adding a RelationType

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

Object[] params = {library};
String[] signature = {""};

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...

Example 5.3. Building 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
Role bookRole = new Role("books", bookList);

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

// now create the relation
Object[] params = {personalLibraryId, libraryTypeName, libraryList};
String[] signature = {"java.lang.String", "java.lang.String", ""};
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.

Using Examples from the JMX Reference Implementation

The RelationService examples which can be downloaded from the JMX website will run in the OpenJMX implementation. The few changes required are due to the fact that OpenJMX 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:

  • Remove: import com.sun.jdmk.Trace;
  • Remove: Trace.parseTraceProperties();
  • Change all calls for
    • getAllRelationTypeNames
    • getRelationServiceName
    • getRelationId
    • getAllRelationIds
    • getReferencedMBeans Note: except where the call comes from an external relation(represented by a subclass of or a type of
    • getRelationTypeName Note: same as above
    • getAllRoles Note: same as above
    • setRole Note: same as above
    from server.invoke(...) to server.getAttribute(....) , server.setAttribute(...) depending on whether it sets or gets.