The relation service provides a facility to associate MBeans with each other. You use the metadata classes provided by the relation service to describe and then establish n-ary relationships between registered MBeans, as dictated by your application policies. You then use the relation service to maintain the consistency of those relationships so that those application policies are followed. The relation service must be implemented by every compliant JMX implementation.
In this chapter, we will examine the JMX relation service and see how to write code to use it. We will begin with an overview of the concepts employed by the relation service, such as roles and relations, then we will look at the relation service classes that implement these concepts. Next, we will see how to write code to use the relation service classes to describe relationships between MBeans used in the sample application. This chapter concludes with a look at the support classes provided by the relation service, their purpose, and how to use them.
The code we will develop in this chapter to describe relations, roles, etc. runs within an agent. Thus, I will use the terms “we” and “you” synonymously with “the agent.”
To use the relation service effectively, you need to understand a few key concepts:
- Role
A named category of functionality that is performed by an MBean. For example, in the sample application, there are two subclasses of
Workerwhose names correspond to the roles they perform:ConsumerandSupplier. A role describes the MBean objects that perform that role and is implemented by theRoleclass.- Role information
Metadata about a role, such as the role name and the minimum and maximum number of MBeans that are allowed to perform that role. Role information is implemented by the
RoleInfoclass.- Relation type
Metadata that describes the relationships between
RoleInfoobjects. TheRelationTypeinterface provides information about the relation type, such as the name of the relation type and the various roles that make up that type. The relation service provides a method, createRelationType( ), that allows the agent to easily create relation type objects that the relation service will maintain internally. Relation types created by the relation service and maintained internally are called internal relation types. Compliant JMX implementations of the relation service also provide a class calledRelationTypeSupportthat the agent can subclass (or use as-is) that handles relation types in a generic fashion. These relation types are called external relation types and are added to the relation service through its addRelationType( ) method.- Relation
An instance of a relation type. It is critical to the correct functioning of the relation service that all relation types remain consistent. In other words, the metadata describing the relationship between MBeans (i.e., the relation type) provides the constraints on the relation that allow the relation service to be used to ensure that the relation remains consistent at all times. Once a relation has been instantiated, it must remain consistent, or the relation service will throw an exception.
Each of these concepts is implemented in the JMX RI as a class in the
javax.management.relation package.
The Relation
interface provides information about the relation, such as the name
of the relation (the ID, as it is called in the specification), and
access to the Role and RoleInfo
objects that make up the relation. As with relation types, there are
two ways to
create
a relation. The first way is to call the createRelation(
)
method of the relation service, which will
create an internal
relation
(i.e., one that is maintained
internally by the relation service). The second way to create a
relation is to use (or subclass) the
RelationSupport
class, instantiate it, and add it to the relation service by calling
the addRelation(
)
method. This type of relation is referred
to as an external
relation
.
It is the responsibility of the agent developer to create the necessary relation classes to describe the roles, relation types, and relations that are to be maintained by the relation service. We will discuss how to do this later in this chapter.