1/* 2 * Copyright (c) 1999, 2016, 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 26package javax.management; 27 28 29// java import 30import java.util.Set; 31import java.io.ObjectInputStream; 32 33// RI import 34import javax.management.loading.ClassLoaderRepository; 35 36/** 37 * <p>This is the interface for MBean manipulation on the agent 38 * side. It contains the methods necessary for the creation, 39 * registration, and deletion of MBeans as well as the access methods 40 * for registered MBeans. This is the core component of the JMX 41 * infrastructure.</p> 42 * 43 * <p>User code does not usually implement this interface. Instead, 44 * an object that implements this interface is obtained with one of 45 * the methods in the {@link javax.management.MBeanServerFactory} class.</p> 46 * 47 * <p>Every MBean which is added to the MBean server becomes 48 * manageable: its attributes and operations become remotely 49 * accessible through the connectors/adaptors connected to that MBean 50 * server. A Java object cannot be registered in the MBean server 51 * unless it is a JMX compliant MBean.</p> 52 * 53 * <p id="notif">When an MBean is registered or unregistered in the 54 * MBean server a {@link javax.management.MBeanServerNotification 55 * MBeanServerNotification} Notification is emitted. To register an 56 * object as listener to MBeanServerNotifications you should call the 57 * MBean server method {@link #addNotificationListener 58 * addNotificationListener} with <CODE>ObjectName</CODE> the 59 * <CODE>ObjectName</CODE> of the {@link 60 * javax.management.MBeanServerDelegate MBeanServerDelegate}. This 61 * <CODE>ObjectName</CODE> is: <BR> 62 * <CODE>JMImplementation:type=MBeanServerDelegate</CODE>.</p> 63 * 64 * <p>An object obtained from the {@link 65 * MBeanServerFactory#createMBeanServer(String) createMBeanServer} or 66 * {@link MBeanServerFactory#newMBeanServer(String) newMBeanServer} 67 * methods of the {@link MBeanServerFactory} class applies security 68 * checks to its methods, as follows.</p> 69 * 70 * <p>First, if there is no security manager ({@link 71 * System#getSecurityManager()} is null), then an implementation of 72 * this interface is free not to make any checks.</p> 73 * 74 * <p>Assuming that there is a security manager, or that the 75 * implementation chooses to make checks anyway, the checks are made 76 * as detailed below. In what follows, and unless otherwise specified, 77 * {@code className} is the 78 * string returned by {@link MBeanInfo#getClassName()} for the target 79 * MBean.</p> 80 * 81 * <p>If a security check fails, the method throws {@link 82 * SecurityException}.</p> 83 * 84 * <p>For methods that can throw {@link InstanceNotFoundException}, 85 * this exception is thrown for a non-existent MBean, regardless of 86 * permissions. This is because a non-existent MBean has no 87 * <code>className</code>.</p> 88 * 89 * <ul> 90 * 91 * <li><p>For the {@link #invoke invoke} method, the caller's 92 * permissions must imply {@link 93 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 94 * MBeanPermission(className, operationName, name, "invoke")}.</p> 95 * 96 * <li><p>For the {@link #getAttribute getAttribute} method, the 97 * caller's permissions must imply {@link 98 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 99 * MBeanPermission(className, attribute, name, "getAttribute")}.</p> 100 * 101 * <li><p>For the {@link #getAttributes getAttributes} method, the 102 * caller's permissions must imply {@link 103 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 104 * MBeanPermission(className, null, name, "getAttribute")}. 105 * Additionally, for each attribute <em>a</em> in the {@link 106 * AttributeList}, if the caller's permissions do not imply {@link 107 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 108 * MBeanPermission(className, <em>a</em>, name, "getAttribute")}, the 109 * MBean server will behave as if that attribute had not been in the 110 * supplied list.</p> 111 * 112 * <li><p>For the {@link #setAttribute setAttribute} method, the 113 * caller's permissions must imply {@link 114 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 115 * MBeanPermission(className, attrName, name, "setAttribute")}, where 116 * <code>attrName</code> is {@link Attribute#getName() 117 * attribute.getName()}.</p> 118 * 119 * <li><p>For the {@link #setAttributes setAttributes} method, the 120 * caller's permissions must imply {@link 121 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 122 * MBeanPermission(className, null, name, "setAttribute")}. 123 * Additionally, for each attribute <em>a</em> in the {@link 124 * AttributeList}, if the caller's permissions do not imply {@link 125 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 126 * MBeanPermission(className, <em>a</em>, name, "setAttribute")}, the 127 * MBean server will behave as if that attribute had not been in the 128 * supplied list.</p> 129 * 130 * <li><p>For the <code>addNotificationListener</code> methods, 131 * the caller's permissions must imply {@link 132 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 133 * MBeanPermission(className, null, name, 134 * "addNotificationListener")}.</p> 135 * 136 * <li><p>For the <code>removeNotificationListener</code> methods, 137 * the caller's permissions must imply {@link 138 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 139 * MBeanPermission(className, null, name, 140 * "removeNotificationListener")}.</p> 141 * 142 * <li><p>For the {@link #getMBeanInfo getMBeanInfo} method, the 143 * caller's permissions must imply {@link 144 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 145 * MBeanPermission(className, null, name, "getMBeanInfo")}.</p> 146 * 147 * <li><p>For the {@link #getObjectInstance getObjectInstance} method, 148 * the caller's permissions must imply {@link 149 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 150 * MBeanPermission(className, null, name, "getObjectInstance")}.</p> 151 * 152 * <li><p>For the {@link #isInstanceOf isInstanceOf} method, the 153 * caller's permissions must imply {@link 154 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 155 * MBeanPermission(className, null, name, "isInstanceOf")}.</p> 156 * 157 * <li><p>For the {@link #queryMBeans queryMBeans} method, the 158 * caller's permissions must imply {@link 159 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 160 * MBeanPermission(null, null, null, "queryMBeans")}. 161 * Additionally, for each MBean <em>n</em> that matches <code>name</code>, 162 * if the caller's permissions do not imply {@link 163 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 164 * MBeanPermission(className, null, <em>n</em>, "queryMBeans")}, the 165 * MBean server will behave as if that MBean did not exist.</p> 166 * 167 * <p>Certain query elements perform operations on the MBean server. 168 * If the caller does not have the required permissions for a given 169 * MBean, that MBean will not be included in the result of the query. 170 * The standard query elements that are affected are {@link 171 * Query#attr(String)}, {@link Query#attr(String,String)}, and {@link 172 * Query#classattr()}.</p> 173 * 174 * <li><p>For the {@link #queryNames queryNames} method, the checks 175 * are the same as for <code>queryMBeans</code> except that 176 * <code>"queryNames"</code> is used instead of 177 * <code>"queryMBeans"</code> in the <code>MBeanPermission</code> 178 * objects. Note that a <code>"queryMBeans"</code> permission implies 179 * the corresponding <code>"queryNames"</code> permission.</p> 180 * 181 * <li><p>For the {@link #getDomains getDomains} method, the caller's 182 * permissions must imply {@link 183 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 184 * MBeanPermission(null, null, null, "getDomains")}. Additionally, 185 * for each domain <var>d</var> in the returned array, if the caller's 186 * permissions do not imply {@link 187 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 188 * MBeanPermission(null, null, new ObjectName("<var>d</var>:x=x"), 189 * "getDomains")}, the domain is eliminated from the array. Here, 190 * <code>x=x</code> is any <var>key=value</var> pair, needed to 191 * satisfy ObjectName's constructor but not otherwise relevant.</p> 192 * 193 * <li><p>For the {@link #getClassLoader getClassLoader} method, the 194 * caller's permissions must imply {@link 195 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 196 * MBeanPermission(className, null, loaderName, 197 * "getClassLoader")}.</p> 198 * 199 * <li><p>For the {@link #getClassLoaderFor getClassLoaderFor} method, 200 * the caller's permissions must imply {@link 201 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 202 * MBeanPermission(className, null, mbeanName, 203 * "getClassLoaderFor")}.</p> 204 * 205 * <li><p>For the {@link #getClassLoaderRepository 206 * getClassLoaderRepository} method, the caller's permissions must 207 * imply {@link 208 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 209 * MBeanPermission(null, null, null, "getClassLoaderRepository")}.</p> 210 * 211 * <li><p>For the deprecated <code>deserialize</code> methods, the 212 * required permissions are the same as for the methods that replace 213 * them.</p> 214 * 215 * <li><p>For the <code>instantiate</code> methods, the caller's 216 * permissions must imply {@link 217 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 218 * MBeanPermission(className, null, null, "instantiate")}, 219 * where {@code className} is the name of the class which is to 220 * be instantiated.</p> 221 * 222 * <li><p>For the {@link #registerMBean registerMBean} method, the 223 * caller's permissions must imply {@link 224 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 225 * MBeanPermission(className, null, name, "registerMBean")}. 226 * 227 * <p>If the <code>MBeanPermission</code> check succeeds, the MBean's 228 * class is validated by checking that its {@link 229 * java.security.ProtectionDomain ProtectionDomain} implies {@link 230 * MBeanTrustPermission#MBeanTrustPermission(String) 231 * MBeanTrustPermission("register")}.</p> 232 * 233 * <p>Finally, if the <code>name</code> argument is null, another 234 * <code>MBeanPermission</code> check is made using the 235 * <code>ObjectName</code> returned by {@link 236 * MBeanRegistration#preRegister MBeanRegistration.preRegister}.</p> 237 * 238 * <li><p>For the <code>createMBean</code> methods, the caller's 239 * permissions must imply the permissions needed by the equivalent 240 * <code>instantiate</code> followed by 241 * <code>registerMBean</code>.</p> 242 * 243 * <li><p>For the {@link #unregisterMBean unregisterMBean} method, 244 * the caller's permissions must imply {@link 245 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 246 * MBeanPermission(className, null, name, "unregisterMBean")}.</p> 247 * 248 * </ul> 249 * 250 * @since 1.5 251 */ 252 253/* DELETED: 254 * 255 * <li><p>For the {@link #isRegistered isRegistered} method, the 256 * caller's permissions must imply {@link 257 * MBeanPermission#MBeanPermission(String,String,ObjectName,String) 258 * MBeanPermission(null, null, name, "isRegistered")}.</p> 259 */ 260public interface MBeanServer extends MBeanServerConnection { 261 262 /** 263 * {@inheritDoc} 264 * <p>If this method successfully creates an MBean, a notification 265 * is sent as described <a href="#notif">above</a>.</p> 266 * 267 * @throws RuntimeOperationsException {@inheritDoc} 268 * @throws RuntimeMBeanException {@inheritDoc} 269 * @throws RuntimeErrorException {@inheritDoc} 270 */ 271 public ObjectInstance createMBean(String className, ObjectName name) 272 throws ReflectionException, InstanceAlreadyExistsException, 273 MBeanRegistrationException, MBeanException, 274 NotCompliantMBeanException; 275 276 /** 277 * {@inheritDoc} 278 * <p>If this method successfully creates an MBean, a notification 279 * is sent as described <a href="#notif">above</a>.</p> 280 * 281 * @throws RuntimeOperationsException {@inheritDoc} 282 * @throws RuntimeMBeanException {@inheritDoc} 283 * @throws RuntimeErrorException {@inheritDoc} 284 */ 285 public ObjectInstance createMBean(String className, ObjectName name, 286 ObjectName loaderName) 287 throws ReflectionException, InstanceAlreadyExistsException, 288 MBeanRegistrationException, MBeanException, 289 NotCompliantMBeanException, InstanceNotFoundException; 290 291 /** 292 * {@inheritDoc} 293 * <p>If this method successfully creates an MBean, a notification 294 * is sent as described <a href="#notif">above</a>.</p> 295 * 296 * @throws RuntimeOperationsException {@inheritDoc} 297 * @throws RuntimeMBeanException {@inheritDoc} 298 * @throws RuntimeErrorException {@inheritDoc} 299 */ 300 public ObjectInstance createMBean(String className, ObjectName name, 301 Object params[], String signature[]) 302 throws ReflectionException, InstanceAlreadyExistsException, 303 MBeanRegistrationException, MBeanException, 304 NotCompliantMBeanException; 305 306 /** 307 * {@inheritDoc} 308 * <p>If this method successfully creates an MBean, a notification 309 * is sent as described <a href="#notif">above</a>.</p> 310 * 311 * @throws RuntimeOperationsException {@inheritDoc} 312 * @throws RuntimeMBeanException {@inheritDoc} 313 * @throws RuntimeErrorException {@inheritDoc} 314 */ 315 public ObjectInstance createMBean(String className, ObjectName name, 316 ObjectName loaderName, Object params[], 317 String signature[]) 318 throws ReflectionException, InstanceAlreadyExistsException, 319 MBeanRegistrationException, MBeanException, 320 NotCompliantMBeanException, InstanceNotFoundException; 321 322 /** 323 * <p>Registers a pre-existing object as an MBean with the MBean 324 * server. If the object name given is null, the MBean must 325 * provide its own name by implementing the {@link 326 * javax.management.MBeanRegistration MBeanRegistration} interface 327 * and returning the name from the {@link 328 * MBeanRegistration#preRegister preRegister} method. 329 * 330 * <p>If this method successfully registers an MBean, a notification 331 * is sent as described <a href="#notif">above</a>.</p> 332 * 333 * @param object The MBean to be registered as an MBean. 334 * @param name The object name of the MBean. May be null. 335 * 336 * @return An <CODE>ObjectInstance</CODE>, containing the 337 * <CODE>ObjectName</CODE> and the Java class name of the newly 338 * registered MBean. If the contained <code>ObjectName</code> 339 * is <code>n</code>, the contained Java class name is 340 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>. 341 * 342 * @exception InstanceAlreadyExistsException The MBean is already 343 * under the control of the MBean server. 344 * @exception MBeanRegistrationException The 345 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE> 346 * interface) method of the MBean has thrown an exception. The 347 * MBean will not be registered. 348 * @exception RuntimeMBeanException If the <CODE>postRegister</CODE> 349 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a 350 * <CODE>RuntimeException</CODE>, the <CODE>registerMBean</CODE> method will 351 * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean 352 * registration succeeded. In such a case, the MBean will be actually 353 * registered even though the <CODE>registerMBean</CODE> method 354 * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can 355 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 356 * will not be registered. 357 * @exception RuntimeErrorException If the <CODE>postRegister</CODE> 358 * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an 359 * <CODE>Error</CODE>, the <CODE>registerMBean</CODE> method will 360 * throw a <CODE>RuntimeErrorException</CODE>, although the MBean 361 * registration succeeded. In such a case, the MBean will be actually 362 * registered even though the <CODE>registerMBean</CODE> method 363 * threw an exception. Note that <CODE>RuntimeErrorException</CODE> can 364 * also be thrown by <CODE>preRegister</CODE>, in which case the MBean 365 * will not be registered. 366 * @exception NotCompliantMBeanException This object is not a JMX 367 * compliant MBean 368 * @exception RuntimeOperationsException Wraps a 369 * <CODE>java.lang.IllegalArgumentException</CODE>: The object 370 * passed in parameter is null or no object name is specified. 371 * @see javax.management.MBeanRegistration 372 */ 373 public ObjectInstance registerMBean(Object object, ObjectName name) 374 throws InstanceAlreadyExistsException, MBeanRegistrationException, 375 NotCompliantMBeanException; 376 377 /** 378 * {@inheritDoc} 379 * 380 * <p>If this method successfully unregisters an MBean, a notification 381 * is sent as described <a href="#notif">above</a>.</p> 382 * 383 * @throws RuntimeOperationsException {@inheritDoc} 384 * @throws RuntimeMBeanException {@inheritDoc} 385 * @throws RuntimeErrorException {@inheritDoc} 386 */ 387 public void unregisterMBean(ObjectName name) 388 throws InstanceNotFoundException, MBeanRegistrationException; 389 390 // doc comment inherited from MBeanServerConnection 391 public ObjectInstance getObjectInstance(ObjectName name) 392 throws InstanceNotFoundException; 393 394 /** 395 * {@inheritDoc} 396 * @throws RuntimeOperationsException {@inheritDoc} 397 */ 398 public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query); 399 400 /** 401 * {@inheritDoc} 402 * @throws RuntimeOperationsException {@inheritDoc} 403 */ 404 public Set<ObjectName> queryNames(ObjectName name, QueryExp query); 405 406 // doc comment inherited from MBeanServerConnection 407 /** 408 * @throws RuntimeOperationsException {@inheritDoc} 409 */ 410 public boolean isRegistered(ObjectName name); 411 412 /** 413 * Returns the number of MBeans registered in the MBean server. 414 * 415 * @return the number of registered MBeans, wrapped in an Integer. 416 * If the caller's permissions are restricted, this number may 417 * be greater than the number of MBeans the caller can access. 418 */ 419 public Integer getMBeanCount(); 420 421 // doc comment inherited from MBeanServerConnection 422 /** 423 * @throws RuntimeOperationsException {@inheritDoc} 424 */ 425 public Object getAttribute(ObjectName name, String attribute) 426 throws MBeanException, AttributeNotFoundException, 427 InstanceNotFoundException, ReflectionException; 428 429 // doc comment inherited from MBeanServerConnection 430 /** 431 * @throws RuntimeOperationsException {@inheritDoc} 432 */ 433 public AttributeList getAttributes(ObjectName name, String[] attributes) 434 throws InstanceNotFoundException, ReflectionException; 435 436 // doc comment inherited from MBeanServerConnection 437 /** 438 * @throws RuntimeOperationsException {@inheritDoc} 439 */ 440 public void setAttribute(ObjectName name, Attribute attribute) 441 throws InstanceNotFoundException, AttributeNotFoundException, 442 InvalidAttributeValueException, MBeanException, 443 ReflectionException; 444 445 // doc comment inherited from MBeanServerConnection 446 /** 447 * @throws RuntimeOperationsException {@inheritDoc} 448 */ 449 public AttributeList setAttributes(ObjectName name, 450 AttributeList attributes) 451 throws InstanceNotFoundException, ReflectionException; 452 453 // doc comment inherited from MBeanServerConnection 454 public Object invoke(ObjectName name, String operationName, 455 Object params[], String signature[]) 456 throws InstanceNotFoundException, MBeanException, 457 ReflectionException; 458 459 // doc comment inherited from MBeanServerConnection 460 public String getDefaultDomain(); 461 462 // doc comment inherited from MBeanServerConnection 463 public String[] getDomains(); 464 465 // doc comment inherited from MBeanServerConnection, plus: 466 /** 467 * {@inheritDoc} 468 * If the source of the notification 469 * is a reference to an MBean object, the MBean server will replace it 470 * by that MBean's ObjectName. Otherwise the source is unchanged. 471 */ 472 public void addNotificationListener(ObjectName name, 473 NotificationListener listener, 474 NotificationFilter filter, 475 Object handback) 476 throws InstanceNotFoundException; 477 478 /** 479 * {@inheritDoc} 480 * @throws RuntimeOperationsException {@inheritDoc} 481 */ 482 public void addNotificationListener(ObjectName name, 483 ObjectName listener, 484 NotificationFilter filter, 485 Object handback) 486 throws InstanceNotFoundException; 487 488 // doc comment inherited from MBeanServerConnection 489 public void removeNotificationListener(ObjectName name, 490 ObjectName listener) 491 throws InstanceNotFoundException, ListenerNotFoundException; 492 493 // doc comment inherited from MBeanServerConnection 494 public void removeNotificationListener(ObjectName name, 495 ObjectName listener, 496 NotificationFilter filter, 497 Object handback) 498 throws InstanceNotFoundException, ListenerNotFoundException; 499 500 // doc comment inherited from MBeanServerConnection 501 public void removeNotificationListener(ObjectName name, 502 NotificationListener listener) 503 throws InstanceNotFoundException, ListenerNotFoundException; 504 505 // doc comment inherited from MBeanServerConnection 506 public void removeNotificationListener(ObjectName name, 507 NotificationListener listener, 508 NotificationFilter filter, 509 Object handback) 510 throws InstanceNotFoundException, ListenerNotFoundException; 511 512 // doc comment inherited from MBeanServerConnection 513 public MBeanInfo getMBeanInfo(ObjectName name) 514 throws InstanceNotFoundException, IntrospectionException, 515 ReflectionException; 516 517 518 // doc comment inherited from MBeanServerConnection 519 public boolean isInstanceOf(ObjectName name, String className) 520 throws InstanceNotFoundException; 521 522 /** 523 * <p>Instantiates an object using the list of all class loaders 524 * registered in the MBean server's {@link 525 * javax.management.loading.ClassLoaderRepository Class Loader 526 * Repository}. The object's class should have a public 527 * constructor. This method returns a reference to the newly 528 * created object. The newly created object is not registered in 529 * the MBean server.</p> 530 * 531 * <p>This method is equivalent to {@link 532 * #instantiate(String,Object[],String[]) 533 * instantiate(className, (Object[]) null, (String[]) null)}.</p> 534 * 535 * @param className The class name of the object to be instantiated. 536 * 537 * @return The newly instantiated object. 538 * 539 * @exception ReflectionException Wraps a 540 * <CODE>java.lang.ClassNotFoundException</CODE> or the 541 * <CODE>java.lang.Exception</CODE> that occurred when trying to 542 * invoke the object's constructor. 543 * @exception MBeanException The constructor of the object has 544 * thrown an exception 545 * @exception RuntimeOperationsException Wraps a 546 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 547 * passed in parameter is null. 548 */ 549 public Object instantiate(String className) 550 throws ReflectionException, MBeanException; 551 552 553 /** 554 * <p>Instantiates an object using the class Loader specified by its 555 * <CODE>ObjectName</CODE>. If the loader name is null, the 556 * ClassLoader that loaded the MBean Server will be used. The 557 * object's class should have a public constructor. This method 558 * returns a reference to the newly created object. The newly 559 * created object is not registered in the MBean server.</p> 560 * 561 * <p>This method is equivalent to {@link 562 * #instantiate(String,ObjectName,Object[],String[]) 563 * instantiate(className, loaderName, (Object[]) null, (String[]) 564 * null)}.</p> 565 * 566 * @param className The class name of the MBean to be instantiated. 567 * @param loaderName The object name of the class loader to be used. 568 * 569 * @return The newly instantiated object. 570 * 571 * @exception ReflectionException Wraps a 572 * <CODE>java.lang.ClassNotFoundException</CODE> or the 573 * <CODE>java.lang.Exception</CODE> that occurred when trying to 574 * invoke the object's constructor. 575 * @exception MBeanException The constructor of the object has 576 * thrown an exception. 577 * @exception InstanceNotFoundException The specified class loader 578 * is not registered in the MBeanServer. 579 * @exception RuntimeOperationsException Wraps a 580 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 581 * passed in parameter is null. 582 */ 583 public Object instantiate(String className, ObjectName loaderName) 584 throws ReflectionException, MBeanException, 585 InstanceNotFoundException; 586 587 /** 588 * <p>Instantiates an object using the list of all class loaders 589 * registered in the MBean server {@link 590 * javax.management.loading.ClassLoaderRepository Class Loader 591 * Repository}. The object's class should have a public 592 * constructor. The call returns a reference to the newly created 593 * object. The newly created object is not registered in the 594 * MBean server.</p> 595 * 596 * @param className The class name of the object to be instantiated. 597 * @param params An array containing the parameters of the 598 * constructor to be invoked. 599 * @param signature An array containing the signature of the 600 * constructor to be invoked. 601 * 602 * @return The newly instantiated object. 603 * 604 * @exception ReflectionException Wraps a 605 * <CODE>java.lang.ClassNotFoundException</CODE> or the 606 * <CODE>java.lang.Exception</CODE> that occurred when trying to 607 * invoke the object's constructor. 608 * @exception MBeanException The constructor of the object has 609 * thrown an exception 610 * @exception RuntimeOperationsException Wraps a 611 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 612 * passed in parameter is null. 613 */ 614 public Object instantiate(String className, Object params[], 615 String signature[]) 616 throws ReflectionException, MBeanException; 617 618 /** 619 * <p>Instantiates an object. The class loader to be used is 620 * identified by its object name. If the object name of the loader 621 * is null, the ClassLoader that loaded the MBean server will be 622 * used. The object's class should have a public constructor. 623 * The call returns a reference to the newly created object. The 624 * newly created object is not registered in the MBean server.</p> 625 * 626 * @param className The class name of the object to be instantiated. 627 * @param params An array containing the parameters of the 628 * constructor to be invoked. 629 * @param signature An array containing the signature of the 630 * constructor to be invoked. 631 * @param loaderName The object name of the class loader to be used. 632 * 633 * @return The newly instantiated object. 634 * 635 * @exception ReflectionException Wraps a <CODE>java.lang.ClassNotFoundException</CODE> or the <CODE>java.lang.Exception</CODE> that 636 * occurred when trying to invoke the object's constructor. 637 * @exception MBeanException The constructor of the object has 638 * thrown an exception 639 * @exception InstanceNotFoundException The specified class loader 640 * is not registered in the MBean server. 641 * @exception RuntimeOperationsException Wraps a 642 * <CODE>java.lang.IllegalArgumentException</CODE>: The className 643 * passed in parameter is null. 644 */ 645 public Object instantiate(String className, ObjectName loaderName, 646 Object params[], String signature[]) 647 throws ReflectionException, MBeanException, 648 InstanceNotFoundException; 649 650 /** 651 * <p>De-serializes a byte array in the context of the class loader 652 * of an MBean.</p> 653 * 654 * @param name The name of the MBean whose class loader should be 655 * used for the de-serialization. 656 * @param data The byte array to be de-sererialized. 657 * 658 * @implSpec This method throws {@link UnsupportedOperationException} by default. 659 * 660 * @return The de-serialized object stream. 661 * 662 * @exception InstanceNotFoundException The MBean specified is not 663 * found. 664 * @exception OperationsException Any of the usual Input/Output 665 * related exceptions. 666 * 667 * @deprecated Use {@link #getClassLoaderFor getClassLoaderFor} to 668 * obtain the appropriate class loader for deserialization. 669 */ 670 @Deprecated(since="1.5") 671 default public ObjectInputStream deserialize(ObjectName name, byte[] data) 672 throws InstanceNotFoundException, OperationsException { 673 throw new UnsupportedOperationException("Not supported."); 674 } 675 676 /** 677 * <p>De-serializes a byte array in the context of a given MBean 678 * class loader. The class loader is found by loading the class 679 * <code>className</code> through the {@link 680 * javax.management.loading.ClassLoaderRepository Class Loader 681 * Repository}. The resultant class's class loader is the one to 682 * use. 683 * 684 * @param className The name of the class whose class loader should be 685 * used for the de-serialization. 686 * @param data The byte array to be de-sererialized. 687 * 688 * @implSpec This method throws {@link UnsupportedOperationException} by default. 689 * 690 * @return The de-serialized object stream. 691 * 692 * @exception OperationsException Any of the usual Input/Output 693 * related exceptions. 694 * @exception ReflectionException The specified class could not be 695 * loaded by the class loader repository 696 * 697 * @deprecated Use {@link #getClassLoaderRepository} to obtain the 698 * class loader repository and use it to deserialize. 699 */ 700 @Deprecated(since="1.5") 701 default public ObjectInputStream deserialize(String className, byte[] data) 702 throws OperationsException, ReflectionException { 703 throw new UnsupportedOperationException("Not supported."); 704 } 705 706 707 /** 708 * <p>De-serializes a byte array in the context of a given MBean 709 * class loader. The class loader is the one that loaded the 710 * class with name "className". The name of the class loader to 711 * be used for loading the specified class is specified. If null, 712 * the MBean Server's class loader will be used.</p> 713 * 714 * @param className The name of the class whose class loader should be 715 * used for the de-serialization. 716 * @param data The byte array to be de-sererialized. 717 * @param loaderName The name of the class loader to be used for 718 * loading the specified class. If null, the MBean Server's class 719 * loader will be used. 720 * 721 * @implSpec This method throws {@link UnsupportedOperationException} by default. 722 * 723 * @return The de-serialized object stream. 724 * 725 * @exception InstanceNotFoundException The specified class loader 726 * MBean is not found. 727 * @exception OperationsException Any of the usual Input/Output 728 * related exceptions. 729 * @exception ReflectionException The specified class could not be 730 * loaded by the specified class loader. 731 * 732 * @deprecated Use {@link #getClassLoader getClassLoader} to obtain 733 * the class loader for deserialization. 734 */ 735 @Deprecated(since="1.5") 736 default public ObjectInputStream deserialize(String className, 737 ObjectName loaderName, 738 byte[] data) 739 throws InstanceNotFoundException, OperationsException, 740 ReflectionException { 741 throw new UnsupportedOperationException("Not supported."); 742 } 743 744 /** 745 * <p>Return the {@link java.lang.ClassLoader} that was used for 746 * loading the class of the named MBean.</p> 747 * 748 * @param mbeanName The ObjectName of the MBean. 749 * 750 * @return The ClassLoader used for that MBean. If <var>l</var> 751 * is the MBean's actual ClassLoader, and <var>r</var> is the 752 * returned value, then either: 753 * 754 * <ul> 755 * <li><var>r</var> is identical to <var>l</var>; or 756 * <li>the result of <var>r</var>{@link 757 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the 758 * same as <var>l</var>{@link ClassLoader#loadClass(String) 759 * .loadClass(<var>s</var>)} for any string <var>s</var>. 760 * </ul> 761 * 762 * What this means is that the ClassLoader may be wrapped in 763 * another ClassLoader for security or other reasons. 764 * 765 * @exception InstanceNotFoundException if the named MBean is not found. 766 * 767 */ 768 public ClassLoader getClassLoaderFor(ObjectName mbeanName) 769 throws InstanceNotFoundException; 770 771 /** 772 * <p>Return the named {@link java.lang.ClassLoader}.</p> 773 * 774 * @param loaderName The ObjectName of the ClassLoader. May be 775 * null, in which case the MBean server's own ClassLoader is 776 * returned. 777 * 778 * @return The named ClassLoader. If <var>l</var> is the actual 779 * ClassLoader with that name, and <var>r</var> is the returned 780 * value, then either: 781 * 782 * <ul> 783 * <li><var>r</var> is identical to <var>l</var>; or 784 * <li>the result of <var>r</var>{@link 785 * ClassLoader#loadClass(String) .loadClass(<var>s</var>)} is the 786 * same as <var>l</var>{@link ClassLoader#loadClass(String) 787 * .loadClass(<var>s</var>)} for any string <var>s</var>. 788 * </ul> 789 * 790 * What this means is that the ClassLoader may be wrapped in 791 * another ClassLoader for security or other reasons. 792 * 793 * @exception InstanceNotFoundException if the named ClassLoader is 794 * not found. 795 * 796 */ 797 public ClassLoader getClassLoader(ObjectName loaderName) 798 throws InstanceNotFoundException; 799 800 /** 801 * <p>Return the ClassLoaderRepository for this MBeanServer. 802 * @return The ClassLoaderRepository for this MBeanServer. 803 * 804 */ 805 public ClassLoaderRepository getClassLoaderRepository(); 806} 807