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