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-2012 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 a string representation of the client connection. 297 * 298 * @return A string representation of the client connection. 299 */ 300 String toString(); 301 }