| Frames | No Frames |
1: /* MBeanServer.java -- Represents a management server. 2: Copyright (C) 2006 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package javax.management; 39: 40: import java.io.ObjectInputStream; 41: 42: import java.util.Set; 43: 44: import javax.management.loading.ClassLoaderRepository; 45: 46: /** 47: * <p> 48: * This interface represents a server for management beans, 49: * providing facilities for the creation, registration and 50: * removal of such beans. This interface is central to the 51: * Java management architecture. Users do not usually implement 52: * this class. Instead, implementations of this class 53: * may be obtained using an {@link MBeanServerFactory}. 54: * </p> 55: * <p> 56: * Registering a bean with the server makes its attributes and 57: * operations accessible via the server. Only JMX compliant 58: * beans may be registered with the server. When a bean 59: * is registered or unregistered, an {@link MBeanServerNotification} 60: * is emitted by the server's {@link MBeanServerDelegate}. 61: * Listeners may be registered with this bean in order to 62: * obtain such notifications. It has the {@link ObjectName} 63: * <code>JMImplementation:type=MBeanServerDelegate</code>. 64: * </p> 65: * <p> 66: * Security checks are applied on the methods of the server, 67: * as detailed below, if it is obtained using the 68: * {@link MBeanServerFactory#createMBeanServer()} or 69: * {@link MBeanServerFactory#newMBeanServer()} methods and 70: * {@link System.getSecurityManager()} returns a non-<code>null</code> 71: * value. If a check fails, a {@link SecurityException} 72: * is thrown. Note than the class name used in the exception 73: * is that of the bean, and thus, as a result, an 74: * {@link InstanceNotFoundException} 75: * precludes these security checks, due to the class name 76: * that would be used in the exception being unavailable. 77: * </p> 78: * 79: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 80: * @since 1.5 81: */ 82: public interface MBeanServer 83: extends MBeanServerConnection 84: { 85: 86: /** 87: * Registers the supplied listener with the specified management 88: * bean. Notifications emitted by the management bean are forwarded 89: * to the listener via the server, which will convert any MBean 90: * references in the source to portable {@link ObjectName} 91: * instances. The notification is otherwise unchanged. 92: * 93: * @param name the name of the management bean with which the listener 94: * should be registered. 95: * @param listener the listener which will handle notifications from 96: * the bean. 97: * @param filter the filter to apply to incoming notifications, or 98: * <code>null</code> if no filtering should be applied. 99: * @param passback an object to be passed to the listener when a 100: * notification is emitted. 101: * @throws InstanceNotFoundException if the name of the management bean 102: * could not be resolved. 103: * @throws SecurityException if a security manager exists and the 104: * caller's permissions don't imply {@link 105: * MBeanPermission(String,String,ObjectName,String) 106: * <code>MBeanPermission(className, null, name, 107: * "addNotificationListener")</code>}. 108: * @see #removeNotificationListener(ObjectName, NotificationListener) 109: * @see #removeNotificationListener(ObjectName, NotificationListener, 110: * NotificationFilter, Object) 111: * @see NotificationBroadcaster#addNotificationListener(NotificationListener, 112: * NotificationFilter, 113: * Object) 114: */ 115: void addNotificationListener(ObjectName name, NotificationListener listener, 116: NotificationFilter filter, Object passback) 117: throws InstanceNotFoundException; 118: 119: /** 120: * <p> 121: * Registers the supplied listener with the specified management 122: * bean. Notifications emitted by the management bean are forwarded 123: * to the listener via the server, which will convert any MBean 124: * references in the source to portable {@link ObjectName} 125: * instances. The notification is otherwise unchanged. 126: * </p> 127: * <p> 128: * The listener that receives notifications will be the one that is 129: * registered with the given name at the time this method is called. 130: * Even if it later unregisters and ceases to use that name, it will 131: * still receive notifications. 132: * </p> 133: * 134: * @param name the name of the management bean with which the listener 135: * should be registered. 136: * @param listener the name of the listener which will handle 137: * notifications from the bean. 138: * @param filter the filter to apply to incoming notifications, or 139: * <code>null</code> if no filtering should be applied. 140: * @param passback an object to be passed to the listener when a 141: * notification is emitted. 142: * @throws InstanceNotFoundException if the name of the management bean 143: * could not be resolved. 144: * @throws RuntimeOperationsException if the bean associated with the given 145: * object name is not a 146: * {@link NotificationListener}. This 147: * exception wraps an 148: * {@link IllegalArgumentException}. 149: * @throws SecurityException if a security manager exists and the 150: * caller's permissions don't imply {@link 151: * MBeanPermission(String,String,ObjectName,String) 152: * <code>MBeanPermission(className, null, name, 153: * "addNotificationListener")</code>}. 154: * @see #removeNotificationListener(ObjectName, NotificationListener) 155: * @see #removeNotificationListener(ObjectName, NotificationListener, 156: * NotificationFilter, Object) 157: * @see NotificationBroadcaster#addNotificationListener(NotificationListener, 158: * NotificationFilter, 159: * Object) 160: */ 161: void addNotificationListener(ObjectName name, ObjectName listener, 162: NotificationFilter filter, Object passback) 163: throws InstanceNotFoundException; 164: 165: /** 166: * <p> 167: * Instantiates a new instance of the specified management bean 168: * using the default constructor and registers it with the server 169: * under the supplied name. The class is loaded using the 170: * {@link javax.management.loading.ClassLoaderRepository default 171: * loader repository} of the server. 172: * </p> 173: * <p> 174: * If the name supplied is <code>null</code>, then the bean is 175: * expected to implement the {@link MBeanRegistration} interface. 176: * The {@link MBeanRegistration#preRegister preRegister} method 177: * of this interface will be used to obtain the name in this case. 178: * </p> 179: * <p> 180: * This method is equivalent to calling {@link 181: * #createMBean(String, ObjectName, Object[], String[]) 182: * <code>createMBean(className, name, (Object[]) null, 183: * (String[]) null)</code>} with <code>null</code> parameters 184: * and signature. 185: * </p> 186: * 187: * @param className the class of the management bean, of which 188: * an instance should be created. 189: * @param name the name to register the new bean with. 190: * @return an {@link ObjectInstance} containing the {@link ObjectName} 191: * and Java class name of the created instance. 192: * @throws ReflectionException if an exception occurs in creating 193: * an instance of the bean. 194: * @throws InstanceAlreadyExistsException if a matching instance 195: * already exists. 196: * @throws MBeanRegistrationException if an exception occurs in 197: * calling the preRegister 198: * method. 199: * @throws MBeanException if the bean's constructor throws an exception. 200: * @throws NotCompliantMBeanException if the created bean is not 201: * compliant with the JMX specification. 202: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 203: * is thrown by the server due to a 204: * <code>null</code> class name or object 205: * name or if the object name is a pattern. 206: * @throws SecurityException if a security manager exists and the 207: * caller's permissions don't imply the 208: * use of the <code>instantiate</code> 209: * and <code>registerMBean</code> methods. 210: * @see #createMBean(String, ObjectName, Object[], String[]) 211: */ 212: ObjectInstance createMBean(String className, ObjectName name) 213: throws ReflectionException, InstanceAlreadyExistsException, 214: MBeanRegistrationException, MBeanException, 215: NotCompliantMBeanException; 216: 217: /** 218: * <p> 219: * Instantiates a new instance of the specified management bean 220: * using the given constructor and registers it with the server 221: * under the supplied name. The class is loaded using the 222: * {@link javax.management.loading.ClassLoaderRepository default 223: * loader repository} of the server. 224: * </p> 225: * <p> 226: * If the name supplied is <code>null</code>, then the bean is 227: * expected to implement the {@link MBeanRegistration} interface. 228: * The {@link MBeanRegistration#preRegister preRegister} method 229: * of this interface will be used to obtain the name in this case. 230: * </p> 231: * 232: * @param className the class of the management bean, of which 233: * an instance should be created. 234: * @param name the name to register the new bean with. 235: * @param params the parameters for the bean's constructor. 236: * @param sig the signature of the constructor to use. 237: * @return an {@link ObjectInstance} containing the {@link ObjectName} 238: * and Java class name of the created instance. 239: * @throws ReflectionException if an exception occurs in creating 240: * an instance of the bean. 241: * @throws InstanceAlreadyExistsException if a matching instance 242: * already exists. 243: * @throws MBeanRegistrationException if an exception occurs in 244: * calling the preRegister 245: * method. 246: * @throws MBeanException if the bean's constructor throws an exception. 247: * @throws NotCompliantMBeanException if the created bean is not 248: * compliant with the JMX specification. 249: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 250: * is thrown by the server due to a 251: * <code>null</code> class name or object 252: * name or if the object name is a pattern. 253: * @throws SecurityException if a security manager exists and the 254: * caller's permissions don't imply the 255: * use of the <code>instantiate</code> 256: * and <code>registerMBean</code> methods. 257: */ 258: ObjectInstance createMBean(String className, ObjectName name, 259: Object[] params, String[] sig) 260: throws ReflectionException, InstanceAlreadyExistsException, 261: MBeanRegistrationException, MBeanException, 262: NotCompliantMBeanException; 263: 264: /** 265: * <p> 266: * Instantiates a new instance of the specified management bean 267: * using the default constructor and registers it with the server 268: * under the supplied name. The class is loaded using the 269: * given class loader. If this argument is <code>null</code>, 270: * then the same class loader as was used to load the server 271: * is used. 272: * </p> 273: * <p> 274: * If the name supplied is <code>null</code>, then the bean is 275: * expected to implement the {@link MBeanRegistration} interface. 276: * The {@link MBeanRegistration#preRegister preRegister} method 277: * of this interface will be used to obtain the name in this case. 278: * </p> 279: * <p> 280: * This method is equivalent to calling {@link 281: * #createMBean(String, ObjectName, ObjectName, Object[], String) 282: * <code>createMBean(className, name, loaderName, (Object[]) null, 283: * (String) null)</code>} with <code>null</code> parameters 284: * and signature. 285: * </p> 286: * 287: * @param className the class of the management bean, of which 288: * an instance should be created. 289: * @param name the name to register the new bean with. 290: * @param loaderName the name of the class loader. 291: * @return an {@link ObjectInstance} containing the {@link ObjectName} 292: * and Java class name of the created instance. 293: * @throws ReflectionException if an exception occurs in creating 294: * an instance of the bean. 295: * @throws InstanceAlreadyExistsException if a matching instance 296: * already exists. 297: * @throws MBeanRegistrationException if an exception occurs in 298: * calling the preRegister 299: * method. 300: * @throws MBeanException if the bean's constructor throws an exception. 301: * @throws NotCompliantMBeanException if the created bean is not 302: * compliant with the JMX specification. 303: * @throws InstanceNotFoundException if the specified class loader is not 304: * registered with the server. 305: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 306: * is thrown by the server due to a 307: * <code>null</code> class name or object 308: * name or if the object name is a pattern. 309: * @throws SecurityException if a security manager exists and the 310: * caller's permissions don't imply the 311: * use of the <code>instantiate</code> 312: * and <code>registerMBean</code> methods. 313: * @see #createMBean(String, ObjectName, ObjectName, Object[], String[]) 314: */ 315: ObjectInstance createMBean(String className, ObjectName name, 316: ObjectName loaderName) 317: throws ReflectionException, InstanceAlreadyExistsException, 318: MBeanRegistrationException, MBeanException, 319: NotCompliantMBeanException, InstanceNotFoundException; 320: 321: /** 322: * <p> 323: * Instantiates a new instance of the specified management bean 324: * using the given constructor and registers it with the server 325: * under the supplied name. The class is loaded using the 326: * given class loader. If this argument is <code>null</code>, 327: * then the same class loader as was used to load the server 328: * is used. 329: * </p> 330: * <p> 331: * If the name supplied is <code>null</code>, then the bean is 332: * expected to implement the {@link MBeanRegistration} interface. 333: * The {@link MBeanRegistration#preRegister preRegister} method 334: * of this interface will be used to obtain the name in this case. 335: * </p> 336: * 337: * @param className the class of the management bean, of which 338: * an instance should be created. 339: * @param name the name to register the new bean with. 340: * @param loaderName the name of the class loader. 341: * @param params the parameters for the bean's constructor. 342: * @param sig the signature of the constructor to use. 343: * @return an {@link ObjectInstance} containing the {@link ObjectName} 344: * and Java class name of the created instance. 345: * @throws ReflectionException if an exception occurs in creating 346: * an instance of the bean. 347: * @throws InstanceAlreadyExistsException if a matching instance 348: * already exists. 349: * @throws MBeanRegistrationException if an exception occurs in 350: * calling the preRegister 351: * method. 352: * @throws MBeanException if the bean's constructor throws an exception. 353: * @throws NotCompliantMBeanException if the created bean is not 354: * compliant with the JMX specification. 355: * @throws InstanceNotFoundException if the specified class loader is not 356: * registered with the server. 357: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 358: * is thrown by the server due to a 359: * <code>null</code> class name or object 360: * name or if the object name is a pattern. 361: * @throws SecurityException if a security manager exists and the 362: * caller's permissions don't imply the 363: * use of the <code>instantiate</code> 364: * and <code>registerMBean</code> methods. 365: */ 366: ObjectInstance createMBean(String className, ObjectName name, 367: ObjectName loaderName, Object[] params, 368: String[] sig) 369: throws ReflectionException, InstanceAlreadyExistsException, 370: MBeanRegistrationException, MBeanException, 371: NotCompliantMBeanException, InstanceNotFoundException; 372: 373: /** 374: * Deserializes a byte array using the class loader of the specified 375: * management bean as its context. 376: * 377: * @param name the name of the bean whose class loader should be used. 378: * @param data the byte array to be deserialized. 379: * @return the deserialized object stream. 380: * @deprecated {@link #getClassLoaderFor(ObjectName)} should be used 381: * to obtain the class loader of the bean, which can then 382: * be used to perform deserialization in the user's code. 383: * @throws InstanceNotFoundException if the specified bean is not 384: * registered with the server. 385: * @throws OperationsException if any I/O error is thrown by the 386: * deserialization process. 387: * @throws SecurityException if a security manager exists and the 388: * caller's permissions don't imply {@link 389: * MBeanPermission(String,String,ObjectName,String) 390: * <code>MBeanPermission(className, null, name, 391: * "getClassLoaderFor")</code> 392: */ 393: ObjectInputStream deserialize(ObjectName name, byte[] data) 394: throws InstanceNotFoundException, OperationsException; 395: 396: /** 397: * Deserializes a byte array using the same class loader for its context 398: * as was used to load the given class. This class loader is obtained by 399: * loading the specified class using the {@link 400: * javax.management.loading.ClassLoaderRepository Class Loader Repository} 401: * and then using the class loader of the resulting {@link Class} instance. 402: * 403: * @param name the name of the class which should be loaded to obtain the 404: * class loader. 405: * @param data the byte array to be deserialized. 406: * @return the deserialized object stream. 407: * @deprecated {@link #getClassLoaderRepository} should be used 408: * to obtain the class loading repository, which can then 409: * be used to obtain the {@link Class} instance and deserialize 410: * the array using its class loader. 411: * @throws OperationsException if any I/O error is thrown by the 412: * deserialization process. 413: * @throws ReflectionException if an error occurs in obtaining the 414: * {@link Class} instance. 415: * @throws SecurityException if a security manager exists and the 416: * caller's permissions don't imply {@link 417: * MBeanPermission(String,String,ObjectName,String) 418: * <code>MBeanPermission(null, null, null, 419: * "getClassLoaderRepository")</code> 420: */ 421: ObjectInputStream deserialize(String name, byte[] data) 422: throws OperationsException, ReflectionException; 423: 424: /** 425: * Deserializes a byte array using the same class loader for its context 426: * as was used to load the given class. The name of the class loader to 427: * be used is supplied, and may be <code>null</code> if the server's 428: * class loader should be used instead. 429: * 430: * @param name the name of the class which should be loaded to obtain the 431: * class loader. 432: * @param loader the name of the class loader to use, or <code>null</code> 433: * if the class loader of the server should be used. 434: * @param data the byte array to be deserialized. 435: * @return the deserialized object stream. 436: * @deprecated {@link #getClassLoader(ObjectName} can be used to obtain 437: * the named class loader and deserialize the array. 438: * @throws InstanceNotFoundException if the specified class loader is not 439: * registered with the server. 440: * @throws OperationsException if any I/O error is thrown by the 441: * deserialization process. 442: * @throws ReflectionException if an error occurs in obtaining the 443: * {@link Class} instance. 444: * @throws SecurityException if a security manager exists and the 445: * caller's permissions don't imply {@link 446: * MBeanPermission(String,String,ObjectName,String) 447: * <code>MBeanPermission(className, null, loader, 448: * "getClassLoader")</code> 449: */ 450: ObjectInputStream deserialize(String name, ObjectName loader, byte[] data) 451: throws InstanceNotFoundException, ReflectionException, 452: OperationsException; 453: 454: /** 455: * Returns the value of the supplied attribute from the specified 456: * management bean. 457: * 458: * @param bean the bean to retrieve the value from. 459: * @param name the name of the attribute to retrieve. 460: * @return the value of the attribute. 461: * @throws AttributeNotFoundException if the attribute could not be 462: * accessed from the bean. 463: * @throws MBeanException if the management bean's accessor throws 464: * an exception. 465: * @throws InstanceNotFoundException if the bean can not be found. 466: * @throws ReflectionException if an exception was thrown in trying 467: * to invoke the bean's accessor. 468: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 469: * is thrown by the server due to a 470: * <code>null</code> bean or attribute 471: * name. 472: * @throws SecurityException if a security manager exists and the 473: * caller's permissions don't imply {@link 474: * MBeanPermission(String,String,ObjectName,String) 475: * <code>MBeanPermission(className, name, bean, 476: * "getAttribute")</code>}. 477: * @see DynamicMBean#getAttribute(String) 478: */ 479: Object getAttribute(ObjectName bean, String name) 480: throws MBeanException, AttributeNotFoundException, 481: InstanceNotFoundException, ReflectionException; 482: 483: /** 484: * Returns the values of the named attributes from the specified 485: * management bean. 486: * 487: * @param bean the bean to retrieve the value from. 488: * @param names the names of the attributes to retrieve. 489: * @return the values of the attributes. 490: * @throws InstanceNotFoundException if the bean can not be found. 491: * @throws ReflectionException if an exception was thrown in trying 492: * to invoke the bean's accessor. 493: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 494: * is thrown by the server due to a 495: * <code>null</code> bean or attribute 496: * name. 497: * @throws SecurityException if a security manager exists and the 498: * caller's permissions don't imply {@link 499: * MBeanPermission(String,String,ObjectName,String) 500: * <code>MBeanPermission(className, null, bean, 501: * "getAttribute")</code>}. Additionally, 502: * for an attribute name, <code>n</code>, the 503: * caller's permission must imply {@link 504: * MBeanPermission(String,String,ObjectName,String) 505: * <code>MBeanPermission(className, n, bean, 506: * "getAttribute")</code>} or that attribute will 507: * not be included. 508: * 509: * @see DynamicMBean#getAttributes(String[]) 510: */ 511: AttributeList getAttributes(ObjectName bean, String[] names) 512: throws InstanceNotFoundException, ReflectionException; 513: 514: /** 515: * Returns the specified class loader. If the specified value is 516: * <code>null</code>, then the class loader of the server will be 517: * returned. If <code>l</code> is the requested class loader, 518: * and <code>r</code> is the actual class loader returned, then 519: * either <code>l</code> and <code>r</code> will be identical, 520: * or they will at least return the same class from 521: * {@link ClassLoader#loadClass(String)} for any given string. 522: * They may not be identical due to one or the other 523: * being wrapped in another class loader (e.g. for security). 524: * 525: * @param name the name of the class loader to return. 526: * @return the class loader. 527: * @throws InstanceNotFoundException if the class loader can not 528: * be found. 529: * @throws SecurityException if a security manager exists and the 530: * caller's permissions don't imply {@link 531: * MBeanPermission(String,String,ObjectName,String) 532: * <code>MBeanPermission(className, null, name, 533: * "getClassLoader")</code> 534: */ 535: ClassLoader getClassLoader(ObjectName name) 536: throws InstanceNotFoundException; 537: 538: /** 539: * Returns the class loader of the specified management bean. If 540: * <code>l</code> is the requested class loader, and <code>r</code> 541: * is the actual class loader returned, then either <code>l</code> 542: * and <code>r</code> will be identical, or they will at least 543: * return the same class from {@link ClassLoader#loadClass(String)} 544: * for any given string. They may not be identical due to one or 545: * the other being wrapped in another class loader (e.g. for 546: * security). 547: * 548: * @param name the name of the bean whose class loader should be 549: * returned. 550: * @return the class loader. 551: * @throws InstanceNotFoundException if the bean is not registered 552: * with the server. 553: * @throws SecurityException if a security manager exists and the 554: * caller's permissions don't imply {@link 555: * MBeanPermission(String,String,ObjectName,String) 556: * <code>MBeanPermission(className, null, name, 557: * "getClassLoaderFor")</code> 558: */ 559: ClassLoader getClassLoaderFor(ObjectName name) 560: throws InstanceNotFoundException; 561: 562: /** 563: * Returns the class loader repository used by this server. 564: * 565: * @return the class loader repository. 566: * @throws SecurityException if a security manager exists and the 567: * caller's permissions don't imply {@link 568: * MBeanPermission(String,String,ObjectName,String) 569: * <code>MBeanPermission(null, null, null, 570: * "getClassLoaderRepository")</code> 571: */ 572: ClassLoaderRepository getClassLoaderRepository(); 573: 574: /** 575: * Returns the default domain this server applies to beans that have 576: * no specified domain. 577: * 578: * @return the default domain. 579: */ 580: String getDefaultDomain(); 581: 582: /** 583: * Returns an array containing all the domains used by beans registered 584: * with this server. The ordering of the array is undefined. 585: * 586: * @return the list of domains. 587: * @throws SecurityException if a security manager exists and the 588: * caller's permissions don't imply {@link 589: * MBeanPermission(String,String,ObjectName,String) 590: * <code>MBeanPermission(null, null, name, 591: * "getDomains")</code>}. Additionally, 592: * for an domain, <code>d</code>, the 593: * caller's permission must imply {@link 594: * MBeanPermission(String,String,ObjectName,String) 595: * <code>MBeanPermission(null, null, 596: * new ObjectName("d:x=x"), "getDomains")</code>} 597: * or that domain will not be included. Note 598: * that "x=x" is an arbitrary key-value pair 599: * provided to satisfy the constructor. 600: * @see ObjectName#getDomain() 601: */ 602: String[] getDomains(); 603: 604: /** 605: * Returns the number of management beans registered with this server. 606: * This may be less than the real number if the caller's access is 607: * restricted. 608: * 609: * @return the number of registered beans. 610: */ 611: Integer getMBeanCount(); 612: 613: /** 614: * Returns information on the given management bean. 615: * 616: * @param name the name of the management bean. 617: * @return an instance of {@link MBeanInfo} for the bean. 618: * @throws IntrospectionException if an exception occurs in examining 619: * the bean. 620: * @throws InstanceNotFoundException if the bean can not be found. 621: * @throws ReflectionException if an exception occurs when trying 622: * to invoke {@link DynamicMBean#getMBeanInfo()} 623: * on the bean. 624: * @throws SecurityException if a security manager exists and the 625: * caller's permissions don't imply {@link 626: * MBeanPermission(String,String,ObjectName,String) 627: * <code>MBeanPermission(className, null, name, 628: * "getMBeanInfo")</code>}. 629: * @see DynamicMBean#getMBeanInfo() 630: */ 631: MBeanInfo getMBeanInfo(ObjectName name) 632: throws InstanceNotFoundException, IntrospectionException, 633: ReflectionException; 634: 635: /** 636: * Returns the {@link ObjectInstance} created for the specified 637: * management bean on registration. 638: * 639: * @param name the name of the bean. 640: * @return the corresponding {@link ObjectInstance} instance. 641: * @throws InstanceNotFoundException if the bean can not be found. 642: * @throws SecurityException if a security manager exists and the 643: * caller's permissions don't imply {@link 644: * MBeanPermission(String,String,ObjectName,String) 645: * <code>MBeanPermission(className, null, name, 646: * "getObjectInstance")</code> 647: * @see #createMBean(String, ObjectName) 648: */ 649: ObjectInstance getObjectInstance(ObjectName name) 650: throws InstanceNotFoundException; 651: 652: /** 653: * <p> 654: * Creates an instance of the specified class using the list of 655: * class loaders from the {@link 656: * javax.management.loading.ClassLoaderRepository Class Loader 657: * Repository}. The class should have a public constructor 658: * with no arguments. A reference to the new instance is returned, 659: * but the instance is not yet registered with the server. 660: * </p> 661: * <p> 662: * This method is equivalent to calling {@link 663: * #instantiate(String, Object[], String[]) 664: * <code>instantiate(name, (Object[]) null, (String[]) null)</code>} 665: * with <code>null</code> parameters and signature. 666: * </p> 667: * 668: * @param name the name of the class of bean to be instantiated. 669: * @return an instance of the given class. 670: * @throws ReflectionException if an exception is thrown during 671: * loading the class or calling the 672: * constructor. 673: * @throws MBeanException if the constructor throws an exception. 674: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 675: * is thrown by the server due to a 676: * <code>null</code> name. 677: * @throws SecurityException if a security manager exists and the 678: * caller's permissions don't imply {@link 679: * MBeanPermission(String,String,ObjectName,String) 680: * <code>MBeanPermission(className, null, null, 681: * "instantiate")</code>}. 682: * @see #instantiate(String, Object[], String[]) 683: */ 684: Object instantiate(String name) 685: throws ReflectionException, MBeanException; 686: 687: /** 688: * Creates an instance of the specified class using the list of 689: * class loaders from the {@link 690: * javax.management.loading.ClassLoaderRepository Class Loader 691: * Repository}. The class should have a public constructor 692: * matching the supplied signature. A reference to the new 693: * instance is returned, but the instance is not yet 694: * registered with the server. 695: * 696: * @param name the name of the class of bean to be instantiated. 697: * @param params the parameters for the constructor. 698: * @param sig the signature of the constructor. 699: * @return an instance of the given class. 700: * @throws ReflectionException if an exception is thrown during 701: * loading the class or calling the 702: * constructor. 703: * @throws MBeanException if the constructor throws an exception. 704: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 705: * is thrown by the server due to a 706: * <code>null</code> name. 707: * @throws SecurityException if a security manager exists and the 708: * caller's permissions don't imply {@link 709: * MBeanPermission(String,String,ObjectName,String) 710: * <code>MBeanPermission(className, null, null, 711: * "instantiate")</code>}. 712: */ 713: Object instantiate(String name, Object[] params, String[] sig) 714: throws ReflectionException, MBeanException; 715: 716: /** 717: * <p> 718: * Creates an instance of the specified class using the supplied 719: * class loader. If the class loader given is <code>null</code>, 720: * then the class loader of the server will be used. The class 721: * should have a public constructor with no arguments. A reference 722: * to the new instance is returned, but the instance is not yet 723: * registered with the server. 724: * </p> 725: * <p> 726: * This method is equivalent to calling {@link 727: * #instantiate(String, ObjectName, Object[], String[]) 728: * <code>instantiate(name, loaderName, (Object[]) null, 729: * (String[]) null)</code>} with <code>null</code> parameters 730: * and signature. 731: * </p> 732: * 733: * @param name the name of the class of bean to be instantiated. 734: * @param loaderName the name of the class loader to use. 735: * @return an instance of the given class. 736: * @throws InstanceNotFoundException if the class loader is not 737: * registered with the server. 738: * @throws ReflectionException if an exception is thrown during 739: * loading the class or calling the 740: * constructor. 741: * @throws MBeanException if the constructor throws an exception. 742: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 743: * is thrown by the server due to a 744: * <code>null</code> name. 745: * @throws SecurityException if a security manager exists and the 746: * caller's permissions don't imply {@link 747: * MBeanPermission(String,String,ObjectName,String) 748: * <code>MBeanPermission(className, null, null, 749: * "instantiate")</code>}. 750: * @see #instantiate(String, Object[], String[]) 751: */ 752: Object instantiate(String name, ObjectName loaderName) 753: throws InstanceNotFoundException, ReflectionException, 754: MBeanException; 755: 756: /** 757: * Creates an instance of the specified class using the supplied 758: * class loader. If the class loader given is <code>null</code>, 759: * then the class loader of the server will be used. The class 760: * should have a public constructor matching the supplied 761: * signature. A reference to the new instance is returned, 762: * but the instance is not yet registered with the server. 763: * 764: * @param name the name of the class of bean to be instantiated. 765: * @param loaderName the name of the class loader to use. 766: * @param params the parameters for the constructor. 767: * @param sig the signature of the constructor. 768: * @return an instance of the given class. 769: * @throws InstanceNotFoundException if the class loader is not 770: * registered with the server. 771: * @throws ReflectionException if an exception is thrown during 772: * loading the class or calling the 773: * constructor. 774: * @throws MBeanException if the constructor throws an exception. 775: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 776: * is thrown by the server due to a 777: * <code>null</code> name. 778: * @throws SecurityException if a security manager exists and the 779: * caller's permissions don't imply {@link 780: * MBeanPermission(String,String,ObjectName,String) 781: * <code>MBeanPermission(className, null, null, 782: * "instantiate")</code>}. 783: */ 784: Object instantiate(String name, ObjectName loaderName, 785: Object[] params, String[] sig) 786: throws InstanceNotFoundException, ReflectionException, 787: MBeanException; 788: 789: /** 790: * Invokes the supplied operation on the specified management 791: * bean. The class objects specified in the signature are loaded 792: * using the same class loader as was used for the management bean. 793: * 794: * @param bean the management bean whose operation should be invoked. 795: * @param name the name of the operation to invoke. 796: * @param params the parameters of the operation. 797: * @param sig the signature of the operation. 798: * @return the return value of the method. 799: * @throws InstanceNotFoundException if the bean can not be found. 800: * @throws MBeanException if the method invoked throws an exception. 801: * @throws ReflectionException if an exception is thrown in invoking the 802: * method. 803: * @throws SecurityException if a security manager exists and the 804: * caller's permissions don't imply {@link 805: * MBeanPermission(String,String,ObjectName,String) 806: * <code>MBeanPermission(className, name, bean, 807: * "invoke")</code>}. 808: * @see DynamicMBean#invoke(String, Object[], String[]) 809: */ 810: Object invoke(ObjectName bean, String name, Object[] params, String[] sig) 811: throws InstanceNotFoundException, MBeanException, 812: ReflectionException; 813: 814: /** 815: * <p> 816: * Returns true if the specified management bean is an instance 817: * of the supplied class. 818: * </p> 819: * <p> 820: * A bean, B, is an instance of a class, C, if either of the following 821: * conditions holds: 822: * </p> 823: * <ul> 824: * <li>The class name in B's {@link MBeanInfo} is equal to the supplied 825: * name.</li> 826: * <li>Both the class of B and C were loaded by the same class loader, 827: * and B is assignable to C.</li> 828: * </ul> 829: * 830: * @param name the name of the management bean. 831: * @param className the name of the class to test if <code>name</code> is 832: * an instance of. 833: * @return true if either B is directly an instance of the named class, 834: * or B is assignable to the class, given that both it and B's 835: * current class were loaded using the same class loader. 836: * @throws InstanceNotFoundException if the bean can not be found. 837: * @throws SecurityException if a security manager exists and the 838: * caller's permissions don't imply {@link 839: * MBeanPermission(String,String,ObjectName,String) 840: * <code>MBeanPermission(className, null, name, 841: * "isInstanceOf")</code> 842: */ 843: boolean isInstanceOf(ObjectName name, String className) 844: throws InstanceNotFoundException; 845: 846: /** 847: * Returns true if the specified management bean is registered with 848: * the server. 849: * 850: * @param name the name of the management bean. 851: * @return true if the bean is registered. 852: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 853: * is thrown by the server due to a 854: * <code>null</code> bean name. 855: */ 856: boolean isRegistered(ObjectName name); 857: 858: /** 859: * <p> 860: * Returns a set of {@link ObjectInstance}s matching the specified 861: * criteria. The full set of beans registered with the server 862: * are passed through two filters: 863: * </p> 864: * <ol> 865: * <li>Pattern matching is performed using the supplied 866: * {@link ObjectName}.</li> 867: * <li>The supplied query expression is applied.</li> 868: * </ol> 869: * <p> 870: * If both the object name and the query expression are <code>null</code>, 871: * or the object name has no domain and no key properties, 872: * no filtering will be performed and all beans are returned. 873: * </p> 874: * 875: * @param name an {@link ObjectName} to use as a filter. 876: * @param query a query expression to apply to each of the beans that match 877: * the given object name. 878: * @return a set of {@link ObjectInstance}s matching the filtered beans. 879: * @throws SecurityException if a security manager exists and the 880: * caller's permissions don't imply {@link 881: * MBeanPermission(String,String,ObjectName,String) 882: * <code>MBeanPermission(null, null, name, 883: * "queryMBeans")</code>}. Additionally, 884: * for an bean, <code>b</code>, the 885: * caller's permission must imply {@link 886: * MBeanPermission(String,String,ObjectName,String) 887: * <code>MBeanPermission(className, b, name, 888: * "queryMBeans")</code>} or that bean will 889: * not be included. Such an exception may also 890: * arise from the execution of the query, in which 891: * case that particular bean will again be excluded. 892: */ 893: Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query); 894: 895: /** 896: * <p> 897: * Returns a set of {@link ObjectName}s matching the specified 898: * criteria. The full set of beans registered with the server 899: * are passed through two filters: 900: * </p> 901: * <ol> 902: * <li>Pattern matching is performed using the supplied 903: * {@link ObjectName}.</li> 904: * <li>The supplied query expression is applied.</li> 905: * </ol> 906: * <p> 907: * If both the object name and the query expression are <code>null</code>, 908: * or the object name has no domain and no key properties, 909: * no filtering will be performed and all beans are returned. 910: * </p> 911: * 912: * @param name an {@link ObjectName} to use as a filter. 913: * @param query a query expression to apply to each of the beans that match 914: * the given object name. 915: * @return a set of {@link ObjectName}s matching the filtered beans. 916: * @throws SecurityException if a security manager exists and the 917: * caller's permissions don't imply {@link 918: * MBeanPermission(String,String,ObjectName,String) 919: * <code>MBeanPermission(null, null, name, 920: * "queryNames")</code>}. Additionally, 921: * for an name, <code>n</code>, the 922: * caller's permission must imply {@link 923: * MBeanPermission(String,String,ObjectName,String) 924: * <code>MBeanPermission(className, n, name, 925: * "queryNames")</code>} or that name will 926: * not be included. Such an exception may also 927: * arise from the execution of the query, in which 928: * case that particular bean will again be excluded. 929: * Note that these permissions are implied if the 930: * <code>queryMBeans</code> permissions are available. 931: */ 932: Set<ObjectName> queryNames(ObjectName name, QueryExp query); 933: 934: /** 935: * Registers the supplied instance with the server, using the specified 936: * {@link ObjectName}. If the name given is <code>null</code>, then 937: * the bean supplied is expected to implement the {@link MBeanRegistration} 938: * interface and provide the name via the 939: * {@link MBeanRegistration#preRegister preRegister} method 940: * of this interface. 941: * 942: * @param obj the object to register with the server. 943: * @param name the name under which to register the object, 944: * or <code>null</code> if the {@link MBeanRegistration} 945: * interface should be used. 946: * @throws InstanceAlreadyExistsException if a matching instance 947: * already exists. 948: * @throws MBeanRegistrationException if an exception occurs in 949: * calling the preRegister 950: * method. 951: * @throws NotCompliantMBeanException if the created bean is not 952: * compliant with the JMX specification. 953: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 954: * is thrown by the server due to a 955: * <code>null</code> object. 956: * @throws SecurityException if a security manager exists and the 957: * caller's permissions don't imply {@link 958: * MBeanPermission(String,String,ObjectName,String) 959: * <code>MBeanPermission(className, null, name, 960: * "registerMBean")</code>}. <code>className</code> 961: * here corresponds to the result of 962: * {@link MBeanInfo#getClassName()} for objects of 963: * this class. If this check succeeds, a check 964: * is also made on its 965: * {@link java.security.ProtectionDomain} to ensure 966: * it implies {@link MBeanTrustPermission(String) 967: * <code>MBeanTrustPermission("register")</code>}. 968: * The use of the {@link MBeanRegistration} interface 969: * results in another {@link MBeanPermission} check 970: * being made on the returned {@link ObjectName}. 971: */ 972: ObjectInstance registerMBean(Object obj, ObjectName name) 973: throws InstanceAlreadyExistsException, MBeanRegistrationException, 974: NotCompliantMBeanException; 975: 976: /** 977: * Removes the specified listener from the list of recipients 978: * of notifications from the supplied bean. This includes all 979: * combinations of filters and passback objects registered for 980: * this listener. For more specific removal of listeners, see 981: * {@link #removeNotificationListener(ObjectName, 982: * NotificationListener,NotificationFilter,Object)} 983: * 984: * @param name the name of the management bean from which the 985: * listener should be removed. 986: * @param listener the listener to remove. 987: * @throws InstanceNotFoundException if the bean can not be found. 988: * @throws ListenerNotFoundException if the specified listener 989: * is not registered with the bean. 990: * @throws SecurityException if a security manager exists and the 991: * caller's permissions don't imply {@link 992: * MBeanPermission(String,String,ObjectName,String) 993: * <code>MBeanPermission(className, null, name, 994: * "removeNotificationListener")</code>}. 995: * @see #addNotificationListener(NotificationListener, NotificationFilter, 996: * java.lang.Object) 997: * @see NotificationBroadcaster#removeNotificationListener(NotificationListener) 998: */ 999: void removeNotificationListener(ObjectName name, 1000: NotificationListener listener) 1001: throws InstanceNotFoundException, ListenerNotFoundException; 1002: 1003: /** 1004: * Removes the specified listener from the list of recipients 1005: * of notifications from the supplied bean. Only the first instance with 1006: * the supplied filter and passback object is removed. 1007: * <code>null</code> is used as a valid value for these parameters, 1008: * rather than as a way to remove all registration instances for 1009: * the specified listener; for this behaviour instead, see 1010: * {@link #removeNotificationListener(ObjectName, NotificationListener)}. 1011: * 1012: * @param name the name of the management bean from which the 1013: * listener should be removed. 1014: * @param listener the listener to remove. 1015: * @param filter the filter of the listener to remove. 1016: * @param passback the passback object of the listener to remove. 1017: * @throws InstanceNotFoundException if the bean can not be found. 1018: * @throws ListenerNotFoundException if the specified listener 1019: * is not registered with the bean. 1020: * @throws SecurityException if a security manager exists and the 1021: * caller's permissions don't imply {@link 1022: * MBeanPermission(String,String,ObjectName,String) 1023: * <code>MBeanPermission(className, null, name, 1024: * "removeNotificationListener")</code>}. 1025: * @see #addNotificationListener(ObjectName, NotificationListener, 1026: * NotificationFilter, Object) 1027: * @see NotificationEmitter#removeNotificationListener(NotificationListener, 1028: * NotificationFilter, 1029: * Object) 1030: */ 1031: void removeNotificationListener(ObjectName name, 1032: NotificationListener listener, 1033: NotificationFilter filter, 1034: Object passback) 1035: throws InstanceNotFoundException, ListenerNotFoundException; 1036: 1037: /** 1038: * Removes the specified listener from the list of recipients 1039: * of notifications from the supplied bean. This includes all 1040: * combinations of filters and passback objects registered for 1041: * this listener. For more specific removal of listeners, see 1042: * {@link #removeNotificationListener(ObjectName, 1043: * ObjectName,NotificationFilter,Object)} 1044: * 1045: * @param name the name of the management bean from which the 1046: * listener should be removed. 1047: * @param listener the name of the listener to remove. 1048: * @throws InstanceNotFoundException if a name doesn't match a registered 1049: * bean. 1050: * @throws ListenerNotFoundException if the specified listener 1051: * is not registered with the bean. 1052: * @throws SecurityException if a security manager exists and the 1053: * caller's permissions don't imply {@link 1054: * MBeanPermission(String,String,ObjectName,String) 1055: * <code>MBeanPermission(className, null, name, 1056: * "removeNotificationListener")</code>}. 1057: * @see #addNotificationListener(NotificationListener, NotificationFilter, 1058: * java.lang.Object) 1059: * @see NotificationBroadcaster#removeNotificationListener(NotificationListener) 1060: */ 1061: void removeNotificationListener(ObjectName name, ObjectName listener) 1062: throws InstanceNotFoundException, ListenerNotFoundException; 1063: 1064: /** 1065: * Removes the specified listener from the list of recipients 1066: * of notifications from the supplied bean. Only the first instance with 1067: * the supplied filter and passback object is removed. 1068: * <code>null</code> is used as a valid value for these parameters, 1069: * rather than as a way to remove all registration instances for 1070: * the specified listener; for this behaviour instead, see 1071: * {@link #removeNotificationListener(ObjectName, ObjectName)}. 1072: * 1073: * @param name the name of the management bean from which the 1074: * listener should be removed. 1075: * @param listener the name of the listener to remove. 1076: * @param filter the filter of the listener to remove. 1077: * @param passback the passback object of the listener to remove. 1078: * @throws InstanceNotFoundException if a name doesn't match a registered 1079: * bean. 1080: * @throws ListenerNotFoundException if the specified listener 1081: * is not registered with the bean. 1082: * @throws SecurityException if a security manager exists and the 1083: * caller's permissions don't imply {@link 1084: * MBeanPermission(String,String,ObjectName,String) 1085: * <code>MBeanPermission(className, null, name, 1086: * "removeNotificationListener")</code>}. 1087: * @see #addNotificationListener(ObjectName, NotificationListener, 1088: * NotificationFilter, Object) 1089: * @see NotificationEmitter#removeNotificationListener(NotificationListener, 1090: * NotificationFilter, 1091: * Object) 1092: */ 1093: void removeNotificationListener(ObjectName name, 1094: ObjectName listener, 1095: NotificationFilter filter, 1096: Object passback) 1097: throws InstanceNotFoundException, ListenerNotFoundException; 1098: 1099: /** 1100: * Sets the value of the specified attribute of the supplied 1101: * management bean. 1102: * 1103: * @param name the name of the management bean. 1104: * @param attribute the attribute to set. 1105: * @throws InstanceNotFoundException if the bean can not be found. 1106: * @throws AttributeNotFoundException if the attribute does not 1107: * correspond to an attribute 1108: * of the bean. 1109: * @throws InvalidAttributeValueException if the value is invalid 1110: * for this particular 1111: * attribute of the bean. 1112: * @throws MBeanException if setting the attribute causes 1113: * the bean to throw an exception (which 1114: * becomes the cause of this exception). 1115: * @throws ReflectionException if an exception occurred in trying 1116: * to use the reflection interface 1117: * to lookup the attribute. The 1118: * thrown exception is the cause of 1119: * this exception. 1120: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1121: * is thrown by the server due to a 1122: * <code>null</code> bean or attribute 1123: * name. 1124: * @throws SecurityException if a security manager exists and the 1125: * caller's permissions don't imply {@link 1126: * MBeanPermission(String,String,ObjectName,String) 1127: * <code>MBeanPermission(className, name, bean, 1128: * "setAttribute")</code>}. 1129: * @see #getAttribute(ObjectName, String) 1130: * @see DynamicMBean#setAttribute(Attribute) 1131: */ 1132: void setAttribute(ObjectName name, Attribute attribute) 1133: throws InstanceNotFoundException, AttributeNotFoundException, 1134: InvalidAttributeValueException, MBeanException, 1135: ReflectionException; 1136: 1137: /** 1138: * Sets the value of each of the specified attributes 1139: * of the supplied management bean to that specified by 1140: * the {@link Attribute} object. The returned list contains 1141: * the attributes that were set and their new values. 1142: * 1143: * @param name the name of the management bean. 1144: * @param attributes the attributes to set. 1145: * @return a list of the changed attributes. 1146: * @throws InstanceNotFoundException if the bean can not be found. 1147: * @throws ReflectionException if an exception occurred in trying 1148: * to use the reflection interface 1149: * to lookup the attribute. The 1150: * thrown exception is the cause of 1151: * this exception. 1152: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1153: * is thrown by the server due to a 1154: * <code>null</code> bean or attribute 1155: * list. 1156: * @throws SecurityException if a security manager exists and the 1157: * caller's permissions don't imply {@link 1158: * MBeanPermission(String,String,ObjectName,String) 1159: * <code>MBeanPermission(className, null, bean, 1160: * "setAttribute")</code>}. Additionally, 1161: * for an attribute name, <code>n</code>, the 1162: * caller's permission must imply {@link 1163: * MBeanPermission(String,String,ObjectName,String) 1164: * <code>MBeanPermission(className, n, bean, 1165: * "setAttribute")</code>} or that attribute will 1166: * not be included. 1167: * @see #getAttributes(ObjectName, String[]) 1168: * @see DynamicMBean#setAttributes(AttributeList) 1169: */ 1170: AttributeList setAttributes(ObjectName name, AttributeList attributes) 1171: throws InstanceNotFoundException, ReflectionException; 1172: 1173: /** 1174: * Unregisters the specified management bean. Following this operation, 1175: * the bean instance is no longer accessible from the server via this 1176: * name. Prior to unregistering the bean, the 1177: * {@link MBeanRegistration#preDeregister()} method will be called if 1178: * the bean implements the {@link MBeanRegistration} interface. 1179: * 1180: * @param name the name of the management bean. 1181: * @throws InstanceNotFoundException if the bean can not be found. 1182: * @throws MBeanRegistrationException if an exception occurs in 1183: * calling the preDeregister 1184: * method. 1185: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1186: * is thrown by the server due to a 1187: * <code>null</code> bean name or a 1188: * request being made to unregister the 1189: * {@link MBeanServerDelegate} bean. 1190: * @throws SecurityException if a security manager exists and the 1191: * caller's permissions don't imply {@link 1192: * MBeanPermission(String,String,ObjectName,String) 1193: * <code>MBeanPermission(className, null, name, 1194: * "unregisterMBean")</code>}. 1195: */ 1196: void unregisterMBean(ObjectName name) 1197: throws InstanceNotFoundException, MBeanRegistrationException; 1198: 1199: }