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