001/* 002 * Copyright 2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2020 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2020 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk; 037 038 039 040import java.net.InetAddress; 041import javax.net.SocketFactory; 042import javax.net.ssl.SSLSession; 043 044import com.unboundid.util.NotExtensible; 045import com.unboundid.util.ThreadSafety; 046import com.unboundid.util.ThreadSafetyLevel; 047 048 049 050/** 051 * This interface defines a number of methods that may be used to obtain 052 * information about an LDAP connection. This should be treated as a 053 * read-only interface, and when a connection is used in the context of this 054 * interface, no processing should be performed that would alter any state. 055 */ 056@NotExtensible() 057@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 058public interface LDAPConnectionInfo 059{ 060 /** 061 * Indicates whether this connection is currently established. 062 * 063 * @return {@code true} if this connection is currently established, or 064 * {@code false} if it is not. 065 */ 066 boolean isConnected(); 067 068 069 070 /** 071 * Retrieves the socket factory that was used when creating the socket for the 072 * last connection attempt (whether successful or unsuccessful) for this LDAP 073 * connection. 074 * 075 * @return The socket factory that was used when creating the socket for the 076 * last connection attempt for this LDAP connection, or {@code null} 077 * if no attempt has yet been made to establish this connection. 078 */ 079 SocketFactory getLastUsedSocketFactory(); 080 081 082 083 /** 084 * Retrieves the socket factory to use to create the socket for subsequent 085 * connection attempts. This may or may not be the socket factory that was 086 * used to create the current established connection. 087 * 088 * @return The socket factory to use to create the socket for subsequent 089 * connection attempts. 090 */ 091 SocketFactory getSocketFactory(); 092 093 094 095 /** 096 * Retrieves the {@code SSLSession} currently being used to secure 097 * communication on this connection. This may be available for connections 098 * that were secured at the time they were created (via an 099 * {@code SSLSocketFactory}), or for connections secured after their creation 100 * (via the StartTLS extended operation). This will not be available for 101 * unencrypted connections, or connections secured in other ways (e.g., via 102 * SASL QoP). 103 * 104 * @return The {@code SSLSession} currently being used to secure 105 * communication on this connection, or {@code null} if no 106 * {@code SSLSession} is available. 107 */ 108 SSLSession getSSLSession(); 109 110 111 112 /** 113 * Retrieves a value that uniquely identifies this connection within the JVM 114 * Each {@code LDAPConnection} object will be assigned a different connection 115 * ID, and that connection ID will not change over the life of the object, 116 * even if the connection is closed and re-established (whether re-established 117 * to the same server or a different server). 118 * 119 * @return A value that uniquely identifies this connection within the JVM. 120 */ 121 long getConnectionID(); 122 123 124 125 /** 126 * Retrieves the user-friendly name that has been assigned to this connection. 127 * 128 * @return The user-friendly name that has been assigned to this connection, 129 * or {@code null} if none has been assigned. 130 */ 131 String getConnectionName(); 132 133 134 135 /** 136 * Retrieves the user-friendly name that has been assigned to the connection 137 * pool with which this connection is associated. 138 * 139 * @return The user-friendly name that has been assigned to the connection 140 * pool with which this connection is associated, or {@code null} if 141 * none has been assigned or this connection is not associated with a 142 * connection pool. 143 */ 144 String getConnectionPoolName(); 145 146 147 148 /** 149 * Retrieves a string representation of the host and port for the server to 150 * to which the last connection attempt was made. It does not matter whether 151 * the connection attempt was successful, nor does it matter whether it is 152 * still established. This is primarily intended for internal use in error 153 * messages. 154 * 155 * @return A string representation of the host and port for the server to 156 * which the last connection attempt was made, or an empty string if 157 * no connection attempt has yet been made on this connection. 158 */ 159 String getHostPort(); 160 161 162 163 /** 164 * Retrieves the address of the directory server to which this connection is 165 * currently established. 166 * 167 * @return The address of the directory server to which this connection is 168 * currently established, or {@code null} if the connection is not 169 * established. 170 */ 171 String getConnectedAddress(); 172 173 174 175 /** 176 * Retrieves the string representation of the IP address to which this 177 * connection is currently established. 178 * 179 * @return The string representation of the IP address to which this 180 * connection is currently established, or {@code null} if the 181 * connection is not established. 182 */ 183 String getConnectedIPAddress(); 184 185 186 187 /** 188 * Retrieves an {@code InetAddress} object that represents the address of the 189 * server to which this connection is currently established. 190 * 191 * @return An {@code InetAddress} that represents the address of the server 192 * to which this connection is currently established, or {@code null} 193 * if the connection is not established. 194 */ 195 InetAddress getConnectedInetAddress(); 196 197 198 199 /** 200 * Retrieves the port of the directory server to which this connection is 201 * currently established. 202 * 203 * @return The port of the directory server to which this connection is 204 * currently established, or -1 if the connection is not established. 205 */ 206 int getConnectedPort(); 207 208 209 210 /** 211 * Retrieves a stack trace of the thread that last attempted to establish this 212 * connection. Note that this will only be available if an attempt has been 213 * made to establish this connection and the 214 * {@link LDAPConnectionOptions#captureConnectStackTrace()} method for the 215 * associated connection options returns {@code true}. 216 * 217 * @return A stack trace of the thread that last attempted to establish this 218 * connection, or {@code null} connect stack traces are not enabled, 219 * or if no attempt has been made to establish this connection. 220 */ 221 StackTraceElement[] getConnectStackTrace(); 222 223 224 225 /** 226 * Retrieves the disconnect type for this connection, if available. 227 * 228 * @return The disconnect type for this connection, or {@code null} if no 229 * disconnect type has been set. 230 */ 231 DisconnectType getDisconnectType(); 232 233 234 235 /** 236 * Retrieves the disconnect message for this connection, which may provide 237 * additional information about the reason for the disconnect, if available. 238 * 239 * @return The disconnect message for this connection, or {@code null} if 240 * no disconnect message has been set. 241 */ 242 String getDisconnectMessage(); 243 244 245 246 /** 247 * Retrieves the disconnect cause for this connection, which is an exception 248 * or error that triggered the connection termination, if available. 249 * 250 * @return The disconnect cause for this connection, or {@code null} if no 251 * disconnect cause has been set. 252 */ 253 Throwable getDisconnectCause(); 254 255 256 257 /** 258 * Retrieves the last successful bind request processed on this connection. 259 * 260 * @return The last successful bind request processed on this connection. It 261 * may be {@code null} if no bind has been performed, or if the last 262 * bind attempt was not successful. 263 */ 264 BindRequest getLastBindRequest(); 265 266 267 268 /** 269 * Retrieves the StartTLS request used to secure this connection. 270 * 271 * @return The StartTLS request used to secure this connection, or 272 * {@code null} if StartTLS has not been used to secure this 273 * connection. 274 */ 275 ExtendedRequest getStartTLSRequest(); 276 277 278 279 /** 280 * Indicates whether this connection is operating in synchronous mode. 281 * 282 * @return {@code true} if this connection is operating in synchronous mode, 283 * or {@code false} if not. 284 */ 285 boolean synchronousMode(); 286 287 288 289 /** 290 * Retrieves the time that this connection was established in the number of 291 * milliseconds since January 1, 1970 UTC (the same format used by 292 * {@code System.currentTimeMillis}. 293 * 294 * @return The time that this connection was established, or -1 if the 295 * connection is not currently established. 296 */ 297 long getConnectTime(); 298 299 300 301 /** 302 * Retrieves the time that this connection was last used to send or receive an 303 * LDAP message. The value will represent the number of milliseconds since 304 * January 1, 1970 UTC (the same format used by 305 * {@code System.currentTimeMillis}. 306 * 307 * @return The time that this connection was last used to send or receive an 308 * LDAP message. If the connection is not established, then -1 will 309 * be returned. If the connection is established but no 310 * communication has been performed over the connection since it was 311 * established, then the value of {@link #getConnectTime()} will be 312 * returned. 313 */ 314 long getLastCommunicationTime(); 315 316 317 318 /** 319 * Retrieves the connection statistics for this LDAP connection. 320 * 321 * @return The connection statistics for this LDAP connection. 322 */ 323 LDAPConnectionStatistics getConnectionStatistics(); 324 325 326 327 /** 328 * Retrieves the number of outstanding operations on this LDAP connection 329 * (i.e., the number of operations currently in progress). The value will 330 * only be valid for connections not configured to use synchronous mode. 331 * 332 * @return The number of outstanding operations on this LDAP connection, or 333 * -1 if it cannot be determined (e.g., because the connection is not 334 * established or is operating in synchronous mode). 335 */ 336 int getActiveOperationCount(); 337 338 339 340 /** 341 * Retrieves a string representation of this LDAP connection. 342 * 343 * @return A string representation of this LDAP connection. 344 */ 345 @Override() 346 String toString(); 347 348 349 350 /** 351 * Appends a string representation of this LDAP connection to the provided 352 * buffer. 353 * 354 * @param buffer The buffer to which to append a string representation of 355 * this LDAP connection. 356 */ 357 void toString(final StringBuilder buffer); 358}