KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > management > remote > rmi > RMIConnection


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