Java > Open Source Codes > javax > management > MBeanServer


1 /*
2  * @(#)MBeanServer.java 1.140 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.management;
9
10
11 // java import
12 import java.util.Set ;
13 import java.io.ObjectInputStream ;
14
15 // RI import
16 import javax.management.loading.ClassLoaderRepository ;
17
18 /**
19  * <p>This is the interface for MBean manipulation on the agent
20  * side. It contains the methods necessary for the creation,
21  * registration, and deletion of MBeans as well as the access methods
22  * for registered MBeans. This is the core component of the JMX
23  * infrastructure.</p>
24  *
25  * <p>User code does not usually implement this interface. Instead,
26  * an object that implements this interface is obtained with one of
27  * the methods in the {@link MBeanServerFactory} class.</p>
28  *
29  * <p>Every MBean which is added to the MBean server becomes
30  * manageable: its attributes and operations become remotely
31  * accessible through the connectors/adaptors connected to that MBean
32  * server. A Java object cannot be registered in the MBean server
33  * unless it is a JMX compliant MBean.</p>
34  *
35  * <p>When an MBean is registered or unregistered in the MBean server
36  * a {@link javax.management.MBeanServerNotification
37  * MBeanServerNotification} Notification is emitted. To register an
38  * object as listener to MBeanServerNotifications you should call the
39  * MBean server method {@link #addNotificationListener
40  * addNotificationListener} with <CODE>ObjectName</CODE> the
41  * <CODE>ObjectName</CODE> of the {@link
42  * javax.management.MBeanServerDelegate MBeanServerDelegate}. This
43  * <CODE>ObjectName</CODE> is: <BR>
44  * <CODE>JMImplementation:type=MBeanServerDelegate</CODE>.</p>
45  *
46  * <p>An object obtained from the {@link
47  * MBeanServerFactory#createMBeanServer(String) createMBeanServer} or
48  * {@link MBeanServerFactory#newMBeanServer(String) newMBeanServer}
49  * methods of the {@link MBeanServerFactory} class applies security
50  * checks to its methods, as follows.</p>
51  *
52  * <p>First, if there is no security manager ({@link
53  * System#getSecurityManager()} is null), then no checks are made.</p>
54  *
55  * <p>Assuming there is a security manager, the checks are made as
56  * detailed below. In what follows, <code>className</code> is the
57  * string returned by {@link MBeanInfo#getClassName()} for the target
58  * MBean.</p>
59  *
60  * <p>If a security check fails, the method throws {@link
61  * SecurityException}.</p>
62  *
63  * <p>For methods that can throw {@link InstanceNotFoundException},
64  * this exception is thrown for a non-existent MBean, regardless of
65  * permissions. This is because a non-existent MBean has no
66  * <code>className</code>.</p>
67  *
68  * <ul>
69  *
70  * <li><p>For the {@link #invoke invoke} method, the caller's
71  * permissions must imply {@link
72  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
73  * MBeanPermission(className, operationName, name, "invoke")}.</p>
74  *
75  * <li><p>For the {@link #getAttribute getAttribute} method, the
76  * caller's permissions must imply {@link
77  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
78  * MBeanPermission(className, attribute, name, "getAttribute")}.</p>
79  *
80  * <li><p>For the {@link #getAttributes getAttributes} method, the
81  * caller's permissions must imply {@link
82  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
83  * MBeanPermission(className, null, name, "getAttribute")}.
84  * Additionally, for each attribute <em>a</em> in the {@link
85  * AttributeList}, if the caller's permissions do not imply {@link
86  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
87  * MBeanPermission(className, <em>a</em>, name, "getAttribute")}, the
88  * MBean server will behave as if that attribute had not been in the
89  * supplied list.</p>
90  *
91  * <li><p>For the {@link #setAttribute setAttribute} method, the
92  * caller's permissions must imply {@link
93  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
94  * MBeanPermission(className, attrName, name, "setAttribute")}, where
95  * <code>attrName</code> is {@link Attribute#getName()
96  * attribute.getName()}.</p>
97  *
98  * <li><p>For the {@link #setAttributes setAttributes} method, the
99  * caller's permissions must imply {@link
100  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
101  * MBeanPermission(className, null, name, "setAttribute")}.
102  * Additionally, for each attribute <em>a</em> in the {@link
103  * AttributeList}, if the caller's permissions do not imply {@link
104  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
105  * MBeanPermission(className, <em>a</em>, name, "setAttribute")}, the
106  * MBean server will behave as if that attribute had not been in the
107  * supplied list.</p>
108  *
109  * <li><p>For the <code>addNotificationListener</code> methods,
110  * the caller's permissions must imply {@link
111  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
112  * MBeanPermission(className, null, name,
113  * "addNotificationListener")}.</p>
114  *
115  * <li><p>For the <code>removeNotificationListener</code> methods,
116  * the caller's permissions must imply {@link
117  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
118  * MBeanPermission(className, null, name,
119  * "removeNotificationListener")}.</p>
120  *
121  * <li><p>For the {@link #getMBeanInfo getMBeanInfo} method, the
122  * caller's permissions must imply {@link
123  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
124  * MBeanPermission(className, null, name, "getMBeanInfo")}.</p>
125  *
126  * <li><p>For the {@link #getObjectInstance getObjectInstance} method,
127  * the caller's permissions must imply {@link
128  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
129  * MBeanPermission(className, null, name, "getObjectInstance")}.</p>
130  *
131  * <li><p>For the {@link #isInstanceOf isInstanceOf} method, the
132  * caller's permissions must imply {@link
133  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
134  * MBeanPermission(className, null, name, "isInstanceOf")}.</p>
135  *
136  * <li><p>For the {@link #queryMBeans queryMBeans} method, the
137  * caller's permissions must imply {@link
138  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
139  * MBeanPermission(null, null, name, "queryMBeans")}.
140  * Additionally, for each MBean that matches <code>name</code>,
141  * if the caller's permissions do not imply {@link
142  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
143  * MBeanPermission(className, null, name, "queryMBeans")}, the
144  * MBean server will behave as if that MBean did not exist.</p>
145  *
146  * <p>Certain query elements perform operations on the MBean server.
147  * If the caller does not have the required permissions for a given
148  * MBean, that MBean will not be included in the result of the query.
149  * The standard query elements that are affected are {@link
150  * Query#attr(String)}, {@link Query#attr(String,String)}, and {@link
151  * Query#classattr()}.</p>
152  *
153  * <li><p>For the {@link #queryNames queryNames} method, the checks
154  * are the same as for <code>queryMBeans</code> except that
155  * <code>"queryNames"</code> is used instead of
156  * <code>"queryMBeans"</code> in the <code>MBeanPermission</code>
157  * objects. Note that a <code>"queryMBeans"</code> permission implies
158  * the corresponding <code>"queryNames"</code> permission.</p>
159  *
160  * <li><p>For the {@link #getDomains getDomains} method, the caller's
161  * permissions must imply {@link
162  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
163  * MBeanPermission(null, null, name, "getDomains")}. Additionally,
164  * for each domain <var>d</var> in the returned array, if the caller's
165  * permissions do not imply {@link
166  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
167  * MBeanPermission(null, null, new ObjectName("<var>d</var>:x=x"),
168  * "getDomains")}, the domain is eliminated from the array. Here,
169  * <code>x=x</code> is any <var>key=value</var> pair, needed to
170  * satisfy ObjectName's constructor but not otherwise relevant.</p>
171  *
172  * <li><p>For the {@link #getClassLoader getClassLoader} method, the
173  * caller's permissions must imply {@link
174  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
175  * MBeanPermission(className, null, loaderName,
176  * "getClassLoader")}.</p>
177  *
178  * <li><p>For the {@link #getClassLoaderFor getClassLoaderFor} method,
179  * the caller's permissions must imply {@link
180  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
181  * MBeanPermission(className, null, mbeanName,
182  * "getClassLoaderFor")}.</p>
183  *
184  * <li><p>For the {@link #getClassLoaderRepository
185  * getClassLoaderRepository} method, the caller's permissions must
186  * imply {@link
187  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
188  * MBeanPermission(null, null, null, "getClassLoaderRepository")}.</p>
189  *
190  * <li><p>For the deprecated <code>deserialize</code> methods, the
191  * required permissions are the same as for the methods that replace
192  * them.</p>
193  *
194  * <li><p>For the <code>instantiate</code> methods, the caller's
195  * permissions must imply {@link
196  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
197  * MBeanPermission(className, null, null, "instantiate")}.</p>
198  *
199  * <li><p>For the {@link #registerMBean registerMBean} method, the
200  * caller's permissions must imply {@link
201  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
202  * MBeanPermission(className, null, name, "registerMBean")}. Here
203  * <code>className</code> is the string returned by {@link
204  * MBeanInfo#getClassName()} for an object of this class.
205  *
206  * <p>If the <code>MBeanPermission</code> check succeeds, the MBean's
207  * class is validated by checking that its {@link
208  * java.security.ProtectionDomain ProtectionDomain} implies {@link
209  * MBeanTrustPermission#MBeanTrustPermission(String)
210  * MBeanTrustPermission("register")}.</p>
211  *
212  * <p>Finally, if the <code>name</code> argument is null, another
213  * <code>MBeanPermission</code> check is made using the
214  * <code>ObjectName</code> returned by {@link
215  * MBeanRegistration#preRegister MBeanRegistration.preRegister}.</p>
216  *
217  * <li><p>For the <code>createMBean</code> methods, the caller's
218  * permissions must imply the permissions needed by the equivalent
219  * <code>instantiate</code> followed by
220  * <code>registerMBean</code>.</p>
221  *
222  * <li><p>For the {@link #unregisterMBean unregisterMBean} method,
223  * the caller's permissions must imply {@link
224  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
225  * MBeanPermission(className, null, name, "unregisterMBean")}.</p>
226  *
227  * </ul>
228  *
229  * @since 1.5
230  */
231  
232 /* DELETED:
233  *
234  * <li><p>For the {@link #isRegistered isRegistered} method, the
235  * caller's permissions must imply {@link
236  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
237  * MBeanPermission(null, null, name, "isRegistered")}.</p>
238  */
239 public interface MBeanServer extends MBeanServerConnection {
240     /**
241      * <p>Instantiates and registers an MBean in the MBean server. The
242      * MBean server will use its {@link
243      * javax.management.loading.ClassLoaderRepository Default Loader
244      * Repository} to load the class of the MBean. An object name is
245      * associated to the MBean. If the object name given is null, the
246      * MBean must provide its own name by implementing the {@link
247      * javax.management.MBeanRegistration MBeanRegistration} interface
248      * and returning the name from the {@link
249      * MBeanRegistration#preRegister preRegister} method.</p>
250      *
251      * <p>This method is equivalent to {@link
252      * #createMBean(String,ObjectName,Object[],String[])
253      * createMBean(className, name, (Object[]) null, (String[])
254      * null)}.</p>
255      *
256      * @param className The class name of the MBean to be instantiated.
257      * @param name The object name of the MBean. May be null.
258      *
259      * @return An <CODE>ObjectInstance</CODE>, containing the
260      * <CODE>ObjectName</CODE> and the Java class name of the newly
261      * instantiated MBean. If the contained <code>ObjectName</code>
262      * is <code>n</code>, the contained Java class name is
263      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
264      *
265      * @exception ReflectionException Wraps a
266      * <CODE>java.lang.ClassNotFoundException</CODE> or a
267      * <CODE><CODE>java.lang.Exception</CODE></CODE> that occurred
268      * when trying to invoke the MBean's constructor.
269      * @exception InstanceAlreadyExistsException The MBean is already
270      * under the control of the MBean server.
271      * @exception MBeanRegistrationException The
272      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
273      * interface) method of the MBean has thrown an exception. The
274      * MBean will not be registered.
275      * @exception MBeanException The constructor of the MBean has
276      * thrown an exception
277      * @exception NotCompliantMBeanException This class is not a JMX
278      * compliant MBean
279      * @exception RuntimeOperationsException Wraps a
280      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
281      * passed in parameter is null, the <CODE>ObjectName</CODE> passed
282      * in parameter contains a pattern or no <CODE>ObjectName</CODE>
283      * is specified for the MBean.
284      */
285     public ObjectInstance createMBean(String className, ObjectName name)
286         throws ReflectionException , InstanceAlreadyExistsException ,
287            MBeanRegistrationException , MBeanException ,
288            NotCompliantMBeanException ;
289
290     /**
291      * <p>Instantiates and registers an MBean in the MBean server. The
292      * class loader to be used is identified by its object name. An
293      * object name is associated to the MBean. If the object name of
294      * the loader is null, the ClassLoader that loaded the MBean
295      * server will be used. If the MBean's object name given is null,
296      * the MBean must provide its own name by implementing the {@link
297      * javax.management.MBeanRegistration MBeanRegistration} interface
298      * and returning the name from the {@link
299      * MBeanRegistration#preRegister preRegister} method.</p>
300      *
301      * <p>This method is equivalent to {@link
302      * #createMBean(String,ObjectName,ObjectName,Object[],String[])
303      * createMBean(className, name, loaderName, (Object[]) null,
304      * (String[]) null)}.</p>
305      *
306      * @param className The class name of the MBean to be instantiated.
307      * @param name The object name of the MBean. May be null.
308      * @param loaderName The object name of the class loader to be used.
309      *
310      * @return An <CODE>ObjectInstance</CODE>, containing the
311      * <CODE>ObjectName</CODE> and the Java class name of the newly
312      * instantiated MBean. If the contained <code>ObjectName</code>
313      * is <code>n</code>, the contained Java class name is
314      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
315      *
316      * @exception ReflectionException Wraps a
317      * <CODE>java.lang.ClassNotFoundException</CODE> or a
318      * <CODE>java.lang.Exception</CODE> that occurred when trying to
319      * invoke the MBean's constructor.
320      * @exception InstanceAlreadyExistsException The MBean is already
321      * under the control of the MBean server.
322      * @exception MBeanRegistrationException The
323      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
324      * interface) method of the MBean has thrown an exception. The
325      * MBean will not be registered.
326      * @exception MBeanException The constructor of the MBean has
327      * thrown an exception
328      * @exception NotCompliantMBeanException This class is not a JMX
329      * compliant MBean
330      * @exception InstanceNotFoundException The specified class loader
331      * is not registered in the MBean server.
332      * @exception RuntimeOperationsException Wraps a
333      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
334      * passed in parameter is null, the <CODE>ObjectName</CODE> passed
335      * in parameter contains a pattern or no <CODE>ObjectName</CODE>
336      * is specified for the MBean.
337      */
338     public ObjectInstance createMBean(String className, ObjectName name,
339                       ObjectName loaderName)
340         throws ReflectionException , InstanceAlreadyExistsException ,
341            MBeanRegistrationException , MBeanException ,
342            NotCompliantMBeanException , InstanceNotFoundException ;
343
344
345
346     /**
347      * Instantiates and registers an MBean in the MBean server. The
348      * MBean server will use its {@link
349      * javax.management.loading.ClassLoaderRepository Default Loader
350      * Repository} to load the class of the MBean. An object name is
351      * associated to the MBean. If the object name given is null, the
352      * MBean must provide its own name by implementing the {@link
353      * javax.management.MBeanRegistration MBeanRegistration} interface
354      * and returning the name from the {@link
355      * MBeanRegistration#preRegister preRegister} method.
356      *
357      * @param className The class name of the MBean to be instantiated.
358      * @param name The object name of the MBean. May be null.
359      * @param params An array containing the parameters of the
360      * constructor to be invoked.
361      * @param signature An array containing the signature of the
362      * constructor to be invoked.
363      *
364      * @return An <CODE>ObjectInstance</CODE>, containing the
365      * <CODE>ObjectName</CODE> and the Java class name of the newly
366      * instantiated MBean. If the contained <code>ObjectName</code>
367      * is <code>n</code>, the contained Java class name is
368      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
369      *
370      * @exception ReflectionException Wraps a
371      * <CODE>java.lang.ClassNotFoundException</CODE> or a
372      * <CODE>java.lang.Exception</CODE> that occurred when trying to
373      * invoke the MBean's constructor.
374      * @exception InstanceAlreadyExistsException The MBean is already
375      * under the control of the MBean server.
376      * @exception MBeanRegistrationException The
377      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
378      * interface) method of the MBean has thrown an exception. The
379      * MBean will not be registered.
380      * @exception MBeanException The constructor of the MBean has
381      * thrown an exception
382      * @exception NotCompliantMBeanException This class is not a JMX
383      * compliant MBean
384      * @exception RuntimeOperationsException Wraps a
385      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
386      * passed in parameter is null, the <CODE>ObjectName</CODE> passed
387      * in parameter contains a pattern or no <CODE>ObjectName</CODE>
388      * is specified for the MBean.
389      */
390     public ObjectInstance createMBean(String className, ObjectName name,
391                       Object params[], String signature[])
392         throws ReflectionException , InstanceAlreadyExistsException ,
393                MBeanRegistrationException , MBeanException ,
394                NotCompliantMBeanException ;
395
396     /**
397      * Instantiates and registers an MBean in the MBean server. The
398      * class loader to be used is identified by its object name. An
399      * object name is associated to the MBean. If the object name of
400      * the loader is not specified, the ClassLoader that loaded the
401      * MBean server will be used. If the MBean object name given is
402      * null, the MBean must provide its own name by implementing the
403      * {@link javax.management.MBeanRegistration MBeanRegistration}
404      * interface and returning the name from the {@link
405      * MBeanRegistration#preRegister preRegister} method.
406      *
407      * @param className The class name of the MBean to be instantiated.
408      * @param name The object name of the MBean. May be null.
409      * @param params An array containing the parameters of the
410      * constructor to be invoked.
411      * @param signature An array containing the signature of the
412      * constructor to be invoked.
413      * @param loaderName The object name of the class loader to be used.
414      *
415      * @return An <CODE>ObjectInstance</CODE>, containing the
416      * <CODE>ObjectName</CODE> and the Java class name of the newly
417      * instantiated MBean. If the contained <code>ObjectName</code>
418      * is <code>n</code>, the contained Java class name is
419      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
420      *
421      * @exception ReflectionException Wraps a
422      * <CODE>java.lang.ClassNotFoundException</CODE> or a
423      * <CODE>java.lang.Exception</CODE> that occurred when trying to
424      * invoke the MBean's constructor.
425      * @exception InstanceAlreadyExistsException The MBean is already
426      * under the control of the MBean server.
427      * @exception MBeanRegistrationException The
428      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
429      * interface) method of the MBean has thrown an exception. The
430      * MBean will not be registered.
431      * @exception MBeanException The constructor of the MBean has
432      * thrown an exception
433      * @exception NotCompliantMBeanException This class is not a JMX
434      * compliant MBean
435      * @exception InstanceNotFoundException The specified class loader
436      * is not registered in the MBean server.
437      * @exception RuntimeOperationsException Wraps a
438      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
439      * passed in parameter is null, the <CODE>ObjectName</CODE> passed
440      * in parameter contains a pattern or no <CODE>ObjectName</CODE>
441      * is specified for the MBean.
442      *
443      */
444     public ObjectInstance createMBean(String className, ObjectName name,
445                       ObjectName loaderName, Object params[],
446                       String signature[])
447         throws ReflectionException , InstanceAlreadyExistsException ,
448                MBeanRegistrationException , MBeanException ,
449                NotCompliantMBeanException , InstanceNotFoundException ;
450
451     /**
452      * Registers a pre-existing object as an MBean with the MBean
453      * server. If the object name given is null, the MBean must
454      * provide its own name by implementing the {@link
455      * javax.management.MBeanRegistration MBeanRegistration} interface
456      * and returning the name from the {@link
457      * MBeanRegistration#preRegister preRegister} method.
458      *
459      * @param object The MBean to be registered as an MBean.
460      * @param name The object name of the MBean. May be null.
461      *
462      * @return An <CODE>ObjectInstance</CODE>, containing the
463      * <CODE>ObjectName</CODE> and the Java class name of the newly
464      * registered MBean. If the contained <code>ObjectName</code>
465      * is <code>n</code>, the contained Java class name is
466      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
467      *
468      * @exception InstanceAlreadyExistsException The MBean is already
469      * under the control of the MBean server.
470      * @exception MBeanRegistrationException The
471      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
472      * interface) method of the MBean has thrown an exception. The
473      * MBean will not be registered.
474      * @exception NotCompliantMBeanException This object is not a JMX
475      * compliant MBean
476      * @exception RuntimeOperationsException Wraps a
477      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
478      * passed in parameter is null or no object name is specified.
479      */
480     public ObjectInstance registerMBean(Object object, ObjectName name)
481         throws InstanceAlreadyExistsException , MBeanRegistrationException ,
482            NotCompliantMBeanException ;
483
484     /**
485      * Unregisters an MBean from the MBean server. The MBean is
486      * identified by its object name. Once the method has been
487      * invoked, the MBean may no longer be accessed by its object
488      * name.
489      *
490      * @param name The object name of the MBean to be unregistered.
491      *
492      * @exception InstanceNotFoundException The MBean specified is not
493      * registered in the MBean server.
494      * @exception MBeanRegistrationException The preDeregister
495      * ((<CODE>MBeanRegistration</CODE> interface) method of the MBean
496      * has thrown an exception.
497      * @exception RuntimeOperationsException Wraps a
498      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
499      * name in parameter is null or the MBean you are when trying to
500      * unregister is the {@link javax.management.MBeanServerDelegate
501      * MBeanServerDelegate} MBean.
502      *
503      */
504     public void unregisterMBean(ObjectName name)
505         throws InstanceNotFoundException , MBeanRegistrationException ;
506
507     /**
508      * Gets the <CODE>ObjectInstance</CODE> for a given MBean
509      * registered with the MBean server.
510      *
511      * @param name The object name of the MBean.
512      *
513      * @return The <CODE>ObjectInstance</CODE> associated with the MBean
514      * specified by <VAR>name</VAR>. The contained <code>ObjectName</code>
515      * is <code>name</code> and the contained class name is
516      * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.
517      *
518      * @exception InstanceNotFoundException The MBean specified is not
519      * registered in the MBean server.
520      */
521     public ObjectInstance getObjectInstance(ObjectName name)
522         throws InstanceNotFoundException ;
523
524     /**
525      * Gets MBeans controlled by the MBean server. This method allows
526      * any of the following to be obtained: All MBeans, a set of
527      * MBeans specified by pattern matching on the
528      * <CODE>ObjectName</CODE> and/or a Query expression, a specific
529      * MBean. When the object name is null or no domain and key
530      * properties are specified, all objects are to be selected (and
531      * filtered if a query is specified). It returns the set of
532      * <CODE>ObjectInstance</CODE> objects (containing the
533      * <CODE>ObjectName</CODE> and the Java Class name) for the
534      * selected MBeans.
535      *
536      * @param name The object name pattern identifying the MBeans to
537      * be retrieved. If null or no domain and key properties are
538      * specified, all the MBeans registered will be retrieved.
539      * @param query The query expression to be applied for selecting
540      * MBeans. If null no query expression will be applied for
541      * selecting MBeans.
542      *
543      * @return A set containing the <CODE>ObjectInstance</CODE>
544      * objects for the selected MBeans. If no MBean satisfies the
545      * query an empty set is returned.
546      */
547     public Set queryMBeans(ObjectName name, QueryExp query);
548
549     /**
550      * Gets the names of MBeans controlled by the MBean server. This
551      * method enables any of the following to be obtained: The names
552      * of all MBeans, the names of a set of MBeans specified by
553      * pattern matching on the <CODE>ObjectName</CODE> and/or a Query
554      * expression, a specific MBean name (equivalent to testing
555      * whether an MBean is registered). When the object name is null
556      * or no domain and key properties are specified, all objects are
557      * selected (and filtered if a query is specified). It returns the
558      * set of ObjectNames for the MBeans selected.
559      *
560      * @param name The object name pattern identifying the MBean names
561      * to be retrieved. If null or no domain and key properties are
562      * specified, the name of all registered MBeans will be retrieved.
563      * @param query The query expression to be applied for selecting
564      * MBeans. If null no query expression will be applied for
565      * selecting MBeans.
566      *
567      * @return A set containing the ObjectNames for the MBeans
568      * selected. If no MBean satisfies the query, an empty set is
569      * returned.
570      */
571     public Set queryNames(ObjectName name, QueryExp query);
572
573     /**
574      * Checks whether an MBean, identified by its object name, is
575      * already registered with the MBean server.
576      *
577      * @param name The object name of the MBean to be checked.
578      *
579      * @return True if the MBean is already registered in the MBean
580      * server, false otherwise.
581      *
582      * @exception RuntimeOperationsException Wraps a
583      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
584      * name in parameter is null.
585      */
586     public boolean isRegistered(ObjectName name);
587
588     /**
589      * Returns the number of MBeans registered in the MBean server.
590      *
591      * @return the number of registered MBeans, wrapped in an Integer.
592      * If the caller's permissions are restricted, this number may
593      * be greater than the number of MBeans the caller can access.
594      */
595     public Integer getMBeanCount();
596
597     /**
598      * Gets the value of a specific attribute of a named MBean. The MBean
599      * is identified by its object name.
600      *
601      * @param name The object name of the MBean from which the
602      * attribute is to be retrieved.
603      * @param attribute A String specifying the name of the attribute
604      * to be retrieved.
605      *
606      * @return The value of the retrieved attribute.
607      *
608      * @exception AttributeNotFoundException The attribute specified
609      * is not accessible in the MBean.
610      * @exception MBeanException Wraps an exception thrown by the
611      * MBean's getter.
612      * @exception InstanceNotFoundException The MBean specified is not
613      * registered in the MBean server.
614      * @exception ReflectionException Wraps a
615      * <CODE>java.lang.Exception</CODE> thrown when trying to invoke
616      * the setter.
617      * @exception RuntimeOperationsException Wraps a
618      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
619      * name in parameter is null or the attribute in parameter is
620      * null.
621      *
622      * @see #setAttribute
623      */
624     public Object getAttribute(ObjectName name, String attribute)
625         throws MBeanException , AttributeNotFoundException ,
626                InstanceNotFoundException , ReflectionException ;
627
628     /**
629      * Gets the values of several attributes of a named MBean. The MBean
630      * is identified by its object name.
631      *
632      * @param name The object name of the MBean from which the
633      * attributes are retrieved.
634      * @param attributes A list of the attributes to be retrieved.
635      *
636      * @return The list of the retrieved attributes.
637      *
638      * @exception InstanceNotFoundException The MBean specified is not
639      * registered in the MBean server.
640      * @exception ReflectionException An exception occurred when
641      * trying to invoke the getAttributes method of a Dynamic MBean.
642      * @exception RuntimeOperationsException Wrap a
643      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
644      * name in parameter is null or attributes in parameter is null.
645      *
646      * @see #setAttributes
647      */
648     public AttributeList getAttributes(ObjectName name, String [] attributes)
649         throws InstanceNotFoundException , ReflectionException ;
650
651     /**
652      * Sets the value of a specific attribute of a named MBean. The MBean
653      * is identified by its object name.
654      *
655      * @param name The name of the MBean within which the attribute is
656      * to be set.
657      * @param attribute The identification of the attribute to be set
658      * and the value it is to be set to.
659      *
660      * @exception InstanceNotFoundException The MBean specified is not
661      * registered in the MBean server.
662      * @exception AttributeNotFoundException The attribute specified
663      * is not accessible in the MBean.
664      * @exception InvalidAttributeValueException The value specified
665      * for the attribute is not valid.
666      * @exception MBeanException Wraps an exception thrown by the
667      * MBean's setter.
668      * @exception ReflectionException Wraps a
669      * <CODE>java.lang.Exception</CODE> thrown when trying to invoke
670      * the setter.
671      * @exception RuntimeOperationsException Wraps a
672      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
673      * name in parameter is null or the attribute in parameter is
674      * null.
675      *
676      * @see #getAttribute
677      */
678     public void setAttribute(ObjectName name, Attribute attribute)
679         throws InstanceNotFoundException , AttributeNotFoundException ,
680            InvalidAttributeValueException , MBeanException ,
681            ReflectionException ;
682
683
684
685     /**
686      * Sets the values of several attributes of a named MBean. The MBean is
687      * identified by its object name.
688      *
689      * @param name The object name of the MBean within which the
690      * attributes are to be set.
691      * @param attributes A list of attributes: The identification of
692      * the attributes to be set and the values they are to be set to.
693      *
694      * @return The list of attributes that were set, with their new
695      * values.
696      *
697      * @exception InstanceNotFoundException The MBean specified is not
698      * registered in the MBean server.
699      * @exception ReflectionException An exception occurred when
700      * trying to invoke the setAttributes method of a Dynamic MBean.
701      * @exception RuntimeOperationsException Wraps a
702      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
703      * name in parameter is null or attributes in parameter is null.
704      *
705      * @see #getAttributes
706      */
707     public AttributeList setAttributes(ObjectName name,
708                        AttributeList attributes)
709     throws InstanceNotFoundException , ReflectionException ;
710
711     /**
712      * Invokes an operation on an MBean.
713      *
714      * @param name The object name of the MBean on which the method is
715      * to be invoked.
716      * @param operationName The name of the operation to be invoked.
717      * @param params An array containing the parameters to be set when
718      * the operation is invoked
719      * @param signature An array containing the signature of the
720      * operation. The class objects will be loaded using the same
721      * class loader as the one used for loading the MBean on which the
722      * operation was invoked.
723      *
724      * @return The object returned by the operation, which represents
725      * the result of invoking the operation on the MBean specified.
726      *
727      * @exception InstanceNotFoundException The MBean specified is not
728      * registered in the MBean server.
729      * @exception MBeanException Wraps an exception thrown by the
730      * MBean's invoked method.
731      * @exception ReflectionException Wraps a
732      * <CODE>java.lang.Exception</CODE> thrown while trying to invoke
733      * the method.
734      */
735     public Object invoke(ObjectName name, String operationName,
736              Object params[], String signature[])
737         throws InstanceNotFoundException , MBeanException ,
738            ReflectionException ;
739  
740     /**
741      * Returns the default domain used for naming the MBean.
742      * The default domain name is used as the domain part in the ObjectName
743      * of MBeans if no domain is specified by the user.
744      *
745      * @return the default domain.
746      */
747     public String getDefaultDomain();
748
749     /**
750      * <p>Returns the list of domains in which any MBean is currently
751      * registered. A string is in the returned array if and only if
752      * there is at least one MBean registered with an ObjectName whose
753      * {@link ObjectName#getDomain() getDomain()} is equal to that
754      * string. The order of strings within the returned array is
755      * not defined.</p>
756      *
757      * @return the list of domains.
758      *
759      * @since.unbundled JMX 1.2
760      */
761     public String [] getDomains();
762
763     /**
764      * <p>Adds a listener to a registered MBean.</p>
765      *
766      * <P> A notification emitted by the MBean will be forwarded by the
767      * MBeanServer to the listener. If the source of the notification
768      * is a reference to the MBean object, the MBean server will replace it
769      * by the MBean's ObjectName. Otherwise the source is unchanged.
770      *
771      * @param name The name of the MBean on which the listener should
772      * be added.
773      * @param listener The listener object which will handle the
774      * notifications emitted by the registered MBean.
775      * @param filter The filter object. If filter is null, no
776      * filtering will be performed before handling notifications.
777      * @param handback The context to be sent to the listener when a
778      * notification is emitted.
779      *
780      * @exception InstanceNotFoundException The MBean name provided
781      * does not match any of the registered MBeans.
782      *
783      * @see #removeNotificationListener(ObjectName, NotificationListener)
784      * @see #removeNotificationListener(ObjectName, NotificationListener,
785      * NotificationFilter, Object)
786      */
787     public void addNotificationListener(ObjectName name,
788                     NotificationListener listener,
789                     NotificationFilter filter,
790                     Object handback)
791         throws InstanceNotFoundException ;
792
793
794     /**
795      * <p>Adds a listener to a registered MBean.</p>
796      *
797      * <P> A notification emitted by the MBean will be forwarded by the
798      * MBeanServer to the listener. If the source of the notification
799      * is a reference to the MBean object, the MBean server will replace it
800      * by the MBean's ObjectName. Otherwise the source is unchanged.
801      *
802      * <p>The listener object that receives notifications is the one
803      * that is registered with the given name at the time this method
804      * is called. Even if it is subsequently unregistered, it will
805      * continue to receive notifications.</p>
806      *
807      * @param name The name of the MBean on which the listener should
808      * be added.
809      * @param listener The object name of the listener which will
810      * handle the notifications emitted by the registered MBean.
811      * @param filter The filter object. If filter is null, no
812      * filtering will be performed before handling notifications.
813      * @param handback The context to be sent to the listener when a
814      * notification is emitted.
815      *
816      * @exception InstanceNotFoundException The MBean name of the
817      * notification listener or of the notification broadcaster does
818      * not match any of the registered MBeans.
819      * @exception RuntimeOperationsException Wraps an {@link
820      * IllegalArgumentException}. The MBean named by
821      * <code>listener</code> exists but does not implement the {@link
822      * NotificationListener} interface.
823      *
824      * @see #removeNotificationListener(ObjectName, ObjectName)
825      * @see #removeNotificationListener(ObjectName, ObjectName,
826      * NotificationFilter, Object)
827      */
828     public void addNotificationListener(ObjectName name,
829                     ObjectName listener,
830                     NotificationFilter filter,
831                     Object handback)
832         throws InstanceNotFoundException ;
833
834     /**
835      * Removes a listener from a registered MBean.
836      *
837      * <P> If the listener is registered more than once, perhaps with
838      * different filters or callbacks, this method will remove all
839      * those registrations.
840      *
841      * @param name The name of the MBean on which the listener should
842      * be removed.
843      * @param listener The object name of the listener to be removed.
844      *
845      * @exception InstanceNotFoundException The MBean name provided
846      * does not match any of the registered MBeans.
847      * @exception ListenerNotFoundException The listener is not
848      * registered in the MBean.
849      *
850      * @see #addNotificationListener(ObjectName, ObjectName,
851      * NotificationFilter, Object)
852      */
853     public void removeNotificationListener(ObjectName name,
854                        ObjectName listener)
855     throws InstanceNotFoundException , ListenerNotFoundException ;
856
857     /**
858      * <p>Removes a listener from a registered MBean.</p>
859      *
860      * <p>The MBean must have a listener that exactly matches the
861      * given <code>listener</code>, <code>filter</code>, and
862      * <code>handback</code> parameters. If there is more than one
863      * such listener, only one is removed.</p>
864      *
865      * <p>The <code>filter</code> and <code>handback</code> parameters
866      * may be null if and only if they are null in a listener to be
867      * removed.</p>
868      *
869      * @param name The name of the MBean on which the listener should
870      * be removed.
871      * @param listener A listener that was previously added to this
872      * MBean.
873      * @param filter The filter that was specified when the listener
874      * was added.
875      * @param handback The handback that was specified when the
876      * listener was added.
877      *
878      * @exception InstanceNotFoundException The MBean name provided
879      * does not match any of the registered MBeans.
880      * @exception ListenerNotFoundException The listener is not
881      * registered in the MBean, or it is not registered with the given
882      * filter and handback.
883      *
884      * @see #addNotificationListener(ObjectName, ObjectName,
885      * NotificationFilter, Object)
886      *
887      * @since.unbundled JMX 1.2
888      */
889     public void removeNotificationListener(ObjectName name,
890                        ObjectName listener,
891                        NotificationFilter filter,
892                        Object handback)
893         throws InstanceNotFoundException , ListenerNotFoundException ;
894
895
896     /**
897      * <p>Removes a listener from a registered MBean.</p>
898      *
899      * <P> If the listener is registered more than once, perhaps with
900      * different filters or callbacks, this method will remove all
901      * those registrations.
902      *
903      * @param name The name of the MBean on which the listener should
904      * be removed.
905      * @param listener The object name of the listener to be removed.
906      *
907      * @exception InstanceNotFoundException The MBean name provided
908      * does not match any of the registered MBeans.
909      * @exception ListenerNotFoundException The listener is not
910      * registered in the MBean.
911      *
912      * @see #addNotificationListener(ObjectName, NotificationListener,
913      * NotificationFilter, Object)
914      */
915     public void removeNotificationListener(ObjectName name,
916                        NotificationListener listener)
917         throws InstanceNotFoundException , ListenerNotFoundException ;
918
919     /**
920      * <p>Removes a listener from a registered MBean.</p>
921      *
922      * <p>The MBean must have a listener that exactly matches the
923      * given <code>listener</code>, <code>filter</code>, and
924      * <code>handback</code> parameters. If there is more than one
925      * such listener, only one is removed.&l