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-2018 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.common.types; 028 029 030 031import java.net.InetAddress; 032import java.util.List; 033 034import com.unboundid.ldap.sdk.LDAPException; 035import com.unboundid.ldap.sdk.ResultCode; 036import com.unboundid.util.NotExtensible; 037import com.unboundid.util.ThreadSafety; 038import 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) 049public 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}