| Frames | No Frames |
1: /* RMIConnection.java -- RMI object representing a MBean server connection. 2: Copyright (C) 2007, 2008 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.remote.rmi; 39: 40: import java.io.Closeable; 41: import java.io.IOException; 42: 43: import java.rmi.MarshalledObject; 44: import java.rmi.Remote; 45: 46: import java.util.Set; 47: 48: import javax.management.AttributeList; 49: import javax.management.AttributeNotFoundException; 50: import javax.management.InstanceAlreadyExistsException; 51: import javax.management.InstanceNotFoundException; 52: import javax.management.IntrospectionException; 53: import javax.management.InvalidAttributeValueException; 54: import javax.management.ListenerNotFoundException; 55: import javax.management.MBeanInfo; 56: import javax.management.MBeanException; 57: import javax.management.MBeanRegistrationException; 58: import javax.management.NotCompliantMBeanException; 59: import javax.management.ObjectInstance; 60: import javax.management.ObjectName; 61: import javax.management.ReflectionException; 62: 63: import javax.management.remote.NotificationResult; 64: 65: import javax.security.auth.Subject; 66: 67: /** 68: * <p> 69: * RMI interface for forwarding requests to a remote 70: * {@link javax.management.MBeanServer}. This interface 71: * parallels the {@link javax.management.MBeanServerConnection} 72: * interface, providing a way of invoking those methods using 73: * the RMI protocol. When a client wishes to call a method 74: * of an MBean server using RMI, the method is called on the stub 75: * on the client side, which serializes the object parameters 76: * and sends them to the server where they are deserialized and 77: * an implementation of this interface forwards them to the 78: * appropriate MBean server. Return values follow the same 79: * process, only in reverse. Each client obtains its own 80: * implementation of this interface from an {@link RMIServer} 81: * instance. 82: * </p> 83: * <p> 84: * Implementations of this interface do more than simply 85: * forward requests directly to the server. The arguments 86: * of the server methods are wrapped in {@link MarshalledObject} 87: * instances, so that the correct classloader can be used to 88: * deserialize the arguments. When a method is called, the 89: * implementation must first retrieve the appropriate classloader 90: * and then use it to deserialize the marshalled object. Unless 91: * explicitly specified in the documentation for the method, 92: * a parameter of the type {@link MarshalledObject} or an array 93: * of that type should not be {@code null}. 94: * </p> 95: * <p> 96: * Security is also handled by this interface, as the methods 97: * use an additional {@link javax.security.auth.Subject} parameter 98: * for role delegation. 99: * </p> 100: * 101: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 102: * @since 1.5 103: */ 104: public interface RMIConnection 105: extends Closeable, Remote 106: { 107: 108: /** 109: * Handles {@link 110: * MBeanServerConnection#addNotificationListener(ObjectName, 111: * ObjectName, NotificationFilter, Object)} by 112: * registering the supplied listener with the specified management 113: * bean. Notifications emitted by the management bean are forwarded 114: * to the listener via the server, which will convert any MBean 115: * references in the source to portable {@link ObjectName} 116: * instances. The notification is otherwise unchanged. The filter 117: * and handback object are wrapped in a {@link MarshalledObject} 118: * so that they are deserialised using the bean's classloader. 119: * 120: * @param name the name of the management bean with which the listener 121: * should be registered. 122: * @param listener the listener which will handle notifications from 123: * the bean. 124: * @param filter a wrapper containing a filter to apply to incoming 125: * notifications, or <code>null</code> if no filtering 126: * should be applied. 127: * @param passback a wrapper containing an object to be passed to the 128: * listener when a notification is emitted. 129: * @param delegationSubject a {@link javax.security.auth.Subject} instance 130: * containing the delegation principles or 131: * {@code null} if authentication is used. 132: * @throws InstanceNotFoundException if the name of the management bean 133: * could not be resolved. 134: * @throws RuntimeOperationsException if the bean associated with the given 135: * object name is not a 136: * {@link NotificationListener}. This 137: * exception wraps an 138: * {@link IllegalArgumentException}. 139: * @throws SecurityException if the client or delegated subject (if any) 140: * does not have permission to invoke this operation. 141: * @throws IOException if an I/O error occurred in communicating with 142: * the bean server. 143: * @see #removeNotificationListener(ObjectName, ObjectName, 144: * javax.security.auth.Subject) 145: * @see #removeNotificationListener(ObjectName, ObjectName, 146: * java.rmi.MarshalledObject, 147: * java.rmi.MarshalledObject, 148: * javax.security.auth.Subject) 149: * @see #removeNotificationListeners(ObjectName, Integer[], 150: * javax.security.auth.Subject) 151: * @see NotificationBroadcaster#addNotificationListener(NotificationListener, 152: * NotificationFilter, 153: * Object) 154: */ 155: @SuppressWarnings("rawtypes") 156: void addNotificationListener(ObjectName name, ObjectName listener, 157: MarshalledObject filter, MarshalledObject passback, 158: Subject delegationSubject) 159: throws InstanceNotFoundException, IOException; 160: 161: /** 162: * Handles {@link 163: * MBeanServerConnection#addNotificationListener(ObjectName, 164: * NotificationListener, NotificationFilter, Object)} by 165: * registering for notifications from the specified management 166: * beans. The array of filters is assumed to be aligned with 167: * the array of bean names, so that the notifications from each 168: * bean are matched against the appropriate filter (or left as 169: * is if the filter is {@code null}. Notifications emitted by 170: * the management beans are forwarded to a local listener created 171: * by this method, via the server, which converts any MBean 172: * references in the source to portable {@link ObjectName} 173: * instances. The notification is otherwise unchanged. 174: * </p> 175: * <p> 176: * This local listener buffers the notifications for retrieval by 177: * {@link #fetchNotifications(long,int,long). This method returns 178: * an array of listener identifiers which aligns with the supplied 179: * array of beans so that the appropriate listener can be identified 180: * by the client, which retains its own listener and handback object. 181: * The filters are wrapped in {@link MarshalledObject}s so that they are 182: * deserialised using the bean's classloader. 183: * </p> 184: * 185: * @param names the names of the management bean whose notifications 186: * should be recorded. 187: * @param filters an array of wrappers containing filters to apply to 188: * incoming notifications. An element may be <code>null</code> 189: * if no filtering should be applied to a bean's notifications. 190: * @param delegationSubjects an array of {@link javax.security.auth.Subject} 191: * instances containing the delegation principles for 192: * each listener. An element may be {@code null} if 193: * authentication is used instead, or the entire 194: * argument itself may be {@code null}. In the latter 195: * case, this is treated as an array of {@code null} 196: * values. 197: * @return an array of integers which act as listener identifiers, so that 198: * notifications retrieved from {@link #fetchNotifications(long,int,long) 199: * can be matched to the beans they were emitted from. The array is 200: * aligned against the array of beans supplied to this methods, so that 201: * the identifier in position 0 represents the bean in position 0 of the 202: * input array. 203: * @throws IllegalArgumentException if the {@code names} or {@code filters} array 204: * is {@code null}, the {@code names} array contains 205: * a {@code null} value or the three arrays are not 206: * of the same size. 207: * @throws ClassCastException if an element of the {@code filters} array unmarshalls 208: * as a non-null object that is not a {@link NotificationFilter}. 209: * @throws InstanceNotFoundException if the name of one of the management beans 210: * could not be resolved. 211: * @throws SecurityException if, for one of the beans, the client or delegated subject 212: * (if any) does not have permission to invoke this operation. 213: * @throws IOException if an I/O error occurred in communicating with 214: * the bean server. 215: * @see #removeNotificationListener(ObjectName, ObjectName, 216: * javax.security.auth.Subject) 217: * @see #removeNotificationListener(ObjectName, ObjectName, 218: * java.rmi.MarshalledObject, 219: * java.rmi.MarshalledObject, 220: * javax.security.auth.Subject) 221: * @see #removeNotificationListeners(ObjectName, Integer[], 222: * javax.security.auth.Subject) 223: * @see NotificationBroadcaster#addNotificationListener(NotificationListener, 224: * NotificationFilter, 225: * Object) 226: */ 227: @SuppressWarnings("rawtypes") 228: Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, 229: Subject[] delegationSubjects) 230: throws InstanceNotFoundException, IOException; 231: 232: /** 233: * Closes the connection and unexports the RMI object implementing this 234: * interface. Following this call, future method calls to this instance 235: * will fail. 236: * 237: * @throws IOException if there is an I/O error in transmitting the close 238: * request via RMI, closing the connection, or unexporting 239: * the RMI object. 240: */ 241: void close() 242: throws IOException; 243: 244: /** 245: * <p> 246: * Handles {@link 247: * MBeanServerConnection#createMBean(String, ObjectName, 248: * Object[], String[])}. The array of parameters is wrapped in 249: * a {@link MarshalledObject} so that it is deserialised using the 250: * bean's classloader. 251: * </p> 252: * <p> 253: * Instantiates a new instance of the specified management bean 254: * using the given constructor and registers it with the server 255: * under the supplied name. The class is loaded using the 256: * {@link javax.management.loading.ClassLoaderRepository default 257: * loader repository} of the server. 258: * </p> 259: * <p> 260: * If the name supplied is <code>null</code>, then the bean is 261: * expected to implement the {@link MBeanRegistration} interface. 262: * The {@link MBeanRegistration#preRegister preRegister} method 263: * of this interface will be used to obtain the name in this case. 264: * </p> 265: * 266: * @param className the class of the management bean, of which 267: * an instance should be created. 268: * @param name the name to register the new bean with. This may 269: * be <code>null</code>. 270: * @param params the parameters for the bean's constructor, encapsulated 271: * in a {@link MarshalledObject}. If this parameter is 272: * <code>null</code>, it will be judged equivalent to an 273: * empty array. 274: * @param sig the signature of the constructor to use. If this parameter 275: * is <code>null</code>, it will be judged equivalent to an 276: * empty array. 277: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 278: * containing the delegation principles. This may be 279: * {@code null} is authentication is used instead. 280: * @return an {@link ObjectInstance} containing the {@link ObjectName} 281: * and Java class name of the created instance. 282: * @throws ReflectionException if an exception occurs in creating 283: * an instance of the bean. 284: * @throws InstanceAlreadyExistsException if a matching instance 285: * already exists. 286: * @throws MBeanRegistrationException if an exception occurs in 287: * calling the preRegister 288: * method. 289: * @throws MBeanException if the bean's constructor throws an exception. 290: * @throws NotCompliantMBeanException if the created bean is not 291: * compliant with the JMX specification. 292: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 293: * is thrown by the server due to a 294: * <code>null</code> class name or object 295: * name or if the object name is a pattern. 296: * @throws SecurityException if the client or delegated subject (if any) does 297: * not have permission to invoke this operation. 298: * @throws IOException if an I/O error occurred in communicating with 299: * the bean server. 300: */ 301: @SuppressWarnings("rawtypes") 302: ObjectInstance createMBean(String className, ObjectName name, 303: MarshalledObject params, String[] sig, 304: Subject delegationSubject) 305: throws ReflectionException, InstanceAlreadyExistsException, 306: MBeanRegistrationException, MBeanException, 307: NotCompliantMBeanException, IOException; 308: 309: /** 310: * <p> 311: * Handles {@link 312: * MBeanServerConnection#createMBean(String, ObjectName, 313: * ObjectName, Object[], String[])}. The array of parameters is 314: * wrapped in a {@link MarshalledObject} so that it is deserialised 315: * using the bean's classloader. 316: * </p> 317: * <p> 318: * Instantiates a new instance of the specified management bean 319: * using the given constructor and registers it with the server 320: * under the supplied name. The class is loaded using the 321: * given class loader. If this argument is <code>null</code>, 322: * then the same class loader as was used to load the server 323: * is used. 324: * </p> 325: * <p> 326: * If the name supplied is <code>null</code>, then the bean is 327: * expected to implement the {@link MBeanRegistration} interface. 328: * The {@link MBeanRegistration#preRegister preRegister} method 329: * of this interface will be used to obtain the name in this case. 330: * </p> 331: * 332: * @param className the class of the management bean, of which 333: * an instance should be created. 334: * @param name the name to register the new bean with. This may 335: * be <code>null</code>. 336: * @param loaderName the name of the class loader. 337: * @param params the parameters for the bean's constructor, encapsulated 338: * in a {@link MarshalledObject}. If this parameter is 339: * <code>null</code>, it will be judged equivalent to an 340: * empty array. 341: * @param sig the signature of the constructor to use. If this parameter 342: * is <code>null</code>, it will be judged equivalent to an 343: * empty array. 344: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 345: * containing the delegation principles. This may be 346: * {@code null} is authentication is used instead. 347: * @return an {@link ObjectInstance} containing the {@link ObjectName} 348: * and Java class name of the created instance. 349: * @throws ReflectionException if an exception occurs in creating 350: * an instance of the bean. 351: * @throws InstanceAlreadyExistsException if a matching instance 352: * already exists. 353: * @throws MBeanRegistrationException if an exception occurs in 354: * calling the preRegister 355: * method. 356: * @throws MBeanException if the bean's constructor throws an exception. 357: * @throws NotCompliantMBeanException if the created bean is not 358: * compliant with the JMX specification. 359: * @throws InstanceNotFoundException if the specified class loader is not 360: * registered with the server. 361: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 362: * is thrown by the server due to a 363: * <code>null</code> class name or object 364: * name or if the object name is a pattern. 365: * @throws SecurityException if the client or delegated subject (if any) does 366: * not have permission to invoke this operation. 367: * @throws IOException if an I/O error occurred in communicating with 368: * the bean server. 369: */ 370: @SuppressWarnings("rawtypes") 371: ObjectInstance createMBean(String className, ObjectName name, 372: ObjectName loaderName, MarshalledObject params, 373: String[] sig, Subject delegationSubject) 374: throws ReflectionException, InstanceAlreadyExistsException, 375: MBeanRegistrationException, MBeanException, 376: NotCompliantMBeanException, InstanceNotFoundException, 377: IOException; 378: 379: /** 380: * <p> 381: * Handles {@link 382: * MBeanServerConnection#createMBean(String, ObjectName, 383: * ObjectName)} by instantiating a new instance of the specified 384: * management bean using the default constructor and registering 385: * it with the server under the supplied name. The class is loaded 386: * using the given class loader. If this argument is <code>null</code>, 387: * then the same class loader as was used to load the server 388: * is used. 389: * </p> 390: * <p> 391: * If the name supplied is <code>null</code>, then the bean is 392: * expected to implement the {@link MBeanRegistration} interface. 393: * The {@link MBeanRegistration#preRegister preRegister} method 394: * of this interface will be used to obtain the name in this case. 395: * </p> 396: * <p> 397: * This method is equivalent to calling {@link 398: * #createMBean(String, ObjectName, ObjectName, Object[], String) 399: * <code>createMBean(className, name, loaderName, (Object[]) null, 400: * (String) null)</code>} with <code>null</code> parameters 401: * and signature. 402: * </p> 403: * 404: * @param className the class of the management bean, of which 405: * an instance should be created. 406: * @param name the name to register the new bean with. This may 407: * be <code>null</code>. 408: * @param loaderName the name of the class loader. 409: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 410: * containing the delegation principles. This may be 411: * {@code null} is authentication is used instead. 412: * @return an {@link ObjectInstance} containing the {@link ObjectName} 413: * and Java class name of the created instance. 414: * @throws ReflectionException if an exception occurs in creating 415: * an instance of the bean. 416: * @throws InstanceAlreadyExistsException if a matching instance 417: * already exists. 418: * @throws MBeanRegistrationException if an exception occurs in 419: * calling the preRegister 420: * method. 421: * @throws MBeanException if the bean's constructor throws an exception. 422: * @throws NotCompliantMBeanException if the created bean is not 423: * compliant with the JMX specification. 424: * @throws InstanceNotFoundException if the specified class loader is not 425: * registered with the server. 426: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 427: * is thrown by the server due to a 428: * <code>null</code> class name or object 429: * name or if the object name is a pattern. 430: * @throws SecurityException if the client or delegated subject (if any) does 431: * not have permission to invoke this operation. 432: * @throws IOException if an I/O error occurred in communicating with 433: * the bean server. 434: * @see #createMBean(String, ObjectName, ObjectName, MarshalledObject, 435: * String[], Subject) 436: */ 437: ObjectInstance createMBean(String className, ObjectName name, 438: ObjectName loaderName, Subject delegationSubject) 439: throws ReflectionException, InstanceAlreadyExistsException, 440: MBeanRegistrationException, MBeanException, 441: NotCompliantMBeanException, InstanceNotFoundException, 442: IOException; 443: 444: /** 445: * <p> 446: * Handles {@link 447: * MBeanServerConnection#createMBean(String, ObjectName)} by 448: * instantiating a new instance of the specified management bean 449: * using the default constructor and registering it with the server 450: * under the supplied name. The class is loaded using the 451: * {@link javax.management.loading.ClassLoaderRepository default 452: * loader repository} of the server. 453: * </p> 454: * <p> 455: * If the name supplied is <code>null</code>, then the bean is 456: * expected to implement the {@link MBeanRegistration} interface. 457: * The {@link MBeanRegistration#preRegister preRegister} method 458: * of this interface will be used to obtain the name in this case. 459: * </p> 460: * <p> 461: * This method is equivalent to calling {@link 462: * #createMBean(String, ObjectName, Object[], String[]) 463: * <code>createMBean(className, name, (Object[]) null, 464: * (String[]) null)</code>} with <code>null</code> parameters 465: * and signature. 466: * </p> 467: * 468: * @param className the class of the management bean, of which 469: * an instance should be created. 470: * @param name the name to register the new bean with. This may 471: * be <code>null</code>. 472: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 473: * containing the delegation principles. This may be 474: * {@code null} is authentication is used instead. 475: * @return an {@link ObjectInstance} containing the {@link ObjectName} 476: * and Java class name of the created instance. 477: * @throws ReflectionException if an exception occurs in creating 478: * an instance of the bean. 479: * @throws InstanceAlreadyExistsException if a matching instance 480: * already exists. 481: * @throws MBeanRegistrationException if an exception occurs in 482: * calling the preRegister 483: * method. 484: * @throws MBeanException if the bean's constructor throws an exception. 485: * @throws NotCompliantMBeanException if the created bean is not 486: * compliant with the JMX specification. 487: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 488: * is thrown by the server due to a 489: * <code>null</code> class name or object 490: * name or if the object name is a pattern. 491: * @throws SecurityException if the client or delegated subject (if any) does 492: * not have permission to invoke this operation. 493: * @throws IOException if an I/O error occurred in communicating with 494: * the bean server. 495: * @see #createMBean(String, ObjectName, MarshalledObject, String[], Subject) 496: */ 497: ObjectInstance createMBean(String className, ObjectName name, 498: Subject delegationSubject) 499: throws ReflectionException, InstanceAlreadyExistsException, 500: MBeanRegistrationException, MBeanException, 501: NotCompliantMBeanException, IOException; 502: 503: /** 504: * <p> 505: * Retrieves any waiting notifications from the server. When notifications 506: * are requested using the {@link #addNotificationListeners(ObjectName[], 507: * MarshalledObject[], Subject[])} method, the server sets up an internal 508: * listener to receive notifications from the bean and buffer them. When 509: * this method is called, these buffered notifications can be retrieved. 510: * </p> 511: * <p> 512: * The blocking behaviour of this method depends on the timeout value specified. 513: * If there are no waiting notifications in the buffer, a value of 0 will cause 514: * the method to return immediately. Conversely, if the value is 515: * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification 516: * arrives. For any other value, it waits until a notification arrives or the 517: * number of milliseconds specified by the timeout value is exceeded. The 518: * behaviour for a negative timeout value is undefined. 519: * </p> 520: * <p> 521: * For a notification to be returned, the following criteria must be fulfilled: 522: * </p> 523: * <ul> 524: * <li>the client must have previously requested notifications from at least 525: * one bean</li> 526: * <li>a bean from which notifications have been requested must have emitted 527: * a notification since the last call to this method</li> 528: * <li>the emitted notification must pass through any filters established 529: * when notifications were requested</li> 530: * <li>the sequence number of the notification must be greater than or equal 531: * to the specified sequence number (if non-negative)</li> 532: * </ul> 533: * 534: * @param sequenceNumber the sequence number of each notification returned 535: * must be greater than or equal to this value. If 536: * the number is negative, this is interpreted as 537: * meaning the sequence number of the next notification 538: * and so all notifications are allowed through. 539: * @param maxNotifications the maximum number of notifications to return. 540: * This does not include any duplicates so the 541: * number of actual notifications returned may 542: * be larger. 543: * @param timeout the number of milliseconds to wait for a notification 544: * if the buffer is empty. <code>0</code> causes the 545: * method to return immediately even if there are no 546: * notifications available (non-blocking behaviour) while 547: * a value of {@link Long#MAX_VALUE} causes it to wait 548: * indefinitely (blocking behaviour). The response to 549: * a negative value is undefined. 550: * @return a {@link NotificationResult} object containing the buffered 551: * notifications. 552: * @throws IOException if an I/O error occurs. 553: */ 554: NotificationResult fetchNotifications(long sequenceNumber, 555: int maxNotifications, 556: long timeout) 557: throws IOException; 558: 559: /** 560: * Handles {@link 561: * MBeanServerConnection#getAttribute(ObjectName, String)}, 562: * returning the value of the supplied attribute from the specified 563: * management bean. 564: * 565: * @param bean the bean to retrieve the value from. 566: * @param name the name of the attribute to retrieve. 567: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 568: * containing the delegation principles. This may be 569: * {@code null} is authentication is used instead. 570: * @return the value of the attribute. 571: * @throws AttributeNotFoundException if the attribute could not be 572: * accessed from the bean. 573: * @throws MBeanException if the management bean's accessor throws 574: * an exception. 575: * @throws InstanceNotFoundException if the bean can not be found. 576: * @throws ReflectionException if an exception was thrown in trying 577: * to invoke the bean's accessor. 578: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 579: * is thrown by the server due to a 580: * <code>null</code> bean or attribute 581: * name. 582: * @throws SecurityException if the client or delegated subject (if any) does 583: * not have permission to invoke this operation. 584: * @throws IOException if an I/O error occurred in communicating with 585: * the bean server. 586: * @see DynamicMBean#getAttribute(String) 587: */ 588: Object getAttribute(ObjectName bean, String name, Subject delegationSubject) 589: throws MBeanException, AttributeNotFoundException, 590: InstanceNotFoundException, ReflectionException, 591: IOException; 592: 593: /** 594: * Handles {@link 595: * MBeanServerConnection#getAttribute(ObjectName, String)}, 596: * returning the values of the named attributes from the specified 597: * management bean. 598: * 599: * @param bean the bean to retrieve the value from. 600: * @param names the names of the attributes to retrieve. 601: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 602: * containing the delegation principles. This may be 603: * {@code null} is authentication is used instead. 604: * @return the values of the attributes. 605: * @throws InstanceNotFoundException if the bean can not be found. 606: * @throws ReflectionException if an exception was thrown in trying 607: * to invoke the bean's accessor. 608: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 609: * is thrown by the server due to a 610: * <code>null</code> bean or attribute 611: * name. 612: * @throws SecurityException if the client or delegated subject (if any) does 613: * not have permission to invoke this operation. 614: * @throws IOException if an I/O error occurred in communicating with 615: * the bean server. 616: * @see DynamicMBean#getAttributes(String[]) 617: */ 618: AttributeList getAttributes(ObjectName bean, String[] names, 619: Subject delegationSubject) 620: throws InstanceNotFoundException, ReflectionException, 621: IOException; 622: 623: /** 624: * Returns the unique identifier for this connection to the RMI 625: * server. 626: * 627: * @return the connection ID. 628: * @throws IOException if an I/O error occurred. 629: */ 630: String getConnectionId() 631: throws IOException; 632: 633: /** 634: * Handles {@link 635: * MBeanServerConnection#getDefaultDomain()} by returning the default 636: * domain this server applies to beans that have no specified domain. 637: * 638: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 639: * containing the delegation principles. This may be 640: * {@code null} is authentication is used instead. 641: * @return the default domain. 642: * @throws SecurityException if the client or delegated subject (if any) does 643: * not have permission to invoke this operation. 644: * @throws IOException if an I/O error occurred in communicating with 645: * the bean server. 646: */ 647: String getDefaultDomain(Subject delegationSubject) 648: throws IOException; 649: 650: /** 651: * Handles {@link 652: * MBeanServerConnection#getDomains()} by returning an array 653: * containing all the domains used by beans registered with 654: * this server. The ordering of the array is undefined. 655: * 656: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 657: * containing the delegation principles. This may be 658: * {@code null} is authentication is used instead. 659: * @return the list of domains. 660: * @throws SecurityException if the client or delegated subject (if any) does 661: * not have permission to invoke this operation. 662: * @throws IOException if an I/O error occurred in communicating with 663: * the bean server. 664: * @see ObjectName#getDomain() 665: */ 666: String[] getDomains(Subject delegationSubject) 667: throws IOException; 668: 669: /** 670: * Handles {@link 671: * MBeanServerConnection#getMBeanCount()} by returning the number of 672: * management beans registered with this server. 673: * 674: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 675: * containing the delegation principles. This may be 676: * {@code null} is authentication is used instead. 677: * @return the number of registered beans. 678: * @throws SecurityException if the client or delegated subject (if any) does 679: * not have permission to invoke this operation. 680: * @throws IOException if an I/O error occurred in communicating with 681: * the bean server. 682: */ 683: Integer getMBeanCount(Subject delegationSubject) 684: throws IOException; 685: 686: /** 687: * Handles {@link 688: * MBeanServerConnection#getMBeanInfo(ObjectName)} by returning 689: * information on the given management bean. 690: * 691: * @param name the name of the management bean. 692: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 693: * containing the delegation principles. This may be 694: * {@code null} is authentication is used instead. 695: * @return an instance of {@link MBeanInfo} for the bean. 696: * @throws IntrospectionException if an exception occurs in examining 697: * the bean. 698: * @throws InstanceNotFoundException if the bean can not be found. 699: * @throws ReflectionException if an exception occurs when trying 700: * to invoke {@link DynamicMBean#getMBeanInfo()} 701: * on the bean. 702: * @throws SecurityException if the client or delegated subject (if any) does 703: * not have permission to invoke this operation. 704: * @throws IOException if an I/O error occurred in communicating with 705: * the bean server. 706: * @see DynamicMBean#getMBeanInfo() 707: */ 708: MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject) 709: throws InstanceNotFoundException, IntrospectionException, 710: ReflectionException, IOException; 711: 712: /** 713: * Handles {@link 714: * MBeanServerConnection#getObjectInstance(ObjectName)} by returning 715: * the {@link ObjectInstance} created for the specified management 716: * bean on registration. 717: * 718: * @param name the name of the bean. 719: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 720: * containing the delegation principles. This may be 721: * {@code null} is authentication is used instead. 722: * @return the corresponding {@link ObjectInstance} instance. 723: * @throws InstanceNotFoundException if the bean can not be found. 724: * @throws SecurityException if the client or delegated subject (if any) does 725: * not have permission to invoke this operation. 726: * @throws IOException if an I/O error occurred in communicating with 727: * the bean server. 728: * @see #createMBean(String, ObjectName, Subject) 729: */ 730: ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject) 731: throws InstanceNotFoundException, IOException; 732: 733: /** 734: * <p> 735: * Handles {@link 736: * MBeanServerConnection#invoke(ObjectName, String, Object[], 737: * String[])}. The array of parameters is wrapped in a 738: * {@link MarshalledObject} so that it is deserialised 739: * using the bean's classloader. 740: * </p> 741: * <p> 742: * Invokes the supplied operation on the specified management 743: * bean. The class objects specified in the signature are loaded 744: * using the same class loader as was used for the management bean. 745: * 746: * @param bean the management bean whose operation should be invoked. 747: * @param name the name of the operation to invoke. 748: * @param params the parameters for the bean's constructor, encapsulated 749: * in a {@link MarshalledObject}. If this parameter is 750: * <code>null</code>, it will be judged equivalent to an 751: * empty array. 752: * @param sig the signature of the constructor to use. If this parameter 753: * is <code>null</code>, it will be judged equivalent to an 754: * empty array. The class objects will be loaded using the 755: * bean's classloader. 756: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 757: * containing the delegation principles. This may be 758: * {@code null} is authentication is used instead. 759: * @return the return value of the method. 760: * @throws InstanceNotFoundException if the bean can not be found. 761: * @throws MBeanException if the method invoked throws an exception. 762: * @throws ReflectionException if an exception is thrown in invoking the 763: * method. 764: * @throws SecurityException if the client or delegated subject (if any) does 765: * not have permission to invoke this operation. 766: * @throws IOException if an I/O error occurred in communicating with 767: * the bean server. 768: * @see DynamicMBean#invoke(String, Object[], String[]) 769: */ 770: @SuppressWarnings("rawtypes") 771: Object invoke(ObjectName bean, String name, MarshalledObject params, 772: String[] sig, Subject delegationSubject) 773: throws InstanceNotFoundException, MBeanException, 774: ReflectionException, IOException; 775: 776: /** 777: * <p> 778: * Handles {@link 779: * MBeanServerConnection#isInstanceOf(ObjectName, String) by 780: * returning true if the specified management bean is an instance 781: * of the supplied class. 782: * </p> 783: * <p> 784: * A bean, B, is an instance of a class, C, if either of the following 785: * conditions holds: 786: * </p> 787: * <ul> 788: * <li>The class name in B's {@link MBeanInfo} is equal to the supplied 789: * name.</li> 790: * <li>Both the class of B and C were loaded by the same class loader, 791: * and B is assignable to C.</li> 792: * </ul> 793: * 794: * @param name the name of the management bean. 795: * @param className the name of the class to test if <code>name</code> is 796: * an instance of. 797: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 798: * containing the delegation principles. This may be 799: * {@code null} is authentication is used instead. 800: * @return true if either B is directly an instance of the named class, 801: * or B is assignable to the class, given that both it and B's 802: * current class were loaded using the same class loader. 803: * @throws InstanceNotFoundException if the bean can not be found. 804: * @throws SecurityException if the client or delegated subject (if any) does 805: * not have permission to invoke this operation. 806: * @throws IOException if an I/O error occurred in communicating with 807: * the bean server. 808: */ 809: boolean isInstanceOf(ObjectName name, String className, 810: Subject delegationSubject) 811: throws InstanceNotFoundException, IOException; 812: 813: /** 814: * Handles {@link 815: * MBeanServerConnection#isRegistered(ObjectName) by returning 816: * true if the specified management bean is registered with 817: * the server. 818: * 819: * @param name the name of the management bean. 820: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 821: * containing the delegation principles. This may be 822: * {@code null} is authentication is used instead. 823: * @return true if the bean is registered. 824: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 825: * is thrown by the server due to a 826: * <code>null</code> bean name. 827: * @throws SecurityException if the client or delegated subject (if any) does 828: * not have permission to invoke this operation. 829: * @throws IOException if an I/O error occurred in communicating with 830: * the bean server. 831: */ 832: boolean isRegistered(ObjectName name, Subject delegationSubject) 833: throws IOException; 834: 835: /** 836: * <p> 837: * Handles {@link 838: * MBeanServerConnection#queryMBeans(ObjectName, QueryExp)}. 839: * The query expression is wrapped in a {@link MarshalledObject} 840: * so that it is deserialised using the bean's classloader. 841: * </p> 842: * <p> 843: * Returns a set of {@link ObjectInstance}s matching the specified 844: * criteria. The full set of beans registered with the server 845: * are passed through two filters: 846: * </p> 847: * <ol> 848: * <li>Pattern matching is performed using the supplied 849: * {@link ObjectName}.</li> 850: * <li>The supplied query expression is applied.</li> 851: * </ol> 852: * <p> 853: * If both the object name and the query expression are <code>null</code>, 854: * or the object name has no domain and no key properties, 855: * no filtering will be performed and all beans are returned. 856: * </p> 857: * 858: * @param name an {@link ObjectName} to use as a filter. 859: * @param query a query expression to apply to each of the beans that match 860: * the given object name, encapsulated in a 861: * {@link MarshalledObject}. If a <code>null</code> value is 862: * encapsulated, then the beans will only be filtered using 863: * pattern matching on the supplied {@link ObjectName}. 864: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 865: * containing the delegation principles. This may be 866: * {@code null} is authentication is used instead. 867: * @return a set of {@link ObjectInstance}s matching the filtered beans. 868: * This is empty if no beans survived the filters. 869: * @throws IOException if an I/O error occurred in communicating with 870: * the bean server. 871: * @throws SecurityException if the client or delegated subject (if any) does 872: * not have permission to invoke this operation. 873: */ 874: @SuppressWarnings("rawtypes") 875: Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query, 876: Subject delegationSubject) 877: throws IOException; 878: 879: /** 880: * <p> 881: * Handles {@link 882: * MBeanServerConnection#queryNames(ObjectName, QueryExp)}. 883: * The query expression is wrapped in a {@link MarshalledObject} 884: * so that it is deserialised using the bean's classloader. 885: * </p> 886: * <p> 887: * Returns a set of {@link ObjectName}s matching the specified 888: * criteria. The full set of beans registered with the server 889: * are passed through two filters: 890: * </p> 891: * <ol> 892: * <li>Pattern matching is performed using the supplied 893: * {@link ObjectName}.</li> 894: * <li>The supplied query expression is applied.</li> 895: * </ol> 896: * <p> 897: * If both the object name and the query expression are <code>null</code>, 898: * or the object name has no domain and no key properties, 899: * no filtering will be performed and all beans are returned. 900: * </p> 901: * 902: * @param name an {@link ObjectName} to use as a filter. 903: * @param query a query expression to apply to each of the beans that match 904: * the given object name, encapsulated in a 905: * {@link MarshalledObject}. If a <code>null</code> value is 906: * encapsulated, then the beans will only be filtered using 907: * pattern matching on the supplied {@link ObjectName}. 908: * @param delegationSubject an instance of {@link javax.security.auth.Subject} 909: * containing the delegation principles. This may be 910: * {@code null} is authentication is used instead. 911: * @return a set of {@link ObjectName}s matching the filtered beans. 912: * @throws SecurityException if the client or delegated subject (if any) does 913: * not have permission to invoke this operation. 914: * @throws IOException if an I/O error occurred in communicating with 915: * the bean server. 916: */ 917: @SuppressWarnings("rawtypes") 918: Set<ObjectName> queryNames(ObjectName name, MarshalledObject query, 919: Subject delegationSubject) 920: throws IOException; 921: 922: /** 923: * <p> 924: * Handles {@link 925: * MBeanServerConnection#removeNotificationListener(ObjectName, 926: * ObjectName, NotificationFilter, Object)}. Both the filter and 927: * the handback object are wrapped in a {@link MarshalledObject} 928: * so that they are deserialised using the bean's classloader. 929: * </p> 930: * <p> 931: * Removes the specified listener from the list of recipients 932: * of notifications from the supplied bean. Only the first instance with 933: * the supplied filter and passback object is removed. 934: * <code>null</code> is used as a valid value for these parameters, 935: * rather than as a way to remove all registration instances for 936: * the specified listener; for this behaviour instead, see 937: * {@link #removeNotificationListener(ObjectName, NotificationListener)}. 938: * </p> 939: * 940: * @param name the name of the management bean from which the 941: * listener should be removed. 942: * @param listener the listener to remove. 943: * @param filter a wrapper containing the filter of the listener 944: * to remove. 945: * @param passback a wrapper containing the handback object of the 946: * listener to remove. 947: * @param delegationSubject a {@link javax.security.auth.Subject} instance 948: * containing the delegation principles or 949: * {@code null} if authentication is used. 950: * @throws InstanceNotFoundException if the bean can not be found. 951: * @throws ListenerNotFoundException if the specified listener 952: * is not registered with the bean. 953: * @throws SecurityException if the client or delegated subject (if any) does 954: * not have permission to invoke this operation. 955: * @throws IOException if an I/O error occurred in communicating with 956: * the bean server. 957: * @see #addNotificationListener(ObjectName, NotificationListener, 958: * MarshalledObject, MarshalledObject, Subject) 959: * @see NotificationEmitter#removeNotificationListener(NotificationListener, 960: * NotificationFilter, 961: * Object) 962: */ 963: @SuppressWarnings("rawtypes") 964: void removeNotificationListener(ObjectName name, 965: ObjectName listener, 966: MarshalledObject filter, 967: MarshalledObject passback, 968: Subject delegationSubject) 969: throws InstanceNotFoundException, ListenerNotFoundException, 970: IOException; 971: 972: /** 973: * Handles {@link 974: * MBeanServerConnection#removeNotificationListener(ObjectName, 975: * ObjectName)} by removing the specified listener from the list 976: * of recipients of notifications from the supplied bean. This 977: * includes all combinations of filters and passback objects 978: * registered for this listener. For more specific removal of 979: * listeners, see {@link #removeNotificationListener(ObjectName, 980: * ObjectName,MarshalledObject,MarshalledObject,Subject)} 981: * 982: * @param name the name of the management bean from which the 983: * listener should be removed. 984: * @param listener the name of the listener to remove. 985: * @param delegationSubject a {@link javax.security.auth.Subject} instance 986: * containing the delegation principles or 987: * {@code null} if authentication is used. 988: * @throws InstanceNotFoundException if a name doesn't match a registered 989: * bean. 990: * @throws ListenerNotFoundException if the specified listener 991: * is not registered with the bean. 992: * @throws SecurityException if the client or delegated subject (if any) does 993: * not have permission to invoke this operation. 994: * @throws IOException if an I/O error occurred in communicating with 995: * the bean server. 996: * @see #addNotificationListener(ObjectName, NotificationListener, 997: * MarshalledObject, MarshalledObject, Subject) 998: * @see NotificationBroadcaster#removeNotificationListener(NotificationListener) 999: */ 1000: void removeNotificationListener(ObjectName name, ObjectName listener, 1001: Subject delegationSubject) 1002: throws InstanceNotFoundException, ListenerNotFoundException, 1003: IOException; 1004: 1005: /** 1006: * Removes one or more {@link NotificationListener}s from the specified 1007: * management bean. This method corresponds to 1008: * {@link #addNotificationListeners(ObjectName[], MarshalledObject[], 1009: * Subject)} and provides a different way of handling 1010: * MBeanServerConnection#removeNotificationListener(ObjectName, 1011: * ObjectName)} and 1012: * {@link MBeanServerConnection#removeNotificationListener(ObjectName, 1013: * ObjectName, NotificationFilter, Object)} by using the integer 1014: * identifiers provided by the 1015: * {@link #addNotificationListeners(ObjectName[], MarshalledObject[], 1016: * Subject)} method to select the listeners to remove. 1017: * 1018: * @param name the name of the management bean from which the 1019: * listeners should be removed. 1020: * @param listenerIds the identifiers of the listeners to remove. 1021: * @param delegationSubject a {@link javax.security.auth.Subject} instance 1022: * containing the delegation principles or 1023: * {@code null} if authentication is used. 1024: * @throws InstanceNotFoundException if a name doesn't match a registered 1025: * bean. 1026: * @throws ListenerNotFoundException if the specified listener 1027: * is not registered with the bean. 1028: * @throws SecurityException if the client or delegated subject (if any) does 1029: * not have permission to invoke this operation. 1030: * @throws IOException if an I/O error occurred in communicating with 1031: * the bean server. 1032: * @throws IllegalArgumentException if either <code>name</code>, 1033: * <code>listenerIds</code> or an element 1034: * of <code>listenerIds</code> 1035: * is <code>null</code>. 1036: * @see #addNotificationListeners(ObjectName[], MarshalledObject[], Subject) 1037: */ 1038: void removeNotificationListeners(ObjectName name, Integer[] listenerIds, 1039: Subject delegationSubject) 1040: throws InstanceNotFoundException, ListenerNotFoundException, 1041: IOException; 1042: 1043: /** 1044: * Handles {@link 1045: * MBeanServerConnection#setAttribute(ObjectName, Attribute)} 1046: * by setting the value of the specified attribute of the supplied 1047: * management bean. The attribute is wrapped in a 1048: * {@link MarshalledObject} so that it is deserialised using the 1049: * bean's classloader. 1050: * 1051: * @param name the name of the management bean. 1052: * @param attribute the attribute to set, encapsulated in a 1053: * {@link MarshalledObject}. 1054: * @param delegationSubject a {@link javax.security.auth.Subject} instance 1055: * containing the delegation principles or 1056: * {@code null} if authentication is used. 1057: * @throws InstanceNotFoundException if the bean can not be found. 1058: * @throws AttributeNotFoundException if the attribute does not 1059: * correspond to an attribute 1060: * of the bean. 1061: * @throws InvalidAttributeValueException if the value is invalid 1062: * for this particular 1063: * attribute of the bean. 1064: * @throws MBeanException if setting the attribute causes 1065: * the bean to throw an exception (which 1066: * becomes the cause of this exception). 1067: * @throws ReflectionException if an exception occurred in trying 1068: * to use the reflection interface 1069: * to lookup the attribute. The 1070: * thrown exception is the cause of 1071: * this exception. 1072: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1073: * is thrown by the server due to a 1074: * <code>null</code> bean or attribute 1075: * name. 1076: * @throws SecurityException if the client or delegated subject (if any) does 1077: * not have permission to invoke this operation. 1078: * @throws IOException if an I/O error occurred in communicating with 1079: * the bean server. 1080: * @see #getAttribute(ObjectName, String, Subject) 1081: * @see javax.management.DynamicMBean#setAttribute(Attribute) 1082: */ 1083: @SuppressWarnings("rawtypes") 1084: void setAttribute(ObjectName name, MarshalledObject attribute, 1085: Subject delegationSubject) 1086: throws InstanceNotFoundException, AttributeNotFoundException, 1087: InvalidAttributeValueException, MBeanException, 1088: ReflectionException, IOException; 1089: 1090: /** 1091: * Handles {@link 1092: * MBeanServerConnection#setAttributes(ObjectName, AttributeList)} 1093: * by setting the value of each of the specified attributes 1094: * of the supplied management bean to that specified by 1095: * the {@link Attribute} object. The returned list contains 1096: * the attributes that were set and their new values. 1097: * The attribute list is wrapped in a {@link MarshalledObject} so 1098: * that it is deserialised using the bean's classloader. 1099: * 1100: * @param name the name of the management bean. 1101: * @param attributes the attributes to set, encapsulated in a 1102: * {@link MarshalledObject}. 1103: * @param delegationSubject a {@link javax.security.auth.Subject} instance 1104: * containing the delegation principles or 1105: * {@code null} if authentication is used. 1106: * @return a list of the changed attributes. 1107: * @throws InstanceNotFoundException if the bean can not be found. 1108: * @throws ReflectionException if an exception occurred in trying 1109: * to use the reflection interface 1110: * to lookup the attribute. The 1111: * thrown exception is the cause of 1112: * this exception. 1113: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1114: * is thrown by the server due to a 1115: * <code>null</code> bean or attribute 1116: * list. 1117: * @throws SecurityException if the client or delegated subject (if any) does 1118: * not have permission to invoke this operation. 1119: * @throws IOException if an I/O error occurred in communicating with 1120: * the bean server. 1121: * @see #getAttributes(ObjectName, String[]) 1122: * @see DynamicMBean#setAttributes(AttributeList) 1123: */ 1124: @SuppressWarnings("rawtypes") 1125: AttributeList setAttributes(ObjectName name, MarshalledObject attributes, 1126: Subject delegationSubject) 1127: throws InstanceNotFoundException, ReflectionException, 1128: IOException; 1129: 1130: /** 1131: * Handles {@link 1132: * MBeanServerConnection#unregisterMBean(ObjectName)} by unregistering 1133: * the specified management bean. Following this operation, 1134: * the bean instance is no longer accessible from the server via this 1135: * name. Prior to unregistering the bean, the 1136: * {@link MBeanRegistration#preDeregister()} method will be called if 1137: * the bean implements the {@link MBeanRegistration} interface. 1138: * 1139: * @param name the name of the management bean. 1140: * @param delegationSubject a {@link javax.security.auth.Subject} instance 1141: * containing the delegation principles or 1142: * {@code null} if authentication is used. 1143: * @throws InstanceNotFoundException if the bean can not be found. 1144: * @throws MBeanRegistrationException if an exception occurs in 1145: * calling the preDeregister 1146: * method. 1147: * @throws RuntimeOperationsException if an {@link IllegalArgumentException} 1148: * is thrown by the server due to a 1149: * <code>null</code> bean name or a 1150: * request being made to unregister the 1151: * {@link MBeanServerDelegate} bean. 1152: * @throws SecurityException if the client or delegated subject (if any) does 1153: * not have permission to invoke this operation. 1154: * @throws IOException if an I/O error occurred in communicating with 1155: * the bean server. 1156: */ 1157: void unregisterMBean(ObjectName name, Subject delegationSubject) 1158: throws InstanceNotFoundException, MBeanRegistrationException, 1159: IOException; 1160: 1161: }