View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.management;
27  
28  
29  // java import
30  import java.util.Set;
31  import java.io.ObjectInputStream;
32  
33  // RI import
34  import javax.management.loading.ClassLoaderRepository;
35  
36  /**
37   * <p>This is the interface for MBean manipulation on the agent
38   * side. It contains the methods necessary for the creation,
39   * registration, and deletion of MBeans as well as the access methods
40   * for registered MBeans.  This is the core component of the JMX
41   * infrastructure.</p>
42   *
43   * <p>User code does not usually implement this interface.  Instead,
44   * an object that implements this interface is obtained with one of
45   * the methods in the {@link javax.management.MBeanServerFactory} class.</p>
46   *
47   * <p>Every MBean which is added to the MBean server becomes
48   * manageable: its attributes and operations become remotely
49   * accessible through the connectors/adaptors connected to that MBean
50   * server.  A Java object cannot be registered in the MBean server
51   * unless it is a JMX compliant MBean.</p>
52   *
53   * <p id="notif">When an MBean is registered or unregistered in the
54   * MBean server a {@link javax.management.MBeanServerNotification
55   * MBeanServerNotification} Notification is emitted. To register an
56   * object as listener to MBeanServerNotifications you should call the
57   * MBean server method {@link #addNotificationListener
58   * addNotificationListener} with <CODE>ObjectName</CODE> the
59   * <CODE>ObjectName</CODE> of the {@link
60   * javax.management.MBeanServerDelegate MBeanServerDelegate}.  This
61   * <CODE>ObjectName</CODE> is: <BR>
62   * <CODE>JMImplementation:type=MBeanServerDelegate</CODE>.</p>
63   *
64   * <p>An object obtained from the {@link
65   * MBeanServerFactory#createMBeanServer(String) createMBeanServer} or
66   * {@link MBeanServerFactory#newMBeanServer(String) newMBeanServer}
67   * methods of the {@link MBeanServerFactory} class applies security
68   * checks to its methods, as follows.</p>
69   *
70   * <p>First, if there is no security manager ({@link
71   * System#getSecurityManager()} is null), then an implementation of
72   * this interface is free not to make any checks.</p>
73   *
74   * <p>Assuming that there is a security manager, or that the
75   * implementation chooses to make checks anyway, the checks are made
76   * as detailed below.  In what follows, and unless otherwise specified,
77   * {@code className} is the
78   * string returned by {@link MBeanInfo#getClassName()} for the target
79   * MBean.</p>
80   *
81   * <p>If a security check fails, the method throws {@link
82   * SecurityException}.</p>
83   *
84   * <p>For methods that can throw {@link InstanceNotFoundException},
85   * this exception is thrown for a non-existent MBean, regardless of
86   * permissions.  This is because a non-existent MBean has no
87   * <code>className</code>.</p>
88   *
89   * <ul>
90   *
91   * <li><p>For the {@link #invoke invoke} method, the caller's
92   * permissions must imply {@link
93   * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
94   * MBeanPermission(className, operationName, name, "invoke")}.</p>
95   *
96   * <li><p>For the {@link #getAttribute getAttribute} method, the
97   * caller's permissions must imply {@link
98   * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
99   * MBeanPermission(className, attribute, name, "getAttribute")}.</p>
100  *
101  * <li><p>For the {@link #getAttributes getAttributes} method, the
102  * caller's permissions must imply {@link
103  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
104  * MBeanPermission(className, null, name, "getAttribute")}.
105  * Additionally, for each attribute <em>a</em> in the {@link
106  * AttributeList}, if the caller's permissions do not imply {@link
107  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
108  * MBeanPermission(className, <em>a</em>, name, "getAttribute")}, the
109  * MBean server will behave as if that attribute had not been in the
110  * supplied list.</p>
111  *
112  * <li><p>For the {@link #setAttribute setAttribute} method, the
113  * caller's permissions must imply {@link
114  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
115  * MBeanPermission(className, attrName, name, "setAttribute")}, where
116  * <code>attrName</code> is {@link Attribute#getName()
117  * attribute.getName()}.</p>
118  *
119  * <li><p>For the {@link #setAttributes setAttributes} method, the
120  * caller's permissions must imply {@link
121  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
122  * MBeanPermission(className, null, name, "setAttribute")}.
123  * Additionally, for each attribute <em>a</em> in the {@link
124  * AttributeList}, if the caller's permissions do not imply {@link
125  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
126  * MBeanPermission(className, <em>a</em>, name, "setAttribute")}, the
127  * MBean server will behave as if that attribute had not been in the
128  * supplied list.</p>
129  *
130  * <li><p>For the <code>addNotificationListener</code> methods,
131  * the caller's permissions must imply {@link
132  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
133  * MBeanPermission(className, null, name,
134  * "addNotificationListener")}.</p>
135  *
136  * <li><p>For the <code>removeNotificationListener</code> methods,
137  * the caller's permissions must imply {@link
138  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
139  * MBeanPermission(className, null, name,
140  * "removeNotificationListener")}.</p>
141  *
142  * <li><p>For the {@link #getMBeanInfo getMBeanInfo} method, the
143  * caller's permissions must imply {@link
144  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
145  * MBeanPermission(className, null, name, "getMBeanInfo")}.</p>
146  *
147  * <li><p>For the {@link #getObjectInstance getObjectInstance} method,
148  * the caller's permissions must imply {@link
149  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
150  * MBeanPermission(className, null, name, "getObjectInstance")}.</p>
151  *
152  * <li><p>For the {@link #isInstanceOf isInstanceOf} method, the
153  * caller's permissions must imply {@link
154  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
155  * MBeanPermission(className, null, name, "isInstanceOf")}.</p>
156  *
157  * <li><p>For the {@link #queryMBeans queryMBeans} method, the
158  * caller's permissions must imply {@link
159  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
160  * MBeanPermission(null, null, null, "queryMBeans")}.
161  * Additionally, for each MBean <em>n</em> that matches <code>name</code>,
162  * if the caller's permissions do not imply {@link
163  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
164  * MBeanPermission(className, null, <em>n</em>, "queryMBeans")}, the
165  * MBean server will behave as if that MBean did not exist.</p>
166  *
167  * <p>Certain query elements perform operations on the MBean server.
168  * If the caller does not have the required permissions for a given
169  * MBean, that MBean will not be included in the result of the query.
170  * The standard query elements that are affected are {@link
171  * Query#attr(String)}, {@link Query#attr(String,String)}, and {@link
172  * Query#classattr()}.</p>
173  *
174  * <li><p>For the {@link #queryNames queryNames} method, the checks
175  * are the same as for <code>queryMBeans</code> except that
176  * <code>"queryNames"</code> is used instead of
177  * <code>"queryMBeans"</code> in the <code>MBeanPermission</code>
178  * objects.  Note that a <code>"queryMBeans"</code> permission implies
179  * the corresponding <code>"queryNames"</code> permission.</p>
180  *
181  * <li><p>For the {@link #getDomains getDomains} method, the caller's
182  * permissions must imply {@link
183  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
184  * MBeanPermission(null, null, null, "getDomains")}.  Additionally,
185  * for each domain <var>d</var> in the returned array, if the caller's
186  * permissions do not imply {@link
187  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
188  * MBeanPermission(null, null, new ObjectName("<var>d</var>:x=x"),
189  * "getDomains")}, the domain is eliminated from the array.  Here,
190  * <code>x=x</code> is any <var>key=value</var> pair, needed to
191  * satisfy ObjectName's constructor but not otherwise relevant.</p>
192  *
193  * <li><p>For the {@link #getClassLoader getClassLoader} method, the
194  * caller's permissions must imply {@link
195  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
196  * MBeanPermission(className, null, loaderName,
197  * "getClassLoader")}.</p>
198  *
199  * <li><p>For the {@link #getClassLoaderFor getClassLoaderFor} method,
200  * the caller's permissions must imply {@link
201  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
202  * MBeanPermission(className, null, mbeanName,
203  * "getClassLoaderFor")}.</p>
204  *
205  * <li><p>For the {@link #getClassLoaderRepository
206  * getClassLoaderRepository} method, the caller's permissions must
207  * imply {@link
208  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
209  * MBeanPermission(null, null, null, "getClassLoaderRepository")}.</p>
210  *
211  * <li><p>For the deprecated <code>deserialize</code> methods, the
212  * required permissions are the same as for the methods that replace
213  * them.</p>
214  *
215  * <li><p>For the <code>instantiate</code> methods, the caller's
216  * permissions must imply {@link
217  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
218  * MBeanPermission(className, null, null, "instantiate")},
219  * where {@code className} is the name of the class which is to
220  * be instantiated.</p>
221  *
222  * <li><p>For the {@link #registerMBean registerMBean} method, the
223  * caller's permissions must imply {@link
224  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
225  * MBeanPermission(className, null, name, "registerMBean")}.
226  *
227  * <p>If the <code>MBeanPermission</code> check succeeds, the MBean's
228  * class is validated by checking that its {@link
229  * java.security.ProtectionDomain ProtectionDomain} implies {@link
230  * MBeanTrustPermission#MBeanTrustPermission(String)
231  * MBeanTrustPermission("register")}.</p>
232  *
233  * <p>Finally, if the <code>name</code> argument is null, another
234  * <code>MBeanPermission</code> check is made using the
235  * <code>ObjectName</code> returned by {@link
236  * MBeanRegistration#preRegister MBeanRegistration.preRegister}.</p>
237  *
238  * <li><p>For the <code>createMBean</code> methods, the caller's
239  * permissions must imply the permissions needed by the equivalent
240  * <code>instantiate</code> followed by
241  * <code>registerMBean</code>.</p>
242  *
243  * <li><p>For the {@link #unregisterMBean unregisterMBean} method,
244  * the caller's permissions must imply {@link
245  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
246  * MBeanPermission(className, null, name, "unregisterMBean")}.</p>
247  *
248  * </ul>
249  *
250  * @since 1.5
251  */
252 
253 /* DELETED:
254  *
255  * <li><p>For the {@link #isRegistered isRegistered} method, the
256  * caller's permissions must imply {@link
257  * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
258  * MBeanPermission(null, null, name, "isRegistered")}.</p>
259  */
260 public interface MBeanServer extends MBeanServerConnection {
261 
262     /**
263      * {@inheritDoc}
264      * <p>If this method successfully creates an MBean, a notification
265      * is sent as described <a href="#notif">above</a>.</p>
266      *
267      * @throws RuntimeOperationsException {@inheritDoc}
268      * @throws RuntimeMBeanException {@inheritDoc}
269      * @throws RuntimeErrorException {@inheritDoc}
270      */
271     public ObjectInstance createMBean(String className, ObjectName name)
272             throws ReflectionException, InstanceAlreadyExistsException,
273                    MBeanRegistrationException, MBeanException,
274                    NotCompliantMBeanException;
275 
276     /**
277      * {@inheritDoc}
278      * <p>If this method successfully creates an MBean, a notification
279      * is sent as described <a href="#notif">above</a>.</p>
280      *
281      * @throws RuntimeOperationsException {@inheritDoc}
282      * @throws RuntimeMBeanException {@inheritDoc}
283      * @throws RuntimeErrorException {@inheritDoc}
284      */
285     public ObjectInstance createMBean(String className, ObjectName name,
286                                       ObjectName loaderName)
287             throws ReflectionException, InstanceAlreadyExistsException,
288                    MBeanRegistrationException, MBeanException,
289                    NotCompliantMBeanException, InstanceNotFoundException;
290 
291     /**
292      * {@inheritDoc}
293      * <p>If this method successfully creates an MBean, a notification
294      * is sent as described <a href="#notif">above</a>.</p>
295      *
296      * @throws RuntimeOperationsException {@inheritDoc}
297      * @throws RuntimeMBeanException {@inheritDoc}
298      * @throws RuntimeErrorException {@inheritDoc}
299      */
300     public ObjectInstance createMBean(String className, ObjectName name,
301                                       Object params[], String signature[])
302             throws ReflectionException, InstanceAlreadyExistsException,
303                    MBeanRegistrationException, MBeanException,
304                    NotCompliantMBeanException;
305 
306     /**
307      * {@inheritDoc}
308      * <p>If this method successfully creates an MBean, a notification
309      * is sent as described <a href="#notif">above</a>.</p>
310      *
311      * @throws RuntimeOperationsException {@inheritDoc}
312      * @throws RuntimeMBeanException {@inheritDoc}
313      * @throws RuntimeErrorException {@inheritDoc}
314      */
315     public ObjectInstance createMBean(String className, ObjectName name,
316                                       ObjectName loaderName, Object params[],
317                                       String signature[])
318             throws ReflectionException, InstanceAlreadyExistsException,
319                    MBeanRegistrationException, MBeanException,
320                    NotCompliantMBeanException, InstanceNotFoundException;
321 
322     /**
323      * <p>Registers a pre-existing object as an MBean with the MBean
324      * server. If the object name given is null, the MBean must
325      * provide its own name by implementing the {@link
326      * javax.management.MBeanRegistration MBeanRegistration} interface
327      * and returning the name from the {@link
328      * MBeanRegistration#preRegister preRegister} method.
329      *
330      * <p>If this method successfully registers an MBean, a notification
331      * is sent as described <a href="#notif">above</a>.</p>
332      *
333      * @param object The  MBean to be registered as an MBean.
334      * @param name The object name of the MBean. May be null.
335      *
336      * @return An <CODE>ObjectInstance</CODE>, containing the
337      * <CODE>ObjectName</CODE> and the Java class name of the newly
338      * registered MBean.  If the contained <code>ObjectName</code>
339      * is <code>n</code>, the contained Java class name is
340      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
341      *
342      * @exception InstanceAlreadyExistsException The MBean is already
343      * under the control of the MBean server.
344      * @exception MBeanRegistrationException The
345      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
346      * interface) method of the MBean has thrown an exception. The
347      * MBean will not be registered.
348      * @exception RuntimeMBeanException If the <CODE>postRegister</CODE>
349      * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a
350      * <CODE>RuntimeException</CODE>, the <CODE>registerMBean</CODE> method will
351      * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean
352      * registration succeeded. In such a case, the MBean will be actually
353      * registered even though the <CODE>registerMBean</CODE> method
354      * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can
355      * also be thrown by <CODE>preRegister</CODE>, in which case the MBean
356      * will not be registered.
357      * @exception RuntimeErrorException If the <CODE>postRegister</CODE>
358      * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an
359      * <CODE>Error</CODE>, the <CODE>registerMBean</CODE> method will
360      * throw a <CODE>RuntimeErrorException</CODE>, although the MBean
361      * registration succeeded. In such a case, the MBean will be actually
362      * registered even though the <CODE>registerMBean</CODE> method
363      * threw an exception.  Note that <CODE>RuntimeErrorException</CODE> can
364      * also be thrown by <CODE>preRegister</CODE>, in which case the MBean
365      * will not be registered.
366      * @exception NotCompliantMBeanException This object is not a JMX
367      * compliant MBean
368      * @exception RuntimeOperationsException Wraps a
369      * <CODE>java.lang.IllegalArgumentException</CODE>: The object
370      * passed in parameter is null or no object name is specified.
371      * @see javax.management.MBeanRegistration
372      */
373     public ObjectInstance registerMBean(Object object, ObjectName name)
374             throws InstanceAlreadyExistsException, MBeanRegistrationException,
375                    NotCompliantMBeanException;
376 
377     /**
378      * {@inheritDoc}
379      *
380      * <p>If this method successfully unregisters an MBean, a notification
381      * is sent as described <a href="#notif">above</a>.</p>
382      *
383      * @throws RuntimeOperationsException {@inheritDoc}
384      * @throws RuntimeMBeanException {@inheritDoc}
385      * @throws RuntimeErrorException {@inheritDoc}
386      */
387     public void unregisterMBean(ObjectName name)
388             throws InstanceNotFoundException, MBeanRegistrationException;
389 
390     // doc comment inherited from MBeanServerConnection
391     public ObjectInstance getObjectInstance(ObjectName name)
392             throws InstanceNotFoundException;
393 
394     /**
395      * {@inheritDoc}
396       * @throws RuntimeOperationsException {@inheritDoc}
397      */
398     public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query);
399 
400     /**
401      * {@inheritDoc}
402       * @throws RuntimeOperationsException {@inheritDoc}
403     */
404     public Set<ObjectName> queryNames(ObjectName name, QueryExp query);
405 
406     // doc comment inherited from MBeanServerConnection
407     /**
408      * @throws RuntimeOperationsException {@inheritDoc}
409      */
410     public boolean isRegistered(ObjectName name);
411 
412     /**
413      * Returns the number of MBeans registered in the MBean server.
414      *
415      * @return the number of registered MBeans, wrapped in an Integer.
416      * If the caller's permissions are restricted, this number may
417      * be greater than the number of MBeans the caller can access.
418      */
419     public Integer getMBeanCount();
420 
421     // doc comment inherited from MBeanServerConnection
422     /**
423      * @throws RuntimeOperationsException {@inheritDoc}
424      */
425     public Object getAttribute(ObjectName name, String attribute)
426             throws MBeanException, AttributeNotFoundException,
427                    InstanceNotFoundException, ReflectionException;
428 
429     // doc comment inherited from MBeanServerConnection
430     /**
431      * @throws RuntimeOperationsException {@inheritDoc}
432      */
433     public AttributeList getAttributes(ObjectName name, String[] attributes)
434             throws InstanceNotFoundException, ReflectionException;
435 
436     // doc comment inherited from MBeanServerConnection
437     /**
438      * @throws RuntimeOperationsException {@inheritDoc}
439      */
440     public void setAttribute(ObjectName name, Attribute attribute)
441             throws InstanceNotFoundException, AttributeNotFoundException,
442                    InvalidAttributeValueException, MBeanException,
443                    ReflectionException;
444 
445     // doc comment inherited from MBeanServerConnection
446     /**
447      * @throws RuntimeOperationsException {@inheritDoc}
448      */
449     public AttributeList setAttributes(ObjectName name,
450                                        AttributeList attributes)
451         throws InstanceNotFoundException, ReflectionException;
452 
453     // doc comment inherited from MBeanServerConnection
454     public Object invoke(ObjectName name, String operationName,
455                          Object params[], String signature[])
456             throws InstanceNotFoundException, MBeanException,
457                    ReflectionException;
458 
459     // doc comment inherited from MBeanServerConnection
460     public String getDefaultDomain();
461 
462     // doc comment inherited from MBeanServerConnection
463     public String[] getDomains();
464 
465     // doc comment inherited from MBeanServerConnection, plus:
466     /**
467      * {@inheritDoc}
468      * If the source of the notification
469      * is a reference to an MBean object, the MBean server will replace it
470      * by that MBean's ObjectName.  Otherwise the source is unchanged.
471      */
472     public void addNotificationListener(ObjectName name,
473                                         NotificationListener listener,
474                                         NotificationFilter filter,
475                                         Object handback)
476             throws InstanceNotFoundException;
477 
478     /**
479      * {@inheritDoc}
480      * @throws RuntimeOperationsException {@inheritDoc}
481      */
482     public void addNotificationListener(ObjectName name,
483                                         ObjectName listener,
484                                         NotificationFilter filter,
485                                         Object handback)
486             throws InstanceNotFoundException;
487 
488     // doc comment inherited from MBeanServerConnection
489     public void removeNotificationListener(ObjectName name,
490                                            ObjectName listener)
491         throws InstanceNotFoundException, ListenerNotFoundException;
492 
493     // doc comment inherited from MBeanServerConnection
494     public void removeNotificationListener(ObjectName name,
495                                            ObjectName listener,
496                                            NotificationFilter filter,
497                                            Object handback)
498             throws InstanceNotFoundException, ListenerNotFoundException;
499 
500     // doc comment inherited from MBeanServerConnection
501     public void removeNotificationListener(ObjectName name,
502                                            NotificationListener listener)
503             throws InstanceNotFoundException, ListenerNotFoundException;
504 
505     // doc comment inherited from MBeanServerConnection
506     public void removeNotificationListener(ObjectName name,
507                                            NotificationListener listener,
508                                            NotificationFilter filter,
509                                            Object handback)
510             throws InstanceNotFoundException, ListenerNotFoundException;
511 
512     // doc comment inherited from MBeanServerConnection
513     public MBeanInfo getMBeanInfo(ObjectName name)
514             throws InstanceNotFoundException, IntrospectionException,
515                    ReflectionException;
516 
517 
518     // doc comment inherited from MBeanServerConnection
519     public boolean isInstanceOf(ObjectName name, String className)
520             throws InstanceNotFoundException;
521 
522     /**
523      * <p>Instantiates an object using the list of all class loaders
524      * registered in the MBean server's {@link
525      * javax.management.loading.ClassLoaderRepository Class Loader
526      * Repository}.  The object's class should have a public
527      * constructor.  This method returns a reference to the newly
528      * created object.  The newly created object is not registered in
529      * the MBean server.</p>
530      *
531      * <p>This method is equivalent to {@link
532      * #instantiate(String,Object[],String[])
533      * instantiate(className, (Object[]) null, (String[]) null)}.</p>
534      *
535      * @param className The class name of the object to be instantiated.
536      *
537      * @return The newly instantiated object.
538      *
539      * @exception ReflectionException Wraps a
540      * <CODE>java.lang.ClassNotFoundException</CODE> or the
541      * <CODE>java.lang.Exception</CODE> that occurred when trying to
542      * invoke the object's constructor.
543      * @exception MBeanException The constructor of the object has
544      * thrown an exception
545      * @exception RuntimeOperationsException Wraps a
546      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
547      * passed in parameter is null.
548      */
549     public Object instantiate(String className)
550             throws ReflectionException, MBeanException;
551 
552 
553     /**
554      * <p>Instantiates an object using the class Loader specified by its
555      * <CODE>ObjectName</CODE>.  If the loader name is null, the
556      * ClassLoader that loaded the MBean Server will be used.  The
557      * object's class should have a public constructor.  This method
558      * returns a reference to the newly created object.  The newly
559      * created object is not registered in the MBean server.</p>
560      *
561      * <p>This method is equivalent to {@link
562      * #instantiate(String,ObjectName,Object[],String[])
563      * instantiate(className, loaderName, (Object[]) null, (String[])
564      * null)}.</p>
565      *
566      * @param className The class name of the MBean to be instantiated.
567      * @param loaderName The object name of the class loader to be used.
568      *
569      * @return The newly instantiated object.
570      *
571      * @exception ReflectionException Wraps a
572      * <CODE>java.lang.ClassNotFoundException</CODE> or the
573      * <CODE>java.lang.Exception</CODE> that occurred when trying to
574      * invoke the object's constructor.
575      * @exception MBeanException The constructor of the object has
576      * thrown an exception.
577      * @exception InstanceNotFoundException The specified class loader
578      * is not registered in the MBeanServer.
579      * @exception RuntimeOperationsException Wraps a
580      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
581      * passed in parameter is null.
582      */
583     public Object instantiate(String className, ObjectName loaderName)
584             throws ReflectionException, MBeanException,
585                    InstanceNotFoundException;
586 
587     /**
588      * <p>Instantiates an object using the list of all class loaders
589      * registered in the MBean server {@link
590      * javax.management.loading.ClassLoaderRepository Class Loader
591      * Repository}.  The object's class should have a public
592      * constructor.  The call returns a reference to the newly created
593      * object.  The newly created object is not registered in the
594      * MBean server.</p>
595      *
596      * @param className The class name of the object to be instantiated.
597      * @param params An array containing the parameters of the
598      * constructor to be invoked.
599      * @param signature An array containing the signature of the
600      * constructor to be invoked.
601      *
602      * @return The newly instantiated object.
603      *
604      * @exception ReflectionException Wraps a
605      * <CODE>java.lang.ClassNotFoundException</CODE> or the
606      * <CODE>java.lang.Exception</CODE> that occurred when trying to
607      * invoke the object's constructor.
608      * @exception MBeanException The constructor of the object has
609      * thrown an exception
610      * @exception RuntimeOperationsException Wraps a
611      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
612      * passed in parameter is null.
613      */
614     public Object instantiate(String className, Object params[],
615                               String signature[])
616             throws ReflectionException, MBeanException;
617 
618     /**
619      * <p>Instantiates an object. The class loader to be used is
620      * identified by its object name. If the object name of the loader
621      * is null, the ClassLoader that loaded the MBean server will be
622      * used.  The object's class should have a public constructor.
623      * The call returns a reference to the newly created object.  The
624      * newly created object is not registered in the MBean server.</p>
625      *
626      * @param className The class name of the object to be instantiated.
627      * @param params An array containing the parameters of the
628      * constructor to be invoked.
629      * @param signature An array containing the signature of the
630      * constructor to be invoked.
631      * @param loaderName The object name of the class loader to be used.
632      *
633      * @return The newly instantiated object.
634      *
635      * @exception ReflectionException Wraps a <CODE>java.lang.ClassNotFoundException</CODE> or the <CODE>java.lang.Exception</CODE> that
636      * occurred when trying to invoke the object's constructor.
637      * @exception MBeanException The constructor of the object has
638      * thrown an exception
639      * @exception InstanceNotFoundException The specified class loader
640      * is not registered in the MBean server.
641      * @exception RuntimeOperationsException Wraps a
642      * <CODE>java.lang.IllegalArgumentException</CODE>: The className
643      * passed in parameter is null.
644      */
645     public Object instantiate(String className, ObjectName loaderName,
646                               Object params[], String signature[])
647             throws ReflectionException, MBeanException,
648                    InstanceNotFoundException;
649 
650     /**
651      * <p>De-serializes a byte array in the context of the class loader
652      * of an MBean.</p>
653      *
654      * @param name The name of the MBean whose class loader should be
655      * used for the de-serialization.
656      * @param data The byte array to be de-sererialized.
657      *
658      * @return The de-serialized object stream.
659      *
660      * @exception InstanceNotFoundException The MBean specified is not
661      * found.
662      * @exception OperationsException Any of the usual Input/Output
663      * related exceptions.
664      *
665      * @deprecated Use {@link #getClassLoaderFor getClassLoaderFor} to
666      * obtain the appropriate class loader for deserialization.
667      */
668     @Deprecated
669     public ObjectInputStream deserialize(ObjectName name, byte[] data)
670             throws InstanceNotFoundException, OperationsException;
671 
672 
673     /**
674      * <p>De-serializes a byte array in the context of a given MBean
675      * class loader.  The class loader is found by loading the class
676      * <code>className</code> through the {@link
677      * javax.management.loading.ClassLoaderRepository Class Loader
678      * Repository}.  The resultant class's class loader is the one to
679      * use.
680      *
681      * @param className The name of the class whose class loader should be
682      * used for the de-serialization.
683      * @param data The byte array to be de-sererialized.
684      *
685      * @return  The de-serialized object stream.
686      *
687      * @exception OperationsException Any of the usual Input/Output
688      * related exceptions.
689      * @exception ReflectionException The specified class could not be
690      * loaded by the class loader repository
691      *
692      * @deprecated Use {@link #getClassLoaderRepository} to obtain the
693      * class loader repository and use it to deserialize.
694      */
695     @Deprecated
696     public ObjectInputStream deserialize(String className, byte[] data)
697             throws OperationsException, ReflectionException;
698 
699 
700     /**
701      * <p>De-serializes a byte array in the context of a given MBean
702      * class loader.  The class loader is the one that loaded the
703      * class with name "className".  The name of the class loader to
704      * be used for loading the specified class is specified.  If null,
705      * the MBean Server's class loader will be used.</p>
706      *
707      * @param className The name of the class whose class loader should be
708      * used for the de-serialization.
709      * @param data The byte array to be de-sererialized.
710      * @param loaderName The name of the class loader to be used for
711      * loading the specified class.  If null, the MBean Server's class
712      * loader will be used.
713      *
714      * @return  The de-serialized object stream.
715      *
716      * @exception InstanceNotFoundException The specified class loader
717      * MBean is not found.
718      * @exception OperationsException Any of the usual Input/Output
719      * related exceptions.
720      * @exception ReflectionException The specified class could not be
721      * loaded by the specified class loader.
722      *
723      * @deprecated Use {@link #getClassLoader getClassLoader} to obtain
724      * the class loader for deserialization.
725      */
726     @Deprecated
727     public ObjectInputStream deserialize(String className,
728                                          ObjectName loaderName,
729                                          byte[] data)
730             throws InstanceNotFoundException, OperationsException,
731                    ReflectionException;
732 
733     /**
734      * <p>Return the {@link java.lang.ClassLoader} that was used for
735      * loading the class of the named MBean.</p>
736      *
737      * @param mbeanName The ObjectName of the MBean.
738      *
739      * @return The ClassLoader used for that MBean.  If <var>l</var>
740      * is the MBean's actual ClassLoader, and <var>r</var> is the
741      * returned value, then either:
742      *
743      * <ul>
744      * <li><var>r</var> is identical to <var>l</var>; or
745      * <li>the result of <var>r</var>{@link
746      * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
747      * same as <var>l</var>{@link ClassLoader#loadClass(String)
748      * .loadClass(<var>s</var>)} for any string <var>s</var>.
749      * </ul>
750      *
751      * What this means is that the ClassLoader may be wrapped in
752      * another ClassLoader for security or other reasons.
753      *
754      * @exception InstanceNotFoundException if the named MBean is not found.
755      *
756      */
757     public ClassLoader getClassLoaderFor(ObjectName mbeanName)
758         throws InstanceNotFoundException;
759 
760     /**
761      * <p>Return the named {@link java.lang.ClassLoader}.</p>
762      *
763      * @param loaderName The ObjectName of the ClassLoader.  May be
764      * null, in which case the MBean server's own ClassLoader is
765      * returned.
766      *
767      * @return The named ClassLoader.  If <var>l</var> is the actual
768      * ClassLoader with that name, and <var>r</var> is the returned
769      * value, then either:
770      *
771      * <ul>
772      * <li><var>r</var> is identical to <var>l</var>; or
773      * <li>the result of <var>r</var>{@link
774      * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
775      * same as <var>l</var>{@link ClassLoader#loadClass(String)
776      * .loadClass(<var>s</var>)} for any string <var>s</var>.
777      * </ul>
778      *
779      * What this means is that the ClassLoader may be wrapped in
780      * another ClassLoader for security or other reasons.
781      *
782      * @exception InstanceNotFoundException if the named ClassLoader is
783      *    not found.
784      *
785      */
786     public ClassLoader getClassLoader(ObjectName loaderName)
787         throws InstanceNotFoundException;
788 
789     /**
790      * <p>Return the ClassLoaderRepository for this MBeanServer.
791      * @return The ClassLoaderRepository for this MBeanServer.
792      *
793      */
794     public ClassLoaderRepository getClassLoaderRepository();
795 }