Admin


1   /***
2    * Fractal JMX
3    * Copyright (C) 2001-2002 France Telecom, INRIA
4    *
5    * This library is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2 of the License, or (at your option) any later version.
9    *
10   * This library is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this library; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   *
19   * Contact: fractal@objectweb.org
20   */
21  
22  package org.objectweb.fractal.jmx.agent;
23  
24  import javax.management.JMException  ;
25  
26  /**
27   * A simple interface for MBean manipulation on the Fractal JMX agent side. 
28   * This interface allows an agent component implementing this interface to register MBeans in its scope, where:
29   * <ul>
30   * <li>the scope of the agent represents its super-components and all sub-components recursively enclosed in its 
31   * super-components (or in itself if the agent has no super-components). 
32   * <li>the MBeans represent component server interfaces or standard JMX 
33   * {@link javax.management.monitor.MonitorMBean monitors} for observing component attributes. 
34   * </ul>
35   * 
36   * <p>For example, in the architecture depicted below, where an agent is added to the composite B:
37   * <center>
38   * <p><img SRC="../../../../../../figures/fractal-jmx-scope.gif">
39   * </center>
40   * <UL>
41   * <LI>The component B, C, D and Agent (itself) are in the agent scope and then candidate
42   * to expose MBeans representing their server interfaces or observer on their attributes.
43   * <LI>The component A is not in the agent scope, and then cannot be managed, since 
44   * it is not a super-component of the agent.
45   * </UL>
46   * <br>
47   * 
48   * <p><B>Naming convention:</B> 
49   * In JMX, an {@link javax.management.ObjectName ObjectName} represents a reference
50   * to an MBean in the agent.
51   * It is unique within an {@link javax.management.MBeanServer MBeanServer} and consists 
52   * of two parts: the domain name and an unordered list of propert-value pairs.
53   * The string representation of an object name must follow the following syntax:
54   * <p><pre>
55   *    [DomainName]:property=value[,property=value]*
56   * </pre>
57   * 
58   * In Fractal JMX, the object name of an MBean representing a component server interface uses this syntax as follows: 
59   * <p><pre>
60   *    FC/[<i>path</i>]<i>component</i>@<i>id</i>[<i>shared</i>]:itf=<i>interface</i>
61   * </pre>
62   * where:
63   * <UL>
64   * <LI><I>component</I>: is the name of the component, as returned by {@link org.objectweb.fractal.api.control.NameController NameController}.
65   * <LI><I>interface</I>: is the name of a server interface of the component,
66   * as returned by {@link org.objectweb.fractal.api.type.InterfaceType InterfaceType}.
67   * <LI><I>path</I>: is a (slash separated) name sequence of the successive super-components of the component, 
68   * in the reverse order.
69   * <LI><I>shared</I>: is an optional field set to "-shared" if the component may be identified by several <I>paths</I>
70   * (i.e. if the component or some component, in its super-component hierarchy, is shared).
71   * <LI><I>id</I>: is an inelegant, but unique, component identifier introduced to avoid JMX name clashes, 
72   * since nothing prevents the same Fractal name sequence to identify several components.
73   * </UL>
74   *
75   * For example, in the figure above, the MBean representing the interface I of the component D 
76   * is identified by: 
77   * 
78   * <p><pre>
79   *    FC/A/B/C/D@56e32:itf=I
80   * </pre>
81   * 
82   * where @56e32 is the unique identifier of component D. 
83   * This identifier is generated by the agent and can be ignored.
84   * 
85   * <p>This naming convention:
86   * <ul>
87   * <li>requires components to have a {@link org.objectweb.fractal.api.control.NameController NameController} 
88   * and to avoid (in component or interface names) characters interpreted in specific ways by 
89   * {@link javax.management.ObjectName ObjectName} (e.g. ":", "*", "&"...).
90   * <li>is used by the 
91   *  {@link AdminAttributes agent attributes}
92   * to filter the relevant MBeans.  
93   * Only the MBeans, whose 
94   * {@link javax.management.ObjectName ObjectName}
95   * matches a pattern defined by these attributes, are registered in the agent. 
96   * These MBeans represent either component server interfaces or monitors for observing component attributes.
97   * In the latter case, the naming convention used by the agent attributes considers some additional property-value pairs
98   * reserved for the configuration of JMX monitors. 
99   * </ul>
100  * 
101  * @version 0.1
102  */
103 public interface Admin {
104 
105     /**
106      * Registers MBeans in the agent. 
107      * This method allows the agent component (implementing this interface) to register MBeans in its scope, 
108      * where:
109      * <ul>
110      * <li>the scope of the agent represents its super-components and all sub-components recursively enclosed in its 
111      * super-components (or in itself if the agent has no super-components). 
112      * <li>the MBeans represent component (server) interfaces or standard JMX 
113      * {@link javax.management.monitor.MonitorMBean monitors} for observing component attributes. 
114      * </ul>
115      * 
116      * <P>This method: 
117      * <UL>
118      * <LI>first unregisters (previously registered) MBeans in the agent.</LI> 
119      * <LI>then registers MBeans in the scope that match the {@link AdminAttributes filter attributes} of the agent. 
120      * </UL>
121      * 
122      * @throws JMException if a problem occurs during the MBean registration.
123      */
124     void expose() throws JMException  ;
125 
126 }
127
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags