4230N/ACopyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/A <
p>Provides the definition of the Relation Service. The
0N/A Relation Service is used to record relationships between
0N/A MBeans in an MBean Server. The Relation Service is itself an
0N/A MBean. More than one instance of a {@link
0N/A MBean can be registered in an MBean Server.</
p>
0N/A <
p>A <
em>relation type</
em> defines a relationship between MBeans.
0N/A It contains <
em>roles</
em> that the MBeans play in the
0N/A relationship. Usually there are at least two roles in a
0N/A <
p>A <
em>relation</
em> is a named instance of a relation type,
0N/A where specific MBeans appear in the roles, represented by
0N/A <
p>For example, suppose there are <
code>Module</
code> MBeans,
0N/A representing modules within an application. A
0N/A <
code>DependsOn</
code> relation type could express the
0N/A relationship that some modules depend on others, which could
0N/A be used to determine the order in which the modules are
0N/A started or stopped. The <
code>DependsOn</
code> relation type
0N/A would have two roles, <
code>dependent</
code> and
0N/A <
code>dependedOn</
code>.</
p>
0N/A <
p>Every role is <
em>typed</
em>, meaning that an MBean that
0N/A appears in that role must be an instance of the role's type.
0N/A In the <
code>DependsOn</
code> example, both roles would be of
0N/A type <
code>Module</
code>.</
p>
0N/A <
p>Every role has a <
em>cardinality</
em>, which provides lower
0N/A and upper bounds on the number of MBeans that can appear in
0N/A that role in a given relation instance. Usually, the lower
0N/A and upper bounds are both 1, with exactly one MBean appearing
0N/A in the role. The cardinality only limits the number of MBeans
0N/A in the role per relation instance. The same MBean can appear
0N/A in the same role in any number of instances of a relation
0N/A type. In the <
code>DependsOn</
code> example, a given module
0N/A can depend on many other modules, and be depended on by many
0N/A others, but any given relation instance links exactly one
0N/A <
code>dependent</
code> module with exactly one
0N/A <
code>dependedOn</
code> module.</
p>
0N/A <
p>A relation type can be created explicitly, as an object
0N/A RelationType} interface, typically a {@link
0N/A RelationTypeSupport}. Alternatively, it can be created
0N/A implicitly using the Relation Service's {@link
0N/A RoleInfo[]) createRelationType} method.</
p>
0N/A <
p>A relation instance can be created explicitly, as an object
0N/A Relation} interface, typically a {@link
0N/A (A <
code>RelationSupport</
code> is itself a valid MBean, so it
0N/A can be registered in the MBean Server, though this is not
0N/A required.) Alternatively, a relation instance can be created
0N/A implicitly using the Relation Service's {@link
0N/A String, RoleList) createRelation} method.</
p>
0N/A <
p>The <
code>DependsOn</
code> example might be coded as follows.</
p>
0N/AMBeanServer mbs = ...;
0N/A// Create the Relation Service MBean
0N/AObjectName relSvcName = new ObjectName(":type=RelationService");
0N/ARelationService relSvcObject = new RelationService(true);
0N/A// Create an MBean proxy for easier access to the Relation Service
0N/ARelationServiceMBean relSvc =
0N/A// Define the DependsOn relation type
0N/ARoleInfo[] dependsOnRoles = {
0N/A// Now define a relation instance "moduleA DependsOn moduleB"
0N/AObjectName moduleA = new ObjectName(":type=Module,name=A");
0N/AObjectName moduleB = new ObjectName(":type=Module,name=B");
0N/ARole[] roleArray = {dependent, dependedOn};
0N/A// Query the Relation Service to find what modules moduleA depends on
0N/AMap<ObjectName,List<String>> dependentAMap =
0N/A// Set of ObjectName containing moduleB
4230N/A Java Platform documentation on JMX technology</
a>,
0N/A JMX Specification, version 1.4</
a>