001/*
002 * Copyright 2020-2023 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2020-2023 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-2023 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.NotNull;
046import com.unboundid.util.Nullable;
047import com.unboundid.util.ThreadSafety;
048import com.unboundid.util.ThreadSafetyLevel;
049
050
051
052/**
053 * This interface defines a number of methods that may be used to obtain
054 * information about an LDAP connection.  This should be treated as a
055 * read-only interface, and when a connection is used in the context of this
056 * interface, no processing should be performed that would alter any state.
057 */
058@NotExtensible()
059@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
060public interface LDAPConnectionInfo
061{
062  /**
063   * Indicates whether this connection is currently established.
064   *
065   * @return  {@code true} if this connection is currently established, or
066   *          {@code false} if it is not.
067   */
068  boolean isConnected();
069
070
071
072  /**
073   * Retrieves the socket factory that was used when creating the socket for the
074   * last connection attempt (whether successful or unsuccessful) for this LDAP
075   * connection.
076   *
077   * @return  The socket factory that was used when creating the socket for the
078   *          last connection attempt for this LDAP connection, or {@code null}
079   *          if no attempt has yet been made to establish this connection.
080   */
081  @Nullable()
082  SocketFactory getLastUsedSocketFactory();
083
084
085
086  /**
087   * Retrieves the socket factory to use to create the socket for subsequent
088   * connection attempts.  This may or may not be the socket factory that was
089   * used to create the current established connection.
090   *
091   * @return  The socket factory to use to create the socket for subsequent
092   *          connection attempts.
093   */
094  @NotNull()
095  SocketFactory getSocketFactory();
096
097
098
099  /**
100   * Retrieves the {@code SSLSession} currently being used to secure
101   * communication on this connection.  This may be available for connections
102   * that were secured at the time they were created (via an
103   * {@code SSLSocketFactory}), or for connections secured after their creation
104   * (via the StartTLS extended operation).  This will not be available for
105   * unencrypted connections, or connections secured in other ways (e.g., via
106   * SASL QoP).
107   *
108   * @return  The {@code SSLSession} currently being used to secure
109   *          communication on this connection, or {@code null} if no
110   *          {@code SSLSession} is available.
111   */
112  @Nullable()
113  SSLSession getSSLSession();
114
115
116
117  /**
118   * Retrieves a value that uniquely identifies this connection within the JVM
119   * Each {@code LDAPConnection} object will be assigned a different connection
120   * ID, and that connection ID will not change over the life of the object,
121   * even if the connection is closed and re-established (whether re-established
122   * to the same server or a different server).
123   *
124   * @return  A value that uniquely identifies this connection within the JVM.
125   */
126  long getConnectionID();
127
128
129
130  /**
131   * Retrieves the user-friendly name that has been assigned to this connection.
132   *
133   * @return  The user-friendly name that has been assigned to this connection,
134   *          or {@code null} if none has been assigned.
135   */
136  @Nullable()
137  String getConnectionName();
138
139
140
141  /**
142   * Retrieves the user-friendly name that has been assigned to the connection
143   * pool with which this connection is associated.
144   *
145   * @return  The user-friendly name that has been assigned to the connection
146   *          pool with which this connection is associated, or {@code null} if
147   *          none has been assigned or this connection is not associated with a
148   *          connection pool.
149   */
150  @Nullable()
151  String getConnectionPoolName();
152
153
154
155  /**
156   * Retrieves a string representation of the host and port for the server to
157   * to which the last connection attempt was made.  It does not matter whether
158   * the connection attempt was successful, nor does it matter whether it is
159   * still established.  This is primarily intended for internal use in error
160   * messages.
161   *
162   * @return  A string representation of the host and port for the server to
163   *          which the last connection attempt was made, or an empty string if
164   *          no connection attempt has yet been made on this connection.
165   */
166  @NotNull()
167  String getHostPort();
168
169
170
171  /**
172   * Retrieves the address of the directory server to which this connection is
173   * currently established.
174   *
175   * @return  The address of the directory server to which this connection is
176   *          currently established, or {@code null} if the connection is not
177   *          established.
178   */
179  @Nullable()
180  String getConnectedAddress();
181
182
183
184  /**
185   * Retrieves the string representation of the IP address to which this
186   * connection is currently established.
187   *
188   * @return  The string representation of the IP address to which this
189   *          connection is currently established, or {@code null} if the
190   *          connection is not established.
191   */
192  @Nullable()
193  String getConnectedIPAddress();
194
195
196
197  /**
198   * Retrieves an {@code InetAddress} object that represents the address of the
199   * server to which this  connection is currently established.
200   *
201   * @return  An {@code InetAddress} that represents the address of the server
202   *          to which this connection is currently established, or {@code null}
203   *          if the connection is not established.
204   */
205  @Nullable()
206  InetAddress getConnectedInetAddress();
207
208
209
210  /**
211   * Retrieves the port of the directory server to which this connection is
212   * currently established.
213   *
214   * @return  The port of the directory server to which this connection is
215   *          currently established, or -1 if the connection is not established.
216   */
217  int getConnectedPort();
218
219
220
221  /**
222   * Retrieves a stack trace of the thread that last attempted to establish this
223   * connection.  Note that this will only be available if an attempt has been
224   * made to establish this connection and the
225   * {@link LDAPConnectionOptions#captureConnectStackTrace()} method for the
226   * associated connection options returns {@code true}.
227   *
228   * @return  A stack trace of the thread that last attempted to establish this
229   *          connection, or {@code null} connect stack traces are not enabled,
230   *          or if no attempt has been made to establish this connection.
231   */
232  @Nullable()
233  StackTraceElement[] getConnectStackTrace();
234
235
236
237  /**
238   * Retrieves the disconnect type for this connection, if available.
239   *
240   * @return  The disconnect type for this connection, or {@code null} if no
241   *          disconnect type has been set.
242   */
243  @Nullable()
244  DisconnectType getDisconnectType();
245
246
247
248  /**
249   * Retrieves the disconnect message for this connection, which may provide
250   * additional information about the reason for the disconnect, if available.
251   *
252   * @return  The disconnect message for this connection, or {@code null} if
253   *          no disconnect message has been set.
254   */
255  @Nullable()
256  String getDisconnectMessage();
257
258
259
260  /**
261   * Retrieves the disconnect cause for this connection, which is an exception
262   * or error that triggered the connection termination, if available.
263   *
264   * @return  The disconnect cause for this connection, or {@code null} if no
265   *          disconnect cause has been set.
266   */
267  @Nullable()
268  Throwable getDisconnectCause();
269
270
271
272  /**
273   * Retrieves the last successful bind request processed on this connection.
274   *
275   * @return  The last successful bind request processed on this connection.  It
276   *          may be {@code null} if no bind has been performed, or if the last
277   *          bind attempt was not successful.
278   */
279  @Nullable()
280  BindRequest getLastBindRequest();
281
282
283
284  /**
285   * Retrieves the StartTLS request used to secure this connection.
286   *
287   * @return  The StartTLS request used to secure this connection, or
288   *          {@code null} if StartTLS has not been used to secure this
289   *          connection.
290   */
291  @Nullable()
292  ExtendedRequest getStartTLSRequest();
293
294
295
296  /**
297   * Indicates whether this connection is operating in synchronous mode.
298   *
299   * @return  {@code true} if this connection is operating in synchronous mode,
300   *          or {@code false} if not.
301   */
302  boolean synchronousMode();
303
304
305
306  /**
307   * Retrieves the time that this connection was established in the number of
308   * milliseconds since January 1, 1970 UTC (the same format used by
309   * {@code System.currentTimeMillis}.
310   *
311   * @return  The time that this connection was established, or -1 if the
312   *          connection is not currently established.
313   */
314  long getConnectTime();
315
316
317
318  /**
319   * Retrieves the time that this connection was last used to send or receive an
320   * LDAP message.  The value will represent the number of milliseconds since
321   * January 1, 1970 UTC (the same format used by
322   * {@code System.currentTimeMillis}.
323   *
324   * @return  The time that this connection was last used to send or receive an
325   *          LDAP message.  If the connection is not established, then -1 will
326   *          be returned.  If the connection is established but no
327   *          communication has been performed over the connection since it was
328   *          established, then the value of {@link #getConnectTime()} will be
329   *          returned.
330   */
331  long getLastCommunicationTime();
332
333
334
335  /**
336   * Retrieves the connection statistics for this LDAP connection.
337   *
338   * @return  The connection statistics for this LDAP connection.
339   */
340  @NotNull()
341  LDAPConnectionStatistics getConnectionStatistics();
342
343
344
345  /**
346   * Retrieves the number of outstanding operations on this LDAP connection
347   * (i.e., the number of operations currently in progress).  The value will
348   * only be valid for connections not configured to use synchronous mode.
349   *
350   * @return  The number of outstanding operations on this LDAP connection, or
351   *          -1 if it cannot be determined (e.g., because the connection is not
352   *          established or is operating in synchronous mode).
353   */
354  int getActiveOperationCount();
355
356
357
358  /**
359   * Retrieves a string representation of this LDAP connection.
360   *
361   * @return  A string representation of this LDAP connection.
362   */
363  @Override()
364  @NotNull()
365  String toString();
366
367
368
369  /**
370   * Appends a string representation of this LDAP connection to the provided
371   * buffer.
372   *
373   * @param  buffer  The buffer to which to append a string representation of
374   *                 this LDAP connection.
375   */
376  void toString(@NotNull final StringBuilder buffer);
377}