001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2010-2013 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.common.types;
028
029
030
031 import java.net.InetAddress;
032 import java.util.List;
033
034 import com.unboundid.ldap.sdk.LDAPException;
035 import com.unboundid.ldap.sdk.ResultCode;
036 import com.unboundid.util.NotExtensible;
037 import com.unboundid.util.ThreadSafety;
038 import com.unboundid.util.ThreadSafetyLevel;
039
040
041
042 /**
043 * This interface defines a set of methods that may be used to obtain
044 * information about a client connection that has been established to the
045 * server.
046 */
047 @NotExtensible()
048 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
049 public interface ClientContext
050 {
051 /**
052 * Retrieves the identifier that has been assigned to the associated client
053 * connection.
054 *
055 * @return The identifier that has been assigned to the associated client
056 * connection.
057 */
058 long getConnectionID();
059
060
061
062 /**
063 * Returns a {@code List} containing the names of all the Connection
064 * Criteria that match this connection. These are the configuration names
065 * (e.g. the RDNs, not the full DNs) of the Connection Criteria.
066 *
067 * @return a list of connection criteria names.
068 */
069 List<String> getMatchedConnectionCriteria();
070
071
072
073 /**
074 * Determines whether this {@code ClientContext} matches the given Connection
075 * Criteria.
076 *
077 * @param criteriaName the name (not the DN) of the Connection Criteria to
078 * check against.
079 * @return true if this {@code ClientContext} matches the specified
080 * Connection Criteria, false otherwise.
081 */
082 boolean matchesConnectionCriteria(final String criteriaName);
083
084
085
086 /**
087 * Indicates whether this represents an internal client connection.
088 *
089 * @return {@code true} if this represents an internal client connection, or
090 * {@code false} if it is from an external client.
091 */
092 boolean isInternal();
093
094
095
096 /**
097 * Retrieves an internal connection that is authenticated as a root user
098 * that is not subject to access control. It may optionally use the client
099 * connection policy from the associated client connection.
100 *
101 * @param usePolicyFromConnection If {@code true}, the internal connection
102 * will use the same client connection policy
103 * as the associated client connection. If
104 * {@code false}, the internal connection
105 * will use the server's default client
106 * connection policy for internal
107 * connections.
108 *
109 * @return An internal connection that is authenticated as a root user.
110 */
111 InternalConnection getInternalRootConnection(
112 final boolean usePolicyFromConnection);
113
114
115
116 /**
117 * Retrieves an internal connection that is authenticated as the same user
118 * as the associated client connection. It may optionally use the client
119 * connection policy from the associated client connection.
120 *
121 * @param usePolicyFromConnection If {@code true}, the internal connection
122 * will use the same client connection policy
123 * as the associated client connection. If
124 * {@code false}, the internal connection
125 * will use the server's default client
126 * connection policy for internal
127 * connections.
128 *
129 * @return An internal connection that is authenticated as the same user as
130 * the associated client connection.
131 *
132 * @throws LDAPException If a problem occurs while attempting to obtain or
133 * authenticate the connection.
134 */
135 InternalConnection getInternalUserConnection(
136 final boolean usePolicyFromConnection)
137 throws LDAPException;
138
139
140
141 /**
142 * Retrieves an internal connection that is authenticated as the specified
143 * user. Operations on the connection may be subject to access control based
144 * on the privileges associated with the specified user. It may optionally
145 * use the client connection policy from the associated client connection.
146 *
147 * @param dn The DN of the user as whom the connection
148 * should be authenticated. It may be
149 * {@code null} or empty if the connection
150 * should be unauthenticated.
151 * @param usePolicyFromConnection If {@code true}, the internal connection
152 * will use the same client connection policy
153 * as the associated client connection. If
154 * {@code false}, the internal connection
155 * will use the server's default client
156 * connection policy for internal
157 * connections.
158 *
159 * @return An internal connection that is authenticated as the specified
160 * user.
161 *
162 * @throws LDAPException If a problem occurs while attempting to
163 * authenticate as the specified user.
164 */
165 InternalConnection getInternalConnection(final String dn,
166 final boolean usePolicyFromConnection)
167 throws LDAPException;
168
169
170
171 /**
172 * Indicates whether the client is communicating with the server in a secure
173 * manner.
174 *
175 * @return {@code true} if the client is communicating with the server in a
176 * secure manner, or {@code false} if not.
177 */
178 boolean isSecure();
179
180
181
182 /**
183 * Retrieves the name of the protocol that the client is using to communicate
184 * with the server.
185 *
186 * @return The name of the protocol that the client is using to communicate
187 * with the server.
188 */
189 String getProtocol();
190
191
192
193 /**
194 * Retrieves the time that the connection was established. The value returned
195 * will be an offset in milliseconds since 12:00 a.m. on January 1, 1970.
196 *
197 * @return The time that the connection was established.
198 */
199 long getConnectTime();
200
201
202
203 /**
204 * Retrieves an {@code InetAddress} representing the address of the client
205 * system, if available.
206 *
207 * @return An {@code InetAddress} representing the address of the client
208 * system, or {@code null} if that is not available or applicable for
209 * the associated client connection.
210 */
211 InetAddress getClientInetAddress();
212
213
214
215 /**
216 * Retrieves an {@code InetAddress} representing the address on the server to
217 * which the client established the connection, if available.
218 *
219 * @return The address on the server to which the client established the
220 * connection, or {@code null} if that is not available or
221 * applicable.
222 */
223 InetAddress getServerInetAddress();
224
225
226
227 /**
228 * Indicates whether the client has authenticated to the server.
229 *
230 * @return {@code true} if the client has authenticated to the server, or
231 * {@code false} if not.
232 */
233 boolean isAuthenticated();
234
235
236
237 /**
238 * Retrieves information about the authentication state of the client
239 * connection.
240 *
241 * @return Information about the authentication state of the client
242 * connection.
243 */
244 AuthInfo getAuthInfo();
245
246
247
248 /**
249 * Attempts to send an unsolicited notification to the client with the
250 * provided information.
251 *
252 * @param oid The OID for the unsolicited notification. It must not
253 * be {@code null}.
254 * @param resultCode The result code to use for the unsolicited
255 * notification. It must not be {@code null}.
256 * @param message A message to include in the unsolicited notification.
257 * It may be {@code null} if no message is needed.
258 */
259 void sendUnsolicitedNotification(final String oid,
260 final ResultCode resultCode,
261 final String message);
262
263
264
265 /**
266 * Terminates the connection to the client and interrupts any operations that
267 * may be in progress on that connection.
268 *
269 * @param reason A general reason that the connection was closed.
270 * @param notifyClient Indicates whether to attempt to send a notice of
271 * disconnection to the client.
272 * @param message A message with information about the reason for the
273 * disconnect. It may be {@code null} if none is
274 * available. It is generally recommended that a
275 * message be provided even if the client should not be
276 * notified, since the message may be used in other
277 * ways (e.g., in log messages).
278 */
279 void disconnect(final DisconnectReason reason, final boolean notifyClient,
280 final String message);
281
282
283
284 /**
285 * Retrieves information about the server with which the client connection is
286 * associated.
287 *
288 * @return Information about the server with which the client connection is
289 * associated.
290 */
291 ServerContext getServerContext();
292
293
294
295 /**
296 * Retrieves an opaque object with information about the state of an active
297 * multi-stage SASL bind. The core server will not make any attempt to
298 * interpret this object, but it is expected that any SASL mechanism handler
299 * which makes use of SASL state information will know how to interact with
300 * this object.
301 *
302 * @return An opaque object with information about the state of an active
303 * multi-stage SASL bind, or {@code null} if no state information is
304 * available (e.g., because no multi-stage SASL bind is in progress,
305 * or because no state information is needed for the active bind
306 * operation).
307 */
308 Object getSASLAuthStateInfo();
309
310
311
312 /**
313 * Sets state information for an active multi-stage SASL bind. It is
314 * recommended that if any SASL state information is set in the connection,
315 * then that state should be cleared when it is no longer required (e.g.,
316 * after the bind has completed or failed).
317 *
318 * @param saslAuthStateInfo An opaque object that may hold information about
319 * the state of an active multi-stage SASL bind.
320 * It may be {@code null} to clear any existing
321 * SASL authentication state. The core sever will
322 * not make any attempt to interpret this object,
323 * but it is expected that any SASL mechanism
324 * handler which makes use of SASL state
325 * information will know how to interact with this
326 * object.
327 */
328 void setSASLAuthStateInfo(final Object saslAuthStateInfo);
329
330
331
332 /**
333 * Retrieves a named object that has been associated with this client
334 * connection.
335 *
336 * @param name The name of the attachment to retrieve. It will be treated
337 * in a case-sensitive manner. Note that attachment names must
338 * be carefully crafted to avoid inadvertent conflicts between
339 * extensions or the core server itself. It is strongly
340 * recommended that attachment names be made unique (e.g.,
341 * by prefixing them with the fully-qualified class name of the
342 * extension with which they are associated) so that attachments
343 * used by one extension do not inadvertently interfere with
344 * those which may be used in another extension or elsewhere in
345 * the server.
346 *
347 * @return The object that has been associated with this client connection
348 * using the given name, or {@code null} if there is no such
349 * attachment.
350 */
351 Object getAttachment(final String name);
352
353
354
355 /**
356 * Attaches an object to this client connection.
357 *
358 * @param name The name of the attachment to retrieve. It will be treated
359 * in a case-sensitive manner. Note that attachment names must
360 * be carefully crafted to avoid inadvertent conflicts between
361 * extensions or the core server itself. It is strongly
362 * recommended that attachment names be made unique (e.g.,
363 * by prefixing them with the fully-qualified class name of the
364 * extension with which they are associated) so that
365 * attachments used by one extension do not inadvertently
366 * interfere with those which may be used in another extension
367 * or elsewhere in the server.
368 * @param value The attachment to set. It may be {@code null} if an
369 * existing attachment with the given name should be removed.
370 *
371 * @return The attachment value held before the new value was assigned, or
372 * {@code null} if the attachment did not previously have a value.
373 */
374 Object setAttachment(final String name, final Object value);
375
376
377
378 /**
379 * Retrieves a string representation of the client connection.
380 *
381 * @return A string representation of the client connection.
382 */
383 String toString();
384 }