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 {@link * javax.management.relation.RelationService 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 {@link javax.management.ObjectName 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 {@link javax.management.relation.RelationType * RelationType} interface, typically a {@link * javax.management.relation.RelationTypeSupport * RelationTypeSupport}. Alternatively, it can be created * implicitly using the Relation Service's {@link * javax.management.relation.RelationServiceMBean#createRelationType(String, * RoleInfo[]) createRelationType} method.
* *A relation instance can be created explicitly, as an object
* implementing the {@link javax.management.relation.Relation
* Relation} interface, typically a {@link
* javax.management.relation.RelationSupport 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 {@link
* javax.management.relation.RelationServiceMBean#createRelation(String,
* String, RoleList) 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
*
*
* @see
* JMX Specification, version 1.4
*
* @since 1.5
*/
package javax.management.relation;