001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Portions Copyright 2010-2023 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.common.scripting;
028
029
030
031import java.security.cert.Certificate;
032import java.util.List;
033import java.util.Map;
034
035import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
036import com.unboundid.directory.sdk.common.config.AccessLoggerConfig;
037import com.unboundid.directory.sdk.common.internal.Reconfigurable;
038import com.unboundid.directory.sdk.common.operation.AbandonRequest;
039import com.unboundid.directory.sdk.common.operation.AddRequest;
040import com.unboundid.directory.sdk.common.operation.AddResult;
041import com.unboundid.directory.sdk.common.operation.BindResult;
042import com.unboundid.directory.sdk.common.operation.CompareRequest;
043import com.unboundid.directory.sdk.common.operation.CompareResult;
044import com.unboundid.directory.sdk.common.operation.DeleteRequest;
045import com.unboundid.directory.sdk.common.operation.DeleteResult;
046import com.unboundid.directory.sdk.common.operation.ExtendedRequest;
047import com.unboundid.directory.sdk.common.operation.ExtendedResult;
048import com.unboundid.directory.sdk.common.operation.GenericResult;
049import com.unboundid.directory.sdk.common.operation.ModifyRequest;
050import com.unboundid.directory.sdk.common.operation.ModifyResult;
051import com.unboundid.directory.sdk.common.operation.ModifyDNRequest;
052import com.unboundid.directory.sdk.common.operation.ModifyDNResult;
053import com.unboundid.directory.sdk.common.operation.SASLBindRequest;
054import com.unboundid.directory.sdk.common.operation.SearchRequest;
055import com.unboundid.directory.sdk.common.operation.SearchResult;
056import com.unboundid.directory.sdk.common.operation.SimpleBindRequest;
057import com.unboundid.directory.sdk.common.operation.UnbindRequest;
058import com.unboundid.directory.sdk.common.types.AssuredReplicationResult;
059import com.unboundid.directory.sdk.common.types.ClientContext;
060import com.unboundid.directory.sdk.common.types.CompletedOperationContext;
061import com.unboundid.directory.sdk.common.types.CompletedSearchOperationContext;
062import com.unboundid.directory.sdk.common.types.DisconnectReason;
063import com.unboundid.directory.sdk.common.types.Entry;
064import com.unboundid.directory.sdk.common.types.ForwardTarget;
065import com.unboundid.directory.sdk.common.types.OperationContext;
066import com.unboundid.directory.sdk.common.types.ServerContext;
067import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
068import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
069import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
070import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
071import com.unboundid.ldap.sdk.Control;
072import com.unboundid.ldap.sdk.IntermediateResponse;
073import com.unboundid.ldap.sdk.LDAPException;
074import com.unboundid.ldap.sdk.ResultCode;
075import com.unboundid.ldap.sdk.unboundidds.MoveSubtreeResult;
076import com.unboundid.util.Extensible;
077import com.unboundid.util.ThreadSafety;
078import com.unboundid.util.ThreadSafetyLevel;
079import com.unboundid.util.args.ArgumentException;
080import com.unboundid.util.args.ArgumentParser;
081
082
083
084/**
085 * This class defines an API that must be implemented by scripted extensions
086 * which record information about interaction with clients, including
087 * connections established and received and operations requested and completed.
088 * <BR><BR>
089 * Access loggers will be invoked for the following events:
090 * <UL>
091 *   <LI>Whenever a new connection is established.</LI>
092 *   <LI>Whenever an existing connection is closed or terminated.</LI>
093 *   <LI>Whenever an abandon, add, bind, compare, delete, extended, modify,
094 *       modify DN, search, or unbind request is received.</LI>
095 *   <LI>Whenever an abandon, add, bind, compare, delete, extended, modify,
096 *       modify DN, or search request is forwarded to another server for
097 *       processing.</LI>
098 *   <LI>If a forwarded add, bind, compare, delete, extended, modify, modify DN,
099 *       or search operation fails.</LI>
100 *   <LI>After sending the result for an add, bind, compare, delete, extended,
101 *       modify, modify DN, or search operation.</LI>
102 *   <LI>After completing processing for an abandon operation.</LI>
103 *   <LI>After sending a search result entry, search result reference, or
104 *       intermediate response message to the client.</LI>
105 * </UL>
106 * <BR><BR>
107 * Each access logger may configured to indicate whether to include or exclude
108 * internal and/or replicated operations, and criteria may be used to provide
109 * filtered logging.  This is handled automatically by the server, so individual
110 * access logger implementations do not need to attempt to perform that
111 * filtering on their own.  However, they may perform additional processing if
112 * desired to further narrow the set of messages that should be logged.
113 * <BR>
114 * <H2>Configuring Groovy-Scripted Access Loggers</H2>
115 * In order to configure a scripted access logger based on this API and written
116 * in the Groovy scripting language, use a command
117 * like:
118 * <PRE>
119 *      dsconfig create-log-publisher \
120 *           --publisher-name "<I>{logger-name}</I>" \
121 *           --type groovy-scripted-access \
122 *           --set enabled:true \
123 *           --set "script-class:<I>{class-name}</I>" \
124 *           --set "script-argument:<I>{name=value}</I>"
125 * </PRE>
126 * where "<I>{logger-name}</I>" is the name to use for the access logger
127 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Groovy
128 * class written using this API, and "<I>{name=value}</I>" represents name-value
129 * pairs for any arguments to provide to the logger.  If multiple arguments
130 * should be provided to the logger, then the
131 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be
132 * provided multiple times.
133 *
134 * @see  com.unboundid.directory.sdk.common.api.AccessLogger
135 * @see  com.unboundid.directory.sdk.common.api.FileBasedAccessLogger
136 * @see  ScriptedFileBasedAccessLogger
137 */
138@Extensible()
139@DirectoryServerExtension()
140@DirectoryProxyServerExtension(appliesToLocalContent=true,
141     appliesToRemoteContent=false)
142@SynchronizationServerExtension(appliesToLocalContent=true,
143     appliesToSynchronizedContent=false)
144@MetricsEngineExtension()
145@BrokerExtension()
146@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
147public abstract class ScriptedAccessLogger
148       implements Reconfigurable<AccessLoggerConfig>
149{
150  /**
151   * Creates a new instance of this access logger.  All access logger
152   * implementations must include a default constructor, but any initialization
153   * should generally be done in the {@code initializeAccessLogger} method.
154   */
155  public ScriptedAccessLogger()
156  {
157    // No implementation is required.
158  }
159
160
161
162  /**
163   * {@inheritDoc}
164   */
165  public void defineConfigArguments(final ArgumentParser parser)
166         throws ArgumentException
167  {
168    // No arguments will be allowed by default.
169  }
170
171
172
173  /**
174   * Initializes this access logger.
175   *
176   * @param  serverContext  A handle to the server context for the server in
177   *                        which this extension is running.
178   * @param  config         The general configuration for this access logger.
179   * @param  parser         The argument parser which has been initialized from
180   *                        the configuration for this access logger.
181   *
182   * @throws  LDAPException  If a problem occurs while initializing this
183   *                         access logger.
184   */
185  public void initializeAccessLogger(final ServerContext serverContext,
186                                     final AccessLoggerConfig config,
187                                     final ArgumentParser parser)
188         throws LDAPException
189  {
190    // No initialization will be performed by default.
191  }
192
193
194
195  /**
196   * Performs any cleanup which may be necessary when this access logger is to
197   * be taken out of service.
198   */
199  public void finalizeAccessLogger()
200  {
201    // No implementation is required.
202  }
203
204
205
206  /**
207   * {@inheritDoc}
208   */
209  public boolean isConfigurationAcceptable(final AccessLoggerConfig config,
210                      final ArgumentParser parser,
211                      final List<String> unacceptableReasons)
212  {
213    // No extended validation will be performed.
214    return true;
215  }
216
217
218
219  /**
220   * {@inheritDoc}
221   */
222  public ResultCode applyConfiguration(final AccessLoggerConfig config,
223                                       final ArgumentParser parser,
224                                       final List<String> adminActionsRequired,
225                                       final List<String> messages)
226  {
227    // By default, no configuration changes will be applied.  If there are any
228    // arguments, then add an admin action message indicating that the extension
229    // needs to be restarted for any changes to take effect.
230    if (! parser.getNamedArguments().isEmpty())
231    {
232      adminActionsRequired.add(
233           "No configuration change has actually been applied.  The new " +
234                "configuration will not take effect until this access logger " +
235                "is disabled and re-enabled or until the server is restarted.");
236    }
237
238    return ResultCode.SUCCESS;
239  }
240
241
242
243  /**
244   * Logs a message indicating that a new connection has been established.
245   *
246   * @param  clientContext  Information about the client connection that has
247   *                        been accepted.
248   */
249  public void logConnect(final ClientContext clientContext)
250  {
251    // No action will be taken by default.
252  }
253
254
255
256  /**
257   * Logs a message indicating that a connection has been closed.
258   *
259   * @param  clientContext     Information about the client connection that has
260   *                           been closed.
261   * @param  disconnectReason  A general reason that the connection has been
262   *                           closed.
263   * @param  message           A message with additional information about the
264   *                           closure.  It may be {@code null} if none is
265   *                           available.
266   */
267  public void logDisconnect(final ClientContext clientContext,
268                            final DisconnectReason disconnectReason,
269                            final String message)
270  {
271    // No action will be taken by default.
272  }
273
274
275
276  /**
277   * Logs a message about security negotiation performed by a client.
278   *
279   * @param  clientContext  Information about the client connection on which
280   *                        the negotiation was completed.
281   * @param  protocol       The security protocol selected by the negotiation.
282   *                        It may be {@code null} if no protocol is available.
283   * @param  cipher         The cipher suite selected by the negotiation.  It
284   *                        may be {@code null} if no cipher is available.
285   * @param  properties     A set of additional properties that may be included
286   *                        in the log message.  It may be {@code null} or empty
287   *                        if no additional properties are needed.
288   */
289  public void logSecurityNegotiation(final ClientContext clientContext,
290                                     final String protocol, final String cipher,
291                                     final Map<String,String> properties)
292  {
293    // No action will be taken by default.
294  }
295
296
297
298  /**
299   * Logs a message about a certificate chain presented by a client.
300   *
301   * @param  clientContext  Information about the client that presented the
302   *                        certificate chain.
303   * @param  certChain      The certificate chain presented by the client.
304   * @param  authDN         The DN of the user as whom the client was
305   *                        automatically authenticated, or {@code null} if the
306   *                        client was not automatically authenticated.
307   */
308  public void logClientCertificateChain(final ClientContext clientContext,
309                                        final Certificate[] certChain,
310                                        final String authDN)
311  {
312    // No action will be taken by default.
313  }
314
315
316
317  /**
318   * Logs a message about an abandon request received from a client.
319   *
320   * @param  opContext  The operation context for the abandon operation.
321   * @param  request    The abandon request that was received.
322   */
323  public void logAbandonRequest(final OperationContext opContext,
324                                final AbandonRequest request)
325  {
326    // No action will be taken by default.
327  }
328
329
330
331  /**
332   * Logs a message about an abandon request that will be forwarded to another
333   * server.
334   *
335   * @param  opContext  The operation context for the abandon operation.
336   * @param  request    The abandon request that was received.
337   * @param  target     Information about the server to which the request will
338   *                    be forwarded.
339   */
340  public void logAbandonForward(final OperationContext opContext,
341                                final AbandonRequest request,
342                                final ForwardTarget target)
343  {
344    // No action will be taken by default.
345  }
346
347
348
349  /**
350   * Logs a message about the result of processing an abandon request.
351   *
352   * @param  opContext  The operation context for the abandon operation.
353   * @param  request    The abandon request that was received.
354   * @param  result     The result of processing the abandon request.
355   */
356  public void logAbandonResult(final CompletedOperationContext opContext,
357                               final AbandonRequest request,
358                               final GenericResult result)
359  {
360    // No action will be taken by default.
361  }
362
363
364
365  /**
366   * Logs a message about an add request received from a client.
367   *
368   * @param  opContext  The operation context for the add operation.
369   * @param  request    The add request that was received.
370   */
371  public void logAddRequest(final OperationContext opContext,
372                            final AddRequest request)
373  {
374    // No action will be taken by default.
375  }
376
377
378
379  /**
380   * Logs a message about an add request that will be forwarded to another
381   * server.
382   *
383   * @param  opContext  The operation context for the add operation.
384   * @param  request    The add request that was received.
385   * @param  target     Information about the server to which the request will
386   *                    be forwarded.
387   */
388  public void logAddForward(final OperationContext opContext,
389                            final AddRequest request,
390                            final ForwardTarget target)
391  {
392    // No action will be taken by default.
393  }
394
395
396
397  /**
398   * Logs a message about a failure encountered while attempting to forward an
399   * add request to another server.
400   *
401   * @param  opContext  The operation context for the add operation.
402   * @param  request    The add request that was received.
403   * @param  target     Information about the server to which the request was
404   *                    forwarded.
405   * @param  failure    The exception that was received when attempting to
406   *                    forward the request.
407   */
408  public void logAddForwardFailure(final OperationContext opContext,
409                                   final AddRequest request,
410                                   final ForwardTarget target,
411                                   final LDAPException failure)
412  {
413    // No action will be taken by default.
414  }
415
416
417
418  /**
419   * Logs a message about the result of processing an add request.
420   *
421   * @param  opContext  The operation context for the add operation.
422   * @param  request    The add request that was received.
423   * @param  result     The result of processing the add request.
424   */
425  public void logAddResponse(final CompletedOperationContext opContext,
426                             final AddRequest request,
427                             final AddResult result)
428  {
429    // No action will be taken by default.
430  }
431
432
433
434  /**
435   * Logs a message about the result of replication assurance processing for an
436   * add operation.
437   *
438   * @param  opContext        The operation context for the add operation.
439   * @param  request          The add request that was received.
440   * @param  result           The result of processing the add request.
441   * @param  assuranceResult  The replication assurance processing result.
442   */
443  public void logAddAssuranceCompleted(
444                   final CompletedOperationContext opContext,
445                   final AddRequest request, final AddResult result,
446                   final AssuredReplicationResult assuranceResult)
447  {
448    // No action will be taken by default.
449  }
450
451
452
453  /**
454   * Logs a message about a simple bind request received from a client.
455   *
456   * @param  opContext  The operation context for the bind operation.
457   * @param  request    The bind request that was received.
458   */
459  public void logBindRequest(final OperationContext opContext,
460                             final SimpleBindRequest request)
461  {
462    // No action will be taken by default.
463  }
464
465
466
467  /**
468   * Logs a message about a simple bind request that will be forwarded to
469   * another server.
470   *
471   * @param  opContext  The operation context for the bind operation.
472   * @param  request    The bind request that was received.
473   * @param  target     Information about the server to which the request will
474   *                    be forwarded.
475   */
476  public void logBindForward(final OperationContext opContext,
477                                final SimpleBindRequest request,
478                                final ForwardTarget target)
479  {
480    // No action will be taken by default.
481  }
482
483
484
485  /**
486   * Logs a message about a failure encountered while attempting to forward a
487   * simple bind request to another server.
488   *
489   * @param  opContext  The operation context for the bind operation.
490   * @param  request    The bind request that was received.
491   * @param  target     Information about the server to which the request was
492   *                    forwarded.
493   * @param  failure    The exception that was received when attempting to
494   *                    forward the request.
495   */
496  public void logBindForwardFailure(final OperationContext opContext,
497                                    final SimpleBindRequest request,
498                                    final ForwardTarget target,
499                                    final LDAPException failure)
500  {
501    // No action will be taken by default.
502  }
503
504
505
506  /**
507   * Logs a message about the result of processing a simple bind request.
508   *
509   * @param  opContext  The operation context for the bind operation.
510   * @param  request    The bind request that was received.
511   * @param  result     The result of processing the bind request.
512   */
513  public void logBindResponse(final CompletedOperationContext opContext,
514                              final SimpleBindRequest request,
515                              final BindResult result)
516  {
517    // No action will be taken by default.
518  }
519
520
521
522  /**
523   * Logs a message about a SASL bind request received from a client.
524   *
525   * @param  opContext  The operation context for the bind operation.
526   * @param  request    The bind request that was received.
527   */
528  public void logBindRequest(final OperationContext opContext,
529                             final SASLBindRequest request)
530  {
531    // No action will be taken by default.
532  }
533
534
535
536  /**
537   * Logs a message about a SASL bind request that will be forwarded to
538   * another server.
539   *
540   * @param  opContext  The operation context for the bind operation.
541   * @param  request    The bind request that was received.
542   * @param  target     Information about the server to which the request will
543   *                    be forwarded.
544   */
545  public void logBindForward(final OperationContext opContext,
546                                final SASLBindRequest request,
547                                final ForwardTarget target)
548  {
549    // No action will be taken by default.
550  }
551
552
553
554  /**
555   * Logs a message about a failure encountered while attempting to forward a
556   * SASL bind request to another server.
557   *
558   * @param  opContext  The operation context for the bind operation.
559   * @param  request    The bind request that was received.
560   * @param  target     Information about the server to which the request was
561   *                    forwarded.
562   * @param  failure    The exception that was received when attempting to
563   *                    forward the request.
564   */
565  public void logBindForwardFailure(final OperationContext opContext,
566                                    final SASLBindRequest request,
567                                    final ForwardTarget target,
568                                    final LDAPException failure)
569  {
570    // No action will be taken by default.
571  }
572
573
574
575  /**
576   * Logs a message about the result of processing a SASL bind request.
577   *
578   * @param  opContext  The operation context for the bind operation.
579   * @param  request    The bind request that was received.
580   * @param  result     The result of processing the bind request.
581   */
582  public void logBindResponse(final CompletedOperationContext opContext,
583                              final SASLBindRequest request,
584                              final BindResult result)
585  {
586    // No action will be taken by default.
587  }
588
589
590
591  /**
592   * Logs a message about a compare request received from a client.
593   *
594   * @param  opContext  The operation context for the compare operation.
595   * @param  request    The compare request that was received.
596   */
597  public void logCompareRequest(final OperationContext opContext,
598                                final CompareRequest request)
599  {
600    // No action will be taken by default.
601  }
602
603
604
605  /**
606   * Logs a message about a compare request that will be forwarded to another
607   * server.
608   *
609   * @param  opContext  The operation context for the compare operation.
610   * @param  request    The compare request that was received.
611   * @param  target     Information about the server to which the request will
612   *                    be forwarded.
613   */
614  public void logCompareForward(final OperationContext opContext,
615                                final CompareRequest request,
616                                final ForwardTarget target)
617  {
618    // No action will be taken by default.
619  }
620
621
622
623  /**
624   * Logs a message about a failure encountered while attempting to forward a
625   * compare request to another server.
626   *
627   * @param  opContext  The operation context for the compare operation.
628   * @param  request    The compare request that was received.
629   * @param  target     Information about the server to which the request was
630   *                    forwarded.
631   * @param  failure    The exception that was received when attempting to
632   *                    forward the request.
633   */
634  public void logCompareForwardFailure(final OperationContext opContext,
635                                       final CompareRequest request,
636                                       final ForwardTarget target,
637                                       final LDAPException failure)
638  {
639    // No action will be taken by default.
640  }
641
642
643
644  /**
645   * Logs a message about the result of processing a compare request.
646   *
647   * @param  opContext  The operation context for the compare operation.
648   * @param  request    The compare request that was received.
649   * @param  result     The result of processing the compare request.
650   */
651  public void logCompareResponse(final CompletedOperationContext opContext,
652                                 final CompareRequest request,
653                                 final CompareResult result)
654  {
655    // No action will be taken by default.
656  }
657
658
659
660  /**
661   * Logs a message about a delete request received from a client.
662   *
663   * @param  opContext  The operation context for the delete operation.
664   * @param  request    The delete request that was received.
665   */
666  public void logDeleteRequest(final OperationContext opContext,
667                               final DeleteRequest request)
668  {
669    // No action will be taken by default.
670  }
671
672
673
674  /**
675   * Logs a message about a delete request that will be forwarded to another
676   * server.
677   *
678   * @param  opContext  The operation context for the delete operation.
679   * @param  request    The delete request that was received.
680   * @param  target     Information about the server to which the request will
681   *                    be forwarded.
682   */
683  public void logDeleteForward(final OperationContext opContext,
684                               final DeleteRequest request,
685                               final ForwardTarget target)
686  {
687    // No action will be taken by default.
688  }
689
690
691
692  /**
693   * Logs a message about a failure encountered while attempting to forward a
694   * delete request to another server.
695   *
696   * @param  opContext  The operation context for the delete operation.
697   * @param  request    The delete request that was received.
698   * @param  target     Information about the server to which the request was
699   *                    forwarded.
700   * @param  failure    The exception that was received when attempting to
701   *                    forward the request.
702   */
703  public void logDeleteForwardFailure(final OperationContext opContext,
704                                      final DeleteRequest request,
705                                      final ForwardTarget target,
706                                      final LDAPException failure)
707  {
708    // No action will be taken by default.
709  }
710
711
712
713  /**
714   * Logs a message about the result of processing a delete request.
715   *
716   * @param  opContext  The operation context for the delete operation.
717   * @param  request    The delete request that was received.
718   * @param  result     The result of processing the delete request.
719   */
720  public void logDeleteResponse(final CompletedOperationContext opContext,
721                                final DeleteRequest request,
722                                final DeleteResult result)
723  {
724    // No action will be taken by default.
725  }
726
727
728
729  /**
730   * Logs a message about the result of replication assurance processing for a
731   * delete operation.
732   *
733   * @param  opContext        The operation context for the delete operation.
734   * @param  request          The delete request that was received.
735   * @param  result           The result of processing the delete request.
736   * @param  assuranceResult  The replication assurance processing result.
737   */
738  public void logDeleteAssuranceCompleted(
739                   final CompletedOperationContext opContext,
740                   final DeleteRequest request, final DeleteResult result,
741                   final AssuredReplicationResult assuranceResult)
742  {
743    // No action will be taken by default.
744  }
745
746
747
748  /**
749   * Logs a message about an extended request received from a client.
750   *
751   * @param  opContext  The operation context for the extended operation.
752   * @param  request    The extended request that was received.
753   */
754  public void logExtendedRequest(final OperationContext opContext,
755                                 final ExtendedRequest request)
756  {
757    // No action will be taken by default.
758  }
759
760
761
762  /**
763   * Logs a message about an extended request that will be forwarded to another
764   * server.
765   *
766   * @param  opContext  The operation context for the extended operation.
767   * @param  request    The extended request that was received.
768   * @param  target     Information about the server to which the request will
769   *                    be forwarded.
770   */
771  public void logExtendedForward(final OperationContext opContext,
772                                 final ExtendedRequest request,
773                                 final ForwardTarget target)
774  {
775    // No action will be taken by default.
776  }
777
778
779
780  /**
781   * Logs a message about a failure encountered while attempting to forward an
782   * extended request to another server.
783   *
784   * @param  opContext  The operation context for the extended operation.
785   * @param  request    The extended request that was received.
786   * @param  target     Information about the server to which the request was
787   *                    forwarded.
788   * @param  failure    The exception that was received when attempting to
789   *                    forward the request.
790   */
791  public void logExtendedForwardFailure(final OperationContext opContext,
792                                        final ExtendedRequest request,
793                                        final ForwardTarget target,
794                                        final LDAPException failure)
795  {
796    // No action will be taken by default.
797  }
798
799
800
801  /**
802   * Logs a message about the result of processing an extended request.
803   *
804   * @param  opContext  The operation context for the extended operation.
805   * @param  request    The extended request that was received.
806   * @param  result     The result of processing the extended request.
807   */
808  public void logExtendedResponse(final CompletedOperationContext opContext,
809                                  final ExtendedRequest request,
810                                  final ExtendedResult result)
811  {
812    // No action will be taken by default.
813  }
814
815
816
817  /**
818   * Logs a message about a modify request received from a client.
819   *
820   * @param  opContext  The operation context for the modify operation.
821   * @param  request    The modify request that was received.
822   */
823  public void logModifyRequest(final OperationContext opContext,
824                               final ModifyRequest request)
825  {
826    // No action will be taken by default.
827  }
828
829
830
831  /**
832   * Logs a message about a modify request that will be forwarded to another
833   * server.
834   *
835   * @param  opContext  The operation context for the modify operation.
836   * @param  request    The modify request that was received.
837   * @param  target     Information about the server to which the request will
838   *                    be forwarded.
839   */
840  public void logModifyForward(final OperationContext opContext,
841                               final ModifyRequest request,
842                               final ForwardTarget target)
843  {
844    // No action will be taken by default.
845  }
846
847
848
849  /**
850   * Logs a message about a failure encountered while attempting to forward a
851   * modify request to another server.
852   *
853   * @param  opContext  The operation context for the modify operation.
854   * @param  request    The modify request that was received.
855   * @param  target     Information about the server to which the request was
856   *                    forwarded.
857   * @param  failure    The exception that was received when attempting to
858   *                    forward the request.
859   */
860  public void logModifyForwardFailure(final OperationContext opContext,
861                                      final ModifyRequest request,
862                                      final ForwardTarget target,
863                                      final LDAPException failure)
864  {
865    // No action will be taken by default.
866  }
867
868
869
870  /**
871   * Logs a message about the result of processing a modify request.
872   *
873   * @param  opContext  The operation context for the modify operation.
874   * @param  request    The modify request that was received.
875   * @param  result     The result of processing the modify request.
876   */
877  public void logModifyResponse(final CompletedOperationContext opContext,
878                                final ModifyRequest request,
879                                final ModifyResult result)
880  {
881    // No action will be taken by default.
882  }
883
884
885
886  /**
887   * Logs a message about the result of replication assurance processing for a
888   * modify operation.
889   *
890   * @param  opContext        The operation context for the modify operation.
891   * @param  request          The modify request that was received.
892   * @param  result           The result of processing the modify request.
893   * @param  assuranceResult  The replication assurance processing result.
894   */
895  public void logModifyAssuranceCompleted(
896                   final CompletedOperationContext opContext,
897                   final ModifyRequest request, final ModifyResult result,
898                   final AssuredReplicationResult assuranceResult)
899  {
900    // No action will be taken by default.
901  }
902
903
904
905  /**
906   * Logs a message about a modify DN request received from a client.
907   *
908   * @param  opContext  The operation context for the modify DN operation.
909   * @param  request    The modify DN request that was received.
910   */
911  public void logModifyDNRequest(final OperationContext opContext,
912                                 final ModifyDNRequest request)
913  {
914    // No action will be taken by default.
915  }
916
917
918
919  /**
920   * Logs a message about a modify DN request that will be forwarded to another
921   * server.
922   *
923   * @param  opContext  The operation context for the modify DN operation.
924   * @param  request    The modify DN request that was received.
925   * @param  target     Information about the server to which the request will
926   *                    be forwarded.
927   */
928  public void logModifyDNForward(final OperationContext opContext,
929                                 final ModifyDNRequest request,
930                                 final ForwardTarget target)
931  {
932    // No action will be taken by default.
933  }
934
935
936
937  /**
938   * Logs a message about a failure encountered while attempting to forward a
939   * modify DN request to another server.
940   *
941   * @param  opContext  The operation context for the modify DN operation.
942   * @param  request    The modify DN request that was received.
943   * @param  target     Information about the server to which the request was
944   *                    forwarded.
945   * @param  failure    The exception that was received when attempting to
946   *                    forward the request.
947   */
948  public void logModifyDNForwardFailure(final OperationContext opContext,
949                                        final ModifyDNRequest request,
950                                        final ForwardTarget target,
951                                        final LDAPException failure)
952  {
953    // No action will be taken by default.
954  }
955
956
957
958  /**
959   * Logs a message about the result of processing a modify DN request.
960   *
961   * @param  opContext  The operation context for the modify DN operation.
962   * @param  request    The modify DN request that was received.
963   * @param  result     The result of processing the modify DN request.
964   */
965  public void logModifyDNResponse(final CompletedOperationContext opContext,
966                                  final ModifyDNRequest request,
967                                  final ModifyDNResult result)
968  {
969    // No action will be taken by default.
970  }
971
972
973
974  /**
975   * Logs a message about the result of replication assurance processing for a
976   * modify DN operation.
977   *
978   * @param  opContext        The operation context for the modify DN operation.
979   * @param  request          The modify DN request that was received.
980   * @param  result           The result of processing the modify DN request.
981   * @param  assuranceResult  The replication assurance processing result.
982   */
983  public void logModifyDNAssuranceCompleted(
984                   final CompletedOperationContext opContext,
985                   final ModifyDNRequest request, final ModifyDNResult result,
986                   final AssuredReplicationResult assuranceResult)
987  {
988    // No action will be taken by default.
989  }
990
991
992
993  /**
994   * Logs a message about a search request received from a client.
995   *
996   * @param  opContext  The operation context for the search operation.
997   * @param  request    The search request that was received.
998   */
999  public void logSearchRequest(final OperationContext opContext,
1000                               final SearchRequest request)
1001  {
1002    // No action will be taken by default.
1003  }
1004
1005
1006
1007  /**
1008   * Logs a message about a search request that will be forwarded to another
1009   * server.
1010   *
1011   * @param  opContext  The operation context for the search operation.
1012   * @param  request    The search request that was received.
1013   * @param  target     Information about the server to which the request will
1014   *                    be forwarded.
1015   */
1016  public void logSearchForward(final OperationContext opContext,
1017                               final SearchRequest request,
1018                               final ForwardTarget target)
1019  {
1020    // No action will be taken by default.
1021  }
1022
1023
1024
1025  /**
1026   * Logs a message about a failure encountered while attempting to forward a
1027   * search request to another server.
1028   *
1029   * @param  opContext  The operation context for the search operation.
1030   * @param  request    The search request that was received.
1031   * @param  target     Information about the server to which the request was
1032   *                    forwarded.
1033   * @param  failure    The exception that was received when attempting to
1034   *                    forward the request.
1035   */
1036  public void logSearchForwardFailure(final OperationContext opContext,
1037                                      final SearchRequest request,
1038                                      final ForwardTarget target,
1039                                      final LDAPException failure)
1040  {
1041    // No action will be taken by default.
1042  }
1043
1044
1045
1046  /**
1047   * Logs a message about a search result entry that was returned to the client.
1048   *
1049   * @param  opContext  The operation context for the search operation.
1050   * @param  request    The search request that was received.
1051   * @param  entry      The entry that was returned.
1052   * @param  controls   The set of controls included with the entry, or an empty
1053   *                    list if there were none.
1054   */
1055  public void logSearchResultEntry(final OperationContext opContext,
1056                                   final SearchRequest request,
1057                                   final Entry entry,
1058                                   final List<Control> controls)
1059  {
1060    // No action will be taken by default.
1061  }
1062
1063
1064
1065  /**
1066   * Logs a message about a search result reference that was returned to the
1067   * client.
1068   *
1069   * @param  opContext     The operation context for the search operation.
1070   * @param  request       The search request that was received.
1071   * @param  referralURLs  The referral URLs for the reference that was
1072   *                       returned.
1073   * @param  controls      The set of controls included with the reference, or
1074   *                       an empty list if there were none.
1075   */
1076  public void logSearchResultReference(final OperationContext opContext,
1077                                       final SearchRequest request,
1078                                       final List<String> referralURLs,
1079                                       final List<Control> controls)
1080  {
1081    // No action will be taken by default.
1082  }
1083
1084
1085
1086  /**
1087   * Logs a message about the result of processing a search request.
1088   *
1089   * @param  opContext  The operation context for the search operation.
1090   * @param  request    The search request that was received.
1091   * @param  result     The result of processing the search request.
1092   */
1093  public void logSearchResultDone(
1094                   final CompletedSearchOperationContext opContext,
1095                   final SearchRequest request, final SearchResult result)
1096  {
1097    // No action will be taken by default.
1098  }
1099
1100
1101
1102  /**
1103   * Logs a message about an unbind request received from a client.
1104   *
1105   * @param  opContext  The operation context for the unbind operation.
1106   * @param  request    The unbind request that was received.
1107   */
1108  public void logUnbindRequest(final OperationContext opContext,
1109                               final UnbindRequest request)
1110  {
1111    // No action will be taken by default.
1112  }
1113
1114
1115
1116  /**
1117   * Logs a message about an intermediate response that was returned to the
1118   * client.
1119   *
1120   * @param  opContext             The operation context for the associated
1121   *                               operation.
1122   * @param  intermediateResponse  The intermediate response that was returned.
1123   */
1124  public void logIntermediateResponse(final OperationContext opContext,
1125                   final IntermediateResponse intermediateResponse)
1126  {
1127    // No action will be taken by default.
1128  }
1129
1130
1131
1132  /**
1133   * Writes a message to the access logger to indicate that the Directory Proxy
1134   * Server will attempt to perform entry rebalancing by migrating a subtree
1135   * from one backend set to another.
1136   *
1137   * @param  rebalancingOperationID  The unique ID assigned to the entry
1138   *                                 balancing operation.
1139   * @param  triggerOperation        The operation that triggered the entry
1140   *                                 rebalancing.  It may be {@code null} if the
1141   *                                 rebalancing operation wasn't triggered by a
1142   *                                 client request.
1143   * @param  baseDN                  The base DN of the subtree to migrate.
1144   * @param  sizeLimit               The maximum number of entries to migrate.
1145   * @param  sourceBackendSetName    The name of the backend set containing the
1146   *                                 subtree to migrate.
1147   * @param  sourceAddress           The address of the server from which the
1148   *                                 source entries will be read.
1149   * @param  sourcePort              The port of the server from which the
1150   *                                 source entries will be read.
1151   * @param  targetBackendSetName    The name of the backend set to which the
1152   *                                 subtree will be migrated.
1153   * @param  targetAddress           The address of the server to which the
1154   *                                 subtree will be migrated.
1155   * @param  targetPort              The port of the server to which the subtree
1156   *                                 will be migrated.
1157   */
1158  public void logEntryRebalancingRequest(final long rebalancingOperationID,
1159                   final OperationContext triggerOperation, final String baseDN,
1160                   final int sizeLimit, final String sourceBackendSetName,
1161                   final String sourceAddress, final int sourcePort,
1162                   final String targetBackendSetName,
1163                   final String targetAddress, final int targetPort)
1164  {
1165    // No action performed by default.
1166  }
1167
1168
1169
1170  /**
1171   * Writes a message to the access logger to indicate that the Directory Proxy
1172   * Server will attempt to perform entry rebalancing by migrating a subtree
1173   * from one backend set to another.
1174   *
1175   * @param  rebalancingOperationID  The unique ID assigned to the entry
1176   *                                 balancing operation.
1177   * @param  triggerOperation        The operation that triggered the entry
1178   *                                 rebalancing.  It may be {@code null} if the
1179   *                                 rebalancing operation wasn't triggered by a
1180   *                                 client request.
1181   * @param  baseDN                  The base DN of the subtree to migrate.
1182   * @param  sizeLimit               The maximum number of entries to migrate.
1183   * @param  sourceBackendSetName    The name of the backend set containing the
1184   *                                 subtree to migrate.
1185   * @param  sourceAddress           The address of the server from which the
1186   *                                 source entries will be read.
1187   * @param  sourcePort              The port of the server from which the
1188   *                                 source entries will be read.
1189   * @param  targetBackendSetName    The name of the backend set to which the
1190   *                                 subtree will be migrated.
1191   * @param  targetAddress           The address of the server to which the
1192   *                                 subtree will be migrated.
1193   * @param  targetPort              The port of the server to which the subtree
1194   *                                 will be migrated.
1195   * @param  moveSubtreeResult       An object with information about the result
1196   *                                 of the subtree move processing.
1197   */
1198  public void logEntryRebalancingResult(final long rebalancingOperationID,
1199                   final OperationContext triggerOperation, final String baseDN,
1200                   final int sizeLimit, final String sourceBackendSetName,
1201                   final String sourceAddress, final int sourcePort,
1202                   final String targetBackendSetName,
1203                   final String targetAddress, final int targetPort,
1204                   final MoveSubtreeResult moveSubtreeResult)
1205  {
1206    // No action performed by default.
1207  }
1208}