management/relation/package.html

0N/A<html>
0N/A<head>
0N/A<title>javax.management.relation package</title>
0N/A<!--
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/A
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/A
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/A
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.
0N/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A-->
0N/A</head>
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    javax.management.relation.RelationService RelationService}
0N/A    MBean can be registered in an MBean Server.</p>
0N/A
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    relation type.</p>
0N/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    their {@link javax.management.ObjectName ObjectName}s.</p>
0N/A
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
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
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
0N/A      <p>A relation type can be created explicitly, as an object
0N/A    implementing the {@link javax.management.relation.RelationType
0N/A    RelationType} interface, typically a {@link
0N/A    javax.management.relation.RelationTypeSupport
0N/A    RelationTypeSupport}.  Alternatively, it can be created
0N/A    implicitly using the Relation Service's {@link
0N/A    javax.management.relation.RelationServiceMBean#createRelationType(String,
0N/A    RoleInfo[]) createRelationType} method.</p>
0N/A
0N/A      <p>A relation instance can be created explicitly, as an object
0N/A    implementing the {@link javax.management.relation.Relation
0N/A    Relation} interface, typically a {@link
0N/A    javax.management.relation.RelationSupport RelationSupport}.
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    javax.management.relation.RelationServiceMBean#createRelation(String,
0N/A    String, RoleList) createRelation} method.</p>
0N/A
0N/A      <p>The <code>DependsOn</code> example might be coded as follows.</p>
0N/A
0N/A<pre>
0N/Aimport java.util.*;
0N/Aimport javax.management.*;
0N/Aimport javax.management.relation.*;
0N/A
0N/A// ...
0N/AMBeanServer mbs = ...;
0N/A
0N/A// Create the Relation Service MBean
0N/AObjectName relSvcName = new ObjectName(":type=RelationService");
0N/ARelationService relSvcObject = new RelationService(true);
0N/Ambs.registerMBean(relSvcObject, relSvcName);
0N/A
0N/A// Create an MBean proxy for easier access to the Relation Service
0N/ARelationServiceMBean relSvc =
0N/A    MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName,
0N/A                          RelationServiceMBean.class,
0N/A                          false);
0N/A
0N/A// Define the DependsOn relation type
0N/ARoleInfo[] dependsOnRoles = {
0N/A    new RoleInfo("dependent", Module.class.getName()),
0N/A    new RoleInfo("dependedOn", Module.class.getName())
0N/A};
0N/ArelSvc.createRelationType("DependsOn", dependsOnRoles);
0N/A
0N/A// Now define a relation instance "moduleA DependsOn moduleB"
0N/A
0N/AObjectName moduleA = new ObjectName(":type=Module,name=A");
0N/AObjectName moduleB = new ObjectName(":type=Module,name=B");
0N/A
0N/ARole dependent = new Role("dependent", Collections.singletonList(moduleA));
0N/ARole dependedOn = new Role("dependedOn", Collections.singletonList(moduleB));
0N/ARole[] roleArray = {dependent, dependedOn};
0N/ARoleList roles = new RoleList(Arrays.asList(roleArray));
0N/ArelSvc.createRelation("A-DependsOn-B", "DependsOn", roles);
0N/A
0N/A// Query the Relation Service to find what modules moduleA depends on
0N/AMap&lt;ObjectName,List&lt;String&gt;&gt; dependentAMap =
0N/A    relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
0N/ASet&lt;ObjectName&gt; dependentASet = dependentAMap.keySet();
0N/A// Set of ObjectName containing moduleB
0N/A</pre>
0N/A
0N/A    @see <a href="{@docRoot}/technotes/guides/jmx/">
4230N/A      Java Platform documentation on JMX technology</a>,
0N/A    in particular the
0N/A    <a href="{@docRoot}/technotes/guides/jmx/JMX_1_4_specification.pdf">
0N/A      JMX Specification, version 1.4</a>
0N/A
0N/A      @since 1.5
0N/A
0N/A</BODY>
0N/A</HTML>