J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2002-2007 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any 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 to 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 MBeanException The constructor of the MBean has |
| 79 | * thrown an exception |
| 80 | * @exception NotCompliantMBeanException This class is not a JMX |
| 81 | * compliant MBean |
| 82 | * @exception RuntimeOperationsException Wraps a |
| 83 | * <CODE>java.lang.IllegalArgumentException</CODE>: The className |
| 84 | * passed in parameter is null, the <CODE>ObjectName</CODE> passed |
| 85 | * in parameter contains a pattern or no <CODE>ObjectName</CODE> |
| 86 | * is specified for the MBean. |
| 87 | * @exception IOException A communication problem occurred when |
| 88 | * talking to the MBean server. |
| 89 | * |
| 90 | */ |
| 91 | public ObjectInstance createMBean(String className, ObjectName name) |
| 92 | throws ReflectionException, InstanceAlreadyExistsException, |
| 93 | MBeanRegistrationException, MBeanException, |
| 94 | NotCompliantMBeanException, IOException; |
| 95 | |
| 96 | /** |
| 97 | * <p>Instantiates and registers an MBean in the MBean server. The |
| 98 | * class loader to be used is identified by its object name. An |
| 99 | * object name is associated to the MBean. If the object name of |
| 100 | * the loader is null, the ClassLoader that loaded the MBean |
| 101 | * server will be used. If the MBean's object name given is null, |
| 102 | * the MBean must provide its own name by implementing the {@link |
| 103 | * javax.management.MBeanRegistration MBeanRegistration} interface |
| 104 | * and returning the name from the {@link |
| 105 | * MBeanRegistration#preRegister preRegister} method.</p> |
| 106 | * |
| 107 | * <p>This method is equivalent to {@link |
| 108 | * #createMBean(String,ObjectName,ObjectName,Object[],String[]) |
| 109 | * createMBean(className, name, loaderName, (Object[]) null, |
| 110 | * (String[]) null)}.</p> |
| 111 | * |
| 112 | * @param className The class name of the MBean to be instantiated. |
| 113 | * @param name The object name of the MBean. May be null. |
| 114 | * @param loaderName The object name of the class loader to be used. |
| 115 | * |
| 116 | * @return An <CODE>ObjectInstance</CODE>, containing the |
| 117 | * <CODE>ObjectName</CODE> and the Java class name of the newly |
| 118 | * instantiated MBean. If the contained <code>ObjectName</code> |
| 119 | * is <code>n</code>, the contained Java class name is |
| 120 | * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. |
| 121 | * |
| 122 | * @exception ReflectionException Wraps a |
| 123 | * <CODE>java.lang.ClassNotFoundException</CODE> or a |
| 124 | * <CODE>java.lang.Exception</CODE> that occurred when trying to |
| 125 | * invoke the MBean's constructor. |
| 126 | * @exception InstanceAlreadyExistsException The MBean is already |
| 127 | * under the control of the MBean server. |
| 128 | * @exception MBeanRegistrationException The |
| 129 | * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> |
| 130 | * interface) method of the MBean has thrown an exception. The |
| 131 | * MBean will not be registered. |
| 132 | * @exception MBeanException The constructor of the MBean has |
| 133 | * thrown an exception |
| 134 | * @exception NotCompliantMBeanException This class is not a JMX |
| 135 | * compliant MBean |
| 136 | * @exception InstanceNotFoundException The specified class loader |
| 137 | * is not registered in the MBean server. |
| 138 | * @exception RuntimeOperationsException Wraps a |
| 139 | * <CODE>java.lang.IllegalArgumentException</CODE>: The className |
| 140 | * passed in parameter is null, the <CODE>ObjectName</CODE> passed |
| 141 | * in parameter contains a pattern or no <CODE>ObjectName</CODE> |
| 142 | * is specified for the MBean. |
| 143 | * @exception IOException A communication problem occurred when |
| 144 | * talking to the MBean server. |
| 145 | */ |
| 146 | public ObjectInstance createMBean(String className, ObjectName name, |
| 147 | ObjectName loaderName) |
| 148 | throws ReflectionException, InstanceAlreadyExistsException, |
| 149 | MBeanRegistrationException, MBeanException, |
| 150 | NotCompliantMBeanException, InstanceNotFoundException, |
| 151 | IOException; |
| 152 | |
| 153 | |
| 154 | /** |
| 155 | * Instantiates and registers an MBean in the MBean server. The |
| 156 | * MBean server will use its {@link |
| 157 | * javax.management.loading.ClassLoaderRepository Default Loader |
| 158 | * Repository} to load the class of the MBean. An object name is |
| 159 | * associated to the MBean. If the object name given is null, the |
| 160 | * MBean must provide its own name by implementing the {@link |
| 161 | * javax.management.MBeanRegistration MBeanRegistration} interface |
| 162 | * and returning the name from the {@link |
| 163 | * MBeanRegistration#preRegister preRegister} method. |
| 164 | * |
| 165 | * @param className The class name of the MBean to be instantiated. |
| 166 | * @param name The object name of the MBean. May be null. |
| 167 | * @param params An array containing the parameters of the |
| 168 | * constructor to be invoked. |
| 169 | * @param signature An array containing the signature of the |
| 170 | * constructor to be invoked. |
| 171 | * |
| 172 | * @return An <CODE>ObjectInstance</CODE>, containing the |
| 173 | * <CODE>ObjectName</CODE> and the Java class name of the newly |
| 174 | * instantiated MBean. If the contained <code>ObjectName</code> |
| 175 | * is <code>n</code>, the contained Java class name is |
| 176 | * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. |
| 177 | * |
| 178 | * @exception ReflectionException Wraps a |
| 179 | * <CODE>java.lang.ClassNotFoundException</CODE> or a |
| 180 | * <CODE>java.lang.Exception</CODE> that occurred when trying to |
| 181 | * invoke the MBean's constructor. |
| 182 | * @exception InstanceAlreadyExistsException The MBean is already |
| 183 | * under the control of the MBean server. |
| 184 | * @exception MBeanRegistrationException The |
| 185 | * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> |
| 186 | * interface) method of the MBean has thrown an exception. The |
| 187 | * MBean will not be registered. |
| 188 | * @exception MBeanException The constructor of the MBean has |
| 189 | * thrown an exception |
| 190 | * @exception NotCompliantMBeanException This class is not a JMX |
| 191 | * compliant MBean |
| 192 | * @exception RuntimeOperationsException Wraps a |
| 193 | * <CODE>java.lang.IllegalArgumentException</CODE>: The className |
| 194 | * passed in parameter is null, the <CODE>ObjectName</CODE> passed |
| 195 | * in parameter contains a pattern or no <CODE>ObjectName</CODE> |
| 196 | * is specified for the MBean. |
| 197 | * @exception IOException A communication problem occurred when |
| 198 | * talking to the MBean server. |
| 199 | * |
| 200 | */ |
| 201 | public ObjectInstance createMBean(String className, ObjectName name, |
| 202 | Object params[], String signature[]) |
| 203 | throws ReflectionException, InstanceAlreadyExistsException, |
| 204 | MBeanRegistrationException, MBeanException, |
| 205 | NotCompliantMBeanException, IOException; |
| 206 | |
| 207 | /** |
| 208 | * Instantiates and registers an MBean in the MBean server. The |
| 209 | * class loader to be used is identified by its object name. An |
| 210 | * object name is associated to the MBean. If the object name of |
| 211 | * the loader is not specified, the ClassLoader that loaded the |
| 212 | * MBean server will be used. If the MBean object name given is |
| 213 | * null, the MBean must provide its own name by implementing the |
| 214 | * {@link javax.management.MBeanRegistration MBeanRegistration} |
| 215 | * interface and returning the name from the {@link |
| 216 | * MBeanRegistration#preRegister preRegister} method. |
| 217 | * |
| 218 | * @param className The class name of the MBean to be instantiated. |
| 219 | * @param name The object name of the MBean. May be null. |
| 220 | * @param params An array containing the parameters of the |
| 221 | * constructor to be invoked. |
| 222 | * @param signature An array containing the signature of the |
| 223 | * constructor to be invoked. |
| 224 | * @param loaderName The object name of the class loader to be used. |
| 225 | * |
| 226 | * @return An <CODE>ObjectInstance</CODE>, containing the |
| 227 | * <CODE>ObjectName</CODE> and the Java class name of the newly |
| 228 | * instantiated MBean. If the contained <code>ObjectName</code> |
| 229 | * is <code>n</code>, the contained Java class name is |
| 230 | * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. |
| 231 | * |
| 232 | * @exception ReflectionException Wraps a |
| 233 | * <CODE>java.lang.ClassNotFoundException</CODE> or a |
| 234 | * <CODE>java.lang.Exception</CODE> that occurred when trying to |
| 235 | * invoke the MBean's constructor. |
| 236 | * @exception InstanceAlreadyExistsException The MBean is already |
| 237 | * under the control of the MBean server. |
| 238 | * @exception MBeanRegistrationException The |
| 239 | * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> |
| 240 | * interface) method of the MBean has thrown an exception. The |
| 241 | * MBean will not be registered. |
| 242 | * @exception MBeanException The constructor of the MBean has |
| 243 | * thrown an exception |
| 244 | * @exception NotCompliantMBeanException This class is not a JMX |
| 245 | * compliant MBean |
| 246 | * @exception InstanceNotFoundException The specified class loader |
| 247 | * is not registered in the MBean server. |
| 248 | * @exception RuntimeOperationsException Wraps a |
| 249 | * <CODE>java.lang.IllegalArgumentException</CODE>: The className |
| 250 | * passed in parameter is null, the <CODE>ObjectName</CODE> passed |
| 251 | * in parameter contains a pattern or no <CODE>ObjectName</CODE> |
| 252 | * is specified for the MBean. |
| 253 | * @exception IOException A communication problem occurred when |
| 254 | * talking to the MBean server. |
| 255 | * |
| 256 | */ |
| 257 | public ObjectInstance createMBean(String className, ObjectName name, |
| 258 | ObjectName loaderName, Object params[], |
| 259 | String signature[]) |
| 260 | throws ReflectionException, InstanceAlreadyExistsException, |
| 261 | MBeanRegistrationException, MBeanException, |
| 262 | NotCompliantMBeanException, InstanceNotFoundException, |
| 263 | IOException; |
| 264 | |
| 265 | /** |
| 266 | * Unregisters an MBean from the MBean server. The MBean is |
| 267 | * identified by its object name. Once the method has been |
| 268 | * invoked, the MBean may no longer be accessed by its object |
| 269 | * name. |
| 270 | * |
| 271 | * @param name The object name of the MBean to be unregistered. |
| 272 | * |
| 273 | * @exception InstanceNotFoundException The MBean specified is not |
| 274 | * registered in the MBean server. |
| 275 | * @exception MBeanRegistrationException The preDeregister |
| 276 | * ((<CODE>MBeanRegistration</CODE> interface) method of the MBean |
| 277 | * has thrown an exception. |
| 278 | * @exception RuntimeOperationsException Wraps a |
| 279 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 280 | * name in parameter is null or the MBean you are when trying to |
| 281 | * unregister is the {@link javax.management.MBeanServerDelegate |
| 282 | * MBeanServerDelegate} MBean. |
| 283 | * @exception IOException A communication problem occurred when |
| 284 | * talking to the MBean server. |
| 285 | * |
| 286 | */ |
| 287 | public void unregisterMBean(ObjectName name) |
| 288 | throws InstanceNotFoundException, MBeanRegistrationException, |
| 289 | IOException; |
| 290 | |
| 291 | /** |
| 292 | * Gets the <CODE>ObjectInstance</CODE> for a given MBean |
| 293 | * registered with the MBean server. |
| 294 | * |
| 295 | * @param name The object name of the MBean. |
| 296 | * |
| 297 | * @return The <CODE>ObjectInstance</CODE> associated with the MBean |
| 298 | * specified by <VAR>name</VAR>. The contained <code>ObjectName</code> |
| 299 | * is <code>name</code> and the contained class name is |
| 300 | * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>. |
| 301 | * |
| 302 | * @exception InstanceNotFoundException The MBean specified is not |
| 303 | * registered in the MBean server. |
| 304 | * @exception IOException A communication problem occurred when |
| 305 | * talking to the MBean server. |
| 306 | */ |
| 307 | public ObjectInstance getObjectInstance(ObjectName name) |
| 308 | throws InstanceNotFoundException, IOException; |
| 309 | |
| 310 | /** |
| 311 | * Gets MBeans controlled by the MBean server. This method allows |
| 312 | * any of the following to be obtained: All MBeans, a set of |
| 313 | * MBeans specified by pattern matching on the |
| 314 | * <CODE>ObjectName</CODE> and/or a Query expression, a specific |
| 315 | * MBean. When the object name is null or no domain and key |
| 316 | * properties are specified, all objects are to be selected (and |
| 317 | * filtered if a query is specified). It returns the set of |
| 318 | * <CODE>ObjectInstance</CODE> objects (containing the |
| 319 | * <CODE>ObjectName</CODE> and the Java Class name) for the |
| 320 | * selected MBeans. |
| 321 | * |
| 322 | * @param name The object name pattern identifying the MBeans to |
| 323 | * be retrieved. If null or no domain and key properties are |
| 324 | * specified, all the MBeans registered will be retrieved. |
| 325 | * @param query The query expression to be applied for selecting |
| 326 | * MBeans. If null no query expression will be applied for |
| 327 | * selecting MBeans. |
| 328 | * |
| 329 | * @return A set containing the <CODE>ObjectInstance</CODE> |
| 330 | * objects for the selected MBeans. If no MBean satisfies the |
| 331 | * query an empty list is returned. |
| 332 | * |
| 333 | * @exception IOException A communication problem occurred when |
| 334 | * talking to the MBean server. |
| 335 | */ |
| 336 | public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query) |
| 337 | throws IOException; |
| 338 | |
| 339 | /** |
| 340 | * Gets the names of MBeans controlled by the MBean server. This |
| 341 | * method enables any of the following to be obtained: The names |
| 342 | * of all MBeans, the names of a set of MBeans specified by |
| 343 | * pattern matching on the <CODE>ObjectName</CODE> and/or a Query |
| 344 | * expression, a specific MBean name (equivalent to testing |
| 345 | * whether an MBean is registered). When the object name is null |
| 346 | * or no domain and key properties are specified, all objects are |
| 347 | * selected (and filtered if a query is specified). It returns the |
| 348 | * set of ObjectNames for the MBeans selected. |
| 349 | * |
| 350 | * @param name The object name pattern identifying the MBean names |
| 351 | * to be retrieved. If null or no domain and key properties are |
| 352 | * specified, the name of all registered MBeans will be retrieved. |
| 353 | * @param query The query expression to be applied for selecting |
| 354 | * MBeans. If null no query expression will be applied for |
| 355 | * selecting MBeans. |
| 356 | * |
| 357 | * @return A set containing the ObjectNames for the MBeans |
| 358 | * selected. If no MBean satisfies the query, an empty list is |
| 359 | * returned. |
| 360 | * |
| 361 | * @exception IOException A communication problem occurred when |
| 362 | * talking to the MBean server. |
| 363 | */ |
| 364 | public Set<ObjectName> queryNames(ObjectName name, QueryExp query) |
| 365 | throws IOException; |
| 366 | |
| 367 | |
| 368 | |
| 369 | /** |
| 370 | * Checks whether an MBean, identified by its object name, is |
| 371 | * already registered with the MBean server. |
| 372 | * |
| 373 | * @param name The object name of the MBean to be checked. |
| 374 | * |
| 375 | * @return True if the MBean is already registered in the MBean |
| 376 | * server, false otherwise. |
| 377 | * |
| 378 | * @exception RuntimeOperationsException Wraps a |
| 379 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 380 | * name in parameter is null. |
| 381 | * @exception IOException A communication problem occurred when |
| 382 | * talking to the MBean server. |
| 383 | */ |
| 384 | public boolean isRegistered(ObjectName name) |
| 385 | throws IOException; |
| 386 | |
| 387 | |
| 388 | /** |
| 389 | * Returns the number of MBeans registered in the MBean server. |
| 390 | * |
| 391 | * @return the number of MBeans registered. |
| 392 | * |
| 393 | * @exception IOException A communication problem occurred when |
| 394 | * talking to the MBean server. |
| 395 | */ |
| 396 | public Integer getMBeanCount() |
| 397 | throws IOException; |
| 398 | |
| 399 | /** |
| 400 | * Gets the value of a specific attribute of a named MBean. The MBean |
| 401 | * is identified by its object name. |
| 402 | * |
| 403 | * @param name The object name of the MBean from which the |
| 404 | * attribute is to be retrieved. |
| 405 | * @param attribute A String specifying the name of the attribute |
| 406 | * to be retrieved. |
| 407 | * |
| 408 | * @return The value of the retrieved attribute. |
| 409 | * |
| 410 | * @exception AttributeNotFoundException The attribute specified |
| 411 | * is not accessible in the MBean. |
| 412 | * @exception MBeanException Wraps an exception thrown by the |
| 413 | * MBean's getter. |
| 414 | * @exception InstanceNotFoundException The MBean specified is not |
| 415 | * registered in the MBean server. |
| 416 | * @exception ReflectionException Wraps a |
| 417 | * <CODE>java.lang.Exception</CODE> thrown when trying to invoke |
| 418 | * the setter. |
| 419 | * @exception RuntimeOperationsException Wraps a |
| 420 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 421 | * name in parameter is null or the attribute in parameter is |
| 422 | * null. |
| 423 | * @exception IOException A communication problem occurred when |
| 424 | * talking to the MBean server. |
| 425 | * |
| 426 | * @see #setAttribute |
| 427 | */ |
| 428 | public Object getAttribute(ObjectName name, String attribute) |
| 429 | throws MBeanException, AttributeNotFoundException, |
| 430 | InstanceNotFoundException, ReflectionException, |
| 431 | IOException; |
| 432 | |
| 433 | |
| 434 | /** |
| 435 | * Enables the values of several attributes of a named MBean. The MBean |
| 436 | * is identified by its object name. |
| 437 | * |
| 438 | * @param name The object name of the MBean from which the |
| 439 | * attributes are retrieved. |
| 440 | * @param attributes A list of the attributes to be retrieved. |
| 441 | * |
| 442 | * @return The list of the retrieved attributes. |
| 443 | * |
| 444 | * @exception InstanceNotFoundException The MBean specified is not |
| 445 | * registered in the MBean server. |
| 446 | * @exception ReflectionException An exception occurred when |
| 447 | * trying to invoke the getAttributes method of a Dynamic MBean. |
| 448 | * @exception RuntimeOperationsException Wrap a |
| 449 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 450 | * name in parameter is null or attributes in parameter is null. |
| 451 | * @exception IOException A communication problem occurred when |
| 452 | * talking to the MBean server. |
| 453 | * |
| 454 | * @see #setAttributes |
| 455 | */ |
| 456 | public AttributeList getAttributes(ObjectName name, String[] attributes) |
| 457 | throws InstanceNotFoundException, ReflectionException, |
| 458 | IOException; |
| 459 | |
| 460 | /** |
| 461 | * Sets the value of a specific attribute of a named MBean. The MBean |
| 462 | * is identified by its object name. |
| 463 | * |
| 464 | * @param name The name of the MBean within which the attribute is |
| 465 | * to be set. |
| 466 | * @param attribute The identification of the attribute to be set |
| 467 | * and the value it is to be set to. |
| 468 | * |
| 469 | * @exception InstanceNotFoundException The MBean specified is not |
| 470 | * registered in the MBean server. |
| 471 | * @exception AttributeNotFoundException The attribute specified |
| 472 | * is not accessible in the MBean. |
| 473 | * @exception InvalidAttributeValueException The value specified |
| 474 | * for the attribute is not valid. |
| 475 | * @exception MBeanException Wraps an exception thrown by the |
| 476 | * MBean's setter. |
| 477 | * @exception ReflectionException Wraps a |
| 478 | * <CODE>java.lang.Exception</CODE> thrown when trying to invoke |
| 479 | * the setter. |
| 480 | * @exception RuntimeOperationsException Wraps a |
| 481 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 482 | * name in parameter is null or the attribute in parameter is |
| 483 | * null. |
| 484 | * @exception IOException A communication problem occurred when |
| 485 | * talking to the MBean server. |
| 486 | * |
| 487 | * @see #getAttribute |
| 488 | */ |
| 489 | public void setAttribute(ObjectName name, Attribute attribute) |
| 490 | throws InstanceNotFoundException, AttributeNotFoundException, |
| 491 | InvalidAttributeValueException, MBeanException, |
| 492 | ReflectionException, IOException; |
| 493 | |
| 494 | |
| 495 | |
| 496 | /** |
| 497 | * Sets the values of several attributes of a named MBean. The MBean is |
| 498 | * identified by its object name. |
| 499 | * |
| 500 | * @param name The object name of the MBean within which the |
| 501 | * attributes are to be set. |
| 502 | * @param attributes A list of attributes: The identification of |
| 503 | * the attributes to be set and the values they are to be set to. |
| 504 | * |
| 505 | * @return The list of attributes that were set, with their new |
| 506 | * values. |
| 507 | * |
| 508 | * @exception InstanceNotFoundException The MBean specified is not |
| 509 | * registered in the MBean server. |
| 510 | * @exception ReflectionException An exception occurred when |
| 511 | * trying to invoke the getAttributes method of a Dynamic MBean. |
| 512 | * @exception RuntimeOperationsException Wraps a |
| 513 | * <CODE>java.lang.IllegalArgumentException</CODE>: The object |
| 514 | * name in parameter is null or attributes in parameter is null. |
| 515 | * @exception IOException A communication problem occurred when |
| 516 | * talking to the MBean server. |
| 517 | * |
| 518 | * @see #getAttributes |
| 519 | */ |
| 520 | public AttributeList setAttributes(ObjectName name, |
| 521 | AttributeList attributes) |
| 522 | throws InstanceNotFoundException, ReflectionException, IOException; |
| 523 | |
| 524 | /** |
| 525 | * Invokes an operation on an MBean. |
| 526 | * |
| 527 | * @param name The object name of the MBean on which the method is |
| 528 | * to be invoked. |
| 529 | * @param operationName The name of the operation to be invoked. |
| 530 | * @param params An array containing the parameters to be set when |
| 531 | * the operation is invoked |
| 532 | * @param signature An array containing the signature of the |
| 533 | * operation. The class objects will be loaded using the same |
| 534 | * class loader as the one used for loading the MBean on which the |
| 535 | * operation was invoked. |
| 536 | * |
| 537 | * @return The object returned by the operation, which represents |
| 538 | * the result of invoking the operation on the MBean specified. |
| 539 | * |
| 540 | * @exception InstanceNotFoundException The MBean specified is not |
| 541 | * registered in the MBean server. |
| 542 | * @exception MBeanException Wraps an exception thrown by the |
| 543 | * MBean's invoked method. |
| 544 | * @exception ReflectionException Wraps a |
| 545 | * <CODE>java.lang.Exception</CODE> thrown while trying to invoke |
| 546 | * the method. |
| 547 | * @exception IOException A communication problem occurred when |
| 548 | * talking to the MBean server. |
| 549 | * |
| 550 | */ |
| 551 | public Object invoke(ObjectName name, String operationName, |
| 552 | Object params[], String signature[]) |
| 553 | throws InstanceNotFoundException, MBeanException, |
| 554 | ReflectionException, IOException; |
| 555 | |
| 556 | |
| 557 | |
| 558 | /** |
| 559 | * Returns the default domain used for naming the MBean. |
| 560 | * The default domain name is used as the domain part in the ObjectName |
| 561 | * of MBeans if no domain is specified by the user. |
| 562 | * |
| 563 | * @return the default domain. |
| 564 | * |
| 565 | * @exception IOException A communication problem occurred when |
| 566 | * talking to the MBean server. |
| 567 | */ |
| 568 | public String getDefaultDomain() |
| 569 | throws IOException; |
| 570 | |
| 571 | /** |
| 572 | * <p>Returns the list of domains in which any MBean is currently |
| 573 | * registered. A string is in the returned array if and only if |
| 574 | * there is at least one MBean registered with an ObjectName whose |
| 575 | * {@link ObjectName#getDomain() getDomain()} is equal to that |
| 576 | * string. The order of strings within the returned array is |
| 577 | * not defined.</p> |
| 578 | * |
| 579 | * @return the list of domains. |
| 580 | * |
| 581 | * @exception IOException A communication problem occurred when |
| 582 | * talking to the MBean server. |
| 583 | * |
| 584 | */ |
| 585 | public String[] getDomains() |
| 586 | throws IOException; |
| 587 | |
| 588 | /** |
| 589 | * <p>Adds a listener to a registered MBean.</p> |
| 590 | * |
| 591 | * <P> A notification emitted by an MBean will be forwarded by the |
| 592 | * MBeanServer to the listener. If the source of the notification |
| 593 | * is a reference to an MBean object, the MBean server will replace it |
| 594 | * by that MBean's ObjectName. Otherwise the source is unchanged. |
| 595 | * |
| 596 | * @param name The name of the MBean on which the listener should |
| 597 | * be added. |
| 598 | * @param listener The listener object which will handle the |
| 599 | * notifications emitted by the registered MBean. |
| 600 | * @param filter The filter object. If filter is null, no |
| 601 | * filtering will be performed before handling notifications. |
| 602 | * @param handback The context to be sent to the listener when a |
| 603 | * notification is emitted. |
| 604 | * |
| 605 | * @exception InstanceNotFoundException The MBean name provided |
| 606 | * does not match any of the registered MBeans. |
| 607 | * @exception IOException A communication problem occurred when |
| 608 | * talking to the MBean server. |
| 609 | * |
| 610 | * @see #removeNotificationListener(ObjectName, NotificationListener) |
| 611 | * @see #removeNotificationListener(ObjectName, NotificationListener, |
| 612 | * NotificationFilter, Object) |
| 613 | */ |
| 614 | public void addNotificationListener(ObjectName name, |
| 615 | NotificationListener listener, |
| 616 | NotificationFilter filter, |
| 617 | Object handback) |
| 618 | throws InstanceNotFoundException, IOException; |
| 619 | |
| 620 | |
| 621 | /** |
| 622 | * <p>Adds a listener to a registered MBean.</p> |
| 623 | * |
| 624 | * <p>A notification emitted by an MBean will be forwarded by the |
| 625 | * MBeanServer to the listener. If the source of the notification |
| 626 | * is a reference to an MBean object, the MBean server will |
| 627 | * replace it by that MBean's ObjectName. Otherwise the source is |
| 628 | * unchanged.</p> |
| 629 | * |
| 630 | * <p>The listener object that receives notifications is the one |
| 631 | * that is registered with the given name at the time this method |
| 632 | * is called. Even if it is subsequently unregistered, it will |
| 633 | * continue to receive notifications.</p> |
| 634 | * |
| 635 | * @param name The name of the MBean on which the listener should |
| 636 | * be added. |
| 637 | * @param listener The object name of the listener which will |
| 638 | * handle the notifications emitted by the registered MBean. |
| 639 | * @param filter The filter object. If filter is null, no |
| 640 | * filtering will be performed before handling notifications. |
| 641 | * @param handback The context to be sent to the listener when a |
| 642 | * notification is emitted. |
| 643 | * |
| 644 | * @exception InstanceNotFoundException The MBean name of the |
| 645 | * notification listener or of the notification broadcaster does |
| 646 | * not match any of the registered MBeans. |
| 647 | * @exception RuntimeOperationsException Wraps an {@link |
| 648 | * IllegalArgumentException}. The MBean named by |
| 649 | * <code>listener</code> exists but does not implement the {@link |
| 650 | * NotificationListener} interface. |
| 651 | * @exception IOException A communication problem occurred when |
| 652 | * talking to the MBean server. |
| 653 | * |
| 654 | * @see #removeNotificationListener(ObjectName, ObjectName) |
| 655 | * @see #removeNotificationListener(ObjectName, ObjectName, |
| 656 | * NotificationFilter, Object) |
| 657 | */ |
| 658 | public void addNotificationListener(ObjectName name, |
| 659 | ObjectName listener, |
| 660 | NotificationFilter filter, |
| 661 | Object handback) |
| 662 | throws InstanceNotFoundException, IOException; |
| 663 | |
| 664 | |
| 665 | /** |
| 666 | * Removes a listener from a registered MBean. |
| 667 | * |
| 668 | * <P> If the listener is registered more than once, perhaps with |
| 669 | * different filters or callbacks, this method will remove all |
| 670 | * those registrations. |
| 671 | * |
| 672 | * @param name The name of the MBean on which the listener should |
| 673 | * be removed. |
| 674 | * @param listener The object name of the listener to be removed. |
| 675 | * |
| 676 | * @exception InstanceNotFoundException The MBean name provided |
| 677 | * does not match any of the registered MBeans. |
| 678 | * @exception ListenerNotFoundException The listener is not |
| 679 | * registered in the MBean. |
| 680 | * @exception IOException A communication problem occurred when |
| 681 | * talking to the MBean server. |
| 682 | * |
| 683 | * @see #addNotificationListener(ObjectName, ObjectName, |
| 684 | * NotificationFilter, Object) |
| 685 | */ |
| 686 | public void removeNotificationListener(ObjectName name, |
| 687 | ObjectName listener) |
| 688 | throws InstanceNotFoundException, ListenerNotFoundException, |
| 689 | IOException; |
| 690 | |
| 691 | /** |
| 692 | * <p>Removes a listener from a registered MBean.</p> |
| 693 | * |
| 694 | * <p>The MBean must have a listener that exactly matches the |
| 695 | * given <code>listener</code>, <code>filter</code>, and |
| 696 | * <code>handback</code> parameters. If there is more than one |
| 697 | * such listener, only one is removed.</p> |
| 698 | * |
| 699 | * <p>The <code>filter</code> and <code>handback</code> parameters |
| 700 | * may be null if and only if they are null in a listener to be |
| 701 | * removed.</p> |
| 702 | * |
| 703 | * @param name The name of the MBean on which the listener should |
| 704 | * be removed. |
| 705 | * @param listener The object name of the listener to be removed. |
| 706 | * @param filter The filter that was specified when the listener |
| 707 | * was added. |
| 708 | * @param handback The handback that was specified when the |
| 709 | * listener was added. |
| 710 | * |
| 711 | * @exception InstanceNotFoundException The MBean name provided |
| 712 | * does not match any of the registered MBeans. |
| 713 | * @exception ListenerNotFoundException The listener is not |
| 714 | * registered in the MBean, or it is not registered with the given |
| 715 | * filter and handback. |
| 716 | * @exception IOException A communication problem occurred when |
| 717 | * talking to the MBean server. |
| 718 | * |
| 719 | * @see #addNotificationListener(ObjectName, ObjectName, |
| 720 | * NotificationFilter, Object) |
| 721 | * |
| 722 | */ |
| 723 | public void removeNotificationListener(ObjectName name, |
| 724 | ObjectName listener, |
| 725 | NotificationFilter filter, |
| 726 | Object handback) |
| 727 | throws InstanceNotFoundException, ListenerNotFoundException, |
| 728 | IOException; |
| 729 | |
| 730 | |
| 731 | /** |
| 732 | * <p>Removes a listener from a registered MBean.</p> |
| 733 | * |
| 734 | * <P> If the listener is registered more than once, perhaps with |
| 735 | * different filters or callbacks, this method will remove all |
| 736 | * those registrations. |
| 737 | * |
| 738 | * @param name The name of the MBean on which the listener should |
| 739 | * be removed. |
| 740 | * @param listener The listener to be removed. |
| 741 | * |
| 742 | * @exception InstanceNotFoundException The MBean name provided |
| 743 | * does not match any of the registered MBeans. |
| 744 | * @exception ListenerNotFoundException The listener is not |
| 745 | * registered in the MBean. |
| 746 | * @exception IOException A communication problem occurred when |
| 747 | * talking to the MBean server. |
| 748 | * |
| 749 | * @see #addNotificationListener(ObjectName, NotificationListener, |
| 750 | * NotificationFilter, Object) |
| 751 | */ |
| 752 | public void removeNotificationListener(ObjectName name, |
| 753 | NotificationListener listener) |
| 754 | throws InstanceNotFoundException, ListenerNotFoundException, |
| 755 | IOException; |
| 756 | |
| 757 | /** |
| 758 | * <p>Removes a listener from a registered MBean.</p> |
| 759 | * |
| 760 | * <p>The MBean must have a listener that exactly matches the |
| 761 | * given <code>listener</code>, <code>filter</code>, and |
| 762 | * <code>handback</code> parameters. If there is more than one |
| 763 | * such listener, only one is removed.</p> |
| 764 | * |
| 765 | * <p>The <code>filter</code> and <code>handback</code> parameters |
| 766 | * may be null if and only if they are null in a listener to be |
| 767 | * removed.</p> |
| 768 | * |
| 769 | * @param name The name of the MBean on which the listener should |
| 770 | * be removed. |
| 771 | * @param listener The listener to be removed. |
| 772 | * @param filter The filter that was specified when the listener |
| 773 | * was added. |
| 774 | * @param handback The handback that was specified when the |
| 775 | * listener was added. |
| 776 | * |
| 777 | * @exception InstanceNotFoundException The MBean name provided |
| 778 | * does not match any of the registered MBeans. |
| 779 | * @exception ListenerNotFoundException The listener is not |
| 780 | * registered in the MBean, or it is not registered with the given |
| 781 | * filter and handback. |
| 782 | * @exception IOException A communication problem occurred when |
| 783 | * talking to the MBean server. |
| 784 | * |
| 785 | * @see #addNotificationListener(ObjectName, NotificationListener, |
| 786 | * NotificationFilter, Object) |
| 787 | * |
| 788 | */ |
| 789 | public void removeNotificationListener(ObjectName name, |
| 790 | NotificationListener listener, |
| 791 | NotificationFilter filter, |
| 792 | Object handback) |
| 793 | throws InstanceNotFoundException, ListenerNotFoundException, |
| 794 | IOException; |
| 795 | |
| 796 | /** |
| 797 | * This method discovers the attributes and operations that an |
| 798 | * MBean exposes for management. |
| 799 | * |
| 800 | * @param name The name of the MBean to analyze |
| 801 | * |
| 802 | * @return An instance of <CODE>MBeanInfo</CODE> allowing the |
| 803 | * retrieval of all attributes and operations of this MBean. |
| 804 | * |
| 805 | * @exception IntrospectionException An exception occurred during |
| 806 | * introspection. |
| 807 | * @exception InstanceNotFoundException The MBean specified was |
| 808 | * not found. |
| 809 | * @exception ReflectionException An exception occurred when |
| 810 | * trying to invoke the getMBeanInfo of a Dynamic MBean. |
| 811 | * @exception IOException A communication problem occurred when |
| 812 | * talking to the MBean server. |
| 813 | */ |
| 814 | public MBeanInfo getMBeanInfo(ObjectName name) |
| 815 | throws InstanceNotFoundException, IntrospectionException, |
| 816 | ReflectionException, IOException; |
| 817 | |
| 818 | |
| 819 | /** |
| 820 | * <p>Returns true if the MBean specified is an instance of the |
| 821 | * specified class, false otherwise.</p> |
| 822 | * |
| 823 | * <p>If <code>name</code> does not name an MBean, this method |
| 824 | * throws {@link InstanceNotFoundException}.</p> |
| 825 | * |
| 826 | * <p>Otherwise, let<br> |
| 827 | * X be the MBean named by <code>name</code>,<br> |
| 828 | * L be the ClassLoader of X,<br> |
| 829 | * N be the class name in X's {@link MBeanInfo}.</p> |
| 830 | * |
| 831 | * <p>If N equals <code>className</code>, the result is true.</p> |
| 832 | * |
| 833 | * <p>Otherwise, if L successfully loads <code>className</code> |
| 834 | * and X is an instance of this class, the result is true. |
| 835 | * |
| 836 | * <p>Otherwise, if L successfully loads both N and |
| 837 | * <code>className</code>, and the second class is assignable from |
| 838 | * the first, the result is true.</p> |
| 839 | * |
| 840 | * <p>Otherwise, the result is false.</p> |
| 841 | * |
| 842 | * @param name The <CODE>ObjectName</CODE> of the MBean. |
| 843 | * @param className The name of the class. |
| 844 | * |
| 845 | * @return true if the MBean specified is an instance of the |
| 846 | * specified class according to the rules above, false otherwise. |
| 847 | * |
| 848 | * @exception InstanceNotFoundException The MBean specified is not |
| 849 | * registered in the MBean server. |
| 850 | * @exception IOException A communication problem occurred when |
| 851 | * talking to the MBean server. |
| 852 | * |
| 853 | * @see Class#isInstance |
| 854 | */ |
| 855 | public boolean isInstanceOf(ObjectName name, String className) |
| 856 | throws InstanceNotFoundException, IOException; |
| 857 | } |