1 /* 2 * Copyright (c) 2002, 2013, 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; 27 28 29 // java import 30 import java.io.IOException; 31 import java.util.Set; 32 33 34 /** 35 * This interface represents a way to talk to an MBean server, whether 36 * local or remote. The {@link MBeanServer} interface, representing a 37 * local MBean server, extends this interface. 38 * 39 * 40 * @since 1.5 41 */ 42 public interface MBeanServerConnection { 43 /** 44 * <p>Instantiates and registers an MBean in the MBean server. The 45 * MBean server will use its {@link 46 * javax.management.loading.ClassLoaderRepository Default Loader 47 * Repository} to load the class of the MBean. An object name is 48 * associated with the MBean. If the object name given is null, the 49 * MBean must provide its own name by implementing the {@link 50 * javax.management.MBeanRegistration MBeanRegistration} interface 51 * and returning the name from the {@link 52 * MBeanRegistration#preRegister preRegister} method.</p> 53 * 54 * <p>This method is equivalent to {@link 55 * #createMBean(String,ObjectName,Object[],String[]) 56 * createMBean(className, name, (Object[]) null, (String[]) 57 * null)}.</p> 58 * 59 * @param className The class name of the MBean to be instantiated. 60 * @param name The object name of the MBean. May be null. 61 * 62 * @return An <CODE>ObjectInstance</CODE>, containing the 63 * <CODE>ObjectName</CODE> and the Java class name of the newly 64 * instantiated MBean. If the contained <code>ObjectName</code> 65 * is <code>n</code>, the contained Java class name is 66 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 67 * 68 * @exception ReflectionException Wraps a 69 * <CODE>java.lang.ClassNotFoundException</CODE> or a 70 * <CODE>java.lang.Exception</CODE> that occurred 71 * when trying to invoke the MBean's constructor. 72 * @exception InstanceAlreadyExistsException The MBean is already 73 * under the control of the MBean server. 74 * @exception MBeanRegistrationException The 75 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> 76 * interface) method of the MBean has thrown an exception. The 77 * MBean will not be registered. 78 * @exception RuntimeMBeanException If the MBean's constructor or its 79 * {@code preRegister} or {@code postRegister} method threw 80 * a {@code RuntimeException}. If the <CODE>postRegister</CODE> 81 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 82 * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will 83 * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation 84 * and registration succeeded. In such a case, the MBean will be actually 85 * registered even though the <CODE>createMBean</CODE> method 86 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 87 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 88 * will not be registered. 89 * @exception RuntimeErrorException If the <CODE>postRegister</CODE> 90 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 91 * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will 92 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation 93 * and registration succeeded. In such a case, the MBean will be actually 94 * registered even though the <CODE>createMBean</CODE> method 95 * threw an exception. Note that <CODE>RuntimeErrorException</CODE> can 96 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 97 * will not be registered. 98 * @exception MBeanException The constructor of the MBean has 99 * thrown an exception 100 * @exception NotCompliantMBeanException This class is not a JMX 101 * compliant MBean 102 * @exception RuntimeOperationsException Wraps a 103 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 104 * passed in parameter is null, the <CODE>ObjectName</CODE> passed 105 * in parameter contains a pattern or no <CODE>ObjectName</CODE> 106 * is specified for the MBean. 107 * @exception IOException A communication problem occurred when 108 * talking to the MBean server. 109 * @see javax.management.MBeanRegistration 110 */ createMBean(String className, ObjectName name)111 public ObjectInstance createMBean(String className, ObjectName name) 112 throws ReflectionException, InstanceAlreadyExistsException, 113 MBeanRegistrationException, MBeanException, 114 NotCompliantMBeanException, IOException; 115 116 /** 117 * <p>Instantiates and registers an MBean in the MBean server. The 118 * class loader to be used is identified by its object name. An 119 * object name is associated with the MBean. If the object name of 120 * the loader is null, the ClassLoader that loaded the MBean 121 * server will be used. If the MBean's object name given is null, 122 * the MBean must provide its own name by implementing the {@link 123 * javax.management.MBeanRegistration MBeanRegistration} interface 124 * and returning the name from the {@link 125 * MBeanRegistration#preRegister preRegister} method.</p> 126 * 127 * <p>This method is equivalent to {@link 128 * #createMBean(String,ObjectName,ObjectName,Object[],String[]) 129 * createMBean(className, name, loaderName, (Object[]) null, 130 * (String[]) null)}.</p> 131 * 132 * @param className The class name of the MBean to be instantiated. 133 * @param name The object name of the MBean. May be null. 134 * @param loaderName The object name of the class loader to be used. 135 * 136 * @return An <CODE>ObjectInstance</CODE>, containing the 137 * <CODE>ObjectName</CODE> and the Java class name of the newly 138 * instantiated MBean. If the contained <code>ObjectName</code> 139 * is <code>n</code>, the contained Java class name is 140 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 141 * 142 * @exception ReflectionException Wraps a 143 * <CODE>java.lang.ClassNotFoundException</CODE> or a 144 * <CODE>java.lang.Exception</CODE> that occurred when trying to 145 * invoke the MBean's constructor. 146 * @exception InstanceAlreadyExistsException The MBean is already 147 * under the control of the MBean server. 148 * @exception MBeanRegistrationException The 149 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> 150 * interface) method of the MBean has thrown an exception. The 151 * MBean will not be registered. 152 * @exception RuntimeMBeanException If the MBean's constructor or its 153 * {@code preRegister} or {@code postRegister} method threw 154 * a {@code RuntimeException}. If the <CODE>postRegister</CODE> 155 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 156 * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will 157 * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation 158 * and registration succeeded. In such a case, the MBean will be actually 159 * registered even though the <CODE>createMBean</CODE> method 160 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 161 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 162 * will not be registered. 163 * @exception RuntimeErrorException If the <CODE>postRegister</CODE> 164 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 165 * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will 166 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation 167 * and registration succeeded. In such a case, the MBean will be actually 168 * registered even though the <CODE>createMBean</CODE> method 169 * threw an exception. Note that <CODE>RuntimeErrorException</CODE> can 170 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 171 * will not be registered. 172 * @exception MBeanException The constructor of the MBean has 173 * thrown an exception 174 * @exception NotCompliantMBeanException This class is not a JMX 175 * compliant MBean 176 * @exception InstanceNotFoundException The specified class loader 177 * is not registered in the MBean server. 178 * @exception RuntimeOperationsException Wraps a 179 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 180 * passed in parameter is null, the <CODE>ObjectName</CODE> passed 181 * in parameter contains a pattern or no <CODE>ObjectName</CODE> 182 * is specified for the MBean. 183 * @exception IOException A communication problem occurred when 184 * talking to the MBean server. 185 * @see javax.management.MBeanRegistration 186 */ createMBean(String className, ObjectName name, ObjectName loaderName)187 public ObjectInstance createMBean(String className, ObjectName name, 188 ObjectName loaderName) 189 throws ReflectionException, InstanceAlreadyExistsException, 190 MBeanRegistrationException, MBeanException, 191 NotCompliantMBeanException, InstanceNotFoundException, 192 IOException; 193 194 195 /** 196 * Instantiates and registers an MBean in the MBean server. The 197 * MBean server will use its {@link 198 * javax.management.loading.ClassLoaderRepository Default Loader 199 * Repository} to load the class of the MBean. An object name is 200 * associated with the MBean. If the object name given is null, the 201 * MBean must provide its own name by implementing the {@link 202 * javax.management.MBeanRegistration MBeanRegistration} interface 203 * and returning the name from the {@link 204 * MBeanRegistration#preRegister preRegister} method. 205 * 206 * @param className The class name of the MBean to be instantiated. 207 * @param name The object name of the MBean. May be null. 208 * @param params An array containing the parameters of the 209 * constructor to be invoked. 210 * @param signature An array containing the signature of the 211 * constructor to be invoked. 212 * 213 * @return An <CODE>ObjectInstance</CODE>, containing the 214 * <CODE>ObjectName</CODE> and the Java class name of the newly 215 * instantiated MBean. If the contained <code>ObjectName</code> 216 * is <code>n</code>, the contained Java class name is 217 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 218 * 219 * @exception ReflectionException Wraps a 220 * <CODE>java.lang.ClassNotFoundException</CODE> or a 221 * <CODE>java.lang.Exception</CODE> that occurred when trying to 222 * invoke the MBean's constructor. 223 * @exception InstanceAlreadyExistsException The MBean is already 224 * under the control of the MBean server. 225 * @exception MBeanRegistrationException The 226 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> 227 * interface) method of the MBean has thrown an exception. The 228 * MBean will not be registered. 229 * @exception RuntimeMBeanException If the MBean's constructor or its 230 * {@code preRegister} or {@code postRegister} method threw 231 * a {@code RuntimeException}. If the <CODE>postRegister</CODE> 232 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 233 * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will 234 * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation 235 * and registration succeeded. In such a case, the MBean will be actually 236 * registered even though the <CODE>createMBean</CODE> method 237 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 238 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 239 * will not be registered. 240 * @exception RuntimeErrorException If the <CODE>postRegister</CODE> 241 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 242 * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will 243 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation 244 * and registration succeeded. In such a case, the MBean will be actually 245 * registered even though the <CODE>createMBean</CODE> method 246 * threw an exception. Note that <CODE>RuntimeErrorException</CODE> can 247 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 248 * will not be registered. 249 * @exception MBeanException The constructor of the MBean has 250 * thrown an exception 251 * @exception NotCompliantMBeanException This class is not a JMX 252 * compliant MBean 253 * @exception RuntimeOperationsException Wraps a 254 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 255 * passed in parameter is null, the <CODE>ObjectName</CODE> passed 256 * in parameter contains a pattern or no <CODE>ObjectName</CODE> 257 * is specified for the MBean. 258 * @exception IOException A communication problem occurred when 259 * talking to the MBean server. 260 * @see javax.management.MBeanRegistration 261 */ createMBean(String className, ObjectName name, Object params[], String signature[])262 public ObjectInstance createMBean(String className, ObjectName name, 263 Object params[], String signature[]) 264 throws ReflectionException, InstanceAlreadyExistsException, 265 MBeanRegistrationException, MBeanException, 266 NotCompliantMBeanException, IOException; 267 268 /** 269 * <p>Instantiates and registers an MBean in the MBean server. The 270 * class loader to be used is identified by its object name. An 271 * object name is associated with the MBean. If the object name of 272 * the loader is not specified, the ClassLoader that loaded the 273 * MBean server will be used. If the MBean object name given is 274 * null, the MBean must provide its own name by implementing the 275 * {@link javax.management.MBeanRegistration MBeanRegistration} 276 * interface and returning the name from the {@link 277 * MBeanRegistration#preRegister preRegister} method. 278 * 279 * @param className The class name of the MBean to be instantiated. 280 * @param name The object name of the MBean. May be null. 281 * @param params An array containing the parameters of the 282 * constructor to be invoked. 283 * @param signature An array containing the signature of the 284 * constructor to be invoked. 285 * @param loaderName The object name of the class loader to be used. 286 * 287 * @return An <CODE>ObjectInstance</CODE>, containing the 288 * <CODE>ObjectName</CODE> and the Java class name of the newly 289 * instantiated MBean. If the contained <code>ObjectName</code> 290 * is <code>n</code>, the contained Java class name is 291 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 292 * 293 * @exception ReflectionException Wraps a 294 * <CODE>java.lang.ClassNotFoundException</CODE> or a 295 * <CODE>java.lang.Exception</CODE> that occurred when trying to 296 * invoke the MBean's constructor. 297 * @exception InstanceAlreadyExistsException The MBean is already 298 * under the control of the MBean server. 299 * @exception MBeanRegistrationException The 300 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> 301 * interface) method of the MBean has thrown an exception. The 302 * MBean will not be registered. 303 * @exception RuntimeMBeanException The MBean's constructor or its 304 * {@code preRegister} or {@code postRegister} method threw 305 * a {@code RuntimeException}. If the <CODE>postRegister</CODE> 306 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 307 * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will 308 * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation 309 * and registration succeeded. In such a case, the MBean will be actually 310 * registered even though the <CODE>createMBean</CODE> method 311 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 312 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 313 * will not be registered. 314 * @exception RuntimeErrorException If the <CODE>postRegister</CODE> method 315 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 316 * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will 317 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation 318 * and registration succeeded. In such a case, the MBean will be actually 319 * registered even though the <CODE>createMBean</CODE> method 320 * threw an exception. Note that <CODE>RuntimeErrorException</CODE> can 321 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 322 * will not be registered. 323 * @exception MBeanException The constructor of the MBean has 324 * thrown an exception 325 * @exception NotCompliantMBeanException This class is not a JMX 326 * compliant MBean 327 * @exception InstanceNotFoundException The specified class loader 328 * is not registered in the MBean server. 329 * @exception RuntimeOperationsException Wraps a 330 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 331 * passed in parameter is null, the <CODE>ObjectName</CODE> passed 332 * in parameter contains a pattern or no <CODE>ObjectName</CODE> 333 * is specified for the MBean. 334 * @exception IOException A communication problem occurred when 335 * talking to the MBean server. 336 * @see javax.management.MBeanRegistration 337 */ createMBean(String className, ObjectName name, ObjectName loaderName, Object params[], String signature[])338 public ObjectInstance createMBean(String className, ObjectName name, 339 ObjectName loaderName, Object params[], 340 String signature[]) 341 throws ReflectionException, InstanceAlreadyExistsException, 342 MBeanRegistrationException, MBeanException, 343 NotCompliantMBeanException, InstanceNotFoundException, 344 IOException; 345 346 /** 347 * Unregisters an MBean from the MBean server. The MBean is 348 * identified by its object name. Once the method has been 349 * invoked, the MBean may no longer be accessed by its object 350 * name. 351 * 352 * @param name The object name of the MBean to be unregistered. 353 * 354 * @exception InstanceNotFoundException The MBean specified is not 355 * registered in the MBean server. 356 * @exception MBeanRegistrationException The preDeregister 357 * ((<CODE>MBeanRegistration</CODE> interface) method of the MBean 358 * has thrown an exception. 359 * @exception RuntimeMBeanException If the <CODE>postDeregister</CODE> 360 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 361 * <CODE>RuntimeException</CODE>, the <CODE>unregisterMBean</CODE> method 362 * will throw a <CODE>RuntimeMBeanException</CODE>, although the MBean 363 * unregistration succeeded. In such a case, the MBean will be actually 364 * unregistered even though the <CODE>unregisterMBean</CODE> method 365 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 366 * also be thrown by <CODE>preDeregister</CODE>, in which case the MBean 367 * will remain registered. 368 * @exception RuntimeErrorException If the <CODE>postDeregister</CODE> 369 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 370 * <CODE>Error</CODE>, the <CODE>unregisterMBean</CODE> method will 371 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean 372 * unregistration succeeded. In such a case, the MBean will be actually 373 * unregistered even though the <CODE>unregisterMBean</CODE> method 374 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 375 * also be thrown by <CODE>preDeregister</CODE>, in which case the MBean 376 * will remain registered. 377 * @exception RuntimeOperationsException Wraps a 378 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 379 * name in parameter is null or the MBean you are when trying to 380 * unregister is the {@link javax.management.MBeanServerDelegate 381 * MBeanServerDelegate} MBean. 382 * @exception IOException A communication problem occurred when 383 * talking to the MBean server. 384 * @see javax.management.MBeanRegistration 385 */ unregisterMBean(ObjectName name)386 public void unregisterMBean(ObjectName name) 387 throws InstanceNotFoundException, MBeanRegistrationException, 388 IOException; 389 390 /** 391 * Gets the <CODE>ObjectInstance</CODE> for a given MBean 392 * registered with the MBean server. 393 * 394 * @param name The object name of the MBean. 395 * 396 * @return The <CODE>ObjectInstance</CODE> associated with the MBean 397 * specified by <VAR>name</VAR>. The contained <code>ObjectName</code> 398 * is <code>name</code> and the contained class name is 399 * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>. 400 * 401 * @exception InstanceNotFoundException The MBean specified is not 402 * registered in the MBean server. 403 * @exception IOException A communication problem occurred when 404 * talking to the MBean server. 405 */ getObjectInstance(ObjectName name)406 public ObjectInstance getObjectInstance(ObjectName name) 407 throws InstanceNotFoundException, IOException; 408 409 /** 410 * Gets MBeans controlled by the MBean server. This method allows 411 * any of the following to be obtained: All MBeans, a set of 412 * MBeans specified by pattern matching on the 413 * <CODE>ObjectName</CODE> and/or a Query expression, a specific 414 * MBean. When the object name is null or no domain and key 415 * properties are specified, all objects are to be selected (and 416 * filtered if a query is specified). It returns the set of 417 * <CODE>ObjectInstance</CODE> objects (containing the 418 * <CODE>ObjectName</CODE> and the Java Class name) for the 419 * selected MBeans. 420 * 421 * @param name The object name pattern identifying the MBeans to 422 * be retrieved. If null or no domain and key properties are 423 * specified, all the MBeans registered will be retrieved. 424 * @param query The query expression to be applied for selecting 425 * MBeans. If null no query expression will be applied for 426 * selecting MBeans. 427 * 428 * @return A set containing the <CODE>ObjectInstance</CODE> 429 * objects for the selected MBeans. If no MBean satisfies the 430 * query an empty list is returned. 431 * 432 * @exception IOException A communication problem occurred when 433 * talking to the MBean server. 434 */ queryMBeans(ObjectName name, QueryExp query)435 public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query) 436 throws IOException; 437 438 /** 439 * Gets the names of MBeans controlled by the MBean server. This 440 * method enables any of the following to be obtained: The names 441 * of all MBeans, the names of a set of MBeans specified by 442 * pattern matching on the <CODE>ObjectName</CODE> and/or a Query 443 * expression, a specific MBean name (equivalent to testing 444 * whether an MBean is registered). When the object name is null 445 * or no domain and key properties are specified, all objects are 446 * selected (and filtered if a query is specified). It returns the 447 * set of ObjectNames for the MBeans selected. 448 * 449 * @param name The object name pattern identifying the MBean names 450 * to be retrieved. If null or no domain and key properties are 451 * specified, the name of all registered MBeans will be retrieved. 452 * @param query The query expression to be applied for selecting 453 * MBeans. If null no query expression will be applied for 454 * selecting MBeans. 455 * 456 * @return A set containing the ObjectNames for the MBeans 457 * selected. If no MBean satisfies the query, an empty list is 458 * returned. 459 * 460 * @exception IOException A communication problem occurred when 461 * talking to the MBean server. 462 */ queryNames(ObjectName name, QueryExp query)463 public Set<ObjectName> queryNames(ObjectName name, QueryExp query) 464 throws IOException; 465 466 467 468 /** 469 * Checks whether an MBean, identified by its object name, is 470 * already registered with the MBean server. 471 * 472 * @param name The object name of the MBean to be checked. 473 * 474 * @return True if the MBean is already registered in the MBean 475 * server, false otherwise. 476 * 477 * @exception RuntimeOperationsException Wraps a 478 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 479 * name in parameter is null. 480 * @exception IOException A communication problem occurred when 481 * talking to the MBean server. 482 */ isRegistered(ObjectName name)483 public boolean isRegistered(ObjectName name) 484 throws IOException; 485 486 487 /** 488 * Returns the number of MBeans registered in the MBean server. 489 * 490 * @return the number of MBeans registered. 491 * 492 * @exception IOException A communication problem occurred when 493 * talking to the MBean server. 494 */ getMBeanCount()495 public Integer getMBeanCount() 496 throws IOException; 497 498 /** 499 * Gets the value of a specific attribute of a named MBean. The MBean 500 * is identified by its object name. 501 * 502 * @param name The object name of the MBean from which the 503 * attribute is to be retrieved. 504 * @param attribute A String specifying the name of the attribute 505 * to be retrieved. 506 * 507 * @return The value of the retrieved attribute. 508 * 509 * @exception AttributeNotFoundException The attribute specified 510 * is not accessible in the MBean. 511 * @exception MBeanException Wraps an exception thrown by the 512 * MBean's getter. 513 * @exception InstanceNotFoundException The MBean specified is not 514 * registered in the MBean server. 515 * @exception ReflectionException Wraps a 516 * <CODE>java.lang.Exception</CODE> thrown when trying to invoke 517 * the setter. 518 * @exception RuntimeOperationsException Wraps a 519 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 520 * name in parameter is null or the attribute in parameter is 521 * null. 522 * @exception IOException A communication problem occurred when 523 * talking to the MBean server. 524 * 525 * @see #setAttribute 526 */ getAttribute(ObjectName name, String attribute)527 public Object getAttribute(ObjectName name, String attribute) 528 throws MBeanException, AttributeNotFoundException, 529 InstanceNotFoundException, ReflectionException, 530 IOException; 531 532 533 /** 534 * <p>Retrieves the values of several attributes of a named MBean. The MBean 535 * is identified by its object name.</p> 536 * 537 * <p>If one or more attributes cannot be retrieved for some reason, they 538 * will be omitted from the returned {@code AttributeList}. The caller 539 * should check that the list is the same size as the {@code attributes} 540 * array. To discover what problem prevented a given attribute from being 541 * retrieved, call {@link #getAttribute getAttribute} for that attribute.</p> 542 * 543 * <p>Here is an example of calling this method and checking that it 544 * succeeded in retrieving all the requested attributes:</p> 545 * 546 * <pre> 547 * String[] attrNames = ...; 548 * AttributeList list = mbeanServerConnection.getAttributes(objectName, attrNames); 549 * if (list.size() == attrNames.length) 550 * System.out.println("All attributes were retrieved successfully"); 551 * else { 552 * {@code List<String>} missing = new {@code ArrayList<String>}(<!-- 553 * -->{@link java.util.Arrays#asList Arrays.asList}(attrNames)); 554 * for (Attribute a : list.asList()) 555 * missing.remove(a.getName()); 556 * System.out.println("Did not retrieve: " + missing); 557 * } 558 * </pre> 559 * 560 * @param name The object name of the MBean from which the 561 * attributes are retrieved. 562 * @param attributes A list of the attributes to be retrieved. 563 * 564 * @return The list of the retrieved attributes. 565 * 566 * @exception InstanceNotFoundException The MBean specified is not 567 * registered in the MBean server. 568 * @exception ReflectionException An exception occurred when 569 * trying to invoke the getAttributes method of a Dynamic MBean. 570 * @exception RuntimeOperationsException Wrap a 571 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 572 * name in parameter is null or attributes in parameter is null. 573 * @exception IOException A communication problem occurred when 574 * talking to the MBean server. 575 * 576 * @see #setAttributes 577 */ getAttributes(ObjectName name, String[] attributes)578 public AttributeList getAttributes(ObjectName name, String[] attributes) 579 throws InstanceNotFoundException, ReflectionException, 580 IOException; 581 582 583 /** 584 * Sets the value of a specific attribute of a named MBean. The MBean 585 * is identified by its object name. 586 * 587 * @param name The name of the MBean within which the attribute is 588 * to be set. 589 * @param attribute The identification of the attribute to be set 590 * and the value it is to be set to. 591 * 592 * @exception InstanceNotFoundException The MBean specified is not 593 * registered in the MBean server. 594 * @exception AttributeNotFoundException The attribute specified 595 * is not accessible in the MBean. 596 * @exception InvalidAttributeValueException The value specified 597 * for the attribute is not valid. 598 * @exception MBeanException Wraps an exception thrown by the 599 * MBean's setter. 600 * @exception ReflectionException Wraps a 601 * <CODE>java.lang.Exception</CODE> thrown when trying to invoke 602 * the setter. 603 * @exception RuntimeOperationsException Wraps a 604 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 605 * name in parameter is null or the attribute in parameter is 606 * null. 607 * @exception IOException A communication problem occurred when 608 * talking to the MBean server. 609 * 610 * @see #getAttribute 611 */ setAttribute(ObjectName name, Attribute attribute)612 public void setAttribute(ObjectName name, Attribute attribute) 613 throws InstanceNotFoundException, AttributeNotFoundException, 614 InvalidAttributeValueException, MBeanException, 615 ReflectionException, IOException; 616 617 618 /** 619 * <p>Sets the values of several attributes of a named MBean. The MBean is 620 * identified by its object name.</p> 621 * 622 * <p>If one or more attributes cannot be set for some reason, they will be 623 * omitted from the returned {@code AttributeList}. The caller should check 624 * that the input {@code AttributeList} is the same size as the output one. 625 * To discover what problem prevented a given attribute from being retrieved, 626 * it will usually be possible to call {@link #setAttribute setAttribute} 627 * for that attribute, although this is not guaranteed to work. (For 628 * example, the values of two attributes may have been rejected because 629 * they were inconsistent with each other. Setting one of them alone might 630 * be allowed.) 631 * 632 * <p>Here is an example of calling this method and checking that it 633 * succeeded in setting all the requested attributes:</p> 634 * 635 * <pre> 636 * AttributeList inputAttrs = ...; 637 * AttributeList outputAttrs = mbeanServerConnection.setAttributes(<!-- 638 * -->objectName, inputAttrs); 639 * if (inputAttrs.size() == outputAttrs.size()) 640 * System.out.println("All attributes were set successfully"); 641 * else { 642 * {@code List<String>} missing = new {@code ArrayList<String>}(); 643 * for (Attribute a : inputAttrs.asList()) 644 * missing.add(a.getName()); 645 * for (Attribute a : outputAttrs.asList()) 646 * missing.remove(a.getName()); 647 * System.out.println("Did not set: " + missing); 648 * } 649 * </pre> 650 * 651 * @param name The object name of the MBean within which the 652 * attributes are to be set. 653 * @param attributes A list of attributes: The identification of 654 * the attributes to be set and the values they are to be set to. 655 * 656 * @return The list of attributes that were set, with their new 657 * values. 658 * 659 * @exception InstanceNotFoundException The MBean specified is not 660 * registered in the MBean server. 661 * @exception ReflectionException An exception occurred when 662 * trying to invoke the getAttributes method of a Dynamic MBean. 663 * @exception RuntimeOperationsException Wraps a 664 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 665 * name in parameter is null or attributes in parameter is null. 666 * @exception IOException A communication problem occurred when 667 * talking to the MBean server. 668 * 669 * @see #getAttributes 670 */ setAttributes(ObjectName name, AttributeList attributes)671 public AttributeList setAttributes(ObjectName name, 672 AttributeList attributes) 673 throws InstanceNotFoundException, ReflectionException, IOException; 674 675 /** 676 * <p>Invokes an operation on an MBean.</p> 677 * 678 * <p>Because of the need for a {@code signature} to differentiate 679 * possibly-overloaded operations, it is much simpler to invoke operations 680 * through an {@linkplain JMX#newMBeanProxy(MBeanServerConnection, ObjectName, 681 * Class) MBean proxy} where possible. For example, suppose you have a 682 * Standard MBean interface like this:</p> 683 * 684 * <pre> 685 * public interface FooMBean { 686 * public int countMatches(String[] patterns, boolean ignoreCase); 687 * } 688 * </pre> 689 * 690 * <p>The {@code countMatches} operation can be invoked as follows:</p> 691 * 692 * <pre> 693 * String[] myPatterns = ...; 694 * int count = (Integer) mbeanServerConnection.invoke( 695 * objectName, 696 * "countMatches", 697 * new Object[] {myPatterns, true}, 698 * new String[] {String[].class.getName(), boolean.class.getName()}); 699 * </pre> 700 * 701 * <p>Alternatively, it can be invoked through a proxy as follows:</p> 702 * 703 * <pre> 704 * String[] myPatterns = ...; 705 * FooMBean fooProxy = JMX.newMBeanProxy( 706 * mbeanServerConnection, objectName, FooMBean.class); 707 * int count = fooProxy.countMatches(myPatterns, true); 708 * </pre> 709 * 710 * @param name The object name of the MBean on which the method is 711 * to be invoked. 712 * @param operationName The name of the operation to be invoked. 713 * @param params An array containing the parameters to be set when 714 * the operation is invoked 715 * @param signature An array containing the signature of the 716 * operation, an array of class names in the format returned by 717 * {@link Class#getName()}. The class objects will be loaded using the same 718 * class loader as the one used for loading the MBean on which the 719 * operation was invoked. 720 * 721 * @return The object returned by the operation, which represents 722 * the result of invoking the operation on the MBean specified. 723 * 724 * @exception InstanceNotFoundException The MBean specified is not 725 * registered in the MBean server. 726 * @exception MBeanException Wraps an exception thrown by the 727 * MBean's invoked method. 728 * @exception ReflectionException Wraps a 729 * <CODE>java.lang.Exception</CODE> thrown while trying to invoke 730 * the method. 731 * @exception IOException A communication problem occurred when 732 * talking to the MBean server. 733 * 734 */ invoke(ObjectName name, String operationName, Object params[], String signature[])735 public Object invoke(ObjectName name, String operationName, 736 Object params[], String signature[]) 737 throws InstanceNotFoundException, MBeanException, 738 ReflectionException, IOException; 739 740 741 742 /** 743 * Returns the default domain used for naming the MBean. 744 * The default domain name is used as the domain part in the ObjectName 745 * of MBeans if no domain is specified by the user. 746 * 747 * @return the default domain. 748 * 749 * @exception IOException A communication problem occurred when 750 * talking to the MBean server. 751 */ getDefaultDomain()752 public String getDefaultDomain() 753 throws IOException; 754 755 /** 756 * <p>Returns the list of domains in which any MBean is currently 757 * registered. A string is in the returned array if and only if 758 * there is at least one MBean registered with an ObjectName whose 759 * {@link ObjectName#getDomain() getDomain()} is equal to that 760 * string. The order of strings within the returned array is 761 * not defined.</p> 762 * 763 * @return the list of domains. 764 * 765 * @exception IOException A communication problem occurred when 766 * talking to the MBean server. 767 * 768 */ getDomains()769 public String[] getDomains() 770 throws IOException; 771 772 /** 773 * <p>Adds a listener to a registered MBean. 774 * Notifications emitted by the MBean will be forwarded to the listener.</p> 775 * 776 * @param name The name of the MBean on which the listener should 777 * be added. 778 * @param listener The listener object which will handle the 779 * notifications emitted by the registered MBean. 780 * @param filter The filter object. If filter is null, no 781 * filtering will be performed before handling notifications. 782 * @param handback The context to be sent to the listener when a 783 * notification is emitted. 784 * 785 * @exception InstanceNotFoundException The MBean name provided 786 * does not match any of the registered MBeans. 787 * @exception IOException A communication problem occurred when 788 * talking to the MBean server. 789 * 790 * @see #removeNotificationListener(ObjectName, NotificationListener) 791 * @see #removeNotificationListener(ObjectName, NotificationListener, 792 * NotificationFilter, Object) 793 */ addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback)794 public void addNotificationListener(ObjectName name, 795 NotificationListener listener, 796 NotificationFilter filter, 797 Object handback) 798 throws InstanceNotFoundException, IOException; 799 800 801 /** 802 * <p>Adds a listener to a registered MBean.</p> 803 * 804 * <p>A notification emitted by an MBean will be forwarded by the 805 * MBeanServer to the listener. If the source of the notification 806 * is a reference to an MBean object, the MBean server will 807 * replace it by that MBean's ObjectName. Otherwise the source is 808 * unchanged.</p> 809 * 810 * <p>The listener object that receives notifications is the one 811 * that is registered with the given name at the time this method 812 * is called. Even if it is subsequently unregistered, it will 813 * continue to receive notifications.</p> 814 * 815 * @param name The name of the MBean on which the listener should 816 * be added. 817 * @param listener The object name of the listener which will 818 * handle the notifications emitted by the registered MBean. 819 * @param filter The filter object. If filter is null, no 820 * filtering will be performed before handling notifications. 821 * @param handback The context to be sent to the listener when a 822 * notification is emitted. 823 * 824 * @exception InstanceNotFoundException The MBean name of the 825 * notification listener or of the notification broadcaster does 826 * not match any of the registered MBeans. 827 * @exception RuntimeOperationsException Wraps an {@link 828 * IllegalArgumentException}. The MBean named by 829 * <code>listener</code> exists but does not implement the {@link 830 * NotificationListener} interface. 831 * @exception IOException A communication problem occurred when 832 * talking to the MBean server. 833 * 834 * @see #removeNotificationListener(ObjectName, ObjectName) 835 * @see #removeNotificationListener(ObjectName, ObjectName, 836 * NotificationFilter, Object) 837 */ addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)838 public void addNotificationListener(ObjectName name, 839 ObjectName listener, 840 NotificationFilter filter, 841 Object handback) 842 throws InstanceNotFoundException, IOException; 843 844 845 /** 846 * Removes a listener from a registered MBean. 847 * 848 * <P> If the listener is registered more than once, perhaps with 849 * different filters or callbacks, this method will remove all 850 * those registrations. 851 * 852 * @param name The name of the MBean on which the listener should 853 * be removed. 854 * @param listener The object name of the listener to be removed. 855 * 856 * @exception InstanceNotFoundException The MBean name provided 857 * does not match any of the registered MBeans. 858 * @exception ListenerNotFoundException The listener is not 859 * registered in the MBean. 860 * @exception IOException A communication problem occurred when 861 * talking to the MBean server. 862 * 863 * @see #addNotificationListener(ObjectName, ObjectName, 864 * NotificationFilter, Object) 865 */ removeNotificationListener(ObjectName name, ObjectName listener)866 public void removeNotificationListener(ObjectName name, 867 ObjectName listener) 868 throws InstanceNotFoundException, ListenerNotFoundException, 869 IOException; 870 871 /** 872 * <p>Removes a listener from a registered MBean.</p> 873 * 874 * <p>The MBean must have a listener that exactly matches the 875 * given <code>listener</code>, <code>filter</code>, and 876 * <code>handback</code> parameters. If there is more than one 877 * such listener, only one is removed.</p> 878 * 879 * <p>The <code>filter</code> and <code>handback</code> parameters 880 * may be null if and only if they are null in a listener to be 881 * removed.</p> 882 * 883 * @param name The name of the MBean on which the listener should 884 * be removed. 885 * @param listener The object name of the listener to be removed. 886 * @param filter The filter that was specified when the listener 887 * was added. 888 * @param handback The handback that was specified when the 889 * listener was added. 890 * 891 * @exception InstanceNotFoundException The MBean name provided 892 * does not match any of the registered MBeans. 893 * @exception ListenerNotFoundException The listener is not 894 * registered in the MBean, or it is not registered with the given 895 * filter and handback. 896 * @exception IOException A communication problem occurred when 897 * talking to the MBean server. 898 * 899 * @see #addNotificationListener(ObjectName, ObjectName, 900 * NotificationFilter, Object) 901 * 902 */ removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)903 public void removeNotificationListener(ObjectName name, 904 ObjectName listener, 905 NotificationFilter filter, 906 Object handback) 907 throws InstanceNotFoundException, ListenerNotFoundException, 908 IOException; 909 910 911 /** 912 * <p>Removes a listener from a registered MBean.</p> 913 * 914 * <P> If the listener is registered more than once, perhaps with 915 * different filters or callbacks, this method will remove all 916 * those registrations. 917 * 918 * @param name The name of the MBean on which the listener should 919 * be removed. 920 * @param listener The listener to be removed. 921 * 922 * @exception InstanceNotFoundException The MBean name provided 923 * does not match any of the registered MBeans. 924 * @exception ListenerNotFoundException The listener is not 925 * registered in the MBean. 926 * @exception IOException A communication problem occurred when 927 * talking to the MBean server. 928 * 929 * @see #addNotificationListener(ObjectName, NotificationListener, 930 * NotificationFilter, Object) 931 */ removeNotificationListener(ObjectName name, NotificationListener listener)932 public void removeNotificationListener(ObjectName name, 933 NotificationListener listener) 934 throws InstanceNotFoundException, ListenerNotFoundException, 935 IOException; 936 937 /** 938 * <p>Removes a listener from a registered MBean.</p> 939 * 940 * <p>The MBean must have a listener that exactly matches the 941 * given <code>listener</code>, <code>filter</code>, and 942 * <code>handback</code> parameters. If there is more than one 943 * such listener, only one is removed.</p> 944 * 945 * <p>The <code>filter</code> and <code>handback</code> parameters 946 * may be null if and only if they are null in a listener to be 947 * removed.</p> 948 * 949 * @param name The name of the MBean on which the listener should 950 * be removed. 951 * @param listener The listener to be removed. 952 * @param filter The filter that was specified when the listener 953 * was added. 954 * @param handback The handback that was specified when the 955 * listener was added. 956 * 957 * @exception InstanceNotFoundException The MBean name provided 958 * does not match any of the registered MBeans. 959 * @exception ListenerNotFoundException The listener is not 960 * registered in the MBean, or it is not registered with the given 961 * filter and handback. 962 * @exception IOException A communication problem occurred when 963 * talking to the MBean server. 964 * 965 * @see #addNotificationListener(ObjectName, NotificationListener, 966 * NotificationFilter, Object) 967 * 968 */ removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback)969 public void removeNotificationListener(ObjectName name, 970 NotificationListener listener, 971 NotificationFilter filter, 972 Object handback) 973 throws InstanceNotFoundException, ListenerNotFoundException, 974 IOException; 975 976 /** 977 * This method discovers the attributes and operations that an 978 * MBean exposes for management. 979 * 980 * @param name The name of the MBean to analyze 981 * 982 * @return An instance of <CODE>MBeanInfo</CODE> allowing the 983 * retrieval of all attributes and operations of this MBean. 984 * 985 * @exception IntrospectionException An exception occurred during 986 * introspection. 987 * @exception InstanceNotFoundException The MBean specified was 988 * not found. 989 * @exception ReflectionException An exception occurred when 990 * trying to invoke the getMBeanInfo of a Dynamic MBean. 991 * @exception IOException A communication problem occurred when 992 * talking to the MBean server. 993 */ getMBeanInfo(ObjectName name)994 public MBeanInfo getMBeanInfo(ObjectName name) 995 throws InstanceNotFoundException, IntrospectionException, 996 ReflectionException, IOException; 997 998 999 /** 1000 * <p>Returns true if the MBean specified is an instance of the 1001 * specified class, false otherwise.</p> 1002 * 1003 * <p>If <code>name</code> does not name an MBean, this method 1004 * throws {@link InstanceNotFoundException}.</p> 1005 * 1006 * <p>Otherwise, let<br> 1007 * X be the MBean named by <code>name</code>,<br> 1008 * L be the ClassLoader of X,<br> 1009 * N be the class name in X's {@link MBeanInfo}.</p> 1010 * 1011 * <p>If N equals <code>className</code>, the result is true.</p> 1012 * 1013 * <p>Otherwise, if L successfully loads <code>className</code> 1014 * and X is an instance of this class, the result is true. 1015 * 1016 * <p>Otherwise, if L successfully loads both N and 1017 * <code>className</code>, and the second class is assignable from 1018 * the first, the result is true.</p> 1019 * 1020 * <p>Otherwise, the result is false.</p> 1021 * 1022 * @param name The <CODE>ObjectName</CODE> of the MBean. 1023 * @param className The name of the class. 1024 * 1025 * @return true if the MBean specified is an instance of the 1026 * specified class according to the rules above, false otherwise. 1027 * 1028 * @exception InstanceNotFoundException The MBean specified is not 1029 * registered in the MBean server. 1030 * @exception IOException A communication problem occurred when 1031 * talking to the MBean server. 1032 * 1033 * @see Class#isInstance 1034 */ isInstanceOf(ObjectName name, String className)1035 public boolean isInstanceOf(ObjectName name, String className) 1036 throws InstanceNotFoundException, IOException; 1037 } 1038