1 /*
2 * Copyright 1999-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 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 MBean server
54 * 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, <code>className</code> is the
77 * string returned by {@link MBeanInfo#getClassName()} for the target
78 * MBean.</p>
79 *
80 * <p>If a security check fails, the method throws {@link
81 * SecurityException}.</p>
82 *
83 * <p>For methods that can throw {@link InstanceNotFoundException},
84 * this exception is thrown for a non-existent MBean, regardless of
85 * permissions. This is because a non-existent MBean has no
86 * <code>className</code>.</p>
87 *
88 * <ul>
89 *
90 * <li><p>For the {@link #invoke invoke} method, the caller's
91 * permissions must imply {@link
92 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
93 * MBeanPermission(className, operationName, name, "invoke")}.</p>
94 *
95 * <li><p>For the {@link #getAttribute getAttribute} method, the
96 * caller's permissions must imply {@link
97 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
98 * MBeanPermission(className, attribute, name, "getAttribute")}.</p>
99 *
100 * <li><p>For the {@link #getAttributes getAttributes} method, the
101 * caller's permissions must imply {@link
102 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
103 * MBeanPermission(className, null, name, "getAttribute")}.
104 * Additionally, for each attribute <em>a</em> in the {@link
105 * AttributeList}, if the caller's permissions do not imply {@link
106 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
107 * MBeanPermission(className, <em>a</em>, name, "getAttribute")}, the
108 * MBean server will behave as if that attribute had not been in the
109 * supplied list.</p>
110 *
111 * <li><p>For the {@link #setAttribute setAttribute} method, the
112 * caller's permissions must imply {@link
113 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
114 * MBeanPermission(className, attrName, name, "setAttribute")}, where
115 * <code>attrName</code> is {@link Attribute#getName()
116 * attribute.getName()}.</p>
117 *
118 * <li><p>For the {@link #setAttributes setAttributes} method, the
119 * caller's permissions must imply {@link
120 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
121 * MBeanPermission(className, null, name, "setAttribute")}.
122 * Additionally, for each attribute <em>a</em> in the {@link
123 * AttributeList}, if the caller's permissions do not imply {@link
124 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
125 * MBeanPermission(className, <em>a</em>, name, "setAttribute")}, the
126 * MBean server will behave as if that attribute had not been in the
127 * supplied list.</p>
128 *
129 * <li><p>For the <code>addNotificationListener</code> methods,
130 * the caller's permissions must imply {@link
131 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
132 * MBeanPermission(className, null, name,
133 * "addNotificationListener")}.</p>
134 *
135 * <li><p>For the <code>removeNotificationListener</code> methods,
136 * the caller's permissions must imply {@link
137 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
138 * MBeanPermission(className, null, name,
139 * "removeNotificationListener")}.</p>
140 *
141 * <li><p>For the {@link #getMBeanInfo getMBeanInfo} method, the
142 * caller's permissions must imply {@link
143 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
144 * MBeanPermission(className, null, name, "getMBeanInfo")}.</p>
145 *
146 * <li><p>For the {@link #getObjectInstance getObjectInstance} method,
147 * the caller's permissions must imply {@link
148 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
149 * MBeanPermission(className, null, name, "getObjectInstance")}.</p>
150 *
151 * <li><p>For the {@link #isInstanceOf isInstanceOf} method, the
152 * caller's permissions must imply {@link
153 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
154 * MBeanPermission(className, null, name, "isInstanceOf")}.</p>
155 *
156 * <li><p>For the {@link #queryMBeans queryMBeans} method, the
157 * caller's permissions must imply {@link
158 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
159 * MBeanPermission(null, null, name, "queryMBeans")}.
160 * Additionally, for each MBean that matches <code>name</code>,
161 * if the caller's permissions do not imply {@link
162 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
163 * MBeanPermission(className, null, name, "queryMBeans")}, the
164 * MBean server will behave as if that MBean did not exist.</p>
165 *
166 * <p>Certain query elements perform operations on the MBean server.
167 * If the caller does not have the required permissions for a given
168 * MBean, that MBean will not be included in the result of the query.
169 * The standard query elements that are affected are {@link
170 * Query#attr(String)}, {@link Query#attr(String,String)}, and {@link
171 * Query#classattr()}.</p>
172 *
173 * <li><p>For the {@link #queryNames queryNames} method, the checks
174 * are the same as for <code>queryMBeans</code> except that
175 * <code>"queryNames"</code> is used instead of
176 * <code>"queryMBeans"</code> in the <code>MBeanPermission</code>
177 * objects. Note that a <code>"queryMBeans"</code> permission implies
178 * the corresponding <code>"queryNames"</code> permission.</p>
179 *
180 * <li><p>For the {@link #getDomains getDomains} method, the caller's
181 * permissions must imply {@link
182 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
183 * MBeanPermission(null, null, name, "getDomains")}. Additionally,
184 * for each domain <var>d</var> in the returned array, if the caller's
185 * permissions do not imply {@link
186 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
187 * MBeanPermission(null, null, new ObjectName("<var>d</var>:x=x"),
188 * "getDomains")}, the domain is eliminated from the array. Here,
189 * <code>x=x</code> is any <var>key=value</var> pair, needed to
190 * satisfy ObjectName's constructor but not otherwise relevant.</p>
191 *
192 * <li><p>For the {@link #getClassLoader getClassLoader} method, the
193 * caller's permissions must imply {@link
194 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
195 * MBeanPermission(className, null, loaderName,
196 * "getClassLoader")}.</p>
197 *
198 * <li><p>For the {@link #getClassLoaderFor getClassLoaderFor} method,
199 * the caller's permissions must imply {@link
200 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
201 * MBeanPermission(className, null, mbeanName,
202 * "getClassLoaderFor")}.</p>
203 *
204 * <li><p>For the {@link #getClassLoaderRepository
205 * getClassLoaderRepository} method, the caller's permissions must
206 * imply {@link
207 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
208 * MBeanPermission(null, null, null, "getClassLoaderRepository")}.</p>
209 *
210 * <li><p>For the deprecated <code>deserialize</code> methods, the
211 * required permissions are the same as for the methods that replace
212 * them.</p>
213 *
214 * <li><p>For the <code>instantiate</code> methods, the caller's
215 * permissions must imply {@link
216 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
217 * MBeanPermission(className, null, null, "instantiate")}.</p>
218 *
219 * <li><p>For the {@link #registerMBean registerMBean} method, the
220 * caller's permissions must imply {@link
221 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
222 * MBeanPermission(className, null, name, "registerMBean")}. Here
223 * <code>className</code> is the string returned by {@link
224 * MBeanInfo#getClassName()} for an object of this class.
225 *
226 * <p>If the <code>MBeanPermission</code> check succeeds, the MBean's
227 * class is validated by checking that its {@link
228 * java.security.ProtectionDomain ProtectionDomain} implies {@link
229 * MBeanTrustPermission#MBeanTrustPermission(String)
230 * MBeanTrustPermission("register")}.</p>
231 *
232 * <p>Finally, if the <code>name</code> argument is null, another
233 * <code>MBeanPermission</code> check is made using the
234 * <code>ObjectName</code> returned by {@link
235 * MBeanRegistration#preRegister MBeanRegistration.preRegister}.</p>
236 *
237 * <li><p>For the <code>createMBean</code> methods, the caller's
238 * permissions must imply the permissions needed by the equivalent
239 * <code>instantiate</code> followed by
240 * <code>registerMBean</code>.</p>
241 *
242 * <li><p>For the {@link #unregisterMBean unregisterMBean} method,
243 * the caller's permissions must imply {@link
244 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
245 * MBeanPermission(className, null, name, "unregisterMBean")}.</p>
246 *
247 * </ul>
248 *
249 * @since 1.5
250 */
251
252 /* DELETED:
253 *
254 * <li><p>For the {@link #isRegistered isRegistered} method, the
255 * caller's permissions must imply {@link
256 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
257 * MBeanPermission(null, null, name, "isRegistered")}.</p>
258 */
259 public interface MBeanServer extends MBeanServerConnection {
260
261 /**
262 * {@inheritDoc}
263 * <p>If this method successfully creates an MBean, a notification
264 * is sent as described <a href="#notif">above</a>.</p>
265 */
266 public ObjectInstance createMBean(String className, ObjectName name)
267 throws ReflectionException, InstanceAlreadyExistsException,
268 MBeanRegistrationException, MBeanException,
269 NotCompliantMBeanException;
270
271 /**
272 * {@inheritDoc}
273 * <p>If this method successfully creates an MBean, a notification
274 * is sent as described <a href="#notif">above</a>.</p>
275 */
276 public ObjectInstance createMBean(String className, ObjectName name,
277 ObjectName loaderName)
278 throws ReflectionException, InstanceAlreadyExistsException,
279 MBeanRegistrationException, MBeanException,
280 NotCompliantMBeanException, InstanceNotFoundException;
281
282 /**
283 * {@inheritDoc}
284 * <p>If this method successfully creates an MBean, a notification
285 * is sent as described <a href="#notif">above</a>.</p>
286 */
287 public ObjectInstance createMBean(String className, ObjectName name,
288 Object params[], String signature[])
289 throws ReflectionException, InstanceAlreadyExistsException,
290 MBeanRegistrationException, MBeanException,
291 NotCompliantMBeanException;
292
293 /**
294 * {@inheritDoc}
295 * <p>If this method successfully creates an MBean, a notification
296 * is sent as described <a href="#notif">above</a>.</p>
297 */
298 public ObjectInstance createMBean(String className, ObjectName name,
299 ObjectName loaderName, Object params[],
300 String signature[])
301 throws ReflectionException, InstanceAlreadyExistsException,
302 MBeanRegistrationException, MBeanException,
303 NotCompliantMBeanException, InstanceNotFoundException;
304
305 /**
306 * <p>Registers a pre-existing object as an MBean with the MBean
307 * server. If the object name given is null, the MBean must
308 * provide its own name by implementing the {@link
309 * javax.management.MBeanRegistration MBeanRegistration} interface
310 * and returning the name from the {@link
311 * MBeanRegistration#preRegister preRegister} method.</p>
312 *
313 * <p>If this method successfully registers an MBean, a notification
314 * is sent as described <a href="#notif">above</a>.</p>
315 *
316 * @param object The MBean to be registered as an MBean.
317 * @param name The object name of the MBean. May be null.
318 *
319 * @return An <CODE>ObjectInstance</CODE>, containing the
320 * <CODE>ObjectName</CODE> and the Java class name of the newly
321 * registered MBean. If the contained <code>ObjectName</code>
322 * is <code>n</code>, the contained Java class name is
323 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
324 *
325 * @exception InstanceAlreadyExistsException The MBean is already
326 * under the control of the MBean server.
327 * @exception MBeanRegistrationException The
328 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
329 * interface) method of the MBean has thrown an exception. The
330 * MBean will not be registered.
331 * @exception NotCompliantMBeanException This object is not a JMX
332 * compliant MBean
333 * @exception RuntimeOperationsException Wraps a
334 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
335 * passed in parameter is null or no object name is specified.
336 */
337 public ObjectInstance registerMBean(Object object, ObjectName name)
338 throws InstanceAlreadyExistsException, MBeanRegistrationException,
339 NotCompliantMBeanException;
340
341 /**
342 * {@inheritDoc}
343 *
344 * <p>If this method successfully unregisters an MBean, a notification
345 * is sent as described <a href="#notif">above</a>.</p>
346 */
347 public void unregisterMBean(ObjectName name)
348 throws InstanceNotFoundException, MBeanRegistrationException;
349
350 // doc comment inherited from MBeanServerConnection
351 public ObjectInstance getObjectInstance(ObjectName name)
352 throws InstanceNotFoundException;
353
354 // doc comment inherited from MBeanServerConnection
355 public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query);
356
357 // doc comment inherited from MBeanServerConnection
358 public Set<ObjectName> queryNames(ObjectName name, QueryExp query);
359
360 // doc comment inherited from MBeanServerConnection
361 public boolean isRegistered(ObjectName name);
362
363 /**
364 * Returns the number of MBeans registered in the MBean server.
365 *
366 * @return the number of registered MBeans, wrapped in an Integer.
367 * If the caller's permissions are restricted, this number may
368 * be greater than the number of MBeans the caller can access.
369 */
370 public Integer getMBeanCount();
371
372 // doc comment inherited from MBeanServerConnection
373 public Object getAttribute(ObjectName name, String attribute)
374 throws MBeanException, AttributeNotFoundException,
375 InstanceNotFoundException, ReflectionException;
376
377 // doc comment inherited from MBeanServerConnection
378 public AttributeList getAttributes(ObjectName name, String[] attributes)
379 throws InstanceNotFoundException, ReflectionException;
380
381 // doc comment inherited from MBeanServerConnection
382 public void setAttribute(ObjectName name, Attribute attribute)
383 throws InstanceNotFoundException, AttributeNotFoundException,
384 InvalidAttributeValueException, MBeanException,
385 ReflectionException;
386
387 // doc comment inherited from MBeanServerConnection
388 public AttributeList setAttributes(ObjectName name,
389 AttributeList attributes)
390 throws InstanceNotFoundException, ReflectionException;
391
392 // doc comment inherited from MBeanServerConnection
393 public Object invoke(ObjectName name, String operationName,
394 Object params[], String signature[])
395 throws InstanceNotFoundException, MBeanException,
396 ReflectionException;
397
398 // doc comment inherited from MBeanServerConnection
399 public String getDefaultDomain();
400
401 // doc comment inherited from MBeanServerConnection
402 public String[] getDomains();
403
404 // doc comment inherited from MBeanServerConnection
405 public void addNotificationListener(ObjectName name,
406 NotificationListener listener,
407 NotificationFilter filter,
408 Object handback)
409 throws InstanceNotFoundException;
410
411 // doc comment inherited from MBeanServerConnection
412 public void addNotificationListener(ObjectName name,
413 ObjectName listener,
414 NotificationFilter filter,
415 Object handback)
416 throws InstanceNotFoundException;
417
418 // doc comment inherited from MBeanServerConnection
419 public void removeNotificationListener(ObjectName name,
420 ObjectName listener)
421 throws InstanceNotFoundException, ListenerNotFoundException;
422
423 // doc comment inherited from MBeanServerConnection
424 public void removeNotificationListener(ObjectName name,
425 ObjectName listener,
426 NotificationFilter filter,
427 Object handback)
428 throws InstanceNotFoundException, ListenerNotFoundException;
429
430 // doc comment inherited from MBeanServerConnection
431 public void removeNotificationListener(ObjectName name,
432 NotificationListener listener)
433 throws InstanceNotFoundException, ListenerNotFoundException;
434
435 // doc comment inherited from MBeanServerConnection
436 public void removeNotificationListener(ObjectName name,
437 NotificationListener listener,
438 NotificationFilter filter,
439 Object handback)
440 throws InstanceNotFoundException, ListenerNotFoundException;
441
442 // doc comment inherited from MBeanServerConnection
443 public MBeanInfo getMBeanInfo(ObjectName name)
444 throws InstanceNotFoundException, IntrospectionException,
445 ReflectionException;
446
447
448 // doc comment inherited from MBeanServerConnection
449 public boolean isInstanceOf(ObjectName name, String className)
450 throws InstanceNotFoundException;
451
452 /**
453 * <p>Instantiates an object using the list of all class loaders
454 * registered in the MBean server's {@link
455 * javax.management.loading.ClassLoaderRepository Class Loader
456 * Repository}. The object's class should have a public
457 * constructor. This method returns a reference to the newly
458 * created object. The newly created object is not registered in
459 * the MBean server.</p>
460 *
461 * <p>This method is equivalent to {@link
462 * #instantiate(String,Object[],String[])
463 * instantiate(className, (Object[]) null, (String[]) null)}.</p>
464 *
465 * @param className The class name of the object to be instantiated.
466 *
467 * @return The newly instantiated object.
468 *
469 * @exception ReflectionException Wraps a
470 * <CODE>java.lang.ClassNotFoundException</CODE> or the
471 * <CODE>java.lang.Exception</CODE> that occurred when trying to
472 * invoke the object's constructor.
473 * @exception MBeanException The constructor of the object has
474 * thrown an exception
475 * @exception RuntimeOperationsException Wraps a
476 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
477 * passed in parameter is null.
478 */
479 public Object instantiate(String className)
480 throws ReflectionException, MBeanException;
481
482
483 /**
484 * <p>Instantiates an object using the class Loader specified by its
485 * <CODE>ObjectName</CODE>. If the loader name is null, the
486 * ClassLoader that loaded the MBean Server will be used. The
487 * object's class should have a public constructor. This method
488 * returns a reference to the newly created object. The newly
489 * created object is not registered in the MBean server.</p>
490 *
491 * <p>This method is equivalent to {@link
492 * #instantiate(String,ObjectName,Object[],String[])
493 * instantiate(className, loaderName, (Object[]) null, (String[])
494 * null)}.</p>
495 *
496 * @param className The class name of the MBean to be instantiated.
497 * @param loaderName The object name of the class loader to be used.
498 *
499 * @return The newly instantiated object.
500 *
501 * @exception ReflectionException Wraps a
502 * <CODE>java.lang.ClassNotFoundException</CODE> or the
503 * <CODE>java.lang.Exception</CODE> that occurred when trying to
504 * invoke the object's constructor.
505 * @exception MBeanException The constructor of the object has
506 * thrown an exception.
507 * @exception InstanceNotFoundException The specified class loader
508 * is not registered in the MBeanServer.
509 * @exception RuntimeOperationsException Wraps a
510 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
511 * passed in parameter is null.
512 */
513 public Object instantiate(String className, ObjectName loaderName)
514 throws ReflectionException, MBeanException,
515 InstanceNotFoundException;
516
517 /**
518 * <p>Instantiates an object using the list of all class loaders
519 * registered in the MBean server {@link
520 * javax.management.loading.ClassLoaderRepository Class Loader
521 * Repository}. The object's class should have a public
522 * constructor. The call returns a reference to the newly created
523 * object. The newly created object is not registered in the
524 * MBean server.</p>
525 *
526 * @param className The class name of the object to be instantiated.
527 * @param params An array containing the parameters of the
528 * constructor to be invoked.
529 * @param signature An array containing the signature of the
530 * constructor to be invoked.
531 *
532 * @return The newly instantiated object.
533 *
534 * @exception ReflectionException Wraps a
535 * <CODE>java.lang.ClassNotFoundException</CODE> or the
536 * <CODE>java.lang.Exception</CODE> that occurred when trying to
537 * invoke the object's constructor.
538 * @exception MBeanException The constructor of the object has
539 * thrown an exception
540 * @exception RuntimeOperationsException Wraps a
541 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
542 * passed in parameter is null.
543 */
544 public Object instantiate(String className, Object params[],
545 String signature[])
546 throws ReflectionException, MBeanException;
547
548 /**
549 * <p>Instantiates an object. The class loader to be used is
550 * identified by its object name. If the object name of the loader
551 * is null, the ClassLoader that loaded the MBean server will be
552 * used. The object's class should have a public constructor.
553 * The call returns a reference to the newly created object. The
554 * newly created object is not registered in the MBean server.</p>
555 *
556 * @param className The class name of the object to be instantiated.
557 * @param params An array containing the parameters of the
558 * constructor to be invoked.
559 * @param signature An array containing the signature of the
560 * constructor to be invoked.
561 * @param loaderName The object name of the class loader to be used.
562 *
563 * @return The newly instantiated object.
564 *
565 * @exception ReflectionException Wraps a <CODE>java.lang.ClassNotFoundException</CODE> or the <CODE>java.lang.Exception</CODE> that
566 * occurred when trying to invoke the object's constructor.
567 * @exception MBeanException The constructor of the object has
568 * thrown an exception
569 * @exception InstanceNotFoundException The specified class loader
570 * is not registered in the MBean server.
571 * @exception RuntimeOperationsException Wraps a
572 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
573 * passed in parameter is null.
574 */
575 public Object instantiate(String className, ObjectName loaderName,
576 Object params[], String signature[])
577 throws ReflectionException, MBeanException,
578 InstanceNotFoundException;
579
580 /**
581 * <p>De-serializes a byte array in the context of the class loader
582 * of an MBean.</p>
583 *
584 * @param name The name of the MBean whose class loader should be
585 * used for the de-serialization.
586 * @param data The byte array to be de-sererialized.
587 *
588 * @return The de-serialized object stream.
589 *
590 * @exception InstanceNotFoundException The MBean specified is not
591 * found.
592 * @exception OperationsException Any of the usual Input/Output
593 * related exceptions.
594 *
595 * @deprecated Use {@link #getClassLoaderFor getClassLoaderFor} to
596 * obtain the appropriate class loader for deserialization.
597 */
598 @Deprecated
599 public ObjectInputStream deserialize(ObjectName name, byte[] data)
600 throws InstanceNotFoundException, OperationsException;
601
602
603 /**
604 * <p>De-serializes a byte array in the context of a given MBean
605 * class loader. The class loader is found by loading the class
606 * <code>className</code> through the {@link
607 * javax.management.loading.ClassLoaderRepository Class Loader
608 * Repository}. The resultant class's class loader is the one to
609 * use.
610 *
611 * @param className The name of the class whose class loader should be
612 * used for the de-serialization.
613 * @param data The byte array to be de-sererialized.
614 *
615 * @return The de-serialized object stream.
616 *
617 * @exception OperationsException Any of the usual Input/Output
618 * related exceptions.
619 * @exception ReflectionException The specified class could not be
620 * loaded by the class loader repository
621 *
622 * @deprecated Use {@link #getClassLoaderRepository} to obtain the
623 * class loader repository and use it to deserialize.
624 */
625 @Deprecated
626 public ObjectInputStream deserialize(String className, byte[] data)
627 throws OperationsException, ReflectionException;
628
629
630 /**
631 * <p>De-serializes a byte array in the context of a given MBean
632 * class loader. The class loader is the one that loaded the
633 * class with name "className". The name of the class loader to
634 * be used for loading the specified class is specified. If null,
635 * the MBean Server's class loader will be used.</p>
636 *
637 * @param className The name of the class whose class loader should be
638 * used for the de-serialization.
639 * @param data The byte array to be de-sererialized.
640 * @param loaderName The name of the class loader to be used for
641 * loading the specified class. If null, the MBean Server's class
642 * loader will be used.
643 *
644 * @return The de-serialized object stream.
645 *
646 * @exception InstanceNotFoundException The specified class loader
647 * MBean is not found.
648 * @exception OperationsException Any of the usual Input/Output
649 * related exceptions.
650 * @exception ReflectionException The specified class could not be
651 * loaded by the specified class loader.
652 *
653 * @deprecated Use {@link #getClassLoader getClassLoader} to obtain
654 * the class loader for deserialization.
655 */
656 @Deprecated
657 public ObjectInputStream deserialize(String className,
658 ObjectName loaderName,
659 byte[] data)
660 throws InstanceNotFoundException, OperationsException,
661 ReflectionException;
662
663 /**
664 * <p>Return the {@link java.lang.ClassLoader} that was used for
665 * loading the class of the named MBean.</p>
666 *
667 * @param mbeanName The ObjectName of the MBean.
668 *
669 * @return The ClassLoader used for that MBean. If <var>l</var>
670 * is the MBean's actual ClassLoader, and <var>r</var> is the
671 * returned value, then either:
672 *
673 * <ul>
674 * <li><var>r</var> is identical to <var>l</var>; or
675 * <li>the result of <var>r</var>{@link
676 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
677 * same as <var>l</var>{@link ClassLoader#loadClass(String)
678 * .loadClass(<var>s</var>)} for any string <var>s</var>.
679 * </ul>
680 *
681 * What this means is that the ClassLoader may be wrapped in
682 * another ClassLoader for security or other reasons.
683 *
684 * @exception InstanceNotFoundException if the named MBean is not found.
685 *
686 */
687 public ClassLoader getClassLoaderFor(ObjectName mbeanName)
688 throws InstanceNotFoundException;
689
690 /**
691 * <p>Return the named {@link java.lang.ClassLoader}.</p>
692 *
693 * @param loaderName The ObjectName of the ClassLoader. May be
694 * null, in which case the MBean server's own ClassLoader is
695 * returned.
696 *
697 * @return The named ClassLoader. If <var>l</var> is the actual
698 * ClassLoader with that name, and <var>r</var> is the returned
699 * value, then either:
700 *
701 * <ul>
702 * <li><var>r</var> is identical to <var>l</var>; or
703 * <li>the result of <var>r</var>{@link
704 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
705 * same as <var>l</var>{@link ClassLoader#loadClass(String)
706 * .loadClass(<var>s</var>)} for any string <var>s</var>.
707 * </ul>
708 *
709 * What this means is that the ClassLoader may be wrapped in
710 * another ClassLoader for security or other reasons.
711 *
712 * @exception InstanceNotFoundException if the named ClassLoader is
713 * not found.
714 *
715 */
716 public ClassLoader getClassLoader(ObjectName loaderName)
717 throws InstanceNotFoundException;
718
719 /**
720 * <p>Return the ClassLoaderRepository for this MBeanServer.
721 * @return The ClassLoaderRepository for this MBeanServer.
722 *
723 */
724 public ClassLoaderRepository getClassLoaderRepository();
725 }
Save This Page