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