| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <html> |
| 2 | <head> |
| 3 | <title>javax.management.relation package</title> |
| 4 | <!-- |
| 5 | Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 8 | This code is free software; you can redistribute it and/or modify it |
| 9 | under the terms of the GNU General Public License version 2 only, as |
| 10 | published by the Free Software Foundation. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 14 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 15 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 16 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 17 | version 2 for more details (a copy is included in the LICENSE file that |
| 18 | accompanied this code). |
| 19 | |
| 20 | You should have received a copy of the GNU General Public License version |
| 21 | 2 along with this work; if not, write to the Free Software Foundation, |
| 22 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 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> |
| 96 | import java.util.*; |
| 97 | import javax.management.*; |
| 98 | import javax.management.relation.*; |
| 99 | |
| 100 | // ... |
| 101 | MBeanServer mbs = ...; |
| 102 | |
| 103 | // Create the Relation Service MBean |
| 104 | ObjectName relSvcName = new ObjectName(":type=RelationService"); |
| 105 | RelationService relSvcObject = new RelationService(true); |
| 106 | mbs.registerMBean(relSvcObject, relSvcName); |
| 107 | |
| 108 | // Create an MBean proxy for easier access to the Relation Service |
| 109 | RelationServiceMBean relSvc = |
| 110 | MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName, |
| 111 | RelationServiceMBean.class, |
| 112 | false); |
| 113 | |
| 114 | // Define the DependsOn relation type |
| 115 | RoleInfo[] dependsOnRoles = { |
| 116 | new RoleInfo("dependent", Module.class.getName()), |
| 117 | new RoleInfo("dependedOn", Module.class.getName()) |
| 118 | }; |
| 119 | relSvc.createRelationType("DependsOn", dependsOnRoles); |
| 120 | |
| 121 | // Now define a relation instance "moduleA DependsOn moduleB" |
| 122 | |
| 123 | ObjectName moduleA = new ObjectName(":type=Module,name=A"); |
| 124 | ObjectName moduleB = new ObjectName(":type=Module,name=B"); |
| 125 | |
| 126 | Role dependent = new Role("dependent", Collections.singletonList(moduleA)); |
| 127 | Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB)); |
| 128 | Role[] roleArray = {dependent, dependedOn}; |
| 129 | RoleList roles = new RoleList(Arrays.asList(roleArray)); |
| 130 | relSvc.createRelation("A-DependsOn-B", "DependsOn", roles); |
| 131 | |
| 132 | // Query the Relation Service to find what modules moduleA depends on |
| 133 | Map<ObjectName,List<String>> dependentAMap = |
| 134 | relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent"); |
| 135 | Set<ObjectName> dependentASet = dependentAMap.keySet(); |
| 136 | // Set of ObjectName containing moduleB |
| 137 | </pre> |
| 138 | |
| 139 | @see <a href="{@docRoot}/../technotes/guides/jmx/"> |
| 140 | Java SE 6 Platform documentation on JMX technology</a>, |
| 141 | in particular the |
| 142 | <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf"> |
| 143 | JMX Specification, version 1.4</a> |
| 144 | |
| 145 | @since 1.5 |
| 146 | |
| 147 | </BODY> |
| 148 | </HTML> |