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