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 java.util.List;
042
043import com.unboundid.util.Extensible;
044import com.unboundid.util.ThreadSafety;
045import com.unboundid.util.ThreadSafetyLevel;
046
047
048
049/**
050 * This class defines an API that may be used to log operations processed on an
051 * LDAP connection.
052 */
053@Extensible()
054@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
055public abstract class LDAPConnectionLogger
056{
057  /**
058   * Performs any appropriate log processing that may be needed when a
059   * connection is established.
060   *
061   * @param  connectionInfo  Information about the connection that has been
062   *                         established.  It will not be {@code null}.
063   * @param  host            The string representation of the address to which
064   *                         the connection was established.  It will not be
065   *                         {@code null}.
066   * @param  inetAddress     The {@code InetAddress} representation of the
067   *                         address to which the connection was established.
068   *                         It will not be {@code null}.
069   * @param  port            The port to which the connection was established.
070   */
071  public void logConnect(final LDAPConnectionInfo connectionInfo,
072                         final String host, final InetAddress inetAddress,
073                         final int port)
074  {
075    // No action will be taken by default.
076  }
077
078
079
080  /**
081   * Performs any appropriate log processing that may be needed when an attempt
082   * to establish a connection fails.
083   *
084   * @param  connectionInfo    Information about the connection that has been
085   *                           established.  It will not be {@code null}.
086   * @param  host              The string representation of the address to which
087   *                           the connection was established.  It will not be
088   *                           {@code null}.
089   * @param  port              The port to which the connection was established.
090   * @param  connectException  An exception with information about the failed
091   *                           connection attempt.  It will not be
092   *                           {@code null}.
093   */
094  public void logConnectFailure(final LDAPConnectionInfo connectionInfo,
095                                final String host, final int port,
096                                final LDAPException connectException)
097  {
098    // No action will be taken by default.
099  }
100
101
102
103  /**
104   * Performs any appropriate log processing that may be needed when a
105   * connection is disconnected, regardless of whether the disconnect was
106   * initiated by the client or server.
107   *
108   * @param  connectionInfo     Information about the connection that has been
109   *                            disconnected.  It will not be {@code null}.
110   * @param  host               The string representation of the address to
111   *                            which the connection was established.  It will
112   *                            not be {@code null}.
113   * @param  port               The port to which the connection was
114   *                            established.
115   * @param  disconnectType     The general reason for the disconnect.  It will
116   *                            not be {@code null}.
117   * @param  disconnectMessage  A human-readable message with additional
118   *                            information about the disconnect.  It may be
119   *                            {@code null} if no additional information is
120   *                            available.
121   * @param  disconnectCause    A {@code Throwable} that may have been
122   *                            responsible for the disconnect.  It may be
123   *                            {@code null} if the disconnect was not caused by
124   *                            an exception or error.
125   */
126  public void logDisconnect(final LDAPConnectionInfo connectionInfo,
127                            final String host, final int port,
128                            final DisconnectType disconnectType,
129                            final String disconnectMessage,
130                            final Throwable disconnectCause)
131  {
132    // No action will be taken by default.
133  }
134
135
136
137  /**
138   * Performs any appropriate log processing that may be needed when an abandon
139   * request is sent over a connection.
140   *
141   * @param  connectionInfo      Information about the connection that will be
142   *                             used to send the abandon request.  It will not
143   *                             be {@code null}.
144   * @param  messageID           The LDAP message ID for the abandon request
145   *                             that is to be sent.
146   * @param  messageIDToAbandon  The LDAP message ID for the request that is to
147   *                             be abandoned.
148   * @param  requestControls     The list of controls included in the abandon
149   *                             request.
150   */
151  public void logAbandonRequest(final LDAPConnectionInfo connectionInfo,
152                                final int messageID,
153                                final int messageIDToAbandon,
154                                final List<Control> requestControls)
155  {
156    // No action will be taken by default.
157  }
158
159
160
161  /**
162   * Performs any appropriate log processing that may be needed when an add
163   * request is sent over a connection.
164   *
165   * @param  connectionInfo  Information about the connection that will be used
166   *                         to send the add request.  It will not be
167   *                         {@code null}.
168   * @param  messageID       The LDAP message ID for the add request that is to
169   *                         be sent.
170   * @param  addRequest      The add request that is to be sent.  This is
171   *                         provided only for informational purposes, and it
172   *                         must not be altered in any way.  It will not be
173   *                         {@code null}.
174   */
175  public void logAddRequest(final LDAPConnectionInfo connectionInfo,
176                            final int messageID,
177                            final ReadOnlyAddRequest addRequest)
178  {
179    // No action will be taken by default.
180  }
181
182
183
184  /**
185   * Performs any appropriate log processing that may be needed when an add
186   * response is received over a connection, or when an exception is caught
187   * while waiting for or attempting to decode an add response.
188   *
189   * @param  connectionInfo    Information about the connection used to send the
190   *                           add request.  It will not be {@code null}.
191   * @param  requestMessageID  The LDAP message ID for the associated add
192   *                           request.
193   * @param  addResult         The add result that was received from the server,
194   *                           or that was generated from an exception.  It will
195   *                           not be {@code null}.
196   */
197  public void logAddResult(final LDAPConnectionInfo connectionInfo,
198                            final int requestMessageID,
199                            final LDAPResult addResult)
200  {
201    // No action will be taken by default.
202  }
203
204
205
206  /**
207   * Performs any appropriate log processing that may be needed when a simple
208   * bind request is sent over a connection.
209   *
210   * @param  connectionInfo  Information about the connection that will be used
211   *                         to send the bind request.  It will not be
212   *                         {@code null}.
213   * @param  messageID       The LDAP message ID for the add request that is to
214   *                         be sent.
215   * @param  bindRequest     The bind request that is to be sent.  This is
216   *                         provided only for informational purposes, and it
217   *                         must not be altered in any way.  It will not be
218   *                         {@code null}.
219   */
220  public void logBindRequest(final LDAPConnectionInfo connectionInfo,
221                             final int messageID,
222                             final SimpleBindRequest bindRequest)
223  {
224    // No action will be taken by default.
225  }
226
227
228
229  /**
230   * Performs any appropriate log processing that may be needed when a SASL
231   * bind request is sent over a connection.
232   *
233   * @param  connectionInfo  Information about the connection that will be used
234   *                         to send the bind request.  It will not be
235   *                         {@code null}.
236   * @param  messageID       The LDAP message ID for the add request that is to
237   *                         be sent.
238   * @param  bindRequest     The bind request that is to be sent.  This is
239   *                         provided only for informational purposes, and it
240   *                         must not be altered in any way.  It will not be
241   *                         {@code null}.
242   */
243  public void logBindRequest(final LDAPConnectionInfo connectionInfo,
244                             final int messageID,
245                             final SASLBindRequest bindRequest)
246  {
247    // No action will be taken by default.
248  }
249
250
251
252  /**
253   * Performs any appropriate log processing that may be needed when a bind
254   * response is received over a connection, or when an exception is caught
255   * while waiting for or attempting to decode a bind response.
256   *
257   * @param  connectionInfo    Information about the connection used to send the
258   *                           add request.  It will not be {@code null}.
259   * @param  requestMessageID  The LDAP message ID for the associated add
260   *                           request.
261   * @param  bindResult        The bind result that was received from the
262   *                           server, or that was generated from an exception.
263   *                           It will not be {@code null}.
264   */
265  public void logBindResult(final LDAPConnectionInfo connectionInfo,
266                            final int requestMessageID,
267                            final BindResult bindResult)
268  {
269    // No action will be taken by default.
270  }
271
272
273
274  /**
275   * Performs any appropriate log processing that may be needed when a compare
276   * request is sent over a connection.
277   *
278   * @param  connectionInfo  Information about the connection that will be used
279   *                         to send the compare request.  It will not be
280   *                         {@code null}.
281   * @param  messageID       The LDAP message ID for the compare request that is
282   *                         to be sent.
283   * @param  compareRequest  The compare request that is to be sent.  This is
284   *                         provided only for informational purposes, and it
285   *                         must not be altered in any way.  It will not be
286   *                         {@code null}.
287   */
288  public void logCompareRequest(final LDAPConnectionInfo connectionInfo,
289                                final int messageID,
290                                final ReadOnlyCompareRequest compareRequest)
291  {
292    // No action will be taken by default.
293  }
294
295
296
297  /**
298   * Performs any appropriate log processing that may be needed when a compare
299   * response is received over a connection, or when an exception is caught
300   * while waiting for or attempting to decode a compare response.
301   *
302   * @param  connectionInfo    Information about the connection used to send the
303   *                           compare request.  It will not be {@code null}.
304   * @param  requestMessageID  The LDAP message ID for the associated compare
305   *                           request.
306   * @param  compareResult     The compare result that was received from the
307   *                           server, or that was generated from an exception.
308   *                           It will not be {@code null}.
309   */
310  public void logCompareResult(final LDAPConnectionInfo connectionInfo,
311                               final int requestMessageID,
312                               final LDAPResult compareResult)
313  {
314    // No action will be taken by default.
315  }
316
317
318
319  /**
320   * Performs any appropriate log processing that may be needed when a delete
321   * request is sent over a connection.
322   *
323   * @param  connectionInfo  Information about the connection that will be used
324   *                         to send the delete request.  It will not be
325   *                         {@code null}.
326   * @param  messageID       The LDAP message ID for the delete request that is
327   *                         to be sent.
328   * @param  deleteRequest   The delete request that is to be sent.  This is
329   *                         provided only for informational purposes, and it
330   *                         must not be altered in any way.  It will not be
331   *                         {@code null}.
332   */
333  public void logDeleteRequest(final LDAPConnectionInfo connectionInfo,
334                               final int messageID,
335                               final ReadOnlyDeleteRequest deleteRequest)
336  {
337    // No action will be taken by default.
338  }
339
340
341
342  /**
343   * Performs any appropriate log processing that may be needed when a delete
344   * response is received over a connection, or when an exception is caught
345   * while waiting for or attempting to decode a delete response.
346   *
347   * @param  connectionInfo    Information about the connection used to send the
348   *                           delete request.  It will not be {@code null}.
349   * @param  requestMessageID  The LDAP message ID for the associated delete
350   *                           request.
351   * @param  deleteResult      The delete result that was received from the
352   *                           server, or that was generated from an exception.
353   *                           It will not be {@code null}.
354   */
355  public void logDeleteResult(final LDAPConnectionInfo connectionInfo,
356                              final int requestMessageID,
357                              final LDAPResult deleteResult)
358  {
359    // No action will be taken by default.
360  }
361
362
363
364  /**
365   * Performs any appropriate log processing that may be needed when an extended
366   * request is sent over a connection.
367   *
368   * @param  connectionInfo   Information about the connection that will be used
369   *                          to send the extended request.  It will not be
370   *                          {@code null}.
371   * @param  messageID        The LDAP message ID for the extended request that
372   *                          is to be sent.
373   * @param  extendedRequest  The extended request that is to be sent.  This is
374   *                          provided only for informational purposes, and it
375   *                          must not be altered in any way.  It will not be
376   *                          {@code null}.
377   */
378  public void logExtendedRequest(final LDAPConnectionInfo connectionInfo,
379                                 final int messageID,
380                                 final ExtendedRequest extendedRequest)
381  {
382    // No action will be taken by default.
383  }
384
385
386
387  /**
388   * Performs any appropriate log processing that may be needed when an extended
389   * response is received over a connection, or when an exception is caught
390   * while waiting for or attempting to decode an extended response.
391   *
392   * @param  connectionInfo    Information about the connection used to send the
393   *                           extended request.  It will not be {@code null}.
394   * @param  requestMessageID  The LDAP message ID for the associated extended
395   *                           request.
396   * @param  extendedResult    The extended result that was received from the
397   *                           server, or that was generated from an exception.
398   *                           It will not be {@code null}.
399   */
400  public void logExtendedResult(final LDAPConnectionInfo connectionInfo,
401                                final int requestMessageID,
402                                final ExtendedResult extendedResult)
403  {
404    // No action will be taken by default.
405  }
406
407
408
409  /**
410   * Performs any appropriate log processing that may be needed when a modify
411   * request is sent over a connection.
412   *
413   * @param  connectionInfo  Information about the connection that will be used
414   *                         to send the modify request.  It will not be
415   *                         {@code null}.
416   * @param  messageID       The LDAP message ID for the modify request that is
417   *                         to be sent.
418   * @param  modifyRequest   The modify request that is to be sent.  This is
419   *                         provided only for informational purposes, and it
420   *                         must not be altered in any way.  It will not be
421   *                         {@code null}.
422   */
423  public void logModifyRequest(final LDAPConnectionInfo connectionInfo,
424                               final int messageID,
425                               final ReadOnlyModifyRequest modifyRequest)
426  {
427    // No action will be taken by default.
428  }
429
430
431
432  /**
433   * Performs any appropriate log processing that may be needed when a modify
434   * response is received over a connection, or when an exception is caught
435   * while waiting for or attempting to decode a modify response.
436   *
437   * @param  connectionInfo    Information about the connection used to send the
438   *                           modify request.  It will not be {@code null}.
439   * @param  requestMessageID  The LDAP message ID for the associated modify
440   *                           request.
441   * @param  modifyResult      The modify result that was received from the
442   *                           server, or that was generated from an exception.
443   *                           It will not be {@code null}.
444   */
445  public void logModifyResult(final LDAPConnectionInfo connectionInfo,
446                              final int requestMessageID,
447                              final LDAPResult modifyResult)
448  {
449    // No action will be taken by default.
450  }
451
452
453
454  /**
455   * Performs any appropriate log processing that may be needed when a modify DN
456   * request is sent over a connection.
457   *
458   * @param  connectionInfo   Information about the connection that will be used
459   *                          to send the modify DN request.  It will not be
460   *                          {@code null}.
461   * @param  messageID        The LDAP message ID for the modify DN request that
462   *                          is to be sent.
463   * @param  modifyDNRequest  The modify DN request that is to be sent.  This is
464   *                          provided only for informational purposes, and it
465   *                          must not be altered in any way.  It will not be
466   *                          {@code null}.
467   */
468  public void logModifyDNRequest(final LDAPConnectionInfo connectionInfo,
469                                 final int messageID,
470                                 final ReadOnlyModifyDNRequest modifyDNRequest)
471  {
472    // No action will be taken by default.
473  }
474
475
476
477  /**
478   * Performs any appropriate log processing that may be needed when a modify DN
479   * response is received over a connection, or when an exception is caught
480   * while waiting for or attempting to decode a modify DN response.
481   *
482   * @param  connectionInfo    Information about the connection used to send the
483   *                           modify DN request.  It will not be {@code null}.
484   * @param  requestMessageID  The LDAP message ID for the associated modify DN
485   *                           request.
486   * @param  modifyDNResult    The modify DN result that was received from the
487   *                           server, or that was generated from an exception.
488   *                           It will not be {@code null}.
489   */
490  public void logModifyDNResult(final LDAPConnectionInfo connectionInfo,
491                                final int requestMessageID,
492                                final LDAPResult modifyDNResult)
493  {
494    // No action will be taken by default.
495  }
496
497
498
499  /**
500   * Performs any appropriate log processing that may be needed when a search
501   * request is sent over a connection.
502   *
503   * @param  connectionInfo  Information about the connection that will be used
504   *                         to send the search request.  It will not be
505   *                         {@code null}.
506   * @param  messageID       The LDAP message ID for the search request that is
507   *                         to be sent.
508   * @param  searchRequest   The search request that is to be sent.  This is
509   *                         provided only for informational purposes, and it
510   *                         must not be altered in any way.  It will not be
511   *                         {@code null}.
512   */
513  public void logSearchRequest(final LDAPConnectionInfo connectionInfo,
514                               final int messageID,
515                               final ReadOnlySearchRequest searchRequest)
516  {
517    // No action will be taken by default.
518  }
519
520
521
522  /**
523   * Performs any appropriate log processing that may be needed when a search
524   * result entry response is received over a connection.
525   *
526   * @param  connectionInfo    Information about the connection used to send the
527   *                           search request.  It will not be {@code null}.
528   * @param  requestMessageID  The LDAP message ID for the associated search
529   *                           request.
530   * @param  searchEntry       The search result entry that was received from
531   *                           the server.  It will not be {@code null}.
532   */
533  public void logSearchEntry(final LDAPConnectionInfo connectionInfo,
534                             final int requestMessageID,
535                             final SearchResultEntry searchEntry)
536  {
537    // No action will be taken by default.
538  }
539
540
541
542  /**
543   * Performs any appropriate log processing that may be needed when a search
544   * result reference response is received over a connection.
545   *
546   * @param  connectionInfo    Information about the connection used to send the
547   *                           search request.  It will not be {@code null}.
548   * @param  requestMessageID  The LDAP message ID for the associated search
549   *                           request.
550   * @param  searchReference   The search result reference that was received
551   *                           from the server.  It will not be {@code null}.
552   */
553  public void logSearchReference(final LDAPConnectionInfo connectionInfo,
554                                 final int requestMessageID,
555                                 final SearchResultReference searchReference)
556  {
557    // No action will be taken by default.
558  }
559
560
561
562  /**
563   * Performs any appropriate log processing that may be needed when a search
564   * result done response is received over a connection, or when an exception is
565   * caught while waiting for or attempting to decode a search result.
566   *
567   * @param  connectionInfo    Information about the connection used to send the
568   *                           search request.  It will not be {@code null}.
569   * @param  requestMessageID  The LDAP message ID for the associated search
570   *                           request.
571   * @param  searchResult      The search result that was received from the
572   *                           server, or that was generated from an exception.
573   *                           It will not be {@code null}.
574   */
575  public void logSearchResult(final LDAPConnectionInfo connectionInfo,
576                               final int requestMessageID,
577                               final SearchResult searchResult)
578  {
579    // No action will be taken by default.
580  }
581
582
583
584  /**
585   * Performs any appropriate log processing that may be needed when an unbind
586   * request is sent over a connection.
587   *
588   * @param  connectionInfo      Information about the connection that will be
589   *                             used to send the unbind request.  It will not
590   *                             be {@code null}.
591   * @param  messageID           The LDAP message ID for the unbind request
592   *                             that is to be sent.
593   * @param  requestControls     The list of controls included in the unbind
594   *                             request.
595   */
596  public void logUnbindRequest(final LDAPConnectionInfo connectionInfo,
597                               final int messageID,
598                               final List<Control> requestControls)
599  {
600    // No action will be taken by default.
601  }
602
603
604
605  /**
606   * Performs any appropriate log processing that may be needed when an
607   * intermediate response message is received over a connection.
608   *
609   * @param  connectionInfo        Information about the connection over which
610   *                               the intermediate response was received.  It
611   *                               will not be {@code null}.
612   * @param  messageID             The LDAP message ID for the intermediate
613   *                               response message.
614   * @param  intermediateResponse  The intermediate response message that was
615   *                               received.
616   */
617  public void logIntermediateResponse(final LDAPConnectionInfo connectionInfo,
618                   final int messageID,
619                   final IntermediateResponse intermediateResponse)
620  {
621    // No action will be taken by default.
622  }
623}