KickJava   Java API By Example, From Geeks To Geeks.

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 JavaDoc;
13 import java.io.ObjectInputStream JavaDoc;
14
15 // RI import
16 import javax.management.loading.ClassLoaderRepository JavaDoc;
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 JavaDoc {
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 JavaDoc createMBean(String JavaDoc className, ObjectName JavaDoc name)
286         throws ReflectionException JavaDoc, InstanceAlreadyExistsException JavaDoc,
287            MBeanRegistrationException JavaDoc, MBeanException JavaDoc,
288            NotCompliantMBeanException JavaDoc;
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 JavaDoc createMBean(String JavaDoc className, ObjectName JavaDoc name,
339                       ObjectName JavaDoc loaderName)
340         throws ReflectionException JavaDoc, InstanceAlreadyExistsException JavaDoc,
341            MBeanRegistrationException JavaDoc, MBeanException JavaDoc,
342            NotCompliantMBeanException JavaDoc, InstanceNotFoundException JavaDoc;
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 JavaDoc createMBean(String JavaDoc className, ObjectName JavaDoc name,
391                       Object JavaDoc params[], String JavaDoc signature[])
392         throws ReflectionException JavaDoc, InstanceAlreadyExistsException JavaDoc,
393                MBeanRegistrationException JavaDoc, MBeanException JavaDoc,
394                NotCompliantMBeanException JavaDoc;
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 JavaDoc createMBean(String JavaDoc className, ObjectName JavaDoc name,
445                       ObjectName JavaDoc loaderName, Object JavaDoc params[],
446                       String JavaDoc signature[])
447         throws ReflectionException JavaDoc, InstanceAlreadyExistsException JavaDoc,
448                MBeanRegistrationException JavaDoc, MBeanException JavaDoc,
449                NotCompliantMBeanException JavaDoc, InstanceNotFoundException JavaDoc;
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 JavaDoc registerMBean(Object JavaDoc object, ObjectName JavaDoc name)
481         throws InstanceAlreadyExistsException JavaDoc, MBeanRegistrationException JavaDoc,
482            NotCompliantMBeanException JavaDoc;
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 JavaDoc name)
505         throws InstanceNotFoundException JavaDoc, MBeanRegistrationException JavaDoc;
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 JavaDoc getObjectInstance(ObjectName JavaDoc name)
522         throws InstanceNotFoundException JavaDoc;
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 JavaDoc queryMBeans(ObjectName JavaDoc name, QueryExp JavaDoc 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 JavaDoc queryNames(ObjectName JavaDoc name, QueryExp JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getAttribute(ObjectName JavaDoc name, String JavaDoc attribute)
625         throws MBeanException JavaDoc, AttributeNotFoundException JavaDoc,
626                InstanceNotFoundException JavaDoc, ReflectionException JavaDoc;
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 JavaDoc getAttributes(ObjectName JavaDoc name, String JavaDoc[] attributes)
649         throws InstanceNotFoundException JavaDoc, ReflectionException JavaDoc;
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 JavaDoc name, Attribute JavaDoc attribute)
679         throws InstanceNotFoundException JavaDoc, AttributeNotFoundException JavaDoc,
680            InvalidAttributeValueException JavaDoc, MBeanException JavaDoc,
681            ReflectionException JavaDoc;
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 JavaDoc setAttributes(ObjectName JavaDoc name,
708                        AttributeList JavaDoc attributes)
709     throws InstanceNotFoundException JavaDoc, ReflectionException JavaDoc;
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 JavaDoc invoke(ObjectName JavaDoc name, String JavaDoc operationName,
736              Object JavaDoc params[], String JavaDoc signature[])
737         throws InstanceNotFoundException JavaDoc, MBeanException JavaDoc,
738            ReflectionException JavaDoc;
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 JavaDoc 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 JavaDoc[] 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 JavaDoc name,
788                     NotificationListener JavaDoc listener,
789                     NotificationFilter JavaDoc filter,
790                     Object JavaDoc handback)
791         throws InstanceNotFoundException JavaDoc;
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 JavaDoc name,
829                     ObjectName JavaDoc listener,
830                     NotificationFilter JavaDoc filter,
831                     Object JavaDoc handback)
832         throws InstanceNotFoundException JavaDoc;
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 JavaDoc name,
854                        ObjectName JavaDoc listener)
855     throws InstanceNotFoundException JavaDoc, ListenerNotFoundException JavaDoc;
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 JavaDoc name,
890                        ObjectName JavaDoc listener,
891                        NotificationFilter JavaDoc filter,
892                        Object JavaDoc handback)
893         throws InstanceNotFoundException JavaDoc, ListenerNotFoundException JavaDoc;
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 JavaDoc name,
916                        NotificationListener JavaDoc listener)
917         throws InstanceNotFoundException JavaDoc, ListenerNotFoundException JavaDoc;
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.</p>
926      *
927      * <p>The <code>filter</code> and <code>handback</code> parameters
928      * may be null if and only if they are null in a listener to be
929      * removed.</p>
930      *
931      * @param name The name of the MBean on which the listener should
932      * be removed.
933      * @param listener A listener that was previously added to this
934      * MBean.
935      * @param filter The filter that was specified when the listener
936      * was added.
937      * @param handback The handback that was specified when the
938      * listener was added.
939      *
940      * @exception InstanceNotFoundException The MBean name provided
941      * does not match any of the registered MBeans.
942      * @exception ListenerNotFoundException The listener is not
943      * registered in the MBean, or it is not registered with the given
944      * filter and handback.
945      *
946      * @see #addNotificationListener(ObjectName, NotificationListener,
947      * NotificationFilter, Object)
948      *
949      * @since.unbundled JMX 1.2
950      */
951     public void removeNotificationListener(ObjectName JavaDoc name,
952                        NotificationListener JavaDoc listener,
953                        NotificationFilter JavaDoc filter,
954                        Object JavaDoc handback)
955         throws InstanceNotFoundException JavaDoc, ListenerNotFoundException JavaDoc;
956
957     /**
958      * This method discovers the attributes and operations that an
959      * MBean exposes for management.
960      *
961      * @param name The name of the MBean to analyze
962      *
963      * @return An instance of <CODE>MBeanInfo</CODE> allowing the
964      * retrieval of all attributes and operations of this MBean.
965      *
966      * @exception IntrospectionException An exception occurred during
967      * introspection.
968      * @exception InstanceNotFoundException The MBean specified was
969      * not found.
970      * @exception ReflectionException An exception occurred when
971      * trying to invoke the getMBeanInfo of a Dynamic MBean.
972      */
973     public MBeanInfo JavaDoc getMBeanInfo(ObjectName JavaDoc name)
974         throws InstanceNotFoundException JavaDoc, IntrospectionException JavaDoc,
975                ReflectionException JavaDoc;
976
977  
978     /**
979      * <p>Returns true if the MBean specified is an instance of the
980      * specified class, false otherwise.</p>
981      *
982      * <p>If <code>name</code> does not name an MBean, this method
983      * throws {@link InstanceNotFoundException}.</p>
984      *
985      * <p>Otherwise, let<br>
986      * X be the MBean named by <code>name</code>,<br>
987      * L be the ClassLoader of X,<br>
988      * N be the class name in X's {@link MBeanInfo}.</p>
989      *
990      * <p>If N equals <code>className</code>, the result is true.</p>
991      *
992      * <p>Otherwise, if L successfully loads both N and
993      * <code>className</code>, and the second class is assignable from
994      * the first, the result is true.</p>
995      *
996      * <p>Otherwise, the result is false.</p>
997      *
998      * @param name The <CODE>ObjectName</CODE> of the MBean.
999      * @param className The name of the class.
1000     *
1001     * @return true if the MBean specified is an instance of the
1002     * specified class according to the rules above, false otherwise.
1003     *
1004     * @exception InstanceNotFoundException The MBean specified is not
1005     * registered in the MBean server.
1006     *
1007     * @see Class#isAssignableFrom(Class)
1008     */
1009    public boolean isInstanceOf(ObjectName JavaDoc name, String JavaDoc className)
1010        throws InstanceNotFoundException JavaDoc;
1011
1012    /**
1013     * <p>Instantiates an object using the list of all class loaders
1014     * registered in the MBean server's {@link
1015     * javax.management.loading.ClassLoaderRepository Class Loader
1016     * Repository}. The object's class should have a public
1017     * constructor. This method returns a reference to the newly
1018     * created object. The newly created object is not registered in
1019     * the MBean server.</p>
1020     *
1021     * <p>This method is equivalent to {@link
1022     * #instantiate(String,Object[],String[])
1023     * instantiate(className, (Object[]) null, (String[]) null)}.</p>
1024     *
1025     * @param className The class name of the object to be instantiated.
1026     *
1027     * @return The newly instantiated object.
1028     *
1029     * @exception ReflectionException Wraps a
1030     * <CODE>java.lang.ClassNotFoundException</CODE> or the
1031     * <CODE>java.lang.Exception</CODE> that occurred when trying to
1032     * invoke the object's constructor.
1033     * @exception MBeanException The constructor of the object has
1034     * thrown an exception
1035     * @exception RuntimeOperationsException Wraps a
1036     * <CODE>java.lang.IllegalArgumentException</CODE>: The className
1037     * passed in parameter is null.
1038     */
1039    public Object JavaDoc instantiate(String JavaDoc className)
1040        throws ReflectionException JavaDoc, MBeanException JavaDoc;
1041
1042
1043    /**
1044     * <p>Instantiates an object using the class Loader specified by its
1045     * <CODE>ObjectName</CODE>. If the loader name is null, the
1046     * ClassLoader that loaded the MBean Server will be used. The
1047     * object's class should have a public constructor. This method
1048     * returns a reference to the newly created object. The newly
1049     * created object is not registered in the MBean server.</p>
1050     *
1051     * <p>This method is equivalent to {@link
1052     * #instantiate(String,ObjectName,Object[],String[])
1053     * instantiate(className, loaderName, (Object[]) null, (String[])
1054     * null)}.</p>
1055     *
1056     * @param className The class name of the MBean to be instantiated.
1057     * @param loaderName The object name of the class loader to be used.
1058     *
1059     * @return The newly instantiated object.
1060     *
1061     * @exception ReflectionException Wraps a
1062     * <CODE>java.lang.ClassNotFoundException</CODE> or the
1063     * <CODE>java.lang.Exception</CODE> that occurred when trying to
1064     * invoke the object's constructor.
1065     * @exception MBeanException The constructor of the object has
1066     * thrown an exception.
1067     * @exception InstanceNotFoundException The specified class loader
1068     * is not registered in the MBeanServer.
1069     * @exception RuntimeOperationsException Wraps a
1070     * <CODE>java.lang.IllegalArgumentException</CODE>: The className
1071     * passed in parameter is null.
1072     */
1073    public Object JavaDoc instantiate(String JavaDoc className, ObjectName JavaDoc loaderName)
1074        throws ReflectionException JavaDoc, MBeanException JavaDoc,
1075           InstanceNotFoundException JavaDoc;
1076
1077    /**
1078     * <p>Instantiates an object using the list of all class loaders
1079     * registered in the MBean server {@link
1080     * javax.management.loading.ClassLoaderRepository Class Loader
1081     * Repository}. The object's class should have a public
1082     * constructor. The call returns a reference to the newly created
1083     * object. The newly created object is not registered in the
1084     * MBean server.</p>
1085     *
1086     * @param className The class name of the object to be instantiated.
1087     * @param params An array containing the parameters of the
1088     * constructor to be invoked.
1089     * @param signature An array containing the signature of the
1090     * constructor to be invoked.
1091     *
1092     * @return The newly instantiated object.
1093     *
1094     * @exception ReflectionException Wraps a
1095     * <CODE>java.lang.ClassNotFoundException</CODE> or the
1096     * <CODE>java.lang.Exception</CODE> that occurred when trying to
1097     * invoke the object's constructor.
1098     * @exception MBeanException The constructor of the object has
1099     * thrown an exception
1100     * @exception RuntimeOperationsException Wraps a
1101     * <CODE>java.lang.IllegalArgumentException</CODE>: The className
1102     * passed in parameter is null.
1103     */
1104    public Object JavaDoc instantiate(String JavaDoc className, Object JavaDoc params[],
1105                  String JavaDoc signature[])
1106        throws ReflectionException JavaDoc, MBeanException JavaDoc;
1107
1108    /**
1109     * <p>Instantiates an object. The class loader to be used is
1110     * identified by its object name. If the object name of the loader
1111     * is null, the ClassLoader that loaded the MBean server will be
1112     * used. The object's class should have a public constructor.
1113     * The call returns a reference to the newly created object. The
1114     * newly created object is not registered in the MBean server.</p>
1115     *
1116     * @param className The class name of the object to be instantiated.
1117     * @param params An array containing the parameters of the
1118     * constructor to be invoked.
1119     * @param signature An array containing the signature of the
1120     * constructor to be invoked.
1121     * @param loaderName The object name of the class loader to be used.
1122     *
1123     * @return The newly instantiated object.
1124     *
1125     * @exception ReflectionException Wraps a <CODE>java.lang.ClassNotFoundException</CODE> or the <CODE>java.lang.Exception</CODE> that
1126     * occurred when trying to invoke the object's constructor.
1127     * @exception MBeanException The constructor of the object has
1128     * thrown an exception
1129     * @exception InstanceNotFoundException The specified class loader
1130     * is not registered in the MBean server.
1131     * @exception RuntimeOperationsException Wraps a
1132     * <CODE>java.lang.IllegalArgumentException</CODE>: The className
1133     * passed in parameter is null.
1134     */
1135    public Object JavaDoc instantiate(String JavaDoc className, ObjectName JavaDoc loaderName,
1136                  Object JavaDoc params[], String JavaDoc signature[])
1137        throws ReflectionException JavaDoc, MBeanException JavaDoc,
1138           InstanceNotFoundException JavaDoc;
1139
1140    /**
1141     * <p>De-serializes a byte array in the context of the class loader
1142     * of an MBean.</p>
1143     *
1144     * @param name The name of the MBean whose class loader should be
1145     * used for the de-serialization.
1146     * @param data The byte array to be de-sererialized.
1147     *
1148     * @return The de-serialized object stream.
1149     *
1150     * @exception InstanceNotFoundException The MBean specified is not
1151     * found.
1152     * @exception OperationsException Any of the usual Input/Output
1153     * related exceptions.
1154     *
1155     * @deprecated Use {@link #getClassLoaderFor getClassLoaderFor} to
1156     * obtain the appropriate class loader for deserialization.
1157     */
1158    @Deprecated JavaDoc
1159    public ObjectInputStream JavaDoc deserialize(ObjectName JavaDoc name, byte[] data)
1160        throws InstanceNotFoundException JavaDoc, OperationsException JavaDoc;
1161
1162
1163    /**
1164     * <p>De-serializes a byte array in the context of a given MBean
1165     * class loader. The class loader is found by loading the class
1166     * <code>className</code> through the {@link
1167     * javax.management.loading.ClassLoaderRepository Class Loader
1168     * Repository}. The resultant class's class loader is the one to
1169     * use.
1170     *
1171     * @param className The name of the class whose class loader should be
1172     * used for the de-serialization.
1173     * @param data The byte array to be de-sererialized.
1174     *
1175     * @return The de-serialized object stream.
1176     *
1177     * @exception OperationsException Any of the usual Input/Output
1178     * related exceptions.
1179     * @exception ReflectionException The specified class could not be
1180     * loaded by the class loader repository
1181     *
1182     * @deprecated Use {@link #getClassLoaderRepository} to obtain the
1183     * class loader repository and use it to deserialize.
1184     */
1185    @Deprecated JavaDoc
1186    public ObjectInputStream JavaDoc deserialize(String JavaDoc className, byte[] data)
1187        throws OperationsException JavaDoc, ReflectionException JavaDoc;
1188
1189   
1190    /**
1191     * <p>De-serializes a byte array in the context of a given MBean
1192     * class loader. The class loader is the one that loaded the
1193     * class with name "className". The name of the class loader to
1194     * be used for loading the specified class is specified. If null,
1195     * the MBean Server's class loader will be used.</p>
1196     *
1197     * @param className The name of the class whose class loader should be
1198     * used for the de-serialization.
1199     * @param data The byte array to be de-sererialized.
1200     * @param loaderName The name of the class loader to be used for
1201     * loading the specified class. If null, the MBean Server's class
1202     * loader will be used.
1203     *
1204     * @return The de-serialized object stream.
1205     *
1206     * @exception InstanceNotFoundException The specified class loader
1207     * MBean is not found.
1208     * @exception OperationsException Any of the usual Input/Output
1209     * related exceptions.
1210     * @exception ReflectionException The specified class could not be
1211     * loaded by the specified class loader.
1212     *
1213     * @deprecated Use {@link #getClassLoader getClassLoader} to obtain
1214     * the class loader for deserialization.
1215     */
1216    @Deprecated JavaDoc
1217    public ObjectInputStream JavaDoc deserialize(String JavaDoc className,
1218                     ObjectName JavaDoc loaderName,
1219                     byte[] data)
1220        throws InstanceNotFoundException JavaDoc, OperationsException JavaDoc,
1221           ReflectionException JavaDoc;
1222
1223    /**
1224     * <p>Return the {@link java.lang.ClassLoader} that was used for
1225     * loading the class of the named MBean.</p>
1226     *
1227     * @param mbeanName The ObjectName of the MBean.
1228     *
1229     * @return The ClassLoader used for that MBean. If <var>l</var>
1230     * is the MBean's actual ClassLoader, and <var>r</var> is the
1231     * returned value, then either:
1232     *
1233     * <ul>
1234     * <li><var>r</var> is identical to <var>l</var>; or
1235     * <li>the result of <var>r</var>{@link
1236     * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
1237     * same as <var>l</var>{@link ClassLoader#loadClass(String)
1238     * .loadClass(<var>s</var>)} for any string <var>s</var>.
1239     * </ul>
1240     *
1241     * What this means is that the ClassLoader may be wrapped in
1242     * another ClassLoader for security or other reasons.
1243     *
1244     * @exception InstanceNotFoundException if the named MBean is not found.
1245     *
1246     * @since.unbundled JMX 1.2
1247     */
1248    public ClassLoader JavaDoc getClassLoaderFor(ObjectName JavaDoc mbeanName)
1249    throws InstanceNotFoundException JavaDoc;
1250
1251    /**
1252     * <p>Return the named {@link java.lang.ClassLoader}.</p>
1253     *
1254     * @param loaderName The ObjectName of the ClassLoader. May be
1255     * null, in which case the MBean server's own ClassLoader is
1256     * returned.
1257     *
1258     * @return The named ClassLoader. If <var>l</var> is the actual
1259     * ClassLoader with that name, and <var>r</var> is the returned
1260     * value, then either:
1261     *
1262     * <ul>
1263     * <li><var>r</var> is identical to <var>l</var>; or
1264     * <li>the result of <var>r</var>{@link
1265     * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
1266     * same as <var>l</var>{@link ClassLoader#loadClass(String)
1267     * .loadClass(<var>s</var>)} for any string <var>s</var>.
1268     * </ul>
1269     *
1270     * What this means is that the ClassLoader may be wrapped in
1271     * another ClassLoader for security or other reasons.
1272     *
1273     * @exception InstanceNotFoundException if the named ClassLoader is
1274     * not found.
1275     *
1276     * @since.unbundled JMX 1.2
1277     */
1278    public ClassLoader JavaDoc getClassLoader(ObjectName JavaDoc loaderName)
1279    throws InstanceNotFoundException JavaDoc;
1280
1281    /**
1282     * <p>Return the ClassLoaderRepository for this MBeanServer.
1283     * @return The ClassLoaderRepository for this MBeanServer.
1284     *
1285     * @since.unbundled JMX 1.2
1286     */
1287    public ClassLoaderRepository JavaDoc getClassLoaderRepository();
1288}
1289
Popular Tags