| blob | 430f1c7dc97ff20a94533ebfb899adb9f0714c57 |
1 /* RMIConnection.java -- RMI object representing a MBean server connection.
2 Copyright (C) 2007, 2008 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
67 /**
68 * <p>
69 * RMI interface for forwarding requests to a remote
70 * {@link javax.management.MBeanServer}. This interface
71 * parallels the {@link javax.management.MBeanServerConnection}
72 * interface, providing a way of invoking those methods using
73 * the RMI protocol. When a client wishes to call a method
74 * of an MBean server using RMI, the method is called on the stub
75 * on the client side, which serializes the object parameters
76 * and sends them to the server where they are deserialized and
77 * an implementation of this interface forwards them to the
78 * appropriate MBean server. Return values follow the same
79 * process, only in reverse. Each client obtains its own
80 * implementation of this interface from an {@link RMIServer}
81 * instance.
82 * </p>
83 * <p>
84 * Implementations of this interface do more than simply
85 * forward requests directly to the server. The arguments
86 * of the server methods are wrapped in {@link MarshalledObject}
87 * instances, so that the correct classloader can be used to
88 * deserialize the arguments. When a method is called, the
89 * implementation must first retrieve the appropriate classloader
90 * and then use it to deserialize the marshalled object. Unless
91 * explicitly specified in the documentation for the method,
92 * a parameter of the type {@link MarshalledObject} or an array
93 * of that type should not be {@code null}.
94 * </p>
95 * <p>
96 * Security is also handled by this interface, as the methods
97 * use an additional {@link javax.security.auth.Subject} parameter
98 * for role delegation.
99 * </p>
100 *
101 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
102 * @since 1.5
103 */
104 public interface RMIConnection
106 {
108 /**
109 * Handles {@link
110 * MBeanServerConnection#addNotificationListener(ObjectName,
111 * ObjectName, NotificationFilter, Object)} by
112 * registering the supplied listener with the specified management
113 * bean. Notifications emitted by the management bean are forwarded
114 * to the listener via the server, which will convert any MBean
115 * references in the source to portable {@link ObjectName}
116 * instances. The notification is otherwise unchanged. The filter
117 * and handback object are wrapped in a {@link MarshalledObject}
118 * so that they are deserialised using the bean's classloader.
119 *
120 * @param name the name of the management bean with which the listener
121 * should be registered.
122 * @param listener the listener which will handle notifications from
123 * the bean.
124 * @param filter a wrapper containing a filter to apply to incoming
125 * notifications, or <code>null</code> if no filtering
126 * should be applied.
127 * @param passback a wrapper containing an object to be passed to the
128 * listener when a notification is emitted.
129 * @param delegationSubject a {@link javax.security.auth.Subject} instance
130 * containing the delegation principles or
131 * {@code null} if authentication is used.
132 * @throws InstanceNotFoundException if the name of the management bean
133 * could not be resolved.
134 * @throws RuntimeOperationsException if the bean associated with the given
135 * object name is not a
136 * {@link NotificationListener}. This
137 * exception wraps an
138 * {@link IllegalArgumentException}.
139 * @throws SecurityException if the client or delegated subject (if any)
140 * does not have permission to invoke this operation.
141 * @throws IOException if an I/O error occurred in communicating with
142 * the bean server.
143 * @see #removeNotificationListener(ObjectName, ObjectName,
144 * javax.security.auth.Subject)
145 * @see #removeNotificationListener(ObjectName, ObjectName,
146 * java.rmi.MarshalledObject,
147 * java.rmi.MarshalledObject,
148 * javax.security.auth.Subject)
149 * @see #removeNotificationListeners(ObjectName, Integer[],
150 * javax.security.auth.Subject)
151 * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
152 * NotificationFilter,
153 * Object)
154 */
158 Subject delegationSubject)
161 /**
162 * Handles {@link
163 * MBeanServerConnection#addNotificationListener(ObjectName,
164 * NotificationListener, NotificationFilter, Object)} by
165 * registering for notifications from the specified management
166 * beans. The array of filters is assumed to be aligned with
167 * the array of bean names, so that the notifications from each
168 * bean are matched against the appropriate filter (or left as
169 * is if the filter is {@code null}. Notifications emitted by
170 * the management beans are forwarded to a local listener created
171 * by this method, via the server, which converts any MBean
172 * references in the source to portable {@link ObjectName}
173 * instances. The notification is otherwise unchanged.
174 * </p>
175 * <p>
176 * This local listener buffers the notifications for retrieval by
177 * {@link #fetchNotifications(long,int,long). This method returns
178 * an array of listener identifiers which aligns with the supplied
179 * array of beans so that the appropriate listener can be identified
180 * by the client, which retains its own listener and handback object.
181 * The filters are wrapped in {@link MarshalledObject}s so that they are
182 * deserialised using the bean's classloader.
183 * </p>
184 *
185 * @param names the names of the management bean whose notifications
186 * should be recorded.
187 * @param filters an array of wrappers containing filters to apply to
188 * incoming notifications. An element may be <code>null</code>
189 * if no filtering should be applied to a bean's notifications.
190 * @param delegationSubjects an array of {@link javax.security.auth.Subject}
191 * instances containing the delegation principles for
192 * each listener. An element may be {@code null} if
193 * authentication is used instead, or the entire
194 * argument itself may be {@code null}. In the latter
195 * case, this is treated as an array of {@code null}
196 * values.
197 * @return an array of integers which act as listener identifiers, so that
198 * notifications retrieved from {@link #fetchNotifications(long,int,long)
199 * can be matched to the beans they were emitted from. The array is
200 * aligned against the array of beans supplied to this methods, so that
201 * the identifier in position 0 represents the bean in position 0 of the
202 * input array.
203 * @throws IllegalArgumentException if the {@code names} or {@code filters} array
204 * is {@code null}, the {@code names} array contains
205 * a {@code null} value or the three arrays are not
206 * of the same size.
207 * @throws ClassCastException if an element of the {@code filters} array unmarshalls
208 * as a non-null object that is not a {@link NotificationFilter}.
209 * @throws InstanceNotFoundException if the name of one of the management beans
210 * could not be resolved.
211 * @throws SecurityException if, for one of the beans, the client or delegated subject
212 * (if any) does not have permission to invoke this operation.
213 * @throws IOException if an I/O error occurred in communicating with
214 * the bean server.
215 * @see #removeNotificationListener(ObjectName, ObjectName,
216 * javax.security.auth.Subject)
217 * @see #removeNotificationListener(ObjectName, ObjectName,
218 * java.rmi.MarshalledObject,
219 * java.rmi.MarshalledObject,
220 * javax.security.auth.Subject)
221 * @see #removeNotificationListeners(ObjectName, Integer[],
222 * javax.security.auth.Subject)
223 * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
224 * NotificationFilter,
225 * Object)
226 */
232 /**
233 * Closes the connection and unexports the RMI object implementing this
234 * interface. Following this call, future method calls to this instance
235 * will fail.
236 *
237 * @throws IOException if there is an I/O error in transmitting the close
238 * request via RMI, closing the connection, or unexporting
239 * the RMI object.
240 */
244 /**
245 * <p>
246 * Handles {@link
247 * MBeanServerConnection#createMBean(String, ObjectName,
248 * Object[], String[])}. The array of parameters is wrapped in
249 * a {@link MarshalledObject} so that it is deserialised using the
250 * bean's classloader.
251 * </p>
252 * <p>
253 * Instantiates a new instance of the specified management bean
254 * using the given constructor and registers it with the server
255 * under the supplied name. The class is loaded using the
256 * {@link javax.management.loading.ClassLoaderRepository default
257 * loader repository} of the server.
258 * </p>
259 * <p>
260 * If the name supplied is <code>null</code>, then the bean is
261 * expected to implement the {@link MBeanRegistration} interface.
262 * The {@link MBeanRegistration#preRegister preRegister} method
263 * of this interface will be used to obtain the name in this case.
264 * </p>
265 *
266 * @param className the class of the management bean, of which
267 * an instance should be created.
268 * @param name the name to register the new bean with. This may
269 * be <code>null</code>.
270 * @param params the parameters for the bean's constructor, encapsulated
271 * in a {@link MarshalledObject}. If this parameter is
272 * <code>null</code>, it will be judged equivalent to an
273 * empty array.
274 * @param sig the signature of the constructor to use. If this parameter
275 * is <code>null</code>, it will be judged equivalent to an
276 * empty array.
277 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
278 * containing the delegation principles. This may be
279 * {@code null} is authentication is used instead.
280 * @return an {@link ObjectInstance} containing the {@link ObjectName}
281 * and Java class name of the created instance.
282 * @throws ReflectionException if an exception occurs in creating
283 * an instance of the bean.
284 * @throws InstanceAlreadyExistsException if a matching instance
285 * already exists.
286 * @throws MBeanRegistrationException if an exception occurs in
287 * calling the preRegister
288 * method.
289 * @throws MBeanException if the bean's constructor throws an exception.
290 * @throws NotCompliantMBeanException if the created bean is not
291 * compliant with the JMX specification.
292 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
293 * is thrown by the server due to a
294 * <code>null</code> class name or object
295 * name or if the object name is a pattern.
296 * @throws SecurityException if the client or delegated subject (if any) does
297 * not have permission to invoke this operation.
298 * @throws IOException if an I/O error occurred in communicating with
299 * the bean server.
300 */
304 Subject delegationSubject)
309 /**
310 * <p>
311 * Handles {@link
312 * MBeanServerConnection#createMBean(String, ObjectName,
313 * ObjectName, Object[], String[])}. The array of parameters is
314 * wrapped in a {@link MarshalledObject} so that it is deserialised
315 * using the bean's classloader.
316 * </p>
317 * <p>
318 * Instantiates a new instance of the specified management bean
319 * using the given constructor and registers it with the server
320 * under the supplied name. The class is loaded using the
321 * given class loader. If this argument is <code>null</code>,
322 * then the same class loader as was used to load the server
323 * is used.
324 * </p>
325 * <p>
326 * If the name supplied is <code>null</code>, then the bean is
327 * expected to implement the {@link MBeanRegistration} interface.
328 * The {@link MBeanRegistration#preRegister preRegister} method
329 * of this interface will be used to obtain the name in this case.
330 * </p>
331 *
332 * @param className the class of the management bean, of which
333 * an instance should be created.
334 * @param name the name to register the new bean with. This may
335 * be <code>null</code>.
336 * @param loaderName the name of the class loader.
337 * @param params the parameters for the bean's constructor, encapsulated
338 * in a {@link MarshalledObject}. If this parameter is
339 * <code>null</code>, it will be judged equivalent to an
340 * empty array.
341 * @param sig the signature of the constructor to use. If this parameter
342 * is <code>null</code>, it will be judged equivalent to an
343 * empty array.
344 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
345 * containing the delegation principles. This may be
346 * {@code null} is authentication is used instead.
347 * @return an {@link ObjectInstance} containing the {@link ObjectName}
348 * and Java class name of the created instance.
349 * @throws ReflectionException if an exception occurs in creating
350 * an instance of the bean.
351 * @throws InstanceAlreadyExistsException if a matching instance
352 * already exists.
353 * @throws MBeanRegistrationException if an exception occurs in
354 * calling the preRegister
355 * method.
356 * @throws MBeanException if the bean's constructor throws an exception.
357 * @throws NotCompliantMBeanException if the created bean is not
358 * compliant with the JMX specification.
359 * @throws InstanceNotFoundException if the specified class loader is not
360 * registered with the server.
361 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
362 * is thrown by the server due to a
363 * <code>null</code> class name or object
364 * name or if the object name is a pattern.
365 * @throws SecurityException if the client or delegated subject (if any) does
366 * not have permission to invoke this operation.
367 * @throws IOException if an I/O error occurred in communicating with
368 * the bean server.
369 */
377 IOException;
379 /**
380 * <p>
381 * Handles {@link
382 * MBeanServerConnection#createMBean(String, ObjectName,
383 * ObjectName)} by instantiating a new instance of the specified
384 * management bean using the default constructor and registering
385 * it with the server under the supplied name. The class is loaded
386 * using the given class loader. If this argument is <code>null</code>,
387 * then the same class loader as was used to load the server
388 * is used.
389 * </p>
390 * <p>
391 * If the name supplied is <code>null</code>, then the bean is
392 * expected to implement the {@link MBeanRegistration} interface.
393 * The {@link MBeanRegistration#preRegister preRegister} method
394 * of this interface will be used to obtain the name in this case.
395 * </p>
396 * <p>
397 * This method is equivalent to calling {@link
398 * #createMBean(String, ObjectName, ObjectName, Object[], String)
399 * <code>createMBean(className, name, loaderName, (Object[]) null,
400 * (String) null)</code>} with <code>null</code> parameters
401 * and signature.
402 * </p>
403 *
404 * @param className the class of the management bean, of which
405 * an instance should be created.
406 * @param name the name to register the new bean with. This may
407 * be <code>null</code>.
408 * @param loaderName the name of the class loader.
409 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
410 * containing the delegation principles. This may be
411 * {@code null} is authentication is used instead.
412 * @return an {@link ObjectInstance} containing the {@link ObjectName}
413 * and Java class name of the created instance.
414 * @throws ReflectionException if an exception occurs in creating
415 * an instance of the bean.
416 * @throws InstanceAlreadyExistsException if a matching instance
417 * already exists.
418 * @throws MBeanRegistrationException if an exception occurs in
419 * calling the preRegister
420 * method.
421 * @throws MBeanException if the bean's constructor throws an exception.
422 * @throws NotCompliantMBeanException if the created bean is not
423 * compliant with the JMX specification.
424 * @throws InstanceNotFoundException if the specified class loader is not
425 * registered with the server.
426 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
427 * is thrown by the server due to a
428 * <code>null</code> class name or object
429 * name or if the object name is a pattern.
430 * @throws SecurityException if the client or delegated subject (if any) does
431 * not have permission to invoke this operation.
432 * @throws IOException if an I/O error occurred in communicating with
433 * the bean server.
434 * @see #createMBean(String, ObjectName, ObjectName, MarshalledObject,
435 * String[], Subject)
436 */
442 IOException;
444 /**
445 * <p>
446 * Handles {@link
447 * MBeanServerConnection#createMBean(String, ObjectName)} by
448 * instantiating a new instance of the specified management bean
449 * using the default constructor and registering it with the server
450 * under the supplied name. The class is loaded using the
451 * {@link javax.management.loading.ClassLoaderRepository default
452 * loader repository} of the server.
453 * </p>
454 * <p>
455 * If the name supplied is <code>null</code>, then the bean is
456 * expected to implement the {@link MBeanRegistration} interface.
457 * The {@link MBeanRegistration#preRegister preRegister} method
458 * of this interface will be used to obtain the name in this case.
459 * </p>
460 * <p>
461 * This method is equivalent to calling {@link
462 * #createMBean(String, ObjectName, Object[], String[])
463 * <code>createMBean(className, name, (Object[]) null,
464 * (String[]) null)</code>} with <code>null</code> parameters
465 * and signature.
466 * </p>
467 *
468 * @param className the class of the management bean, of which
469 * an instance should be created.
470 * @param name the name to register the new bean with. This may
471 * be <code>null</code>.
472 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
473 * containing the delegation principles. This may be
474 * {@code null} is authentication is used instead.
475 * @return an {@link ObjectInstance} containing the {@link ObjectName}
476 * and Java class name of the created instance.
477 * @throws ReflectionException if an exception occurs in creating
478 * an instance of the bean.
479 * @throws InstanceAlreadyExistsException if a matching instance
480 * already exists.
481 * @throws MBeanRegistrationException if an exception occurs in
482 * calling the preRegister
483 * method.
484 * @throws MBeanException if the bean's constructor throws an exception.
485 * @throws NotCompliantMBeanException if the created bean is not
486 * compliant with the JMX specification.
487 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
488 * is thrown by the server due to a
489 * <code>null</code> class name or object
490 * name or if the object name is a pattern.
491 * @throws SecurityException if the client or delegated subject (if any) does
492 * not have permission to invoke this operation.
493 * @throws IOException if an I/O error occurred in communicating with
494 * the bean server.
495 * @see #createMBean(String, ObjectName, MarshalledObject, String[], Subject)
496 */
498 Subject delegationSubject)
503 /**
504 * <p>
505 * Retrieves any waiting notifications from the server. When notifications
506 * are requested using the {@link #addNotificationListeners(ObjectName[],
507 * MarshalledObject[], Subject[])} method, the server sets up an internal
508 * listener to receive notifications from the bean and buffer them. When
509 * this method is called, these buffered notifications can be retrieved.
510 * </p>
511 * <p>
512 * The blocking behaviour of this method depends on the timeout value specified.
513 * If there are no waiting notifications in the buffer, a value of 0 will cause
514 * the method to return immediately. Conversely, if the value is
515 * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification
516 * arrives. For any other value, it waits until a notification arrives or the
517 * number of milliseconds specified by the timeout value is exceeded. The
518 * behaviour for a negative timeout value is undefined.
519 * </p>
520 * <p>
521 * For a notification to be returned, the following criteria must be fulfilled:
522 * </p>
523 * <ul>
524 * <li>the client must have previously requested notifications from at least
525 * one bean</li>
526 * <li>a bean from which notifications have been requested must have emitted
527 * a notification since the last call to this method</li>
528 * <li>the emitted notification must pass through any filters established
529 * when notifications were requested</li>
530 * <li>the sequence number of the notification must be greater than or equal
531 * to the specified sequence number (if non-negative)</li>
532 * </ul>
533 *
534 * @param sequenceNumber the sequence number of each notification returned
535 * must be greater than or equal to this value. If
536 * the number is negative, this is interpreted as
537 * meaning the sequence number of the next notification
538 * and so all notifications are allowed through.
539 * @param maxNotifications the maximum number of notifications to return.
540 * This does not include any duplicates so the
541 * number of actual notifications returned may
542 * be larger.
543 * @param timeout the number of milliseconds to wait for a notification
544 * if the buffer is empty. <code>0</code> causes the
545 * method to return immediately even if there are no
546 * notifications available (non-blocking behaviour) while
547 * a value of {@link Long#MAX_VALUE} causes it to wait
548 * indefinitely (blocking behaviour). The response to
549 * a negative value is undefined.
550 * @return a {@link NotificationResult} object containing the buffered
551 * notifications.
552 * @throws IOException if an I/O error occurs.
553 */
559 /**
560 * Handles {@link
561 * MBeanServerConnection#getAttribute(ObjectName, String)},
562 * returning the value of the supplied attribute from the specified
563 * management bean.
564 *
565 * @param bean the bean to retrieve the value from.
566 * @param name the name of the attribute to retrieve.
567 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
568 * containing the delegation principles. This may be
569 * {@code null} is authentication is used instead.
570 * @return the value of the attribute.
571 * @throws AttributeNotFoundException if the attribute could not be
572 * accessed from the bean.
573 * @throws MBeanException if the management bean's accessor throws
574 * an exception.
575 * @throws InstanceNotFoundException if the bean can not be found.
576 * @throws ReflectionException if an exception was thrown in trying
577 * to invoke the bean's accessor.
578 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
579 * is thrown by the server due to a
580 * <code>null</code> bean or attribute
581 * name.
582 * @throws SecurityException if the client or delegated subject (if any) does
583 * not have permission to invoke this operation.
584 * @throws IOException if an I/O error occurred in communicating with
585 * the bean server.
586 * @see DynamicMBean#getAttribute(String)
587 */
591 IOException;
593 /**
594 * Handles {@link
595 * MBeanServerConnection#getAttribute(ObjectName, String)},
596 * returning the values of the named attributes from the specified
597 * management bean.
598 *
599 * @param bean the bean to retrieve the value from.
600 * @param names the names of the attributes to retrieve.
601 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
602 * containing the delegation principles. This may be
603 * {@code null} is authentication is used instead.
604 * @return the values of the attributes.
605 * @throws InstanceNotFoundException if the bean can not be found.
606 * @throws ReflectionException if an exception was thrown in trying
607 * to invoke the bean's accessor.
608 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
609 * is thrown by the server due to a
610 * <code>null</code> bean or attribute
611 * name.
612 * @throws SecurityException if the client or delegated subject (if any) does
613 * not have permission to invoke this operation.
614 * @throws IOException if an I/O error occurred in communicating with
615 * the bean server.
616 * @see DynamicMBean#getAttributes(String[])
617 */
619 Subject delegationSubject)
621 IOException;
623 /**
624 * Returns the unique identifier for this connection to the RMI
625 * server.
626 *
627 * @return the connection ID.
628 * @throws IOException if an I/O error occurred.
629 */
633 /**
634 * Handles {@link
635 * MBeanServerConnection#getDefaultDomain()} by returning the default
636 * domain this server applies to beans that have no specified domain.
637 *
638 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
639 * containing the delegation principles. This may be
640 * {@code null} is authentication is used instead.
641 * @return the default domain.
642 * @throws SecurityException if the client or delegated subject (if any) does
643 * not have permission to invoke this operation.
644 * @throws IOException if an I/O error occurred in communicating with
645 * the bean server.
646 */
650 /**
651 * Handles {@link
652 * MBeanServerConnection#getDomains()} by returning an array
653 * containing all the domains used by beans registered with
654 * this server. The ordering of the array is undefined.
655 *
656 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
657 * containing the delegation principles. This may be
658 * {@code null} is authentication is used instead.
659 * @return the list of domains.
660 * @throws SecurityException if the client or delegated subject (if any) does
661 * not have permission to invoke this operation.
662 * @throws IOException if an I/O error occurred in communicating with
663 * the bean server.
664 * @see ObjectName#getDomain()
665 */
669 /**
670 * Handles {@link
671 * MBeanServerConnection#getMBeanCount()} by returning the number of
672 * management beans registered with this server.
673 *
674 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
675 * containing the delegation principles. This may be
676 * {@code null} is authentication is used instead.
677 * @return the number of registered beans.
678 * @throws SecurityException if the client or delegated subject (if any) does
679 * not have permission to invoke this operation.
680 * @throws IOException if an I/O error occurred in communicating with
681 * the bean server.
682 */
686 /**
687 * Handles {@link
688 * MBeanServerConnection#getMBeanInfo(ObjectName)} by returning
689 * information on the given management bean.
690 *
691 * @param name the name of the management bean.
692 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
693 * containing the delegation principles. This may be
694 * {@code null} is authentication is used instead.
695 * @return an instance of {@link MBeanInfo} for the bean.
696 * @throws IntrospectionException if an exception occurs in examining
697 * the bean.
698 * @throws InstanceNotFoundException if the bean can not be found.
699 * @throws ReflectionException if an exception occurs when trying
700 * to invoke {@link DynamicMBean#getMBeanInfo()}
701 * on the bean.
702 * @throws SecurityException if the client or delegated subject (if any) does
703 * not have permission to invoke this operation.
704 * @throws IOException if an I/O error occurred in communicating with
705 * the bean server.
706 * @see DynamicMBean#getMBeanInfo()
707 */
712 /**
713 * Handles {@link
714 * MBeanServerConnection#getObjectInstance(ObjectName)} by returning
715 * the {@link ObjectInstance} created for the specified management
716 * bean on registration.
717 *
718 * @param name the name of the bean.
719 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
720 * containing the delegation principles. This may be
721 * {@code null} is authentication is used instead.
722 * @return the corresponding {@link ObjectInstance} instance.
723 * @throws InstanceNotFoundException if the bean can not be found.
724 * @throws SecurityException if the client or delegated subject (if any) does
725 * not have permission to invoke this operation.
726 * @throws IOException if an I/O error occurred in communicating with
727 * the bean server.
728 * @see #createMBean(String, ObjectName, Subject)
729 */
733 /**
734 * <p>
735 * Handles {@link
736 * MBeanServerConnection#invoke(ObjectName, String, Object[],
737 * String[])}. The array of parameters is wrapped in a
738 * {@link MarshalledObject} so that it is deserialised
739 * using the bean's classloader.
740 * </p>
741 * <p>
742 * Invokes the supplied operation on the specified management
743 * bean. The class objects specified in the signature are loaded
744 * using the same class loader as was used for the management bean.
745 *
746 * @param bean the management bean whose operation should be invoked.
747 * @param name the name of the operation to invoke.
748 * @param params the parameters for the bean's constructor, encapsulated
749 * in a {@link MarshalledObject}. If this parameter is
750 * <code>null</code>, it will be judged equivalent to an
751 * empty array.
752 * @param sig the signature of the constructor to use. If this parameter
753 * is <code>null</code>, it will be judged equivalent to an
754 * empty array. The class objects will be loaded using the
755 * bean's classloader.
756 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
757 * containing the delegation principles. This may be
758 * {@code null} is authentication is used instead.
759 * @return the return value of the method.
760 * @throws InstanceNotFoundException if the bean can not be found.
761 * @throws MBeanException if the method invoked throws an exception.
762 * @throws ReflectionException if an exception is thrown in invoking the
763 * method.
764 * @throws SecurityException if the client or delegated subject (if any) does
765 * not have permission to invoke this operation.
766 * @throws IOException if an I/O error occurred in communicating with
767 * the bean server.
768 * @see DynamicMBean#invoke(String, Object[], String[])
769 */
776 /**
777 * <p>
778 * Handles {@link
779 * MBeanServerConnection#isInstanceOf(ObjectName, String) by
780 * returning true if the specified management bean is an instance
781 * of the supplied class.
782 * </p>
783 * <p>
784 * A bean, B, is an instance of a class, C, if either of the following
785 * conditions holds:
786 * </p>
787 * <ul>
788 * <li>The class name in B's {@link MBeanInfo} is equal to the supplied
789 * name.</li>
790 * <li>Both the class of B and C were loaded by the same class loader,
791 * and B is assignable to C.</li>
792 * </ul>
793 *
794 * @param name the name of the management bean.
795 * @param className the name of the class to test if <code>name</code> is
796 * an instance of.
797 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
798 * containing the delegation principles. This may be
799 * {@code null} is authentication is used instead.
800 * @return true if either B is directly an instance of the named class,
801 * or B is assignable to the class, given that both it and B's
802 * current class were loaded using the same class loader.
803 * @throws InstanceNotFoundException if the bean can not be found.
804 * @throws SecurityException if the client or delegated subject (if any) does
805 * not have permission to invoke this operation.
806 * @throws IOException if an I/O error occurred in communicating with
807 * the bean server.
808 */
810 Subject delegationSubject)
813 /**
814 * Handles {@link
815 * MBeanServerConnection#isRegistered(ObjectName) by returning
816 * true if the specified management bean is registered with
817 * the server.
818 *
819 * @param name the name of the management bean.
820 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
821 * containing the delegation principles. This may be
822 * {@code null} is authentication is used instead.
823 * @return true if the bean is registered.
824 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
825 * is thrown by the server due to a
826 * <code>null</code> bean name.
827 * @throws SecurityException if the client or delegated subject (if any) does
828 * not have permission to invoke this operation.
829 * @throws IOException if an I/O error occurred in communicating with
830 * the bean server.
831 */
835 /**
836 * <p>
837 * Handles {@link
838 * MBeanServerConnection#queryMBeans(ObjectName, QueryExp)}.
839 * The query expression is wrapped in a {@link MarshalledObject}
840 * so that it is deserialised using the bean's classloader.
841 * </p>
842 * <p>
843 * Returns a set of {@link ObjectInstance}s matching the specified
844 * criteria. The full set of beans registered with the server
845 * are passed through two filters:
846 * </p>
847 * <ol>
848 * <li>Pattern matching is performed using the supplied
849 * {@link ObjectName}.</li>
850 * <li>The supplied query expression is applied.</li>
851 * </ol>
852 * <p>
853 * If both the object name and the query expression are <code>null</code>,
854 * or the object name has no domain and no key properties,
855 * no filtering will be performed and all beans are returned.
856 * </p>
857 *
858 * @param name an {@link ObjectName} to use as a filter.
859 * @param query a query expression to apply to each of the beans that match
860 * the given object name, encapsulated in a
861 * {@link MarshalledObject}. If a <code>null</code> value is
862 * encapsulated, then the beans will only be filtered using
863 * pattern matching on the supplied {@link ObjectName}.
864 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
865 * containing the delegation principles. This may be
866 * {@code null} is authentication is used instead.
867 * @return a set of {@link ObjectInstance}s matching the filtered beans.
868 * This is empty if no beans survived the filters.
869 * @throws IOException if an I/O error occurred in communicating with
870 * the bean server.
871 * @throws SecurityException if the client or delegated subject (if any) does
872 * not have permission to invoke this operation.
873 */
876 Subject delegationSubject)
879 /**
880 * <p>
881 * Handles {@link
882 * MBeanServerConnection#queryNames(ObjectName, QueryExp)}.
883 * The query expression is wrapped in a {@link MarshalledObject}
884 * so that it is deserialised using the bean's classloader.
885 * </p>
886 * <p>
887 * Returns a set of {@link ObjectName}s matching the specified
888 * criteria. The full set of beans registered with the server
889 * are passed through two filters:
890 * </p>
891 * <ol>
892 * <li>Pattern matching is performed using the supplied
893 * {@link ObjectName}.</li>
894 * <li>The supplied query expression is applied.</li>
895 * </ol>
896 * <p>
897 * If both the object name and the query expression are <code>null</code>,
898 * or the object name has no domain and no key properties,
899 * no filtering will be performed and all beans are returned.
900 * </p>
901 *
902 * @param name an {@link ObjectName} to use as a filter.
903 * @param query a query expression to apply to each of the beans that match
904 * the given object name, encapsulated in a
905 * {@link MarshalledObject}. If a <code>null</code> value is
906 * encapsulated, then the beans will only be filtered using
907 * pattern matching on the supplied {@link ObjectName}.
908 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
909 * containing the delegation principles. This may be
910 * {@code null} is authentication is used instead.
911 * @return a set of {@link ObjectName}s matching the filtered beans.
912 * @throws SecurityException if the client or delegated subject (if any) does
913 * not have permission to invoke this operation.
914 * @throws IOException if an I/O error occurred in communicating with
915 * the bean server.
916 */
919 Subject delegationSubject)
922 /**
923 * <p>
924 * Handles {@link
925 * MBeanServerConnection#removeNotificationListener(ObjectName,
926 * ObjectName, NotificationFilter, Object)}. Both the filter and
927 * the handback object are wrapped in a {@link MarshalledObject}
928 * so that they are deserialised using the bean's classloader.
929 * </p>
930 * <p>
931 * Removes the specified listener from the list of recipients
932 * of notifications from the supplied bean. Only the first instance with
933 * the supplied filter and passback object is removed.
934 * <code>null</code> is used as a valid value for these parameters,
935 * rather than as a way to remove all registration instances for
936 * the specified listener; for this behaviour instead, see
937 * {@link #removeNotificationListener(ObjectName, NotificationListener)}.
938 * </p>
939 *
940 * @param name the name of the management bean from which the
941 * listener should be removed.
942 * @param listener the listener to remove.
943 * @param filter a wrapper containing the filter of the listener
944 * to remove.
945 * @param passback a wrapper containing the handback object of the
946 * listener to remove.
947 * @param delegationSubject a {@link javax.security.auth.Subject} instance
948 * containing the delegation principles or
949 * {@code null} if authentication is used.
950 * @throws InstanceNotFoundException if the bean can not be found.
951 * @throws ListenerNotFoundException if the specified listener
952 * is not registered with the bean.
953 * @throws SecurityException if the client or delegated subject (if any) does
954 * not have permission to invoke this operation.
955 * @throws IOException if an I/O error occurred in communicating with
956 * the bean server.
957 * @see #addNotificationListener(ObjectName, NotificationListener,
958 * MarshalledObject, MarshalledObject, Subject)
959 * @see NotificationEmitter#removeNotificationListener(NotificationListener,
960 * NotificationFilter,
961 * Object)
962 */
965 ObjectName listener,
966 MarshalledObject filter,
967 MarshalledObject passback,
968 Subject delegationSubject)
970 IOException;
972 /**
973 * Handles {@link
974 * MBeanServerConnection#removeNotificationListener(ObjectName,
975 * ObjectName)} by removing the specified listener from the list
976 * of recipients of notifications from the supplied bean. This
977 * includes all combinations of filters and passback objects
978 * registered for this listener. For more specific removal of
979 * listeners, see {@link #removeNotificationListener(ObjectName,
980 * ObjectName,MarshalledObject,MarshalledObject,Subject)}
981 *
982 * @param name the name of the management bean from which the
983 * listener should be removed.
984 * @param listener the name of the listener to remove.
985 * @param delegationSubject a {@link javax.security.auth.Subject} instance
986 * containing the delegation principles or
987 * {@code null} if authentication is used.
988 * @throws InstanceNotFoundException if a name doesn't match a registered
989 * bean.
990 * @throws ListenerNotFoundException if the specified listener
991 * is not registered with the bean.
992 * @throws SecurityException if the client or delegated subject (if any) does
993 * not have permission to invoke this operation.
994 * @throws IOException if an I/O error occurred in communicating with
995 * the bean server.
996 * @see #addNotificationListener(ObjectName, NotificationListener,
997 * MarshalledObject, MarshalledObject, Subject)
998 * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
999 */
1001 Subject delegationSubject)
1003 IOException;
1005 /**
1006 * Removes one or more {@link NotificationListener}s from the specified
1007 * management bean. This method corresponds to
1008 * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1009 * Subject)} and provides a different way of handling
1010 * MBeanServerConnection#removeNotificationListener(ObjectName,
1011 * ObjectName)} and
1012 * {@link MBeanServerConnection#removeNotificationListener(ObjectName,
1013 * ObjectName, NotificationFilter, Object)} by using the integer
1014 * identifiers provided by the
1015 * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1016 * Subject)} method to select the listeners to remove.
1017 *
1018 * @param name the name of the management bean from which the
1019 * listeners should be removed.
1020 * @param listenerIds the identifiers of the listeners to remove.
1021 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1022 * containing the delegation principles or
1023 * {@code null} if authentication is used.
1024 * @throws InstanceNotFoundException if a name doesn't match a registered
1025 * bean.
1026 * @throws ListenerNotFoundException if the specified listener
1027 * is not registered with the bean.
1028 * @throws SecurityException if the client or delegated subject (if any) does
1029 * not have permission to invoke this operation.
1030 * @throws IOException if an I/O error occurred in communicating with
1031 * the bean server.
1032 * @throws IllegalArgumentException if either <code>name</code>,
1033 * <code>listenerIds</code> or an element
1034 * of <code>listenerIds</code>
1035 * is <code>null</code>.
1036 * @see #addNotificationListeners(ObjectName[], MarshalledObject[], Subject)
1037 */
1039 Subject delegationSubject)
1041 IOException;
1043 /**
1044 * Handles {@link
1045 * MBeanServerConnection#setAttribute(ObjectName, Attribute)}
1046 * by setting the value of the specified attribute of the supplied
1047 * management bean. The attribute is wrapped in a
1048 * {@link MarshalledObject} so that it is deserialised using the
1049 * bean's classloader.
1050 *
1051 * @param name the name of the management bean.
1052 * @param attribute the attribute to set, encapsulated in a
1053 * {@link MarshalledObject}.
1054 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1055 * containing the delegation principles or
1056 * {@code null} if authentication is used.
1057 * @throws InstanceNotFoundException if the bean can not be found.
1058 * @throws AttributeNotFoundException if the attribute does not
1059 * correspond to an attribute
1060 * of the bean.
1061 * @throws InvalidAttributeValueException if the value is invalid
1062 * for this particular
1063 * attribute of the bean.
1064 * @throws MBeanException if setting the attribute causes
1065 * the bean to throw an exception (which
1066 * becomes the cause of this exception).
1067 * @throws ReflectionException if an exception occurred in trying
1068 * to use the reflection interface
1069 * to lookup the attribute. The
1070 * thrown exception is the cause of
1071 * this exception.
1072 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1073 * is thrown by the server due to a
1074 * <code>null</code> bean or attribute
1075 * name.
1076 * @throws SecurityException if the client or delegated subject (if any) does
1077 * not have permission to invoke this operation.
1078 * @throws IOException if an I/O error occurred in communicating with
1079 * the bean server.
1080 * @see #getAttribute(ObjectName, String, Subject)
1081 * @see javax.management.DynamicMBean#setAttribute(Attribute)
1082 */
1085 Subject delegationSubject)
1090 /**
1091 * Handles {@link
1092 * MBeanServerConnection#setAttributes(ObjectName, AttributeList)}
1093 * by setting the value of each of the specified attributes
1094 * of the supplied management bean to that specified by
1095 * the {@link Attribute} object. The returned list contains
1096 * the attributes that were set and their new values.
1097 * The attribute list is wrapped in a {@link MarshalledObject} so
1098 * that it is deserialised using the bean's classloader.
1099 *
1100 * @param name the name of the management bean.
1101 * @param attributes the attributes to set, encapsulated in a
1102 * {@link MarshalledObject}.
1103 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1104 * containing the delegation principles or
1105 * {@code null} if authentication is used.
1106 * @return a list of the changed attributes.
1107 * @throws InstanceNotFoundException if the bean can not be found.
1108 * @throws ReflectionException if an exception occurred in trying
1109 * to use the reflection interface
1110 * to lookup the attribute. The
1111 * thrown exception is the cause of
1112 * this exception.
1113 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1114 * is thrown by the server due to a
1115 * <code>null</code> bean or attribute
1116 * list.
1117 * @throws SecurityException if the client or delegated subject (if any) does
1118 * not have permission to invoke this operation.
1119 * @throws IOException if an I/O error occurred in communicating with
1120 * the bean server.
1121 * @see #getAttributes(ObjectName, String[])
1122 * @see DynamicMBean#setAttributes(AttributeList)
1123 */
1126 Subject delegationSubject)
1128 IOException;
1130 /**
1131 * Handles {@link
1132 * MBeanServerConnection#unregisterMBean(ObjectName)} by unregistering
1133 * the specified management bean. Following this operation,
1134 * the bean instance is no longer accessible from the server via this
1135 * name. Prior to unregistering the bean, the
1136 * {@link MBeanRegistration#preDeregister()} method will be called if
1137 * the bean implements the {@link MBeanRegistration} interface.
1138 *
1139 * @param name the name of the management bean.
1140 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1141 * containing the delegation principles or
1142 * {@code null} if authentication is used.
1143 * @throws InstanceNotFoundException if the bean can not be found.
1144 * @throws MBeanRegistrationException if an exception occurs in
1145 * calling the preDeregister
1146 * method.
1147 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1148 * is thrown by the server due to a
1149 * <code>null</code> bean name or a
1150 * request being made to unregister the
1151 * {@link MBeanServerDelegate} bean.
1152 * @throws SecurityException if the client or delegated subject (if any) does
1153 * not have permission to invoke this operation.
1154 * @throws IOException if an I/O error occurred in communicating with
1155 * the bean server.
1156 */
1159 IOException;
1161 }