1 /* 2 * Copyright (c) 2002, 2017, 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="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html"> 77 * JMX Specification, version 1.4</a></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 */ getConnectionId()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 */ close()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 */ createMBean(String className, ObjectName name, Subject delegationSubject)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 */ createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)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 */ createMBean(String className, ObjectName name, MarshalledObject params, String signature[], Subject delegationSubject)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 */ createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String signature[], Subject delegationSubject)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 */ unregisterMBean(ObjectName name, Subject delegationSubject)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 */ getObjectInstance(ObjectName name, Subject delegationSubject)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> queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)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> queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)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 */ isRegistered(ObjectName name, Subject delegationSubject)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 */ getMBeanCount(Subject delegationSubject)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 */ getAttribute(ObjectName name, String attribute, Subject delegationSubject)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 */ getAttributes(ObjectName name, String[] attributes, Subject delegationSubject)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 */ setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)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 */ setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)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 */ invoke(ObjectName name, String operationName, MarshalledObject params, String signature[], Subject delegationSubject)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 */ getDefaultDomain(Subject delegationSubject)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 */ getDomains(Subject delegationSubject)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 */ getMBeanInfo(ObjectName name, Subject delegationSubject)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 */ isInstanceOf(ObjectName name, String className, Subject delegationSubject)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 */ addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)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 */ removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)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 */ removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)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 */ addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)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 */ removeNotificationListeners(ObjectName name, Integer[] listenerIDs, Subject delegationSubject)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 */ fetchNotifications(long clientSequenceNumber, int maxNotifications, long timeout)1088 public NotificationResult fetchNotifications(long clientSequenceNumber, 1089 int maxNotifications, 1090 long timeout) 1091 throws IOException; 1092 } 1093