JMXConnector


1   /*
2    * @(#)JMXConnector.java    1.30 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   
9   package javax.management.remote;
10  
11  import java.io.IOException  ;
12  import java.util.Map  ;
13  
14  import javax.management.ListenerNotFoundException  ;
15  import javax.management.MBeanServerConnection  ;
16  import javax.management.NotificationBroadcaster  ;
17  import javax.management.NotificationEmitter  ;
18  import javax.management.NotificationFilter  ;
19  import javax.management.NotificationListener  ;
20  import javax.security.auth.Subject  ;
21  
22  /**
23   * <p>The client end of a JMX API connector.  An object of this type can
24   * be used to establish a connection to a connector server.</p>
25   *
26   * <p>A newly-created object of this type is unconnected.  Its {@link
27   * #connect connect} method must be called before it can be used.
28   * However, objects created by {@link
29   * JMXConnectorFactory#connect(JMXServiceURL, Map)
30   * JMXConnectorFactory.connect} are already connected.</p>
31   *
32   * @since 1.5
33   * @since.unbundled 1.0
34   */
35  public interface JMXConnector {
36      /**
37        * <p>Name of the attribute that specifies the credentials to send
38        * to the connector server during connection.  The value
39        * associated with this attribute, if any, is a serializable
40        * object of an appropriate type for the server's {@link
41        * JMXAuthenticator}.
42        */
43       public static final String   CREDENTIALS =
44       "jmx.remote.credentials";
45  
46      /**
47       * <p>Establishes the connection to the connector server.  This
48       * method is equivalent to {@link #connect(Map)
49       * connect(null)}.</p>
50       *
51       * @exception IOException if the connection could not be made
52       * because of a communication problem.
53       *
54       * @exception SecurityException if the connection could not be
55       * made for security reasons.
56       */
57      public void connect() throws IOException  ;
58  
59      /**
60       * <p>Establishes the connection to the connector server.</p>
61       *
62       * <p>If <code>connect</code> has already been called successfully
63       * on this object, calling it again has no effect.  If, however,
64       * {@link #close} was called after <code>connect</code>, the new
65       * <code>connect</code> will throw an <code>IOException</code>.<p>
66       *
67       * <p>Otherwise, either <code>connect</code> has never been called
68       * on this object, or it has been called but produced an
69       * exception.  Then calling <code>connect</code> will attempt to
70       * establish a connection to the connector server.</p>
71       *
72       * @param env the properties of the connection.  Properties in
73       * this map override properties in the map specified when the
74       * <code>JMXConnector</code> was created, if any.  This parameter
75       * can be null, which is equivalent to an empty map.
76       *
77       * @exception IOException if the connection could not be made
78       * because of a communication problem.
79       *
80       * @exception SecurityException if the connection could not be
81       * made for security reasons.
82       */
83      public void connect(Map  <String  ,?> env) throws IOException  ;
84  
85      /**
86       * <p>Returns an <code>MBeanServerConnection</code> object
87       * representing a remote MBean server.  For a given
88       * <code>JMXConnector</code>, two successful calls to this method
89       * will usually return the same <code>MBeanServerConnection</code>
90       * object, though this is not required.</p>
91       *
92       * <p>For each method in the returned
93       * <code>MBeanServerConnection</code>, calling the method causes
94       * the corresponding method to be called in the remote MBean
95       * server.  The value returned by the MBean server method is the
96       * value returned to the client.  If the MBean server method
97       * produces an <code>Exception</code>, the same
98       * <code>Exception</code> is seen by the client.  If the MBean
99       * server method, or the attempt to call it, produces an
100      * <code>Error</code>, the <code>Error</code> is wrapped in a
101      * {@link JMXServerErrorException}, which is seen by the
102      * client.</p>
103      *
104      * <p>Calling this method is equivalent to calling
105      * {@link #getMBeanServerConnection(Subject) getMBeanServerConnection(null)}
106      * meaning that no delegation subject is specified and that all the
107      * operations called on the <code>MBeanServerConnection</code> must
108      * use the authenticated subject, if any.</p>
109      *
110      * @return an object that implements the
111      * <code>MBeanServerConnection</code> interface by forwarding its
112      * methods to the remote MBean server.
113      *
114      * @exception IOException if a valid
115      * <code>MBeanServerConnection</code> cannot be created, for
116      * instance because the connection to the remote MBean server has
117      * not yet been established (with the {@link #connect(Map)
118      * connect} method), or it has been closed, or it has broken.
119      */
120     public MBeanServerConnection   getMBeanServerConnection()
121         throws IOException  ;
122 
123     /**
124      * <p>Returns an <code>MBeanServerConnection</code> object representing
125      * a remote MBean server on which operations are performed on behalf of
126      * the supplied delegation subject. For a given <code>JMXConnector</code>
127      * and <code>Subject</code>, two successful calls to this method will
128      * usually return the same <code>MBeanServerConnection</code> object,
129      * though this is not required.</p>
130      *
131      * <p>For each method in the returned
132      * <code>MBeanServerConnection</code>, calling the method causes
133      * the corresponding method to be called in the remote MBean
134      * server on behalf of the given delegation subject instead of the
135      * authenticated subject. The value returned by the MBean server
136      * method is the value returned to the client. If the MBean server
137      * method produces an <code>Exception</code>, the same
138      * <code>Exception</code> is seen by the client. If the MBean
139      * server method, or the attempt to call it, produces an
140      * <code>Error</code>, the <code>Error</code> is wrapped in a
141      * {@link JMXServerErrorException}, which is seen by the
142      * client.</p>
143      *
144      * @param delegationSubject the <code>Subject</code> on behalf of
145      * which requests will be performed.  Can be null, in which case
146      * requests will be performed on behalf of the authenticated
147      * Subject, if any.
148      *
149      * @return an object that implements the <code>MBeanServerConnection</code>
150      * interface by forwarding its methods to the remote MBean server on behalf
151      * of a given delegation subject.
152      *
153      * @exception IOException if a valid <code>MBeanServerConnection</code>
154      * cannot be created, for instance because the connection to the remote
155      * MBean server has not yet been established (with the {@link #connect(Map)
156      * connect} method), or it has been closed, or it has broken.
157      */
158     public MBeanServerConnection   getMBeanServerConnection(
159                            Subject   delegationSubject)
160         throws IOException  ;
161 
162     /**
163      * <p>Closes the client connection to its server.  Any ongoing or new
164      * request using the MBeanServerConnection returned by {@link
165      * #getMBeanServerConnection()} will get an
166      * <code>IOException</code>.</p>
167      *
168      * <p>If <code>close</code> has already been called successfully
169      * on this object, calling it again has no effect.  If
170      * <code>close</code> has never been called, or if it was called
171      * but produced an exception, an attempt will be made to close the
172      * connection.  This attempt can succeed, in which case
173      * <code>close</code> will return normally, or it can generate an
174      * exception.</p>
175      *
176      * <p>Closing a connection is a potentially slow operation.  For
177      * example, if the server has crashed, the close operation might
178      * have to wait for a network protocol timeout.  Callers that do
179      * not want to block in a close operation should do it in a
180      * separate thread.</p>
181      *
182      * @exception IOException if the connection cannot be closed
183      * cleanly.  If this exception is thrown, it is not known whether
184      * the server end of the connection has been cleanly closed.
185      */
186     public void close() throws IOException  ;
187 
188     /**
189      * <p>Adds a listener to be informed of changes in connection
190      * status.  The listener will receive notifications of type {@link
191      * JMXConnectionNotification}.  An implementation can send other
192      * types of notifications too.</p>
193      *
194      * <p>Any number of listeners can be added with this method.  The
195      * same listener can be added more than once with the same or
196      * different values for the filter and handback.  There is no
197      * special treatment of a duplicate entry.  For example, if a
198      * listener is registered twice with no filter, then its
199      * <code>handleNotification</code> method will be called twice for
200      * each notification.</p>
201      *
202      * @param listener a listener to receive connection status
203      * notifications.
204      * @param filter a filter to select which notifications are to be
205      * delivered to the listener, or null if all notifications are to
206      * be delivered.
207      * @param handback an object to be given to the listener along
208      * with each notification.  Can be null.
209      *
210      * @exception NullPointerException if <code>listener</code> is
211      * null.
212      *
213      * @see #removeConnectionNotificationListener
214      * @see NotificationBroadcaster#addNotificationListener
215      */
216     public void
217     addConnectionNotificationListener(NotificationListener   listener,
218                       NotificationFilter   filter,
219                       Object   handback);
220 
221     /**
222      * <p>Removes a listener from the list to be informed of changes
223      * in status.  The listener must previously have been added.  If
224      * there is more than one matching listener, all are removed.</p>
225      *
226      * @param listener a listener to receive connection status
227      * notifications.
228      *
229      * @exception NullPointerException if <code>listener</code> is
230      * null.
231      *
232      * @exception ListenerNotFoundException if the listener is not
233      * registered with this <code>JMXConnector</code>.
234      *
235      * @see #removeConnectionNotificationListener(NotificationListener,
236      * NotificationFilter, Object)
237      * @see #addConnectionNotificationListener
238      * @see NotificationEmitter#removeNotificationListener
239      */
240     public void
241     removeConnectionNotificationListener(NotificationListener   listener)
242         throws ListenerNotFoundException  ;
243 
244     /**
245      * <p>Removes a listener from the list to be informed of changes
246      * in status.  The listener must previously have been added with
247      * the same three parameters.  If there is more than one matching
248      * listener, only one is removed.</p>
249      *
250      * @param l a listener to receive connection status notifications.
251      * @param f a filter to select which notifications are to be
252      * delivered to the listener.  Can be null.
253      * @param handback an object to be given to the listener along
254      * with each notification.  Can be null.
255      *
256      * @exception ListenerNotFoundException if the listener is not
257      * registered with this <code>JMXConnector</code>, or is not
258      * registered with the given filter and handback.
259      *
260      * @see #removeConnectionNotificationListener(NotificationListener)
261      * @see #addConnectionNotificationListener
262      * @see NotificationEmitter#removeNotificationListener
263      */
264     public void removeConnectionNotificationListener(NotificationListener   l,
265                              NotificationFilter   f,
266                              Object   handback)
267         throws ListenerNotFoundException  ;
268 
269     /**
270      * <p>Gets this connection's ID from the connector server.  For a
271      * given connector server, every connection will have a unique id
272      * which does not change during the lifetime of the
273      * connection.</p>
274      *
275      * @return the unique ID of this connection.  This is the same as
276      * the ID that the connector server includes in its {@link
277      * JMXConnectionNotification}s.  The {@link
278      * javax.management.remote package description} describes the
279      * conventions for connection IDs.
280      *
281      * @exception IOException if the connection ID cannot be obtained,
282      * for instance because the connection is closed or broken.
283      */
284     public String   getConnectionId() throws IOException  ;
285 }
286
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags