1 /* 2 * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.management.remote.rmi; 27 28 import java.io.Closeable; 29 import java.io.IOException; 30 import java.rmi.MarshalledObject; 31 import java.rmi.Remote; 32 import java.util.Set; 33 34 import javax.management.AttributeList; 35 import javax.management.AttributeNotFoundException; 36 import javax.management.InstanceAlreadyExistsException; 37 import javax.management.InstanceNotFoundException; 38 import javax.management.IntrospectionException; 39 import javax.management.InvalidAttributeValueException; 40 import javax.management.ListenerNotFoundException; 41 import javax.management.MBeanException; 42 import javax.management.MBeanInfo; 43 import javax.management.MBeanRegistrationException; 44 import javax.management.MBeanServerConnection; 45 import javax.management.NotCompliantMBeanException; 46 47 import javax.management.ObjectInstance; 48 import javax.management.ObjectName; 49 import javax.management.ReflectionException; 50 import javax.management.RuntimeMBeanException; 51 import javax.management.RuntimeOperationsException; 52 import javax.management.remote.NotificationResult; 53 import javax.security.auth.Subject; 54 55 /** 56 * <p>RMI object used to forward an MBeanServer request from a client 57 * to its MBeanServer implementation on the server side. There is one 58 * Remote object implementing this interface for each remote client 59 * connected to an RMI connector.</p> 60 * 61 * <p>User code does not usually refer to this interface. It is 62 * specified as part of the public API so that different 63 * implementations of that API will interoperate.</p> 64 * 65 * <p>To ensure that client parameters will be deserialized at the 66 * server side with the correct classloader, client parameters such as 67 * parameters used to invoke a method are wrapped in a {@link 68 * MarshalledObject}. An implementation of this interface must first 69 * get the appropriate class loader for the operation and its target, 70 * then deserialize the marshalled parameters with this classloader. 71 * Except as noted, a parameter that is a 72 * <code>MarshalledObject</code> or <code>MarshalledObject[]</code> 73 * must not be null; the behavior is unspecified if it is.</p> 74 * 75 * <p>Class loading aspects are detailed in the 76 * <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf"> 77 * JMX Specification, version 1.4</a> PDF document.</p> 78 * 79 * <p>Most methods in this interface parallel methods in the {@link 80 * MBeanServerConnection} interface. Where an aspect of the behavior 81 * of a method is not specified here, it is the same as in the 82 * corresponding <code>MBeanServerConnection</code> method. 83 * 84 * @since 1.5 85 */ 86 /* 87 * Notice that we omit the type parameter from MarshalledObject everywhere, 88 * even though it would add useful information to the documentation. The 89 * reason is that it was only added in Mustang (Java SE 6), whereas versions 90 * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our 91 * commitments for JSR 255. This is also why we suppress rawtypes warnings. 92 */ 93 @SuppressWarnings("rawtypes") 94 public interface RMIConnection extends Closeable, Remote { 95 /** 96 * <p>Returns the connection ID. This string is different for 97 * every open connection to a given RMI connector server.</p> 98 * 99 * @return the connection ID 100 * 101 * @see RMIConnector#connect RMIConnector.connect 102 * 103 * @throws IOException if a general communication exception occurred. 104 */ 105 public String getConnectionId() throws IOException; 106 107 /** 108 * <p>Closes this connection. On return from this method, the RMI 109 * object implementing this interface is unexported, so further 110 * remote calls to it will fail.</p> 111 * 112 * @throws IOException if the connection could not be closed, 113 * or the Remote object could not be unexported, or there was a 114 * communication failure when transmitting the remote close 115 * request. 116 */ 117 public void close() throws IOException; 118 119 /** 120 * Handles the method {@link 121 * javax.management.MBeanServerConnection#createMBean(String, 122 * ObjectName)}. 123 * 124 * @param className The class name of the MBean to be instantiated. 125 * @param name The object name of the MBean. May be null. 126 * @param delegationSubject The <code>Subject</code> containing the 127 * delegation principals or <code>null</code> if the authentication 128 * principal is used instead. 129 * 130 * @return An <code>ObjectInstance</code>, containing the 131 * <code>ObjectName</code> and the Java class name of the newly 132 * instantiated MBean. If the contained <code>ObjectName</code> 133 * is <code>n</code>, the contained Java class name is 134 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 135 * 136 * @throws ReflectionException Wraps a 137 * <code>java.lang.ClassNotFoundException</code> or a 138 * <code>java.lang.Exception</code> that occurred 139 * when trying to invoke the MBean's constructor. 140 * @throws InstanceAlreadyExistsException The MBean is already 141 * under the control of the MBean server. 142 * @throws MBeanRegistrationException The 143 * <code>preRegister</code> (<code>MBeanRegistration</code> 144 * interface) method of the MBean has thrown an exception. The 145 * MBean will not be registered. 146 * @throws MBeanException The constructor of the MBean has 147 * thrown an exception. 148 * @throws NotCompliantMBeanException This class is not a JMX 149 * compliant MBean. 150 * @throws RuntimeOperationsException Wraps a 151 * <code>java.lang.IllegalArgumentException</code>: The className 152 * passed in parameter is null, the <code>ObjectName</code> passed 153 * in parameter contains a pattern or no <code>ObjectName</code> 154 * is specified for the MBean. 155 * @throws SecurityException if the client, or the delegated Subject 156 * if any, does not have permission to perform this operation. 157 * @throws IOException if a general communication exception occurred. 158 */ 159 public ObjectInstance createMBean(String className, 160 ObjectName name, 161 Subject delegationSubject) 162 throws 163 ReflectionException, 164 InstanceAlreadyExistsException, 165 MBeanRegistrationException, 166 MBeanException, 167 NotCompliantMBeanException, 168 IOException; 169 170 /** 171 * Handles the method {@link 172 * javax.management.MBeanServerConnection#createMBean(String, 173 * ObjectName, ObjectName)}. 174 * 175 * @param className The class name of the MBean to be instantiated. 176 * @param name The object name of the MBean. May be null. 177 * @param loaderName The object name of the class loader to be used. 178 * @param delegationSubject The <code>Subject</code> containing the 179 * delegation principals or <code>null</code> if the authentication 180 * principal is used instead. 181 * 182 * @return An <code>ObjectInstance</code>, containing the 183 * <code>ObjectName</code> and the Java class name of the newly 184 * instantiated MBean. If the contained <code>ObjectName</code> 185 * is <code>n</code>, the contained Java class name is 186 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 187 * 188 * @throws ReflectionException Wraps a 189 * <code>java.lang.ClassNotFoundException</code> or a 190 * <code>java.lang.Exception</code> that occurred when trying to 191 * invoke the MBean's constructor. 192 * @throws InstanceAlreadyExistsException The MBean is already 193 * under the control of the MBean server. 194 * @throws MBeanRegistrationException The 195 * <code>preRegister</code> (<code>MBeanRegistration</code> 196 * interface) method of the MBean has thrown an exception. The 197 * MBean will not be registered. 198 * @throws MBeanException The constructor of the MBean has 199 * thrown an exception. 200 * @throws NotCompliantMBeanException This class is not a JMX 201 * compliant MBean. 202 * @throws InstanceNotFoundException The specified class loader 203 * is not registered in the MBean server. 204 * @throws RuntimeOperationsException Wraps a 205 * <code>java.lang.IllegalArgumentException</code>: The className 206 * passed in parameter is null, the <code>ObjectName</code> passed 207 * in parameter contains a pattern or no <code>ObjectName</code> 208 * is specified for the MBean. 209 * @throws SecurityException if the client, or the delegated Subject 210 * if any, does not have permission to perform this operation. 211 * @throws IOException if a general communication exception occurred. 212 */ 213 public ObjectInstance createMBean(String className, 214 ObjectName name, 215 ObjectName loaderName, 216 Subject delegationSubject) 217 throws 218 ReflectionException, 219 InstanceAlreadyExistsException, 220 MBeanRegistrationException, 221 MBeanException, 222 NotCompliantMBeanException, 223 InstanceNotFoundException, 224 IOException; 225 226 /** 227 * Handles the method {@link 228 * javax.management.MBeanServerConnection#createMBean(String, 229 * ObjectName, Object[], String[])}. The <code>Object[]</code> 230 * parameter is wrapped in a <code>MarshalledObject</code>. 231 * 232 * @param className The class name of the MBean to be instantiated. 233 * @param name The object name of the MBean. May be null. 234 * @param params An array containing the parameters of the 235 * constructor to be invoked, encapsulated into a 236 * <code>MarshalledObject</code>. The encapsulated array can be 237 * null, equivalent to an empty array. 238 * @param signature An array containing the signature of the 239 * constructor to be invoked. Can be null, equivalent to an empty 240 * array. 241 * @param delegationSubject The <code>Subject</code> containing the 242 * delegation principals or <code>null</code> if the authentication 243 * principal is used instead. 244 * 245 * @return An <code>ObjectInstance</code>, containing the 246 * <code>ObjectName</code> and the Java class name of the newly 247 * instantiated MBean. If the contained <code>ObjectName</code> 248 * is <code>n</code>, the contained Java class name is 249 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 250 * 251 * @throws ReflectionException Wraps a 252 * <code>java.lang.ClassNotFoundException</code> or a 253 * <code>java.lang.Exception</code> that occurred when trying to 254 * invoke the MBean's constructor. 255 * @throws InstanceAlreadyExistsException The MBean is already 256 * under the control of the MBean server. 257 * @throws MBeanRegistrationException The 258 * <code>preRegister</code> (<code>MBeanRegistration</code> 259 * interface) method of the MBean has thrown an exception. The 260 * MBean will not be registered. 261 * @throws MBeanException The constructor of the MBean has 262 * thrown an exception. 263 * @throws NotCompliantMBeanException This class is not a JMX 264 * compliant MBean. 265 * @throws RuntimeOperationsException Wraps a 266 * <code>java.lang.IllegalArgumentException</code>: The className 267 * passed in parameter is null, the <code>ObjectName</code> passed 268 * in parameter contains a pattern, or no <code>ObjectName</code> 269 * is specified for the MBean. 270 * @throws SecurityException if the client, or the delegated Subject 271 * if any, does not have permission to perform this operation. 272 * @throws IOException if a general communication exception occurred. 273 */ 274 public ObjectInstance createMBean(String className, 275 ObjectName name, 276 MarshalledObject params, 277 String signature[], 278 Subject delegationSubject) 279 throws 280 ReflectionException, 281 InstanceAlreadyExistsException, 282 MBeanRegistrationException, 283 MBeanException, 284 NotCompliantMBeanException, 285 IOException; 286 287 /** 288 * Handles the method {@link 289 * javax.management.MBeanServerConnection#createMBean(String, 290 * ObjectName, ObjectName, Object[], String[])}. The 291 * <code>Object[]</code> parameter is wrapped in a 292 * <code>MarshalledObject</code>. 293 * 294 * @param className The class name of the MBean to be instantiated. 295 * @param name The object name of the MBean. May be null. 296 * @param loaderName The object name of the class loader to be used. 297 * @param params An array containing the parameters of the 298 * constructor to be invoked, encapsulated into a 299 * <code>MarshalledObject</code>. The encapsulated array can be 300 * null, equivalent to an empty array. 301 * @param signature An array containing the signature of the 302 * constructor to be invoked. Can be null, equivalent to an empty 303 * array. 304 * @param delegationSubject The <code>Subject</code> containing the 305 * delegation principals or <code>null</code> if the authentication 306 * principal is used instead. 307 * 308 * @return An <code>ObjectInstance</code>, containing the 309 * <code>ObjectName</code> and the Java class name of the newly 310 * instantiated MBean. If the contained <code>ObjectName</code> 311 * is <code>n</code>, the contained Java class name is 312 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 313 * 314 * @throws ReflectionException Wraps a 315 * <code>java.lang.ClassNotFoundException</code> or a 316 * <code>java.lang.Exception</code> that occurred when trying to 317 * invoke the MBean's constructor. 318 * @throws InstanceAlreadyExistsException The MBean is already 319 * under the control of the MBean server. 320 * @throws MBeanRegistrationException The 321 * <code>preRegister</code> (<code>MBeanRegistration</code> 322 * interface) method of the MBean has thrown an exception. The 323 * MBean will not be registered. 324 * @throws MBeanException The constructor of the MBean has 325 * thrown an exception. 326 * @throws NotCompliantMBeanException This class is not a JMX 327 * compliant MBean. 328 * @throws InstanceNotFoundException The specified class loader 329 * is not registered in the MBean server. 330 * @throws RuntimeOperationsException Wraps a 331 * <code>java.lang.IllegalArgumentException</code>: The className 332 * passed in parameter is null, the <code>ObjectName</code> passed 333 * in parameter contains a pattern, or no <code>ObjectName</code> 334 * is specified for the MBean. 335 * @throws SecurityException if the client, or the delegated Subject 336 * if any, does not have permission to perform this operation. 337 * @throws IOException if a general communication exception occurred. 338 */ 339 public ObjectInstance createMBean(String className, 340 ObjectName name, 341 ObjectName loaderName, 342 MarshalledObject params, 343 String signature[], 344 Subject delegationSubject) 345 throws 346 ReflectionException, 347 InstanceAlreadyExistsException, 348 MBeanRegistrationException, 349 MBeanException, 350 NotCompliantMBeanException, 351 InstanceNotFoundException, 352 IOException; 353 354 /** 355 * Handles the method 356 * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}. 357 * 358 * @param name The object name of the MBean to be unregistered. 359 * @param delegationSubject The <code>Subject</code> containing the 360 * delegation principals or <code>null</code> if the authentication 361 * principal is used instead. 362 * 363 * @throws InstanceNotFoundException The MBean specified is not 364 * registered in the MBean server. 365 * @throws MBeanRegistrationException The preDeregister 366 * ((<code>MBeanRegistration</code> interface) method of the MBean 367 * has thrown an exception. 368 * @throws RuntimeOperationsException Wraps a 369 * <code>java.lang.IllegalArgumentException</code>: The object 370 * name in parameter is null or the MBean you are when trying to 371 * unregister is the {@link javax.management.MBeanServerDelegate 372 * MBeanServerDelegate} MBean. 373 * @throws SecurityException if the client, or the delegated Subject 374 * if any, does not have permission to perform this operation. 375 * @throws IOException if a general communication exception occurred. 376 */ 377 public void unregisterMBean(ObjectName name, Subject delegationSubject) 378 throws 379 InstanceNotFoundException, 380 MBeanRegistrationException, 381 IOException; 382 383 /** 384 * Handles the method 385 * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}. 386 * 387 * @param name The object name of the MBean. 388 * @param delegationSubject The <code>Subject</code> containing the 389 * delegation principals or <code>null</code> if the authentication 390 * principal is used instead. 391 * 392 * @return The <code>ObjectInstance</code> associated with the MBean 393 * specified by <var>name</var>. The contained <code>ObjectName</code> 394 * is <code>name</code> and the contained class name is 395 * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>. 396 * 397 * @throws InstanceNotFoundException The MBean specified is not 398 * registered in the MBean server. 399 * @throws RuntimeOperationsException Wraps a 400 * <code>java.lang.IllegalArgumentException</code>: The object 401 * name in parameter is null. 402 * @throws SecurityException if the client, or the delegated Subject 403 * if any, does not have permission to perform this operation. 404 * @throws IOException if a general communication exception occurred. 405 */ 406 public ObjectInstance getObjectInstance(ObjectName name, 407 Subject delegationSubject) 408 throws InstanceNotFoundException, IOException; 409 410 /** 411 * Handles the method {@link 412 * javax.management.MBeanServerConnection#queryMBeans(ObjectName, 413 * QueryExp)}. The <code>QueryExp</code> is wrapped in a 414 * <code>MarshalledObject</code>. 415 * 416 * @param name The object name pattern identifying the MBeans to 417 * be retrieved. If null or no domain and key properties are 418 * specified, all the MBeans registered will be retrieved. 419 * @param query The query expression to be applied for selecting 420 * MBeans, encapsulated into a <code>MarshalledObject</code>. If 421 * the <code>MarshalledObject</code> encapsulates a null value no 422 * query expression will be applied for selecting MBeans. 423 * @param delegationSubject The <code>Subject</code> containing the 424 * delegation principals or <code>null</code> if the authentication 425 * principal is used instead. 426 * 427 * @return A set containing the <code>ObjectInstance</code> 428 * objects for the selected MBeans. If no MBean satisfies the 429 * query an empty list is returned. 430 * 431 * @throws SecurityException if the client, or the delegated Subject 432 * if any, does not have permission to perform this operation. 433 * @throws IOException if a general communication exception occurred. 434 */ 435 public Set<ObjectInstance> 436 queryMBeans(ObjectName name, 437 MarshalledObject query, 438 Subject delegationSubject) 439 throws IOException; 440 441 /** 442 * Handles the method {@link 443 * javax.management.MBeanServerConnection#queryNames(ObjectName, 444 * QueryExp)}. The <code>QueryExp</code> is wrapped in a 445 * <code>MarshalledObject</code>. 446 * 447 * @param name The object name pattern identifying the MBean names 448 * to be retrieved. If null or no domain and key properties are 449 * specified, the name of all registered MBeans will be retrieved. 450 * @param query The query expression to be applied for selecting 451 * MBeans, encapsulated into a <code>MarshalledObject</code>. If 452 * the <code>MarshalledObject</code> encapsulates a null value no 453 * query expression will be applied for selecting MBeans. 454 * @param delegationSubject The <code>Subject</code> containing the 455 * delegation principals or <code>null</code> if the authentication 456 * principal is used instead. 457 * 458 * @return A set containing the ObjectNames for the MBeans 459 * selected. If no MBean satisfies the query, an empty list is 460 * returned. 461 * 462 * @throws SecurityException if the client, or the delegated Subject 463 * if any, does not have permission to perform this operation. 464 * @throws IOException if a general communication exception occurred. 465 */ 466 public Set<ObjectName> 467 queryNames(ObjectName name, 468 MarshalledObject query, 469 Subject delegationSubject) 470 throws IOException; 471 472 /** 473 * Handles the method 474 * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}. 475 * 476 * @param name The object name of the MBean to be checked. 477 * @param delegationSubject The <code>Subject</code> containing the 478 * delegation principals or <code>null</code> if the authentication 479 * principal is used instead. 480 * 481 * @return True if the MBean is already registered in the MBean 482 * server, false otherwise. 483 * 484 * @throws RuntimeOperationsException Wraps a 485 * <code>java.lang.IllegalArgumentException</code>: The object 486 * name in parameter is null. 487 * @throws SecurityException if the client, or the delegated Subject 488 * if any, does not have permission to perform this operation. 489 * @throws IOException if a general communication exception occurred. 490 */ 491 public boolean isRegistered(ObjectName name, Subject delegationSubject) 492 throws IOException; 493 494 /** 495 * Handles the method 496 * {@link javax.management.MBeanServerConnection#getMBeanCount()}. 497 * 498 * @param delegationSubject The <code>Subject</code> containing the 499 * delegation principals or <code>null</code> if the authentication 500 * principal is used instead. 501 * 502 * @return the number of MBeans registered. 503 * 504 * @throws SecurityException if the client, or the delegated Subject 505 * if any, does not have permission to perform this operation. 506 * @throws IOException if a general communication exception occurred. 507 */ 508 public Integer getMBeanCount(Subject delegationSubject) 509 throws IOException; 510 511 /** 512 * Handles the method {@link 513 * javax.management.MBeanServerConnection#getAttribute(ObjectName, 514 * String)}. 515 * 516 * @param name The object name of the MBean from which the 517 * attribute is to be retrieved. 518 * @param attribute A String specifying the name of the attribute 519 * to be retrieved. 520 * @param delegationSubject The <code>Subject</code> containing the 521 * delegation principals or <code>null</code> if the authentication 522 * principal is used instead. 523 * 524 * @return The value of the retrieved attribute. 525 * 526 * @throws AttributeNotFoundException The attribute specified 527 * is not accessible in the MBean. 528 * @throws MBeanException Wraps an exception thrown by the 529 * MBean's getter. 530 * @throws InstanceNotFoundException The MBean specified is not 531 * registered in the MBean server. 532 * @throws ReflectionException Wraps a 533 * <code>java.lang.Exception</code> thrown when trying to invoke 534 * the getter. 535 * @throws RuntimeOperationsException Wraps a 536 * <code>java.lang.IllegalArgumentException</code>: The object 537 * name in parameter is null or the attribute in parameter is 538 * null. 539 * @throws RuntimeMBeanException Wraps a runtime exception thrown 540 * by the MBean's getter. 541 * @throws SecurityException if the client, or the delegated Subject 542 * if any, does not have permission to perform this operation. 543 * @throws IOException if a general communication exception occurred. 544 * 545 * @see #setAttribute 546 */ 547 public Object getAttribute(ObjectName name, 548 String attribute, 549 Subject delegationSubject) 550 throws 551 MBeanException, 552 AttributeNotFoundException, 553 InstanceNotFoundException, 554 ReflectionException, 555 IOException; 556 557 /** 558 * Handles the method {@link 559 * javax.management.MBeanServerConnection#getAttributes(ObjectName, 560 * String[])}. 561 * 562 * @param name The object name of the MBean from which the 563 * attributes are retrieved. 564 * @param attributes A list of the attributes to be retrieved. 565 * @param delegationSubject The <code>Subject</code> containing the 566 * delegation principals or <code>null</code> if the authentication 567 * principal is used instead. 568 * 569 * @return The list of the retrieved attributes. 570 * 571 * @throws InstanceNotFoundException The MBean specified is not 572 * registered in the MBean server. 573 * @throws ReflectionException An exception occurred when 574 * trying to invoke the getAttributes method of a Dynamic MBean. 575 * @throws RuntimeOperationsException Wrap a 576 * <code>java.lang.IllegalArgumentException</code>: The object 577 * name in parameter is null or attributes in parameter is null. 578 * @throws SecurityException if the client, or the delegated Subject 579 * if any, does not have permission to perform this operation. 580 * @throws IOException if a general communication exception occurred. 581 * 582 * @see #setAttributes 583 */ 584 public AttributeList getAttributes(ObjectName name, 585 String[] attributes, 586 Subject delegationSubject) 587 throws 588 InstanceNotFoundException, 589 ReflectionException, 590 IOException; 591 592 /** 593 * Handles the method {@link 594 * javax.management.MBeanServerConnection#setAttribute(ObjectName, 595 * Attribute)}. The <code>Attribute</code> parameter is wrapped 596 * in a <code>MarshalledObject</code>. 597 * 598 * @param name The name of the MBean within which the attribute is 599 * to be set. 600 * @param attribute The identification of the attribute to be set 601 * and the value it is to be set to, encapsulated into a 602 * <code>MarshalledObject</code>. 603 * @param delegationSubject The <code>Subject</code> containing the 604 * delegation principals or <code>null</code> if the authentication 605 * principal is used instead. 606 * 607 * @throws InstanceNotFoundException The MBean specified is not 608 * registered in the MBean server. 609 * @throws AttributeNotFoundException The attribute specified 610 * is not accessible in the MBean. 611 * @throws InvalidAttributeValueException The value specified 612 * for the attribute is not valid. 613 * @throws MBeanException Wraps an exception thrown by the 614 * MBean's setter. 615 * @throws ReflectionException Wraps a 616 * <code>java.lang.Exception</code> thrown when trying to invoke 617 * the setter. 618 * @throws RuntimeOperationsException Wraps a 619 * <code>java.lang.IllegalArgumentException</code>: The object 620 * name in parameter is null or the attribute in parameter is 621 * null. 622 * @throws SecurityException if the client, or the delegated Subject 623 * if any, does not have permission to perform this operation. 624 * @throws IOException if a general communication exception occurred. 625 * 626 * @see #getAttribute 627 */ 628 public void setAttribute(ObjectName name, 629 MarshalledObject attribute, 630 Subject delegationSubject) 631 throws 632 InstanceNotFoundException, 633 AttributeNotFoundException, 634 InvalidAttributeValueException, 635 MBeanException, 636 ReflectionException, 637 IOException; 638 639 /** 640 * Handles the method {@link 641 * javax.management.MBeanServerConnection#setAttributes(ObjectName, 642 * AttributeList)}. The <code>AttributeList</code> parameter is 643 * wrapped in a <code>MarshalledObject</code>. 644 * 645 * @param name The object name of the MBean within which the 646 * attributes are to be set. 647 * @param attributes A list of attributes: The identification of 648 * the attributes to be set and the values they are to be set to, 649 * encapsulated into a <code>MarshalledObject</code>. 650 * @param delegationSubject The <code>Subject</code> containing the 651 * delegation principals or <code>null</code> if the authentication 652 * principal is used instead. 653 * 654 * @return The list of attributes that were set, with their new 655 * values. 656 * 657 * @throws InstanceNotFoundException The MBean specified is not 658 * registered in the MBean server. 659 * @throws ReflectionException An exception occurred when 660 * trying to invoke the getAttributes method of a Dynamic MBean. 661 * @throws RuntimeOperationsException Wraps a 662 * <code>java.lang.IllegalArgumentException</code>: The object 663 * name in parameter is null or attributes in parameter is null. 664 * @throws SecurityException if the client, or the delegated Subject 665 * if any, does not have permission to perform this operation. 666 * @throws IOException if a general communication exception occurred. 667 * 668 * @see #getAttributes 669 */ 670 public AttributeList setAttributes(ObjectName name, 671 MarshalledObject attributes, 672 Subject delegationSubject) 673 throws 674 InstanceNotFoundException, 675 ReflectionException, 676 IOException; 677 678 /** 679 * Handles the method {@link 680 * javax.management.MBeanServerConnection#invoke(ObjectName, 681 * String, Object[], String[])}. The <code>Object[]</code> 682 * parameter is wrapped in a <code>MarshalledObject</code>. 683 * 684 * @param name The object name of the MBean on which the method is 685 * to be invoked. 686 * @param operationName The name of the operation to be invoked. 687 * @param params An array containing the parameters to be set when 688 * the operation is invoked, encapsulated into a 689 * <code>MarshalledObject</code>. The encapsulated array can be 690 * null, equivalent to an empty array. 691 * @param signature An array containing the signature of the 692 * operation. The class objects will be loaded using the same 693 * class loader as the one used for loading the MBean on which the 694 * operation was invoked. Can be null, equivalent to an empty 695 * array. 696 * @param delegationSubject The <code>Subject</code> containing the 697 * delegation principals or <code>null</code> if the authentication 698 * principal is used instead. 699 * 700 * @return The object returned by the operation, which represents 701 * the result of invoking the operation on the MBean specified. 702 * 703 * @throws InstanceNotFoundException The MBean specified is not 704 * registered in the MBean server. 705 * @throws MBeanException Wraps an exception thrown by the 706 * MBean's invoked method. 707 * @throws ReflectionException Wraps a 708 * <code>java.lang.Exception</code> thrown while trying to invoke 709 * the method. 710 * @throws SecurityException if the client, or the delegated Subject 711 * if any, does not have permission to perform this operation. 712 * @throws IOException if a general communication exception occurred. 713 * @throws RuntimeOperationsException Wraps an {@link 714 * IllegalArgumentException} when <code>name</code> or 715 * <code>operationName</code> is null. 716 */ 717 public Object invoke(ObjectName name, 718 String operationName, 719 MarshalledObject params, 720 String signature[], 721 Subject delegationSubject) 722 throws 723 InstanceNotFoundException, 724 MBeanException, 725 ReflectionException, 726 IOException; 727 728 /** 729 * Handles the method 730 * {@link javax.management.MBeanServerConnection#getDefaultDomain()}. 731 * 732 * @param delegationSubject The <code>Subject</code> containing the 733 * delegation principals or <code>null</code> if the authentication 734 * principal is used instead. 735 * 736 * @return the default domain. 737 * 738 * @throws SecurityException if the client, or the delegated Subject 739 * if any, does not have permission to perform this operation. 740 * @throws IOException if a general communication exception occurred. 741 */ 742 public String getDefaultDomain(Subject delegationSubject) 743 throws IOException; 744 745 /** 746 * Handles the method 747 * {@link javax.management.MBeanServerConnection#getDomains()}. 748 * 749 * @param delegationSubject The <code>Subject</code> containing the 750 * delegation principals or <code>null</code> if the authentication 751 * principal is used instead. 752 * 753 * @return the list of domains. 754 * 755 * @throws SecurityException if the client, or the delegated Subject 756 * if any, does not have permission to perform this operation. 757 * @throws IOException if a general communication exception occurred. 758 */ 759 public String[] getDomains(Subject delegationSubject) 760 throws IOException; 761 762 /** 763 * Handles the method 764 * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}. 765 * 766 * @param name The name of the MBean to analyze 767 * @param delegationSubject The <code>Subject</code> containing the 768 * delegation principals or <code>null</code> if the authentication 769 * principal is used instead. 770 * 771 * @return An instance of <code>MBeanInfo</code> allowing the 772 * retrieval of all attributes and operations of this MBean. 773 * 774 * @throws IntrospectionException An exception occurred during 775 * introspection. 776 * @throws InstanceNotFoundException The MBean specified was 777 * not found. 778 * @throws ReflectionException An exception occurred when 779 * trying to invoke the getMBeanInfo of a Dynamic MBean. 780 * @throws SecurityException if the client, or the delegated Subject 781 * if any, does not have permission to perform this operation. 782 * @throws IOException if a general communication exception occurred. 783 * @throws RuntimeOperationsException Wraps a 784 * <code>java.lang.IllegalArgumentException</code>: The object 785 * name in parameter is null. 786 */ 787 public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject) 788 throws 789 InstanceNotFoundException, 790 IntrospectionException, 791 ReflectionException, 792 IOException; 793 794 /** 795 * Handles the method {@link 796 * javax.management.MBeanServerConnection#isInstanceOf(ObjectName, 797 * String)}. 798 * 799 * @param name The <code>ObjectName</code> of the MBean. 800 * @param className The name of the class. 801 * @param delegationSubject The <code>Subject</code> containing the 802 * delegation principals or <code>null</code> if the authentication 803 * principal is used instead. 804 * 805 * @return true if the MBean specified is an instance of the 806 * specified class according to the rules above, false otherwise. 807 * 808 * @throws InstanceNotFoundException The MBean specified is not 809 * registered in the MBean server. 810 * @throws SecurityException if the client, or the delegated Subject 811 * if any, does not have permission to perform this operation. 812 * @throws IOException if a general communication exception occurred. 813 * @throws RuntimeOperationsException Wraps a 814 * <code>java.lang.IllegalArgumentException</code>: The object 815 * name in parameter is null. 816 */ 817 public boolean isInstanceOf(ObjectName name, 818 String className, 819 Subject delegationSubject) 820 throws InstanceNotFoundException, IOException; 821 822 /** 823 * Handles the method {@link 824 * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, 825 * ObjectName, NotificationFilter, Object)}. The 826 * <code>NotificationFilter</code> parameter is wrapped in a 827 * <code>MarshalledObject</code>. The <code>Object</code> 828 * (handback) parameter is also wrapped in a 829 * <code>MarshalledObject</code>. 830 * 831 * @param name The name of the MBean on which the listener should 832 * be added. 833 * @param listener The object name of the listener which will 834 * handle the notifications emitted by the registered MBean. 835 * @param filter The filter object, encapsulated into a 836 * <code>MarshalledObject</code>. If filter encapsulated in the 837 * <code>MarshalledObject</code> has a null value, no filtering 838 * will be performed before handling notifications. 839 * @param handback The context to be sent to the listener when a 840 * notification is emitted, encapsulated into a 841 * <code>MarshalledObject</code>. 842 * @param delegationSubject The <code>Subject</code> containing the 843 * delegation principals or <code>null</code> if the authentication 844 * principal is used instead. 845 * 846 * @throws InstanceNotFoundException The MBean name of the 847 * notification listener or of the notification broadcaster does 848 * not match any of the registered MBeans. 849 * @throws RuntimeOperationsException Wraps an {@link 850 * IllegalArgumentException}. The MBean named by 851 * <code>listener</code> exists but does not implement the 852 * {@link javax.management.NotificationListener} interface, 853 * or <code>name</code> or <code>listener</code> is null. 854 * @throws SecurityException if the client, or the delegated Subject 855 * if any, does not have permission to perform this operation. 856 * @throws IOException if a general communication exception occurred. 857 * 858 * @see #removeNotificationListener(ObjectName, ObjectName, Subject) 859 * @see #removeNotificationListener(ObjectName, ObjectName, 860 * MarshalledObject, MarshalledObject, Subject) 861 */ 862 public void addNotificationListener(ObjectName name, 863 ObjectName listener, 864 MarshalledObject filter, 865 MarshalledObject handback, 866 Subject delegationSubject) 867 throws InstanceNotFoundException, IOException; 868 869 /** 870 * Handles the method {@link 871 * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, 872 * ObjectName)}. 873 * 874 * @param name The name of the MBean on which the listener should 875 * be removed. 876 * @param listener The object name of the listener to be removed. 877 * @param delegationSubject The <code>Subject</code> containing the 878 * delegation principals or <code>null</code> if the authentication 879 * principal is used instead. 880 * 881 * @throws InstanceNotFoundException The MBean name provided 882 * does not match any of the registered MBeans. 883 * @throws ListenerNotFoundException The listener is not 884 * registered in the MBean. 885 * @throws SecurityException if the client, or the delegated Subject 886 * if any, does not have permission to perform this operation. 887 * @throws IOException if a general communication exception occurred. 888 * @throws RuntimeOperationsException Wraps an {@link 889 * IllegalArgumentException} when <code>name</code> or 890 * <code>listener</code> is null. 891 * 892 * @see #addNotificationListener 893 */ 894 public void removeNotificationListener(ObjectName name, 895 ObjectName listener, 896 Subject delegationSubject) 897 throws 898 InstanceNotFoundException, 899 ListenerNotFoundException, 900 IOException; 901 902 /** 903 * Handles the method {@link 904 * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, 905 * ObjectName, NotificationFilter, Object)}. The 906 * <code>NotificationFilter</code> parameter is wrapped in a 907 * <code>MarshalledObject</code>. The <code>Object</code> 908 * parameter is also wrapped in a <code>MarshalledObject</code>. 909 * 910 * @param name The name of the MBean on which the listener should 911 * be removed. 912 * @param listener A listener that was previously added to this 913 * MBean. 914 * @param filter The filter that was specified when the listener 915 * was added, encapsulated into a <code>MarshalledObject</code>. 916 * @param handback The handback that was specified when the 917 * listener was added, encapsulated into a <code>MarshalledObject</code>. 918 * @param delegationSubject The <code>Subject</code> containing the 919 * delegation principals or <code>null</code> if the authentication 920 * principal is used instead. 921 * 922 * @throws InstanceNotFoundException The MBean name provided 923 * does not match any of the registered MBeans. 924 * @throws ListenerNotFoundException The listener is not 925 * registered in the MBean, or it is not registered with the given 926 * filter and handback. 927 * @throws SecurityException if the client, or the delegated Subject 928 * if any, does not have permission to perform this operation. 929 * @throws IOException if a general communication exception occurred. 930 * @throws RuntimeOperationsException Wraps an {@link 931 * IllegalArgumentException} when <code>name</code> or 932 * <code>listener</code> is null. 933 * 934 * @see #addNotificationListener 935 */ 936 public void removeNotificationListener(ObjectName name, 937 ObjectName listener, 938 MarshalledObject filter, 939 MarshalledObject handback, 940 Subject delegationSubject) 941 throws 942 InstanceNotFoundException, 943 ListenerNotFoundException, 944 IOException; 945 946 // Special Handling of Notifications ------------------------------------- 947 948 /** 949 * <p>Handles the method {@link 950 * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, 951 * NotificationListener, NotificationFilter, Object)}.</p> 952 * 953 * <p>Register for notifications from the given MBeans that match 954 * the given filters. The remote client can subsequently retrieve 955 * the notifications using the {@link #fetchNotifications 956 * fetchNotifications} method.</p> 957 * 958 * <p>For each listener, the original 959 * <code>NotificationListener</code> and <code>handback</code> are 960 * kept on the client side; in order for the client to be able to 961 * identify them, the server generates and returns a unique 962 * <code>listenerID</code>. This <code>listenerID</code> is 963 * forwarded with the <code>Notifications</code> to the remote 964 * client.</p> 965 * 966 * <p>If any one of the given (name, filter) pairs cannot be 967 * registered, then the operation fails with an exception, and no 968 * names or filters are registered.</p> 969 * 970 * @param names the <code>ObjectNames</code> identifying the 971 * MBeans emitting the Notifications. 972 * @param filters an array of marshalled representations of the 973 * <code>NotificationFilters</code>. Elements of this array can 974 * be null. 975 * @param delegationSubjects the <code>Subjects</code> on behalf 976 * of which the listeners are being added. Elements of this array 977 * can be null. Also, the <code>delegationSubjects</code> 978 * parameter itself can be null, which is equivalent to an array 979 * of null values with the same size as the <code>names</code> and 980 * <code>filters</code> arrays. 981 * 982 * @return an array of <code>listenerIDs</code> identifying the 983 * local listeners. This array has the same number of elements as 984 * the parameters. 985 * 986 * @throws IllegalArgumentException if <code>names</code> or 987 * <code>filters</code> is null, or if <code>names</code> contains 988 * a null element, or if the three arrays do not all have the same 989 * size. 990 * @throws ClassCastException if one of the elements of 991 * <code>filters</code> unmarshalls as a non-null object that is 992 * not a <code>NotificationFilter</code>. 993 * @throws InstanceNotFoundException if one of the 994 * <code>names</code> does not correspond to any registered MBean. 995 * @throws SecurityException if, for one of the MBeans, the 996 * client, or the delegated Subject if any, does not have 997 * permission to add a listener. 998 * @throws IOException if a general communication exception occurred. 999 */ 1000 public Integer[] addNotificationListeners(ObjectName[] names, 1001 MarshalledObject[] filters, 1002 Subject[] delegationSubjects) 1003 throws InstanceNotFoundException, IOException; 1004 1005 /** 1006 * <p>Handles the 1007 * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener) 1008 * removeNotificationListener(ObjectName, NotificationListener)} and 1009 * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object) 1010 * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.</p> 1011 * 1012 * <p>This method removes one or more 1013 * <code>NotificationListener</code>s from a given MBean in the 1014 * MBean server.</p> 1015 * 1016 * <p>The <code>NotificationListeners</code> are identified by the 1017 * IDs which were returned by the {@link 1018 * #addNotificationListeners(ObjectName[], MarshalledObject[], 1019 * Subject[])} method.</p> 1020 * 1021 * @param name the <code>ObjectName</code> identifying the MBean 1022 * emitting the Notifications. 1023 * @param listenerIDs the list of the IDs corresponding to the 1024 * listeners to remove. 1025 * @param delegationSubject The <code>Subject</code> containing the 1026 * delegation principals or <code>null</code> if the authentication 1027 * principal is used instead. 1028 * 1029 * @throws InstanceNotFoundException if the given 1030 * <code>name</code> does not correspond to any registered MBean. 1031 * @throws ListenerNotFoundException if one of the listeners was 1032 * not found on the server side. This exception can happen if the 1033 * MBean discarded a listener for some reason other than a call to 1034 * <code>MBeanServer.removeNotificationListener</code>. 1035 * @throws SecurityException if the client, or the delegated Subject 1036 * if any, does not have permission to remove the listeners. 1037 * @throws IOException if a general communication exception occurred. 1038 * @throws IllegalArgumentException if <code>ObjectName</code> or 1039 * <code>listenerIds</code> is null or if <code>listenerIds</code> 1040 * contains a null element. 1041 */ 1042 public void removeNotificationListeners(ObjectName name, 1043 Integer[] listenerIDs, 1044 Subject delegationSubject) 1045 throws 1046 InstanceNotFoundException, 1047 ListenerNotFoundException, 1048 IOException; 1049 1050 /** 1051 * <p>Retrieves notifications from the connector server. This 1052 * method can block until there is at least one notification or 1053 * until the specified timeout is reached. The method can also 1054 * return at any time with zero notifications.</p> 1055 * 1056 * <p>A notification can be included in the result if its sequence 1057 * number is no less than <code>clientSequenceNumber</code> and 1058 * this client has registered at least one listener for the MBean 1059 * generating the notification, with a filter that accepts the 1060 * notification. Each listener that is interested in the 1061 * notification is identified by an Integer ID that was returned 1062 * by {@link #addNotificationListeners(ObjectName[], 1063 * MarshalledObject[], Subject[])}.</p> 1064 * 1065 * @param clientSequenceNumber the first sequence number that the 1066 * client is interested in. If negative, it is interpreted as 1067 * meaning the sequence number that the next notification will 1068 * have. 1069 * 1070 * @param maxNotifications the maximum number of different 1071 * notifications to return. The <code>TargetedNotification</code> 1072 * array in the returned <code>NotificationResult</code> can have 1073 * more elements than this if the same notification appears more 1074 * than once. The behavior is unspecified if this parameter is 1075 * negative. 1076 * 1077 * @param timeout the maximum time in milliseconds to wait for a 1078 * notification to arrive. This can be 0 to indicate that the 1079 * method should not wait if there are no notifications, but 1080 * should return at once. It can be <code>Long.MAX_VALUE</code> 1081 * to indicate that there is no timeout. The behavior is 1082 * unspecified if this parameter is negative. 1083 * 1084 * @return A <code>NotificationResult</code>. 1085 * 1086 * @throws IOException if a general communication exception occurred. 1087 */ 1088 public NotificationResult fetchNotifications(long clientSequenceNumber, 1089 int maxNotifications, 1090 long timeout) 1091 throws IOException; 1092 }