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}