| blob | 38fb544fe457279347147dfdd95c1a52f7e4fb1c |
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 */
157 Subject delegationSubject)
160 /**
161 * Handles {@link
162 * MBeanServerConnection#addNotificationListener(ObjectName,
163 * NotificationListener, NotificationFilter, Object)} by
164 * registering for notifications from the specified management
165 * beans. The array of filters is assumed to be aligned with
166 * the array of bean names, so that the notifications from each
167 * bean are matched against the appropriate filter (or left as
168 * is if the filter is {@code null}. Notifications emitted by
169 * the management beans are forwarded to a local listener created
170 * by this method, via the server, which converts any MBean
171 * references in the source to portable {@link ObjectName}
172 * instances. The notification is otherwise unchanged.
173 * </p>
174 * <p>
175 * This local listener buffers the notifications for retrieval by
176 * {@link #fetchNotifications(long,int,long). This method returns
177 * an array of listener identifiers which aligns with the supplied
178 * array of beans so that the appropriate listener can be identified
179 * by the client, which retains its own listener and handback object.
180 * The filters are wrapped in {@link MarshalledObject}s so that they are
181 * deserialised using the bean's classloader.
182 * </p>
183 *
184 * @param names the names of the management bean whose notifications
185 * should be recorded.
186 * @param filters an array of wrappers containing filters to apply to
187 * incoming notifications. An element may be <code>null</code>
188 * if no filtering should be applied to a bean's notifications.
189 * @param delegationSubjects an array of {@link javax.security.auth.Subject}
190 * instances containing the delegation principles for
191 * each listener. An element may be {@code null} if
192 * authentication is used instead, or the entire
193 * argument itself may be {@code null}. In the latter
194 * case, this is treated as an array of {@code null}
195 * values.
196 * @return an array of integers which act as listener identifiers, so that
197 * notifications retrieved from {@link #fetchNotifications(long,int,long)
198 * can be matched to the beans they were emitted from. The array is
199 * aligned against the array of beans supplied to this methods, so that
200 * the identifier in position 0 represents the bean in position 0 of the
201 * input array.
202 * @throws IllegalArgumentException if the {@code names} or {@code filters} array
203 * is {@code null}, the {@code names} array contains
204 * a {@code null} value or the three arrays are not
205 * of the same size.
206 * @throws ClassCastException if an element of the {@code filters} array unmarshalls
207 * as a non-null object that is not a {@link NotificationFilter}.
208 * @throws InstanceNotFoundException if the name of one of the management beans
209 * could not be resolved.
210 * @throws SecurityException if, for one of the beans, the client or delegated subject
211 * (if any) does not have permission to invoke this operation.
212 * @throws IOException if an I/O error occurred in communicating with
213 * the bean server.
214 * @see #removeNotificationListener(ObjectName, ObjectName,
215 * javax.security.auth.Subject)
216 * @see #removeNotificationListener(ObjectName, ObjectName,
217 * java.rmi.MarshalledObject,
218 * java.rmi.MarshalledObject,
219 * javax.security.auth.Subject)
220 * @see #removeNotificationListeners(ObjectName, Integer[],
221 * javax.security.auth.Subject)
222 * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
223 * NotificationFilter,
224 * Object)
225 */
230 /**
231 * Closes the connection and unexports the RMI object implementing this
232 * interface. Following this call, future method calls to this instance
233 * will fail.
234 *
235 * @throws IOException if there is an I/O error in transmitting the close
236 * request via RMI, closing the connection, or unexporting
237 * the RMI object.
238 */
242 /**
243 * <p>
244 * Handles {@link
245 * MBeanServerConnection#createMBean(String, ObjectName,
246 * Object[], String[])}. The array of parameters is wrapped in
247 * a {@link MarshalledObject} so that it is deserialised using the
248 * bean's classloader.
249 * </p>
250 * <p>
251 * Instantiates a new instance of the specified management bean
252 * using the given constructor and registers it with the server
253 * under the supplied name. The class is loaded using the
254 * {@link javax.management.loading.ClassLoaderRepository default
255 * loader repository} of the server.
256 * </p>
257 * <p>
258 * If the name supplied is <code>null</code>, then the bean is
259 * expected to implement the {@link MBeanRegistration} interface.
260 * The {@link MBeanRegistration#preRegister preRegister} method
261 * of this interface will be used to obtain the name in this case.
262 * </p>
263 *
264 * @param className the class of the management bean, of which
265 * an instance should be created.
266 * @param name the name to register the new bean with. This may
267 * be <code>null</code>.
268 * @param params the parameters for the bean's constructor, encapsulated
269 * in a {@link MarshalledObject}. If this parameter is
270 * <code>null</code>, it will be judged equivalent to an
271 * empty array.
272 * @param sig the signature of the constructor to use. If this parameter
273 * is <code>null</code>, it will be judged equivalent to an
274 * empty array.
275 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
276 * containing the delegation principles. This may be
277 * {@code null} is authentication is used instead.
278 * @return an {@link ObjectInstance} containing the {@link ObjectName}
279 * and Java class name of the created instance.
280 * @throws ReflectionException if an exception occurs in creating
281 * an instance of the bean.
282 * @throws InstanceAlreadyExistsException if a matching instance
283 * already exists.
284 * @throws MBeanRegistrationException if an exception occurs in
285 * calling the preRegister
286 * method.
287 * @throws MBeanException if the bean's constructor throws an exception.
288 * @throws NotCompliantMBeanException if the created bean is not
289 * compliant with the JMX specification.
290 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
291 * is thrown by the server due to a
292 * <code>null</code> class name or object
293 * name or if the object name is a pattern.
294 * @throws SecurityException if the client or delegated subject (if any) does
295 * not have permission to invoke this operation.
296 * @throws IOException if an I/O error occurred in communicating with
297 * the bean server.
298 */
301 Subject delegationSubject)
306 /**
307 * <p>
308 * Handles {@link
309 * MBeanServerConnection#createMBean(String, ObjectName,
310 * ObjectName, Object[], String[])}. The array of parameters is
311 * wrapped in a {@link MarshalledObject} so that it is deserialised
312 * using the bean's classloader.
313 * </p>
314 * <p>
315 * Instantiates a new instance of the specified management bean
316 * using the given constructor and registers it with the server
317 * under the supplied name. The class is loaded using the
318 * given class loader. If this argument is <code>null</code>,
319 * then the same class loader as was used to load the server
320 * is used.
321 * </p>
322 * <p>
323 * If the name supplied is <code>null</code>, then the bean is
324 * expected to implement the {@link MBeanRegistration} interface.
325 * The {@link MBeanRegistration#preRegister preRegister} method
326 * of this interface will be used to obtain the name in this case.
327 * </p>
328 *
329 * @param className the class of the management bean, of which
330 * an instance should be created.
331 * @param name the name to register the new bean with. This may
332 * be <code>null</code>.
333 * @param loaderName the name of the class loader.
334 * @param params the parameters for the bean's constructor, encapsulated
335 * in a {@link MarshalledObject}. If this parameter is
336 * <code>null</code>, it will be judged equivalent to an
337 * empty array.
338 * @param sig the signature of the constructor to use. If this parameter
339 * is <code>null</code>, it will be judged equivalent to an
340 * empty array.
341 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
342 * containing the delegation principles. This may be
343 * {@code null} is authentication is used instead.
344 * @return an {@link ObjectInstance} containing the {@link ObjectName}
345 * and Java class name of the created instance.
346 * @throws ReflectionException if an exception occurs in creating
347 * an instance of the bean.
348 * @throws InstanceAlreadyExistsException if a matching instance
349 * already exists.
350 * @throws MBeanRegistrationException if an exception occurs in
351 * calling the preRegister
352 * method.
353 * @throws MBeanException if the bean's constructor throws an exception.
354 * @throws NotCompliantMBeanException if the created bean is not
355 * compliant with the JMX specification.
356 * @throws InstanceNotFoundException if the specified class loader is not
357 * registered with the server.
358 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
359 * is thrown by the server due to a
360 * <code>null</code> class name or object
361 * name or if the object name is a pattern.
362 * @throws SecurityException if the client or delegated subject (if any) does
363 * not have permission to invoke this operation.
364 * @throws IOException if an I/O error occurred in communicating with
365 * the bean server.
366 */
373 IOException;
375 /**
376 * <p>
377 * Handles {@link
378 * MBeanServerConnection#createMBean(String, ObjectName,
379 * ObjectName)} by instantiating a new instance of the specified
380 * management bean using the default constructor and registering
381 * it with the server under the supplied name. The class is loaded
382 * using the given class loader. If this argument is <code>null</code>,
383 * then the same class loader as was used to load the server
384 * is used.
385 * </p>
386 * <p>
387 * If the name supplied is <code>null</code>, then the bean is
388 * expected to implement the {@link MBeanRegistration} interface.
389 * The {@link MBeanRegistration#preRegister preRegister} method
390 * of this interface will be used to obtain the name in this case.
391 * </p>
392 * <p>
393 * This method is equivalent to calling {@link
394 * #createMBean(String, ObjectName, ObjectName, Object[], String)
395 * <code>createMBean(className, name, loaderName, (Object[]) null,
396 * (String) null)</code>} with <code>null</code> parameters
397 * and signature.
398 * </p>
399 *
400 * @param className the class of the management bean, of which
401 * an instance should be created.
402 * @param name the name to register the new bean with. This may
403 * be <code>null</code>.
404 * @param loaderName the name of the class loader.
405 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
406 * containing the delegation principles. This may be
407 * {@code null} is authentication is used instead.
408 * @return an {@link ObjectInstance} containing the {@link ObjectName}
409 * and Java class name of the created instance.
410 * @throws ReflectionException if an exception occurs in creating
411 * an instance of the bean.
412 * @throws InstanceAlreadyExistsException if a matching instance
413 * already exists.
414 * @throws MBeanRegistrationException if an exception occurs in
415 * calling the preRegister
416 * method.
417 * @throws MBeanException if the bean's constructor throws an exception.
418 * @throws NotCompliantMBeanException if the created bean is not
419 * compliant with the JMX specification.
420 * @throws InstanceNotFoundException if the specified class loader is not
421 * registered with the server.
422 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
423 * is thrown by the server due to a
424 * <code>null</code> class name or object
425 * name or if the object name is a pattern.
426 * @throws SecurityException if the client or delegated subject (if any) does
427 * not have permission to invoke this operation.
428 * @throws IOException if an I/O error occurred in communicating with
429 * the bean server.
430 * @see #createMBean(String, ObjectName, ObjectName, MarshalledObject,
431 * String[], Subject)
432 */
438 IOException;
440 /**
441 * <p>
442 * Handles {@link
443 * MBeanServerConnection#createMBean(String, ObjectName)} by
444 * instantiating a new instance of the specified management bean
445 * using the default constructor and registering it with the server
446 * under the supplied name. The class is loaded using the
447 * {@link javax.management.loading.ClassLoaderRepository default
448 * loader repository} of the server.
449 * </p>
450 * <p>
451 * If the name supplied is <code>null</code>, then the bean is
452 * expected to implement the {@link MBeanRegistration} interface.
453 * The {@link MBeanRegistration#preRegister preRegister} method
454 * of this interface will be used to obtain the name in this case.
455 * </p>
456 * <p>
457 * This method is equivalent to calling {@link
458 * #createMBean(String, ObjectName, Object[], String[])
459 * <code>createMBean(className, name, (Object[]) null,
460 * (String[]) null)</code>} with <code>null</code> parameters
461 * and signature.
462 * </p>
463 *
464 * @param className the class of the management bean, of which
465 * an instance should be created.
466 * @param name the name to register the new bean with. This may
467 * be <code>null</code>.
468 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
469 * containing the delegation principles. This may be
470 * {@code null} is authentication is used instead.
471 * @return an {@link ObjectInstance} containing the {@link ObjectName}
472 * and Java class name of the created instance.
473 * @throws ReflectionException if an exception occurs in creating
474 * an instance of the bean.
475 * @throws InstanceAlreadyExistsException if a matching instance
476 * already exists.
477 * @throws MBeanRegistrationException if an exception occurs in
478 * calling the preRegister
479 * method.
480 * @throws MBeanException if the bean's constructor throws an exception.
481 * @throws NotCompliantMBeanException if the created bean is not
482 * compliant with the JMX specification.
483 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
484 * is thrown by the server due to a
485 * <code>null</code> class name or object
486 * name or if the object name is a pattern.
487 * @throws SecurityException if the client or delegated subject (if any) does
488 * not have permission to invoke this operation.
489 * @throws IOException if an I/O error occurred in communicating with
490 * the bean server.
491 * @see #createMBean(String, ObjectName, MarshalledObject, String[], Subject)
492 */
494 Subject delegationSubject)
499 /**
500 * <p>
501 * Retrieves any waiting notifications from the server. When notifications
502 * are requested using the {@link #addNotificationListeners(ObjectName[],
503 * MarshalledObject[], Subject[])} method, the server sets up an internal
504 * listener to receive notifications from the bean and buffer them. When
505 * this method is called, these buffered notifications can be retrieved.
506 * </p>
507 * <p>
508 * The blocking behaviour of this method depends on the timeout value specified.
509 * If there are no waiting notifications in the buffer, a value of 0 will cause
510 * the method to return immediately. Conversely, if the value is
511 * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification
512 * arrives. For any other value, it waits until a notification arrives or the
513 * number of milliseconds specified by the timeout value is exceeded. The
514 * behaviour for a negative timeout value is undefined.
515 * </p>
516 * <p>
517 * For a notification to be returned, the following criteria must be fulfilled:
518 * </p>
519 * <ul>
520 * <li>the client must have previously requested notifications from at least
521 * one bean</li>
522 * <li>a bean from which notifications have been requested must have emitted
523 * a notification since the last call to this method</li>
524 * <li>the emitted notification must pass through any filters established
525 * when notifications were requested</li>
526 * <li>the sequence number of the notification must be greater than or equal
527 * to the specified sequence number (if non-negative)</li>
528 * </ul>
529 *
530 * @param sequenceNumber the sequence number of each notification returned
531 * must be greater than or equal to this value. If
532 * the number is negative, this is interpreted as
533 * meaning the sequence number of the next notification
534 * and so all notifications are allowed through.
535 * @param maxNotifications the maximum number of notifications to return.
536 * This does not include any duplicates so the
537 * number of actual notifications returned may
538 * be larger.
539 * @param timeout the number of milliseconds to wait for a notification
540 * if the buffer is empty. <code>0</code> causes the
541 * method to return immediately even if there are no
542 * notifications available (non-blocking behaviour) while
543 * a value of {@link Long#MAX_VALUE} causes it to wait
544 * indefinitely (blocking behaviour). The response to
545 * a negative value is undefined.
546 * @return a {@link NotificationResult} object containing the buffered
547 * notifications.
548 * @throws IOException if an I/O error occurs.
549 */
555 /**
556 * Handles {@link
557 * MBeanServerConnection#getAttribute(ObjectName, String)},
558 * returning the value of the supplied attribute from the specified
559 * management bean.
560 *
561 * @param bean the bean to retrieve the value from.
562 * @param name the name of the attribute to retrieve.
563 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
564 * containing the delegation principles. This may be
565 * {@code null} is authentication is used instead.
566 * @return the value of the attribute.
567 * @throws AttributeNotFoundException if the attribute could not be
568 * accessed from the bean.
569 * @throws MBeanException if the management bean's accessor throws
570 * an exception.
571 * @throws InstanceNotFoundException if the bean can not be found.
572 * @throws ReflectionException if an exception was thrown in trying
573 * to invoke the bean's accessor.
574 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
575 * is thrown by the server due to a
576 * <code>null</code> bean or attribute
577 * name.
578 * @throws SecurityException if the client or delegated subject (if any) does
579 * not have permission to invoke this operation.
580 * @throws IOException if an I/O error occurred in communicating with
581 * the bean server.
582 * @see DynamicMBean#getAttribute(String)
583 */
587 IOException;
589 /**
590 * Handles {@link
591 * MBeanServerConnection#getAttribute(ObjectName, String)},
592 * returning the values of the named attributes from the specified
593 * management bean.
594 *
595 * @param bean the bean to retrieve the value from.
596 * @param names the names of the attributes to retrieve.
597 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
598 * containing the delegation principles. This may be
599 * {@code null} is authentication is used instead.
600 * @return the values of the attributes.
601 * @throws InstanceNotFoundException if the bean can not be found.
602 * @throws ReflectionException if an exception was thrown in trying
603 * to invoke the bean's accessor.
604 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
605 * is thrown by the server due to a
606 * <code>null</code> bean or attribute
607 * name.
608 * @throws SecurityException if the client or delegated subject (if any) does
609 * not have permission to invoke this operation.
610 * @throws IOException if an I/O error occurred in communicating with
611 * the bean server.
612 * @see DynamicMBean#getAttributes(String[])
613 */
615 Subject delegationSubject)
617 IOException;
619 /**
620 * Returns the unique identifier for this connection to the RMI
621 * server.
622 *
623 * @return the connection ID.
624 * @throws IOException if an I/O error occurred.
625 */
629 /**
630 * Handles {@link
631 * MBeanServerConnection#getDefaultDomain()} by returning the default
632 * domain this server applies to beans that have no specified domain.
633 *
634 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
635 * containing the delegation principles. This may be
636 * {@code null} is authentication is used instead.
637 * @return the default domain.
638 * @throws SecurityException if the client or delegated subject (if any) does
639 * not have permission to invoke this operation.
640 * @throws IOException if an I/O error occurred in communicating with
641 * the bean server.
642 */
646 /**
647 * Handles {@link
648 * MBeanServerConnection#getDomains()} by returning an array
649 * containing all the domains used by beans registered with
650 * this server. The ordering of the array is undefined.
651 *
652 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
653 * containing the delegation principles. This may be
654 * {@code null} is authentication is used instead.
655 * @return the list of domains.
656 * @throws SecurityException if the client or delegated subject (if any) does
657 * not have permission to invoke this operation.
658 * @throws IOException if an I/O error occurred in communicating with
659 * the bean server.
660 * @see ObjectName#getDomain()
661 */
665 /**
666 * Handles {@link
667 * MBeanServerConnection#getMBeanCount()} by returning the number of
668 * management beans registered with this server.
669 *
670 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
671 * containing the delegation principles. This may be
672 * {@code null} is authentication is used instead.
673 * @return the number of registered beans.
674 * @throws SecurityException if the client or delegated subject (if any) does
675 * not have permission to invoke this operation.
676 * @throws IOException if an I/O error occurred in communicating with
677 * the bean server.
678 */
682 /**
683 * Handles {@link
684 * MBeanServerConnection#getMBeanInfo(ObjectName)} by returning
685 * information on the given management bean.
686 *
687 * @param name the name of the management bean.
688 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
689 * containing the delegation principles. This may be
690 * {@code null} is authentication is used instead.
691 * @return an instance of {@link MBeanInfo} for the bean.
692 * @throws IntrospectionException if an exception occurs in examining
693 * the bean.
694 * @throws InstanceNotFoundException if the bean can not be found.
695 * @throws ReflectionException if an exception occurs when trying
696 * to invoke {@link DynamicMBean#getMBeanInfo()}
697 * on the bean.
698 * @throws SecurityException if the client or delegated subject (if any) does
699 * not have permission to invoke this operation.
700 * @throws IOException if an I/O error occurred in communicating with
701 * the bean server.
702 * @see DynamicMBean#getMBeanInfo()
703 */
708 /**
709 * Handles {@link
710 * MBeanServerConnection#getObjectInstance(ObjectName)} by returning
711 * the {@link ObjectInstance} created for the specified management
712 * bean on registration.
713 *
714 * @param name the name of the bean.
715 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
716 * containing the delegation principles. This may be
717 * {@code null} is authentication is used instead.
718 * @return the corresponding {@link ObjectInstance} instance.
719 * @throws InstanceNotFoundException if the bean can not be found.
720 * @throws SecurityException if the client or delegated subject (if any) does
721 * not have permission to invoke this operation.
722 * @throws IOException if an I/O error occurred in communicating with
723 * the bean server.
724 * @see #createMBean(String, ObjectName, Subject)
725 */
729 /**
730 * <p>
731 * Handles {@link
732 * MBeanServerConnection#invoke(ObjectName, String, Object[],
733 * String[])}. The array of parameters is wrapped in a
734 * {@link MarshalledObject} so that it is deserialised
735 * using the bean's classloader.
736 * </p>
737 * <p>
738 * Invokes the supplied operation on the specified management
739 * bean. The class objects specified in the signature are loaded
740 * using the same class loader as was used for the management bean.
741 *
742 * @param bean the management bean whose operation should be invoked.
743 * @param name the name of the operation to invoke.
744 * @param params the parameters for the bean's constructor, encapsulated
745 * in a {@link MarshalledObject}. If this parameter is
746 * <code>null</code>, it will be judged equivalent to an
747 * empty array.
748 * @param sig the signature of the constructor to use. If this parameter
749 * is <code>null</code>, it will be judged equivalent to an
750 * empty array. The class objects will be loaded using the
751 * bean's classloader.
752 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
753 * containing the delegation principles. This may be
754 * {@code null} is authentication is used instead.
755 * @return the return value of the method.
756 * @throws InstanceNotFoundException if the bean can not be found.
757 * @throws MBeanException if the method invoked throws an exception.
758 * @throws ReflectionException if an exception is thrown in invoking the
759 * method.
760 * @throws SecurityException if the client or delegated subject (if any) does
761 * not have permission to invoke this operation.
762 * @throws IOException if an I/O error occurred in communicating with
763 * the bean server.
764 * @see DynamicMBean#invoke(String, Object[], String[])
765 */
771 /**
772 * <p>
773 * Handles {@link
774 * MBeanServerConnection#isInstanceOf(ObjectName, String) by
775 * returning true if the specified management bean is an instance
776 * of the supplied class.
777 * </p>
778 * <p>
779 * A bean, B, is an instance of a class, C, if either of the following
780 * conditions holds:
781 * </p>
782 * <ul>
783 * <li>The class name in B's {@link MBeanInfo} is equal to the supplied
784 * name.</li>
785 * <li>Both the class of B and C were loaded by the same class loader,
786 * and B is assignable to C.</li>
787 * </ul>
788 *
789 * @param name the name of the management bean.
790 * @param className the name of the class to test if <code>name</code> is
791 * an instance of.
792 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
793 * containing the delegation principles. This may be
794 * {@code null} is authentication is used instead.
795 * @return true if either B is directly an instance of the named class,
796 * or B is assignable to the class, given that both it and B's
797 * current class were loaded using the same class loader.
798 * @throws InstanceNotFoundException if the bean can not be found.
799 * @throws SecurityException if the client or delegated subject (if any) does
800 * not have permission to invoke this operation.
801 * @throws IOException if an I/O error occurred in communicating with
802 * the bean server.
803 */
805 Subject delegationSubject)
808 /**
809 * Handles {@link
810 * MBeanServerConnection#isRegistered(ObjectName) by returning
811 * true if the specified management bean is registered with
812 * the server.
813 *
814 * @param name the name of the management bean.
815 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
816 * containing the delegation principles. This may be
817 * {@code null} is authentication is used instead.
818 * @return true if the bean is registered.
819 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
820 * is thrown by the server due to a
821 * <code>null</code> bean name.
822 * @throws SecurityException if the client or delegated subject (if any) does
823 * not have permission to invoke this operation.
824 * @throws IOException if an I/O error occurred in communicating with
825 * the bean server.
826 */
830 /**
831 * <p>
832 * Handles {@link
833 * MBeanServerConnection#queryMBeans(ObjectName, QueryExp)}.
834 * The query expression is wrapped in a {@link MarshalledObject}
835 * so that it is deserialised using the bean's classloader.
836 * </p>
837 * <p>
838 * Returns a set of {@link ObjectInstance}s matching the specified
839 * criteria. The full set of beans registered with the server
840 * are passed through two filters:
841 * </p>
842 * <ol>
843 * <li>Pattern matching is performed using the supplied
844 * {@link ObjectName}.</li>
845 * <li>The supplied query expression is applied.</li>
846 * </ol>
847 * <p>
848 * If both the object name and the query expression are <code>null</code>,
849 * or the object name has no domain and no key properties,
850 * no filtering will be performed and all beans are returned.
851 * </p>
852 *
853 * @param name an {@link ObjectName} to use as a filter.
854 * @param query a query expression to apply to each of the beans that match
855 * the given object name, encapsulated in a
856 * {@link MarshalledObject}. If a <code>null</code> value is
857 * encapsulated, then the beans will only be filtered using
858 * pattern matching on the supplied {@link ObjectName}.
859 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
860 * containing the delegation principles. This may be
861 * {@code null} is authentication is used instead.
862 * @return a set of {@link ObjectInstance}s matching the filtered beans.
863 * This is empty if no beans survived the filters.
864 * @throws IOException if an I/O error occurred in communicating with
865 * the bean server.
866 * @throws SecurityException if the client or delegated subject (if any) does
867 * not have permission to invoke this operation.
868 */
870 Subject delegationSubject)
873 /**
874 * <p>
875 * Handles {@link
876 * MBeanServerConnection#queryNames(ObjectName, QueryExp)}.
877 * The query expression is wrapped in a {@link MarshalledObject}
878 * so that it is deserialised using the bean's classloader.
879 * </p>
880 * <p>
881 * Returns a set of {@link ObjectName}s matching the specified
882 * criteria. The full set of beans registered with the server
883 * are passed through two filters:
884 * </p>
885 * <ol>
886 * <li>Pattern matching is performed using the supplied
887 * {@link ObjectName}.</li>
888 * <li>The supplied query expression is applied.</li>
889 * </ol>
890 * <p>
891 * If both the object name and the query expression are <code>null</code>,
892 * or the object name has no domain and no key properties,
893 * no filtering will be performed and all beans are returned.
894 * </p>
895 *
896 * @param name an {@link ObjectName} to use as a filter.
897 * @param query a query expression to apply to each of the beans that match
898 * the given object name, encapsulated in a
899 * {@link MarshalledObject}. If a <code>null</code> value is
900 * encapsulated, then the beans will only be filtered using
901 * pattern matching on the supplied {@link ObjectName}.
902 * @param delegationSubject an instance of {@link javax.security.auth.Subject}
903 * containing the delegation principles. This may be
904 * {@code null} is authentication is used instead.
905 * @return a set of {@link ObjectName}s matching the filtered beans.
906 * @throws SecurityException if the client or delegated subject (if any) does
907 * not have permission to invoke this operation.
908 * @throws IOException if an I/O error occurred in communicating with
909 * the bean server.
910 */
912 Subject delegationSubject)
915 /**
916 * <p>
917 * Handles {@link
918 * MBeanServerConnection#removeNotificationListener(ObjectName,
919 * ObjectName, NotificationFilter, Object)}. Both the filter and
920 * the handback object are wrapped in a {@link MarshalledObject}
921 * so that they are deserialised using the bean's classloader.
922 * </p>
923 * <p>
924 * Removes the specified listener from the list of recipients
925 * of notifications from the supplied bean. Only the first instance with
926 * the supplied filter and passback object is removed.
927 * <code>null</code> is used as a valid value for these parameters,
928 * rather than as a way to remove all registration instances for
929 * the specified listener; for this behaviour instead, see
930 * {@link #removeNotificationListener(ObjectName, NotificationListener)}.
931 * </p>
932 *
933 * @param name the name of the management bean from which the
934 * listener should be removed.
935 * @param listener the listener to remove.
936 * @param filter a wrapper containing the filter of the listener
937 * to remove.
938 * @param passback a wrapper containing the handback object of the
939 * listener to remove.
940 * @param delegationSubject a {@link javax.security.auth.Subject} instance
941 * containing the delegation principles or
942 * {@code null} if authentication is used.
943 * @throws InstanceNotFoundException if the bean can not be found.
944 * @throws ListenerNotFoundException if the specified listener
945 * is not registered with the bean.
946 * @throws SecurityException if the client or delegated subject (if any) does
947 * not have permission to invoke this operation.
948 * @throws IOException if an I/O error occurred in communicating with
949 * the bean server.
950 * @see #addNotificationListener(ObjectName, NotificationListener,
951 * MarshalledObject, MarshalledObject, Subject)
952 * @see NotificationEmitter#removeNotificationListener(NotificationListener,
953 * NotificationFilter,
954 * Object)
955 */
957 ObjectName listener,
958 MarshalledObject filter,
959 MarshalledObject passback,
960 Subject delegationSubject)
962 IOException;
964 /**
965 * Handles {@link
966 * MBeanServerConnection#removeNotificationListener(ObjectName,
967 * ObjectName)} by removing the specified listener from the list
968 * of recipients of notifications from the supplied bean. This
969 * includes all combinations of filters and passback objects
970 * registered for this listener. For more specific removal of
971 * listeners, see {@link #removeNotificationListener(ObjectName,
972 * ObjectName,MarshalledObject,MarshalledObject,Subject)}
973 *
974 * @param name the name of the management bean from which the
975 * listener should be removed.
976 * @param listener the name of the listener to remove.
977 * @param delegationSubject a {@link javax.security.auth.Subject} instance
978 * containing the delegation principles or
979 * {@code null} if authentication is used.
980 * @throws InstanceNotFoundException if a name doesn't match a registered
981 * bean.
982 * @throws ListenerNotFoundException if the specified listener
983 * is not registered with the bean.
984 * @throws SecurityException if the client or delegated subject (if any) does
985 * not have permission to invoke this operation.
986 * @throws IOException if an I/O error occurred in communicating with
987 * the bean server.
988 * @see #addNotificationListener(ObjectName, NotificationListener,
989 * MarshalledObject, MarshalledObject, Subject)
990 * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
991 */
993 Subject delegationSubject)
995 IOException;
997 /**
998 * Removes one or more {@link NotificationListener}s from the specified
999 * management bean. This method corresponds to
1000 * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1001 * Subject)} and provides a different way of handling
1002 * MBeanServerConnection#removeNotificationListener(ObjectName,
1003 * ObjectName)} and
1004 * {@link MBeanServerConnection#removeNotificationListener(ObjectName,
1005 * ObjectName, NotificationFilter, Object)} by using the integer
1006 * identifiers provided by the
1007 * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1008 * Subject)} method to select the listeners to remove.
1009 *
1010 * @param name the name of the management bean from which the
1011 * listeners should be removed.
1012 * @param listenerIds the identifiers of the listeners to remove.
1013 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1014 * containing the delegation principles or
1015 * {@code null} if authentication is used.
1016 * @throws InstanceNotFoundException if a name doesn't match a registered
1017 * bean.
1018 * @throws ListenerNotFoundException if the specified listener
1019 * is not registered with the bean.
1020 * @throws SecurityException if the client or delegated subject (if any) does
1021 * not have permission to invoke this operation.
1022 * @throws IOException if an I/O error occurred in communicating with
1023 * the bean server.
1024 * @throws IllegalArgumentException if either <code>name</code>,
1025 * <code>listenerIds</code> or an element
1026 * of <code>listenerIds</code>
1027 * is <code>null</code>.
1028 * @see #addNotificationListeners(ObjectName[], MarshalledObject[], Subject)
1029 */
1031 Subject delegationSubject)
1033 IOException;
1035 /**
1036 * Handles {@link
1037 * MBeanServerConnection#setAttribute(ObjectName, Attribute)}
1038 * by setting the value of the specified attribute of the supplied
1039 * management bean. The attribute is wrapped in a
1040 * {@link MarshalledObject} so that it is deserialised using the
1041 * bean's classloader.
1042 *
1043 * @param name the name of the management bean.
1044 * @param attribute the attribute to set, encapsulated in a
1045 * {@link MarshalledObject}.
1046 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1047 * containing the delegation principles or
1048 * {@code null} if authentication is used.
1049 * @throws InstanceNotFoundException if the bean can not be found.
1050 * @throws AttributeNotFoundException if the attribute does not
1051 * correspond to an attribute
1052 * of the bean.
1053 * @throws InvalidAttributeValueException if the value is invalid
1054 * for this particular
1055 * attribute of the bean.
1056 * @throws MBeanException if setting the attribute causes
1057 * the bean to throw an exception (which
1058 * becomes the cause of this exception).
1059 * @throws ReflectionException if an exception occurred in trying
1060 * to use the reflection interface
1061 * to lookup the attribute. The
1062 * thrown exception is the cause of
1063 * this exception.
1064 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1065 * is thrown by the server due to a
1066 * <code>null</code> bean or attribute
1067 * name.
1068 * @throws SecurityException if the client or delegated subject (if any) does
1069 * not have permission to invoke this operation.
1070 * @throws IOException if an I/O error occurred in communicating with
1071 * the bean server.
1072 * @see #getAttribute(ObjectName, String, Subject)
1073 * @see javax.management.DynamicMBean#setAttribute(Attribute)
1074 */
1076 Subject delegationSubject)
1081 /**
1082 * Handles {@link
1083 * MBeanServerConnection#setAttributes(ObjectName, AttributeList)}
1084 * by setting the value of each of the specified attributes
1085 * of the supplied management bean to that specified by
1086 * the {@link Attribute} object. The returned list contains
1087 * the attributes that were set and their new values.
1088 * The attribute list is wrapped in a {@link MarshalledObject} so
1089 * that it is deserialised using the bean's classloader.
1090 *
1091 * @param name the name of the management bean.
1092 * @param attributes the attributes to set, encapsulated in a
1093 * {@link MarshalledObject}.
1094 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1095 * containing the delegation principles or
1096 * {@code null} if authentication is used.
1097 * @return a list of the changed attributes.
1098 * @throws InstanceNotFoundException if the bean can not be found.
1099 * @throws ReflectionException if an exception occurred in trying
1100 * to use the reflection interface
1101 * to lookup the attribute. The
1102 * thrown exception is the cause of
1103 * this exception.
1104 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1105 * is thrown by the server due to a
1106 * <code>null</code> bean or attribute
1107 * list.
1108 * @throws SecurityException if the client or delegated subject (if any) does
1109 * not have permission to invoke this operation.
1110 * @throws IOException if an I/O error occurred in communicating with
1111 * the bean server.
1112 * @see #getAttributes(ObjectName, String[])
1113 * @see DynamicMBean#setAttributes(AttributeList)
1114 */
1116 Subject delegationSubject)
1118 IOException;
1120 /**
1121 * Handles {@link
1122 * MBeanServerConnection#unregisterMBean(ObjectName)} by unregistering
1123 * the specified management bean. Following this operation,
1124 * the bean instance is no longer accessible from the server via this
1125 * name. Prior to unregistering the bean, the
1126 * {@link MBeanRegistration#preDeregister()} method will be called if
1127 * the bean implements the {@link MBeanRegistration} interface.
1128 *
1129 * @param name the name of the management bean.
1130 * @param delegationSubject a {@link javax.security.auth.Subject} instance
1131 * containing the delegation principles or
1132 * {@code null} if authentication is used.
1133 * @throws InstanceNotFoundException if the bean can not be found.
1134 * @throws MBeanRegistrationException if an exception occurs in
1135 * calling the preDeregister
1136 * method.
1137 * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1138 * is thrown by the server due to a
1139 * <code>null</code> bean name or a
1140 * request being made to unregister the
1141 * {@link MBeanServerDelegate} bean.
1142 * @throws SecurityException if the client or delegated subject (if any) does
1143 * not have permission to invoke this operation.
1144 * @throws IOException if an I/O error occurred in communicating with
1145 * the bean server.
1146 */
1149 IOException;
1151 }