1<html> 2<head> 3<title>javax.management.relation package</title> 4<!-- 5Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. 6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 7 8This code is free software; you can redistribute it and/or modify it 9under the terms of the GNU General Public License version 2 only, as 10published by the Free Software Foundation. Oracle designates this 11particular file as subject to the "Classpath" exception as provided 12by Oracle in the LICENSE file that accompanied this code. 13 14This code is distributed in the hope that it will be useful, but WITHOUT 15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 17version 2 for more details (a copy is included in the LICENSE file that 18accompanied this code). 19 20You should have received a copy of the GNU General Public License version 212 along with this work; if not, write to the Free Software Foundation, 22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 23 24Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 25or visit www.oracle.com if you need additional information or have any 26questions. 27--> 28</head> 29<body bgcolor="white"> 30 <p>Provides the definition of the Relation Service. The 31 Relation Service is used to record relationships between 32 MBeans in an MBean Server. The Relation Service is itself an 33 MBean. More than one instance of a {@link 34 javax.management.relation.RelationService RelationService} 35 MBean can be registered in an MBean Server.</p> 36 37 <p>A <em>relation type</em> defines a relationship between MBeans. 38 It contains <em>roles</em> that the MBeans play in the 39 relationship. Usually there are at least two roles in a 40 relation type.</p> 41 42 <p>A <em>relation</em> is a named instance of a relation type, 43 where specific MBeans appear in the roles, represented by 44 their {@link javax.management.ObjectName ObjectName}s.</p> 45 46 <p>For example, suppose there are <code>Module</code> MBeans, 47 representing modules within an application. A 48 <code>DependsOn</code> relation type could express the 49 relationship that some modules depend on others, which could 50 be used to determine the order in which the modules are 51 started or stopped. The <code>DependsOn</code> relation type 52 would have two roles, <code>dependent</code> and 53 <code>dependedOn</code>.</p> 54 55 <p>Every role is <em>typed</em>, meaning that an MBean that 56 appears in that role must be an instance of the role's type. 57 In the <code>DependsOn</code> example, both roles would be of 58 type <code>Module</code>.</p> 59 60 <p>Every role has a <em>cardinality</em>, which provides lower 61 and upper bounds on the number of MBeans that can appear in 62 that role in a given relation instance. Usually, the lower 63 and upper bounds are both 1, with exactly one MBean appearing 64 in the role. The cardinality only limits the number of MBeans 65 in the role per relation instance. The same MBean can appear 66 in the same role in any number of instances of a relation 67 type. In the <code>DependsOn</code> example, a given module 68 can depend on many other modules, and be depended on by many 69 others, but any given relation instance links exactly one 70 <code>dependent</code> module with exactly one 71 <code>dependedOn</code> module.</p> 72 73 <p>A relation type can be created explicitly, as an object 74 implementing the {@link javax.management.relation.RelationType 75 RelationType} interface, typically a {@link 76 javax.management.relation.RelationTypeSupport 77 RelationTypeSupport}. Alternatively, it can be created 78 implicitly using the Relation Service's {@link 79 javax.management.relation.RelationServiceMBean#createRelationType(String, 80 RoleInfo[]) createRelationType} method.</p> 81 82 <p>A relation instance can be created explicitly, as an object 83 implementing the {@link javax.management.relation.Relation 84 Relation} interface, typically a {@link 85 javax.management.relation.RelationSupport RelationSupport}. 86 (A <code>RelationSupport</code> is itself a valid MBean, so it 87 can be registered in the MBean Server, though this is not 88 required.) Alternatively, a relation instance can be created 89 implicitly using the Relation Service's {@link 90 javax.management.relation.RelationServiceMBean#createRelation(String, 91 String, RoleList) createRelation} method.</p> 92 93 <p>The <code>DependsOn</code> example might be coded as follows.</p> 94 95<pre> 96import java.util.*; 97import javax.management.*; 98import javax.management.relation.*; 99 100// ... 101MBeanServer mbs = ...; 102 103// Create the Relation Service MBean 104ObjectName relSvcName = new ObjectName(":type=RelationService"); 105RelationService relSvcObject = new RelationService(true); 106mbs.registerMBean(relSvcObject, relSvcName); 107 108// Create an MBean proxy for easier access to the Relation Service 109RelationServiceMBean relSvc = 110 MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName, 111 RelationServiceMBean.class, 112 false); 113 114// Define the DependsOn relation type 115RoleInfo[] dependsOnRoles = { 116 new RoleInfo("dependent", Module.class.getName()), 117 new RoleInfo("dependedOn", Module.class.getName()) 118}; 119relSvc.createRelationType("DependsOn", dependsOnRoles); 120 121// Now define a relation instance "moduleA DependsOn moduleB" 122 123ObjectName moduleA = new ObjectName(":type=Module,name=A"); 124ObjectName moduleB = new ObjectName(":type=Module,name=B"); 125 126Role dependent = new Role("dependent", Collections.singletonList(moduleA)); 127Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB)); 128Role[] roleArray = {dependent, dependedOn}; 129RoleList roles = new RoleList(Arrays.asList(roleArray)); 130relSvc.createRelation("A-DependsOn-B", "DependsOn", roles); 131 132// Query the Relation Service to find what modules moduleA depends on 133Map<ObjectName,List<String>> dependentAMap = 134 relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent"); 135Set<ObjectName> dependentASet = dependentAMap.keySet(); 136// Set of ObjectName containing moduleB 137</pre> 138 139 @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html"> 140 JMX Specification, version 1.4</a> 141 142 @since 1.5 143 144</BODY> 145</HTML> 146