001 /* MBeanServer.java -- Represents a management server. 002 Copyright (C) 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package javax.management; 039 040 import java.io.ObjectInputStream; 041 042 import java.util.Set; 043 044 import javax.management.loading.ClassLoaderRepository; 045 046 /** 047 * <p> 048 * This interface represents a server for management beans, 049 * providing facilities for the creation, registration and 050 * removal of such beans. This interface is central to the 051 * Java management architecture. Users do not usually implement 052 * this class. Instead, implementations of this class 053 * may be obtained using an {@link MBeanServerFactory}. 054 * </p> 055 * <p> 056 * Registering a bean with the server makes its attributes and 057 * operations accessible via the server. Only JMX compliant 058 * beans may be registered with the server. When a bean 059 * is registered or unregistered, an {@link MBeanServerNotification} 060 * is emitted by the server's {@link MBeanServerDelegate}. 061 * Listeners may be registered with this bean in order to 062 * obtain such notifications. It has the {@link ObjectName} 063 * <code>JMImplementation:type=MBeanServerDelegate</code>. 064 * </p> 065 * <p> 066 * Security checks are applied on the methods of the server, 067 * as detailed below, if it is obtained using the 068 * {@link MBeanServerFactory#createMBeanServer()} or 069 * {@link MBeanServerFactory#newMBeanServer()} methods and 070 * {@link System.getSecurityManager()} returns a non-<code>null</code> 071 * value. If a check fails, a {@link SecurityException} 072 * is thrown. Note than the class name used in the exception 073 * is that of the bean, and thus, as a result, an 074 * {@link InstanceNotFoundException} 075 * precludes these security checks, due to the class name 076 * that would be used in the exception being unavailable. 077 * </p> 078 * 079 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 080 * @since 1.5 081 */ 082 public interface MBeanServer 083 extends MBeanServerConnection 084 { 085 086 /** 087 * Registers the supplied listener with the specified management 088 * bean. Notifications emitted by the management bean are forwarded 089 * to the listener via the server, which will convert any MBean 090 * references in the source to portable {@link ObjectName} 091 * instances. The notification is otherwise unchanged. 092 * 093 * @param name the name of the management bean with which the listener 094 * should be registered. 095 * @param listener the listener which will handle notifications from 096 * the bean. 097 * @param filter the filter to apply to incoming notifications, or 098 * <code>null</code> if no filtering should be applied. 099 * @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 }