001 /*
002 * Copyright 2002-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management.remote;
027
028 import java.io.Closeable;
029 import java.io.IOException;
030 import java.util.Map;
031 import javax.management.ListenerNotFoundException;
032 import javax.management.MBeanServerConnection;
033 import javax.management.NotificationFilter;
034 import javax.management.NotificationListener;
035 import javax.security.auth.Subject;
036
037 /**
038 * <p>The client end of a JMX API connector. An object of this type can
039 * be used to establish a connection to a connector server.</p>
040 *
041 * <p>A newly-created object of this type is unconnected. Its {@link
042 * #connect connect} method must be called before it can be used.
043 * However, objects created by {@link
044 * JMXConnectorFactory#connect(JMXServiceURL, Map)
045 * JMXConnectorFactory.connect} are already connected.</p>
046 *
047 * @since 1.5
048 */
049 public interface JMXConnector extends Closeable {
050 /**
051 * <p>Name of the attribute that specifies the credentials to send
052 * to the connector server during connection. The value
053 * associated with this attribute, if any, is a serializable
054 * object of an appropriate type for the server's {@link
055 * JMXAuthenticator}.
056 */
057 public static final String CREDENTIALS = "jmx.remote.credentials";
058
059 /**
060 * <p>Establishes the connection to the connector server. This
061 * method is equivalent to {@link #connect(Map)
062 * connect(null)}.</p>
063 *
064 * @exception IOException if the connection could not be made
065 * because of a communication problem.
066 *
067 * @exception SecurityException if the connection could not be
068 * made for security reasons.
069 */
070 public void connect() throws IOException;
071
072 /**
073 * <p>Establishes the connection to the connector server.</p>
074 *
075 * <p>If <code>connect</code> has already been called successfully
076 * on this object, calling it again has no effect. If, however,
077 * {@link #close} was called after <code>connect</code>, the new
078 * <code>connect</code> will throw an <code>IOException</code>.<p>
079 *
080 * <p>Otherwise, either <code>connect</code> has never been called
081 * on this object, or it has been called but produced an
082 * exception. Then calling <code>connect</code> will attempt to
083 * establish a connection to the connector server.</p>
084 *
085 * @param env the properties of the connection. Properties in
086 * this map override properties in the map specified when the
087 * <code>JMXConnector</code> was created, if any. This parameter
088 * can be null, which is equivalent to an empty map.
089 *
090 * @exception IOException if the connection could not be made
091 * because of a communication problem.
092 *
093 * @exception SecurityException if the connection could not be
094 * made for security reasons.
095 */
096 public void connect(Map<String, ?> env) throws IOException;
097
098 /**
099 * <p>Returns an <code>MBeanServerConnection</code> object
100 * representing a remote MBean server. For a given
101 * <code>JMXConnector</code>, two successful calls to this method
102 * will usually return the same <code>MBeanServerConnection</code>
103 * object, though this is not required.</p>
104 *
105 * <p>For each method in the returned
106 * <code>MBeanServerConnection</code>, calling the method causes
107 * the corresponding method to be called in the remote MBean
108 * server. The value returned by the MBean server method is the
109 * value returned to the client. If the MBean server method
110 * produces an <code>Exception</code>, the same
111 * <code>Exception</code> is seen by the client. If the MBean
112 * server method, or the attempt to call it, produces an
113 * <code>Error</code>, the <code>Error</code> is wrapped in a
114 * {@link JMXServerErrorException}, which is seen by the
115 * client.</p>
116 *
117 * <p>Calling this method is equivalent to calling
118 * {@link #getMBeanServerConnection(Subject) getMBeanServerConnection(null)}
119 * meaning that no delegation subject is specified and that all the
120 * operations called on the <code>MBeanServerConnection</code> must
121 * use the authenticated subject, if any.</p>
122 *
123 * @return an object that implements the
124 * <code>MBeanServerConnection</code> interface by forwarding its
125 * methods to the remote MBean server.
126 *
127 * @exception IOException if a valid
128 * <code>MBeanServerConnection</code> cannot be created, for
129 * instance because the connection to the remote MBean server has
130 * not yet been established (with the {@link #connect(Map)
131 * connect} method), or it has been closed, or it has broken.
132 */
133 public MBeanServerConnection getMBeanServerConnection()
134 throws IOException;
135
136 /**
137 * <p>Returns an <code>MBeanServerConnection</code> object representing
138 * a remote MBean server on which operations are performed on behalf of
139 * the supplied delegation subject. For a given <code>JMXConnector</code>
140 * and <code>Subject</code>, two successful calls to this method will
141 * usually return the same <code>MBeanServerConnection</code> object,
142 * though this is not required.</p>
143 *
144 * <p>For each method in the returned
145 * <code>MBeanServerConnection</code>, calling the method causes
146 * the corresponding method to be called in the remote MBean
147 * server on behalf of the given delegation subject instead of the
148 * authenticated subject. The value returned by the MBean server
149 * method is the value returned to the client. If the MBean server
150 * method produces an <code>Exception</code>, the same
151 * <code>Exception</code> is seen by the client. If the MBean
152 * server method, or the attempt to call it, produces an
153 * <code>Error</code>, the <code>Error</code> is wrapped in a
154 * {@link JMXServerErrorException}, which is seen by the
155 * client.</p>
156 *
157 * @param delegationSubject the <code>Subject</code> on behalf of
158 * which requests will be performed. Can be null, in which case
159 * requests will be performed on behalf of the authenticated
160 * Subject, if any.
161 *
162 * @return an object that implements the <code>MBeanServerConnection</code>
163 * interface by forwarding its methods to the remote MBean server on behalf
164 * of a given delegation subject.
165 *
166 * @exception IOException if a valid <code>MBeanServerConnection</code>
167 * cannot be created, for instance because the connection to the remote
168 * MBean server has not yet been established (with the {@link #connect(Map)
169 * connect} method), or it has been closed, or it has broken.
170 */
171 public MBeanServerConnection getMBeanServerConnection(
172 Subject delegationSubject) throws IOException;
173
174 /**
175 * <p>Closes the client connection to its server. Any ongoing or new
176 * request using the MBeanServerConnection returned by {@link
177 * #getMBeanServerConnection()} will get an
178 * <code>IOException</code>.</p>
179 *
180 * <p>If <code>close</code> has already been called successfully
181 * on this object, calling it again has no effect. If
182 * <code>close</code> has never been called, or if it was called
183 * but produced an exception, an attempt will be made to close the
184 * connection. This attempt can succeed, in which case
185 * <code>close</code> will return normally, or it can generate an
186 * exception.</p>
187 *
188 * <p>Closing a connection is a potentially slow operation. For
189 * example, if the server has crashed, the close operation might
190 * have to wait for a network protocol timeout. Callers that do
191 * not want to block in a close operation should do it in a
192 * separate thread.</p>
193 *
194 * @exception IOException if the connection cannot be closed
195 * cleanly. If this exception is thrown, it is not known whether
196 * the server end of the connection has been cleanly closed.
197 */
198 public void close() throws IOException;
199
200 /**
201 * <p>Adds a listener to be informed of changes in connection
202 * status. The listener will receive notifications of type {@link
203 * JMXConnectionNotification}. An implementation can send other
204 * types of notifications too.</p>
205 *
206 * <p>Any number of listeners can be added with this method. The
207 * same listener can be added more than once with the same or
208 * different values for the filter and handback. There is no
209 * special treatment of a duplicate entry. For example, if a
210 * listener is registered twice with no filter, then its
211 * <code>handleNotification</code> method will be called twice for
212 * each notification.</p>
213 *
214 * @param listener a listener to receive connection status
215 * notifications.
216 * @param filter a filter to select which notifications are to be
217 * delivered to the listener, or null if all notifications are to
218 * be delivered.
219 * @param handback an object to be given to the listener along
220 * with each notification. Can be null.
221 *
222 * @exception NullPointerException if <code>listener</code> is
223 * null.
224 *
225 * @see #removeConnectionNotificationListener
226 * @see javax.management.NotificationBroadcaster#addNotificationListener
227 */
228 public void addConnectionNotificationListener(
229 NotificationListener listener, NotificationFilter filter,
230 Object handback);
231
232 /**
233 * <p>Removes a listener from the list to be informed of changes
234 * in status. The listener must previously have been added. If
235 * there is more than one matching listener, all are removed.</p>
236 *
237 * @param listener a listener to receive connection status
238 * notifications.
239 *
240 * @exception NullPointerException if <code>listener</code> is
241 * null.
242 *
243 * @exception ListenerNotFoundException if the listener is not
244 * registered with this <code>JMXConnector</code>.
245 *
246 * @see #removeConnectionNotificationListener(NotificationListener,
247 * NotificationFilter, Object)
248 * @see #addConnectionNotificationListener
249 * @see javax.management.NotificationEmitter#removeNotificationListener
250 */
251 public void removeConnectionNotificationListener(
252 NotificationListener listener)
253 throws ListenerNotFoundException;
254
255 /**
256 * <p>Removes a listener from the list to be informed of changes
257 * in status. The listener must previously have been added with
258 * the same three parameters. If there is more than one matching
259 * listener, only one is removed.</p>
260 *
261 * @param l a listener to receive connection status notifications.
262 * @param f a filter to select which notifications are to be
263 * delivered to the listener. Can be null.
264 * @param handback an object to be given to the listener along
265 * with each notification. Can be null.
266 *
267 * @exception ListenerNotFoundException if the listener is not
268 * registered with this <code>JMXConnector</code>, or is not
269 * registered with the given filter and handback.
270 *
271 * @see #removeConnectionNotificationListener(NotificationListener)
272 * @see #addConnectionNotificationListener
273 * @see javax.management.NotificationEmitter#removeNotificationListener
274 */
275 public void removeConnectionNotificationListener(
276 NotificationListener l, NotificationFilter f,
277 Object handback) throws ListenerNotFoundException;
278
279 /**
280 * <p>Gets this connection's ID from the connector server. For a
281 * given connector server, every connection will have a unique id
282 * which does not change during the lifetime of the
283 * connection.</p>
284 *
285 * @return the unique ID of this connection. This is the same as
286 * the ID that the connector server includes in its {@link
287 * JMXConnectionNotification}s. The {@link
288 * javax.management.remote package description} describes the
289 * conventions for connection IDs.
290 *
291 * @exception IOException if the connection ID cannot be obtained,
292 * for instance because the connection is closed or broken.
293 */
294 public String getConnectionId() throws IOException;
295 }
|