001 /*
002 * Copyright 1999-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management;
027
028 // java import
029 import java.util.Set;
030 import java.io.ObjectInputStream;
031
032 // RI import
033 import javax.management.loading.ClassLoaderRepository;
034
035 /**
036 * <p>This is the interface for MBean manipulation on the agent
037 * side. It contains the methods necessary for the creation,
038 * registration, and deletion of MBeans as well as the access methods
039 * for registered MBeans. This is the core component of the JMX
040 * infrastructure.</p>
041 *
042 * <p>User code does not usually implement this interface. Instead,
043 * an object that implements this interface is obtained with one of
044 * the methods in the {@link MBeanServerFactory} class.</p>
045 *
046 * <p>Every MBean which is added to the MBean server becomes
047 * manageable: its attributes and operations become remotely
048 * accessible through the connectors/adaptors connected to that MBean
049 * server. A Java object cannot be registered in the MBean server
050 * unless it is a JMX compliant MBean.</p>
051 *
052 * <p>When an MBean is registered or unregistered in the MBean server
053 * a {@link javax.management.MBeanServerNotification
054 * MBeanServerNotification} Notification is emitted. To register an
055 * object as listener to MBeanServerNotifications you should call the
056 * MBean server method {@link #addNotificationListener
057 * addNotificationListener} with <CODE>ObjectName</CODE> the
058 * <CODE>ObjectName</CODE> of the {@link
059 * javax.management.MBeanServerDelegate MBeanServerDelegate}. This
060 * <CODE>ObjectName</CODE> is: <BR>
061 * <CODE>JMImplementation:type=MBeanServerDelegate</CODE>.</p>
062 *
063 * <p>An object obtained from the {@link
064 * MBeanServerFactory#createMBeanServer(String) createMBeanServer} or
065 * {@link MBeanServerFactory#newMBeanServer(String) newMBeanServer}
066 * methods of the {@link MBeanServerFactory} class applies security
067 * checks to its methods, as follows.</p>
068 *
069 * <p>First, if there is no security manager ({@link
070 * System#getSecurityManager()} is null), then an implementation of
071 * this interface is free not to make any checks.</p>
072 *
073 * <p>Assuming that there is a security manager, or that the
074 * implementation chooses to make checks anyway, the checks are made
075 * as detailed below. In what follows, <code>className</code> is the
076 * string returned by {@link MBeanInfo#getClassName()} for the target
077 * MBean.</p>
078 *
079 * <p>If a security check fails, the method throws {@link
080 * SecurityException}.</p>
081 *
082 * <p>For methods that can throw {@link InstanceNotFoundException},
083 * this exception is thrown for a non-existent MBean, regardless of
084 * permissions. This is because a non-existent MBean has no
085 * <code>className</code>.</p>
086 *
087 * <ul>
088 *
089 * <li><p>For the {@link #invoke invoke} method, the caller's
090 * permissions must imply {@link
091 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
092 * MBeanPermission(className, operationName, name, "invoke")}.</p>
093 *
094 * <li><p>For the {@link #getAttribute getAttribute} method, the
095 * caller's permissions must imply {@link
096 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
097 * MBeanPermission(className, attribute, name, "getAttribute")}.</p>
098 *
099 * <li><p>For the {@link #getAttributes getAttributes} method, the
100 * caller's permissions must imply {@link
101 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
102 * MBeanPermission(className, null, name, "getAttribute")}.
103 * Additionally, for each attribute <em>a</em> in the {@link
104 * AttributeList}, if the caller's permissions do not imply {@link
105 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
106 * MBeanPermission(className, <em>a</em>, name, "getAttribute")}, the
107 * MBean server will behave as if that attribute had not been in the
108 * supplied list.</p>
109 *
110 * <li><p>For the {@link #setAttribute setAttribute} method, the
111 * caller's permissions must imply {@link
112 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
113 * MBeanPermission(className, attrName, name, "setAttribute")}, where
114 * <code>attrName</code> is {@link Attribute#getName()
115 * attribute.getName()}.</p>
116 *
117 * <li><p>For the {@link #setAttributes setAttributes} method, the
118 * caller's permissions must imply {@link
119 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
120 * MBeanPermission(className, null, name, "setAttribute")}.
121 * Additionally, for each attribute <em>a</em> in the {@link
122 * AttributeList}, if the caller's permissions do not imply {@link
123 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
124 * MBeanPermission(className, <em>a</em>, name, "setAttribute")}, the
125 * MBean server will behave as if that attribute had not been in the
126 * supplied list.</p>
127 *
128 * <li><p>For the <code>addNotificationListener</code> methods,
129 * the caller's permissions must imply {@link
130 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
131 * MBeanPermission(className, null, name,
132 * "addNotificationListener")}.</p>
133 *
134 * <li><p>For the <code>removeNotificationListener</code> methods,
135 * the caller's permissions must imply {@link
136 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
137 * MBeanPermission(className, null, name,
138 * "removeNotificationListener")}.</p>
139 *
140 * <li><p>For the {@link #getMBeanInfo getMBeanInfo} method, the
141 * caller's permissions must imply {@link
142 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
143 * MBeanPermission(className, null, name, "getMBeanInfo")}.</p>
144 *
145 * <li><p>For the {@link #getObjectInstance getObjectInstance} method,
146 * the caller's permissions must imply {@link
147 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
148 * MBeanPermission(className, null, name, "getObjectInstance")}.</p>
149 *
150 * <li><p>For the {@link #isInstanceOf isInstanceOf} method, the
151 * caller's permissions must imply {@link
152 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
153 * MBeanPermission(className, null, name, "isInstanceOf")}.</p>
154 *
155 * <li><p>For the {@link #queryMBeans queryMBeans} method, the
156 * caller's permissions must imply {@link
157 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
158 * MBeanPermission(null, null, name, "queryMBeans")}.
159 * Additionally, for each MBean that matches <code>name</code>,
160 * if the caller's permissions do not imply {@link
161 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
162 * MBeanPermission(className, null, name, "queryMBeans")}, the
163 * MBean server will behave as if that MBean did not exist.</p>
164 *
165 * <p>Certain query elements perform operations on the MBean server.
166 * If the caller does not have the required permissions for a given
167 * MBean, that MBean will not be included in the result of the query.
168 * The standard query elements that are affected are {@link
169 * Query#attr(String)}, {@link Query#attr(String,String)}, and {@link
170 * Query#classattr()}.</p>
171 *
172 * <li><p>For the {@link #queryNames queryNames} method, the checks
173 * are the same as for <code>queryMBeans</code> except that
174 * <code>"queryNames"</code> is used instead of
175 * <code>"queryMBeans"</code> in the <code>MBeanPermission</code>
176 * objects. Note that a <code>"queryMBeans"</code> permission implies
177 * the corresponding <code>"queryNames"</code> permission.</p>
178 *
179 * <li><p>For the {@link #getDomains getDomains} method, the caller's
180 * permissions must imply {@link
181 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
182 * MBeanPermission(null, null, name, "getDomains")}. Additionally,
183 * for each domain <var>d</var> in the returned array, if the caller's
184 * permissions do not imply {@link
185 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
186 * MBeanPermission(null, null, new ObjectName("<var>d</var>:x=x"),
187 * "getDomains")}, the domain is eliminated from the array. Here,
188 * <code>x=x</code> is any <var>key=value</var> pair, needed to
189 * satisfy ObjectName's constructor but not otherwise relevant.</p>
190 *
191 * <li><p>For the {@link #getClassLoader getClassLoader} method, the
192 * caller's permissions must imply {@link
193 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
194 * MBeanPermission(className, null, loaderName,
195 * "getClassLoader")}.</p>
196 *
197 * <li><p>For the {@link #getClassLoaderFor getClassLoaderFor} method,
198 * the caller's permissions must imply {@link
199 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
200 * MBeanPermission(className, null, mbeanName,
201 * "getClassLoaderFor")}.</p>
202 *
203 * <li><p>For the {@link #getClassLoaderRepository
204 * getClassLoaderRepository} method, the caller's permissions must
205 * imply {@link
206 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
207 * MBeanPermission(null, null, null, "getClassLoaderRepository")}.</p>
208 *
209 * <li><p>For the deprecated <code>deserialize</code> methods, the
210 * required permissions are the same as for the methods that replace
211 * them.</p>
212 *
213 * <li><p>For the <code>instantiate</code> methods, the caller's
214 * permissions must imply {@link
215 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
216 * MBeanPermission(className, null, null, "instantiate")}.</p>
217 *
218 * <li><p>For the {@link #registerMBean registerMBean} method, the
219 * caller's permissions must imply {@link
220 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
221 * MBeanPermission(className, null, name, "registerMBean")}. Here
222 * <code>className</code> is the string returned by {@link
223 * MBeanInfo#getClassName()} for an object of this class.
224 *
225 * <p>If the <code>MBeanPermission</code> check succeeds, the MBean's
226 * class is validated by checking that its {@link
227 * java.security.ProtectionDomain ProtectionDomain} implies {@link
228 * MBeanTrustPermission#MBeanTrustPermission(String)
229 * MBeanTrustPermission("register")}.</p>
230 *
231 * <p>Finally, if the <code>name</code> argument is null, another
232 * <code>MBeanPermission</code> check is made using the
233 * <code>ObjectName</code> returned by {@link
234 * MBeanRegistration#preRegister MBeanRegistration.preRegister}.</p>
235 *
236 * <li><p>For the <code>createMBean</code> methods, the caller's
237 * permissions must imply the permissions needed by the equivalent
238 * <code>instantiate</code> followed by
239 * <code>registerMBean</code>.</p>
240 *
241 * <li><p>For the {@link #unregisterMBean unregisterMBean} method,
242 * the caller's permissions must imply {@link
243 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
244 * MBeanPermission(className, null, name, "unregisterMBean")}.</p>
245 *
246 * </ul>
247 *
248 * @since 1.5
249 */
250
251 /* DELETED:
252 *
253 * <li><p>For the {@link #isRegistered isRegistered} method, the
254 * caller's permissions must imply {@link
255 * MBeanPermission#MBeanPermission(String,String,ObjectName,String)
256 * MBeanPermission(null, null, name, "isRegistered")}.</p>
257 */
258 public interface MBeanServer extends MBeanServerConnection {
259
260 // doc comment inherited from MBeanServerConnection
261 public ObjectInstance createMBean(String className, ObjectName name)
262 throws ReflectionException, InstanceAlreadyExistsException,
263 MBeanRegistrationException, MBeanException,
264 NotCompliantMBeanException;
265
266 // doc comment inherited from MBeanServerConnection
267 public ObjectInstance createMBean(String className,
268 ObjectName name, ObjectName loaderName)
269 throws ReflectionException, InstanceAlreadyExistsException,
270 MBeanRegistrationException, MBeanException,
271 NotCompliantMBeanException, InstanceNotFoundException;
272
273 // doc comment inherited from MBeanServerConnection
274 public ObjectInstance createMBean(String className,
275 ObjectName name, Object params[], String signature[])
276 throws ReflectionException, InstanceAlreadyExistsException,
277 MBeanRegistrationException, MBeanException,
278 NotCompliantMBeanException;
279
280 // doc comment inherited from MBeanServerConnection
281 public ObjectInstance createMBean(String className,
282 ObjectName name, ObjectName loaderName, Object params[],
283 String signature[]) throws ReflectionException,
284 InstanceAlreadyExistsException, MBeanRegistrationException,
285 MBeanException, NotCompliantMBeanException,
286 InstanceNotFoundException;
287
288 /**
289 * Registers a pre-existing object as an MBean with the MBean
290 * server. If the object name given is null, the MBean must
291 * provide its own name by implementing the {@link
292 * javax.management.MBeanRegistration MBeanRegistration} interface
293 * and returning the name from the {@link
294 * MBeanRegistration#preRegister preRegister} method.
295 *
296 * @param object The MBean to be registered as an MBean.
297 * @param name The object name of the MBean. May be null.
298 *
299 * @return An <CODE>ObjectInstance</CODE>, containing the
300 * <CODE>ObjectName</CODE> and the Java class name of the newly
301 * registered MBean. If the contained <code>ObjectName</code>
302 * is <code>n</code>, the contained Java class name is
303 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
304 *
305 * @exception InstanceAlreadyExistsException The MBean is already
306 * under the control of the MBean server.
307 * @exception MBeanRegistrationException The
308 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
309 * interface) method of the MBean has thrown an exception. The
310 * MBean will not be registered.
311 * @exception NotCompliantMBeanException This object is not a JMX
312 * compliant MBean
313 * @exception RuntimeOperationsException Wraps a
314 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
315 * passed in parameter is null or no object name is specified.
316 */
317 public ObjectInstance registerMBean(Object object, ObjectName name)
318 throws InstanceAlreadyExistsException,
319 MBeanRegistrationException, NotCompliantMBeanException;
320
321 // doc comment inherited from MBeanServerConnection
322 public void unregisterMBean(ObjectName name)
323 throws InstanceNotFoundException,
324 MBeanRegistrationException;
325
326 // doc comment inherited from MBeanServerConnection
327 public ObjectInstance getObjectInstance(ObjectName name)
328 throws InstanceNotFoundException;
329
330 // doc comment inherited from MBeanServerConnection
331 public Set<ObjectInstance> queryMBeans(ObjectName name,
332 QueryExp query);
333
334 // doc comment inherited from MBeanServerConnection
335 public Set<ObjectName> queryNames(ObjectName name, QueryExp query);
336
337 // doc comment inherited from MBeanServerConnection
338 public boolean isRegistered(ObjectName name);
339
340 /**
341 * Returns the number of MBeans registered in the MBean server.
342 *
343 * @return the number of registered MBeans, wrapped in an Integer.
344 * If the caller's permissions are restricted, this number may
345 * be greater than the number of MBeans the caller can access.
346 */
347 public Integer getMBeanCount();
348
349 // doc comment inherited from MBeanServerConnection
350 public Object getAttribute(ObjectName name, String attribute)
351 throws MBeanException, AttributeNotFoundException,
352 InstanceNotFoundException, ReflectionException;
353
354 // doc comment inherited from MBeanServerConnection
355 public AttributeList getAttributes(ObjectName name,
356 String[] attributes) throws InstanceNotFoundException,
357 ReflectionException;
358
359 // doc comment inherited from MBeanServerConnection
360 public void setAttribute(ObjectName name, Attribute attribute)
361 throws InstanceNotFoundException,
362 AttributeNotFoundException, InvalidAttributeValueException,
363 MBeanException, ReflectionException;
364
365 // doc comment inherited from MBeanServerConnection
366 public AttributeList setAttributes(ObjectName name,
367 AttributeList attributes) throws InstanceNotFoundException,
368 ReflectionException;
369
370 // doc comment inherited from MBeanServerConnection
371 public Object invoke(ObjectName name, String operationName,
372 Object params[], String signature[])
373 throws InstanceNotFoundException, MBeanException,
374 ReflectionException;
375
376 // doc comment inherited from MBeanServerConnection
377 public String getDefaultDomain();
378
379 // doc comment inherited from MBeanServerConnection
380 public String[] getDomains();
381
382 // doc comment inherited from MBeanServerConnection
383 public void addNotificationListener(ObjectName name,
384 NotificationListener listener, NotificationFilter filter,
385 Object handback) throws InstanceNotFoundException;
386
387 // doc comment inherited from MBeanServerConnection
388 public void addNotificationListener(ObjectName name,
389 ObjectName listener, NotificationFilter filter,
390 Object handback) throws InstanceNotFoundException;
391
392 // doc comment inherited from MBeanServerConnection
393 public void removeNotificationListener(ObjectName name,
394 ObjectName listener) throws InstanceNotFoundException,
395 ListenerNotFoundException;
396
397 // doc comment inherited from MBeanServerConnection
398 public void removeNotificationListener(ObjectName name,
399 ObjectName listener, NotificationFilter filter,
400 Object handback) throws InstanceNotFoundException,
401 ListenerNotFoundException;
402
403 // doc comment inherited from MBeanServerConnection
404 public void removeNotificationListener(ObjectName name,
405 NotificationListener listener)
406 throws InstanceNotFoundException, ListenerNotFoundException;
407
408 // doc comment inherited from MBeanServerConnection
409 public void removeNotificationListener(ObjectName name,
410 NotificationListener listener, NotificationFilter filter,
411 Object handback) throws InstanceNotFoundException,
412 ListenerNotFoundException;
413
414 // doc comment inherited from MBeanServerConnection
415 public MBeanInfo getMBeanInfo(ObjectName name)
416 throws InstanceNotFoundException, IntrospectionException,
417 ReflectionException;
418
419 // doc comment inherited from MBeanServerConnection
420 public boolean isInstanceOf(ObjectName name, String className)
421 throws InstanceNotFoundException;
422
423 /**
424 * <p>Instantiates an object using the list of all class loaders
425 * registered in the MBean server's {@link
426 * javax.management.loading.ClassLoaderRepository Class Loader
427 * Repository}. The object's class should have a public
428 * constructor. This method returns a reference to the newly
429 * created object. The newly created object is not registered in
430 * the MBean server.</p>
431 *
432 * <p>This method is equivalent to {@link
433 * #instantiate(String,Object[],String[])
434 * instantiate(className, (Object[]) null, (String[]) null)}.</p>
435 *
436 * @param className The class name of the object to be instantiated.
437 *
438 * @return The newly instantiated object.
439 *
440 * @exception ReflectionException Wraps a
441 * <CODE>java.lang.ClassNotFoundException</CODE> or the
442 * <CODE>java.lang.Exception</CODE> that occurred when trying to
443 * invoke the object's constructor.
444 * @exception MBeanException The constructor of the object has
445 * thrown an exception
446 * @exception RuntimeOperationsException Wraps a
447 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
448 * passed in parameter is null.
449 */
450 public Object instantiate(String className)
451 throws ReflectionException, MBeanException;
452
453 /**
454 * <p>Instantiates an object using the class Loader specified by its
455 * <CODE>ObjectName</CODE>. If the loader name is null, the
456 * ClassLoader that loaded the MBean Server will be used. The
457 * object's class should have a public constructor. This method
458 * returns a reference to the newly created object. The newly
459 * created object is not registered in the MBean server.</p>
460 *
461 * <p>This method is equivalent to {@link
462 * #instantiate(String,ObjectName,Object[],String[])
463 * instantiate(className, loaderName, (Object[]) null, (String[])
464 * null)}.</p>
465 *
466 * @param className The class name of the MBean to be instantiated.
467 * @param loaderName The object name of the class loader to be used.
468 *
469 * @return The newly instantiated object.
470 *
471 * @exception ReflectionException Wraps a
472 * <CODE>java.lang.ClassNotFoundException</CODE> or the
473 * <CODE>java.lang.Exception</CODE> that occurred when trying to
474 * invoke the object's constructor.
475 * @exception MBeanException The constructor of the object has
476 * thrown an exception.
477 * @exception InstanceNotFoundException The specified class loader
478 * is not registered in the MBeanServer.
479 * @exception RuntimeOperationsException Wraps a
480 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
481 * passed in parameter is null.
482 */
483 public Object instantiate(String className, ObjectName loaderName)
484 throws ReflectionException, MBeanException,
485 InstanceNotFoundException;
486
487 /**
488 * <p>Instantiates an object using the list of all class loaders
489 * registered in the MBean server {@link
490 * javax.management.loading.ClassLoaderRepository Class Loader
491 * Repository}. The object's class should have a public
492 * constructor. The call returns a reference to the newly created
493 * object. The newly created object is not registered in the
494 * MBean server.</p>
495 *
496 * @param className The class name of the object to be instantiated.
497 * @param params An array containing the parameters of the
498 * constructor to be invoked.
499 * @param signature An array containing the signature of the
500 * constructor to be invoked.
501 *
502 * @return The newly instantiated object.
503 *
504 * @exception ReflectionException Wraps a
505 * <CODE>java.lang.ClassNotFoundException</CODE> or the
506 * <CODE>java.lang.Exception</CODE> that occurred when trying to
507 * invoke the object's constructor.
508 * @exception MBeanException The constructor of the object has
509 * thrown an exception
510 * @exception RuntimeOperationsException Wraps a
511 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
512 * passed in parameter is null.
513 */
514 public Object instantiate(String className, Object params[],
515 String signature[]) throws ReflectionException,
516 MBeanException;
517
518 /**
519 * <p>Instantiates an object. The class loader to be used is
520 * identified by its object name. If the object name of the loader
521 * is null, the ClassLoader that loaded the MBean server will be
522 * used. The object's class should have a public constructor.
523 * The call returns a reference to the newly created object. The
524 * newly created object is not registered in the 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 * @param loaderName The object name of the class loader to be used.
532 *
533 * @return The newly instantiated object.
534 *
535 * @exception ReflectionException Wraps a <CODE>java.lang.ClassNotFoundException</CODE> or the <CODE>java.lang.Exception</CODE> that
536 * occurred when trying to invoke the object's constructor.
537 * @exception MBeanException The constructor of the object has
538 * thrown an exception
539 * @exception InstanceNotFoundException The specified class loader
540 * is not registered in the MBean server.
541 * @exception RuntimeOperationsException Wraps a
542 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
543 * passed in parameter is null.
544 */
545 public Object instantiate(String className, ObjectName loaderName,
546 Object params[], String signature[])
547 throws ReflectionException, MBeanException,
548 InstanceNotFoundException;
549
550 /**
551 * <p>De-serializes a byte array in the context of the class loader
552 * of an MBean.</p>
553 *
554 * @param name The name of the MBean whose class loader should be
555 * used for the de-serialization.
556 * @param data The byte array to be de-sererialized.
557 *
558 * @return The de-serialized object stream.
559 *
560 * @exception InstanceNotFoundException The MBean specified is not
561 * found.
562 * @exception OperationsException Any of the usual Input/Output
563 * related exceptions.
564 *
565 * @deprecated Use {@link #getClassLoaderFor getClassLoaderFor} to
566 * obtain the appropriate class loader for deserialization.
567 */
568 @Deprecated
569 public ObjectInputStream deserialize(ObjectName name, byte[] data)
570 throws InstanceNotFoundException, OperationsException;
571
572 /**
573 * <p>De-serializes a byte array in the context of a given MBean
574 * class loader. The class loader is found by loading the class
575 * <code>className</code> through the {@link
576 * javax.management.loading.ClassLoaderRepository Class Loader
577 * Repository}. The resultant class's class loader is the one to
578 * use.
579 *
580 * @param className The name of the class whose class loader should be
581 * used for the de-serialization.
582 * @param data The byte array to be de-sererialized.
583 *
584 * @return The de-serialized object stream.
585 *
586 * @exception OperationsException Any of the usual Input/Output
587 * related exceptions.
588 * @exception ReflectionException The specified class could not be
589 * loaded by the class loader repository
590 *
591 * @deprecated Use {@link #getClassLoaderRepository} to obtain the
592 * class loader repository and use it to deserialize.
593 */
594 @Deprecated
595 public ObjectInputStream deserialize(String className, byte[] data)
596 throws OperationsException, ReflectionException;
597
598 /**
599 * <p>De-serializes a byte array in the context of a given MBean
600 * class loader. The class loader is the one that loaded the
601 * class with name "className". The name of the class loader to
602 * be used for loading the specified class is specified. If null,
603 * the MBean Server's class loader will be used.</p>
604 *
605 * @param className The name of the class whose class loader should be
606 * used for the de-serialization.
607 * @param data The byte array to be de-sererialized.
608 * @param loaderName The name of the class loader to be used for
609 * loading the specified class. If null, the MBean Server's class
610 * loader will be used.
611 *
612 * @return The de-serialized object stream.
613 *
614 * @exception InstanceNotFoundException The specified class loader
615 * MBean is not found.
616 * @exception OperationsException Any of the usual Input/Output
617 * related exceptions.
618 * @exception ReflectionException The specified class could not be
619 * loaded by the specified class loader.
620 *
621 * @deprecated Use {@link #getClassLoader getClassLoader} to obtain
622 * the class loader for deserialization.
623 */
624 @Deprecated
625 public ObjectInputStream deserialize(String className,
626 ObjectName loaderName, byte[] data)
627 throws InstanceNotFoundException, OperationsException,
628 ReflectionException;
629
630 /**
631 * <p>Return the {@link java.lang.ClassLoader} that was used for
632 * loading the class of the named MBean.</p>
633 *
634 * @param mbeanName The ObjectName of the MBean.
635 *
636 * @return The ClassLoader used for that MBean. If <var>l</var>
637 * is the MBean's actual ClassLoader, and <var>r</var> is the
638 * returned value, then either:
639 *
640 * <ul>
641 * <li><var>r</var> is identical to <var>l</var>; or
642 * <li>the result of <var>r</var>{@link
643 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
644 * same as <var>l</var>{@link ClassLoader#loadClass(String)
645 * .loadClass(<var>s</var>)} for any string <var>s</var>.
646 * </ul>
647 *
648 * What this means is that the ClassLoader may be wrapped in
649 * another ClassLoader for security or other reasons.
650 *
651 * @exception InstanceNotFoundException if the named MBean is not found.
652 *
653 */
654 public ClassLoader getClassLoaderFor(ObjectName mbeanName)
655 throws InstanceNotFoundException;
656
657 /**
658 * <p>Return the named {@link java.lang.ClassLoader}.</p>
659 *
660 * @param loaderName The ObjectName of the ClassLoader. May be
661 * null, in which case the MBean server's own ClassLoader is
662 * returned.
663 *
664 * @return The named ClassLoader. If <var>l</var> is the actual
665 * ClassLoader with that name, and <var>r</var> is the returned
666 * value, then either:
667 *
668 * <ul>
669 * <li><var>r</var> is identical to <var>l</var>; or
670 * <li>the result of <var>r</var>{@link
671 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the
672 * same as <var>l</var>{@link ClassLoader#loadClass(String)
673 * .loadClass(<var>s</var>)} for any string <var>s</var>.
674 * </ul>
675 *
676 * What this means is that the ClassLoader may be wrapped in
677 * another ClassLoader for security or other reasons.
678 *
679 * @exception InstanceNotFoundException if the named ClassLoader is
680 * not found.
681 *
682 */
683 public ClassLoader getClassLoader(ObjectName loaderName)
684 throws InstanceNotFoundException;
685
686 /**
687 * <p>Return the ClassLoaderRepository for this MBeanServer.
688 * @return The ClassLoaderRepository for this MBeanServer.
689 *
690 */
691 public ClassLoaderRepository getClassLoaderRepository();
692 }
|