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