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}