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