Chapter 7. MX4J Examples
Prev |  | Next

## Chapter 7. MX4J Examples

## Services

### The Relation Service example

#### Introduction

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 7.1. Creating the RelationService

    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:

Example 7.2. Adding a RelationType

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

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

#### Using Examples from the JMX Reference Implementation

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:

- 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 `javax.management.relation.RelationSupport` or a type of `javax.management.relation.Relation`
  - `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.`

Prev | Home | Next
Jython MBean | Up | MBeans