001 /* RMIConnection.java -- RMI object representing a MBean server connection. 002 Copyright (C) 2007, 2008 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package javax.management.remote.rmi; 039 040 import java.io.Closeable; 041 import java.io.IOException; 042 043 import java.rmi.MarshalledObject; 044 import java.rmi.Remote; 045 046 import java.util.Set; 047 048 import javax.management.AttributeList; 049 import javax.management.AttributeNotFoundException; 050 import javax.management.InstanceAlreadyExistsException; 051 import javax.management.InstanceNotFoundException; 052 import javax.management.IntrospectionException; 053 import javax.management.InvalidAttributeValueException; 054 import javax.management.ListenerNotFoundException; 055 import javax.management.MBeanInfo; 056 import javax.management.MBeanException; 057 import javax.management.MBeanRegistrationException; 058 import javax.management.NotCompliantMBeanException; 059 import javax.management.ObjectInstance; 060 import javax.management.ObjectName; 061 import javax.management.ReflectionException; 062 063 import javax.management.remote.NotificationResult; 064 065 import javax.security.auth.Subject; 066 067 /** 068 * <p> 069 * RMI interface for forwarding requests to a remote 070 * {@link javax.management.MBeanServer}. This interface 071 * parallels the {@link javax.management.MBeanServerConnection} 072 * interface, providing a way of invoking those methods using 073 * the RMI protocol. When a client wishes to call a method 074 * of an MBean server using RMI, the method is called on the stub 075 * on the client side, which serializes the object parameters 076 * and sends them to the server where they are deserialized and 077 * an implementation of this interface forwards them to the 078 * appropriate MBean server. Return values follow the same 079 * process, only in reverse. Each client obtains its own 080 * implementation of this interface from an {@link RMIServer} 081 * instance. 082 * </p> 083 * <p> 084 * Implementations of this interface do more than simply 085 * forward requests directly to the server. The arguments 086 * of the server methods are wrapped in {@link MarshalledObject} 087 * instances, so that the correct classloader can be used to 088 * deserialize the arguments. When a method is called, the 089 * implementation must first retrieve the appropriate classloader 090 * and then use it to deserialize the marshalled object. Unless 091 * explicitly specified in the documentation for the method, 092 * a parameter of the type {@link MarshalledObject} or an array 093 * of that type should not be {@code null}. 094 * </p> 095 * <p> 096 * Security is also handled by this interface, as the methods 097 * use an additional {@link javax.security.auth.Subject} parameter 098 * for role delegation. 099 * </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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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("unchecked") 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 }