Provides the definition of the Relation Service. The
Relation Service is used to record relationships between
MBeans in an MBean Server. The Relation Service is itself an
MBean. More than one instance of a RelationService
MBean can be registered in an MBean Server.
A relation type defines a relationship between MBeans.
It contains roles that the MBeans play in the
relationship. Usually there are at least two roles in a
relation type.
A relation is a named instance of a relation type,
where specific MBeans appear in the roles, represented by
their ObjectName
s.
For example, suppose there are Module
MBeans,
representing modules within an application. A
DependsOn
relation type could express the
relationship that some modules depend on others, which could
be used to determine the order in which the modules are
started or stopped. The DependsOn
relation type
would have two roles, dependent
and
dependedOn
.
Every role is typed, meaning that an MBean that
appears in that role must be an instance of the role's type.
In the DependsOn
example, both roles would be of
type Module
.
Every role has a cardinality, which provides lower
and upper bounds on the number of MBeans that can appear in
that role in a given relation instance. Usually, the lower
and upper bounds are both 1, with exactly one MBean appearing
in the role. The cardinality only limits the number of MBeans
in the role per relation instance. The same MBean can appear
in the same role in any number of instances of a relation
type. In the DependsOn
example, a given module
can depend on many other modules, and be depended on by many
others, but any given relation instance links exactly one
dependent
module with exactly one
dependedOn
module.
A relation type can be created explicitly, as an object
implementing the RelationType
interface, typically a RelationTypeSupport
. Alternatively, it can be created
implicitly using the Relation Service's createRelationType
method.
A relation instance can be created explicitly, as an object
implementing the Relation
interface, typically a RelationSupport
.
(A RelationSupport
is itself a valid MBean, so it
can be registered in the MBean Server, though this is not
required.) Alternatively, a relation instance can be created
implicitly using the Relation Service's createRelation
method.
The DependsOn
example might be coded as follows.
import java.util.*;
import javax.management.*;
import javax.management.relation.*;
// ...
MBeanServer mbs = ...;
// Create the Relation Service MBean
ObjectName relSvcName = new ObjectName(":type=RelationService");
RelationService relSvcObject = new RelationService(true);
mbs.registerMBean(relSvcObject, relSvcName);
// Create an MBean proxy for easier access to the Relation Service
RelationServiceMBean relSvc =
MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName,
RelationServiceMBean.class,
false);
// Define the DependsOn relation type
RoleInfo[] dependsOnRoles = {
new RoleInfo("dependent", Module.class.getName()),
new RoleInfo("dependedOn", Module.class.getName())
};
relSvc.createRelationType("DependsOn", dependsOnRoles);
// Now define a relation instance "moduleA DependsOn moduleB"
ObjectName moduleA = new ObjectName(":type=Module,name=A");
ObjectName moduleB = new ObjectName(":type=Module,name=B");
Role dependent = new Role("dependent", Collections.singletonList(moduleA));
Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB));
Role[] roleArray = {dependent, dependedOn};
RoleList roles = new RoleList(Arrays.asList(roleArray));
relSvc.createRelation("A-DependsOn-B", "DependsOn", roles);
// Query the Relation Service to find what modules moduleA depends on
Map<ObjectName,List<String>> dependentAMap =
relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
Set<ObjectName> dependentASet = dependentAMap.keySet();
// Set of ObjectName containing moduleB