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 2011-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.FileBasedAccessLoggerConfig;
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 may be used to create a specific type of
089 * access logger which is intended to write log messages to text files.  This is
090 * a convenience for developers which wish to create custom access loggers that
091 * write to text files and provides support for a wide range of functionality
092 * including high-performance and highly-concurrent logging.  All of the options
093 * available to {@link AccessLogger} implementations are available for
094 * file-based access loggers, as well as options for indicating the log file
095 * path, the rotation and retention policies, whether to buffer the output, etc.
096 * <BR><BR>
097 * Note that file-based access loggers will automatically be registered within
098 * the server as disk space consumers, so there is no need to implement the
099 * {@link DiskSpaceConsumer} interface.  Also note that configuration change
100 * related to the log file (e.g., the log file path, buffer size, queue size,
101 * etc.) will also automatically be handled by the server, so subclasses only
102 * need to be concerned about changes to the custom arguments they define.
103 * <BR>
104 * <H2>Configuring File-Based Access Loggers</H2>
105 * In order to configure a file-based access logger created using this API, use
106 * a command like:
107 * <PRE>
108 *      dsconfig create-log-publisher \
109 *           --publisher-name "<I>{logger-name}</I>" \
110 *           --type third-party-file-based-access \
111 *           --set enabled:true \
112 *           --set "log-file:<I>{path}</I>" \
113 *           --set "rotation-policy:<I>{rotation-policy-name}</I>" \
114 *           --set "retention-policy:<I>{retention-policy-name}</I>" \
115 *           --set "extension-class:<I>{class-name}</I>" \
116 *           --set "extension-argument:<I>{name=value}</I>"
117 * </PRE>
118 * where "<I>{logger-name}</I>" is the name to use for the access logger
119 * instance, "<I>{path}</I>" is the path to the log file to be written,
120 * "<I>{rotation-policy-name}</I>" is the name of the log rotation policy to use
121 * for the log file, "<I>{retention-policy-name}</I>" is the name of the log
122 * retention policy to use for the log file, "<I>{class-name}</I>" is the
123 * fully-qualified name of the Java class that extends
124 * {@code com.unboundid.directory.sdk.common.api.FileBasedAccessLogger}, and
125 * "<I>{name=value}</I>" represents name-value pairs for any arguments to
126 * provide to the logger.  If multiple arguments should be provided to the
127 * logger, then the "<CODE>--set extension-argument:<I>{name=value}</I></CODE>"
128 * option should be provided multiple times.  It is also possible to specify
129 * multiple log rotation and/or retention policies if desired.
130 *
131 * @see  AccessLogger
132 * @see  com.unboundid.directory.sdk.common.scripting.ScriptedAccessLogger
133 * @see
134 *    com.unboundid.directory.sdk.common.scripting.ScriptedFileBasedAccessLogger
135 */
136@Extensible()
137@DirectoryServerExtension()
138@DirectoryProxyServerExtension(appliesToLocalContent=true,
139     appliesToRemoteContent=true)
140@SynchronizationServerExtension(appliesToLocalContent=true,
141     appliesToSynchronizedContent=false)
142@MetricsEngineExtension()
143@BrokerExtension()
144@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
145public abstract class FileBasedAccessLogger
146       implements UnboundIDExtension,
147                  Reconfigurable<FileBasedAccessLoggerConfig>,
148                  ExampleUsageProvider
149{
150  /**
151   * Creates a new instance of this file-based access logger.  All file-based
152   * access logger implementations must include a default constructor, but any
153   * initialization should generally be done in the
154   * {@code initializeAccessLogger} method.
155   */
156  public FileBasedAccessLogger()
157  {
158    // No implementation is required.
159  }
160
161
162
163  /**
164   * {@inheritDoc}
165   */
166  public abstract String getExtensionName();
167
168
169
170  /**
171   * {@inheritDoc}
172   */
173  public abstract String[] getExtensionDescription();
174
175
176
177  /**
178   * {@inheritDoc}
179   */
180  public void defineConfigArguments(final ArgumentParser parser)
181         throws ArgumentException
182  {
183    // No arguments will be allowed by default.
184  }
185
186
187
188  /**
189   * Initializes this file-based access logger.  Note that the work of
190   * initializing the log file writer will automatically be handled by the
191   * server, so the only initialization that needs to be performed is that
192   * required for custom arguments.
193   *
194   * @param  serverContext  A handle to the server context for the server in
195   *                        which this extension is running.
196   * @param  config         The general configuration for this file-based access
197   *                        logger.
198   * @param  parser         The argument parser which has been initialized from
199   *                        the configuration for this file-based access logger.
200   *
201   * @throws  LDAPException  If a problem occurs while initializing this
202   *                         file-based access logger.
203   */
204  public void initializeAccessLogger(final ServerContext serverContext,
205                                     final FileBasedAccessLoggerConfig config,
206                                     final ArgumentParser parser)
207         throws LDAPException
208  {
209    // No initialization will be performed by default.
210  }
211
212
213
214  /**
215   * {@inheritDoc}  Note that the server will automatically handle the work of
216   * validating any changes to properties related to the log file, so only
217   * changes to custom arguments need to be examined here.
218   */
219  public boolean isConfigurationAcceptable(
220                      final FileBasedAccessLoggerConfig config,
221                      final ArgumentParser parser,
222                      final List<String> unacceptableReasons)
223  {
224    // No extended validation will be performed by default.
225    return true;
226  }
227
228
229
230  /**
231   * {@inheritDoc}  Note that the server will automatically handle the work of
232   * applying any changes to properties related to the log file, so only changes
233   * to custom arguments need to be examined here.
234   */
235  public ResultCode applyConfiguration(final FileBasedAccessLoggerConfig config,
236                                       final ArgumentParser parser,
237                                       final List<String> adminActionsRequired,
238                                       final List<String> messages)
239  {
240    // If there are any custom arguments, then add an admin action message
241    // indicating that the extension needs to be restarted for any changes to
242    // take effect.
243    if (! parser.getNamedArguments().isEmpty())
244    {
245      adminActionsRequired.add(
246           "If any extension-argument values have been altered, then " +
247                "those new values have not actually been applied.  The new " +
248                "configuration for those arguments will not take effect " +
249                "until this file-based access logger is disabled and " +
250                "re-enabled, or until the server is restarted.");
251    }
252
253    return ResultCode.SUCCESS;
254  }
255
256
257
258  /**
259   * Performs any cleanup which may be necessary when this file-based access
260   * logger is to be taken out of service.  Any processing required for shutting
261   * down the log file writer will be automatically handled by the server.
262   */
263  public void finalizeAccessLogger()
264  {
265    // No implementation is required.
266  }
267
268
269
270  /**
271   * Logs a message indicating that a new connection has been established.
272   *
273   * @param  clientContext  Information about the client connection that has
274   *                        been accepted.
275   *
276   * @return  The content of the log message that should be written.  It may be
277   *          {@code null} or empty if no message should be written.  It may
278   *          optionally include line breaks if the log message should span
279   *          multiple lines.
280   */
281  public CharSequence logConnect(final ClientContext clientContext)
282  {
283    // No log message will be generated by default.
284    return null;
285  }
286
287
288
289  /**
290   * Logs a message indicating that a connection has been closed.
291   *
292   * @param  clientContext     Information about the client connection that has
293   *                           been closed.
294   * @param  disconnectReason  A general reason that the connection has been
295   *                           closed.
296   * @param  message           A message with additional information about the
297   *                           closure.  It may be {@code null} if none is
298   *                           available.
299   *
300   * @return  The content of the log message that should be written.  It may be
301   *          {@code null} or empty if no message should be written.  It may
302   *          optionally include line breaks if the log message should span
303   *          multiple lines.
304   */
305  public CharSequence logDisconnect(final ClientContext clientContext,
306                                    final DisconnectReason disconnectReason,
307                                    final String message)
308  {
309    // No log message will be generated by default.
310    return null;
311  }
312
313
314
315  /**
316   * Logs a message about security negotiation performed by a client.
317   *
318   * @param  clientContext  Information about the client connection on which
319   *                        the negotiation was completed.
320   * @param  protocol       The security protocol selected by the negotiation.
321   *                        It may be {@code null} if no protocol is available.
322   * @param  cipher         The cipher suite selected by the negotiation.  It
323   *                        may be {@code null} if no cipher is available.
324   * @param  properties     A set of additional properties that may be included
325   *                        in the log message.  It may be {@code null} or empty
326   *                        if no additional properties are needed.
327   *
328   * @return  The content of the log message that should be written.  It may be
329   *          {@code null} or empty if no message should be written.  It may
330   *          optionally include line breaks if the log message should span
331   *          multiple lines.
332   */
333  public CharSequence logSecurityNegotiation(final ClientContext clientContext,
334                           final String protocol, final String cipher,
335                           final Map<String,String> properties)
336  {
337    // No log message will be generated by default.
338    return null;
339  }
340
341
342
343  /**
344   * Logs a message about a certificate chain presented by a client.
345   *
346   * @param  clientContext  Information about the client that presented the
347   *                        certificate chain.
348   * @param  certChain      The certificate chain presented by the client.
349   * @param  authDN         The DN of the user as whom the client was
350   *                        automatically authenticated, or {@code null} if the
351   *                        client was not automatically authenticated.
352   *
353   * @return  The content of the log message that should be written.  It may be
354   *          {@code null} or empty if no message should be written.  It may
355   *          optionally include line breaks if the log message should span
356   *          multiple lines.
357   */
358  public CharSequence logClientCertificateChain(
359                           final ClientContext clientContext,
360                           final Certificate[] certChain, final String authDN)
361  {
362    // No log message will be generated by default.
363    return null;
364  }
365
366
367
368  /**
369   * Logs a message about an abandon request received from a client.
370   *
371   * @param  opContext  The operation context for the abandon operation.
372   * @param  request    The abandon request that was received.
373   *
374   * @return  The content of the log message that should be written.  It may be
375   *          {@code null} or empty if no message should be written.  It may
376   *          optionally include line breaks if the log message should span
377   *          multiple lines.
378   */
379  public CharSequence logAbandonRequest(final OperationContext opContext,
380                                        final AbandonRequest request)
381  {
382    // No log message will be generated by default.
383    return null;
384  }
385
386
387
388  /**
389   * Logs a message about an abandon request that will be forwarded to another
390   * server.
391   *
392   * @param  opContext  The operation context for the abandon operation.
393   * @param  request    The abandon request that was received.
394   * @param  target     Information about the server to which the request will
395   *                    be forwarded.
396   *
397   * @return  The content of the log message that should be written.  It may be
398   *          {@code null} or empty if no message should be written.  It may
399   *          optionally include line breaks if the log message should span
400   *          multiple lines.
401   */
402  public CharSequence logAbandonForward(final OperationContext opContext,
403                                        final AbandonRequest request,
404                                        final ForwardTarget target)
405  {
406    // No log message will be generated by default.
407    return null;
408  }
409
410
411
412  /**
413   * Logs a message about the result of processing an abandon request.
414   *
415   * @param  opContext  The operation context for the abandon operation.
416   * @param  request    The abandon request that was received.
417   * @param  result     The result of processing the abandon request.
418   *
419   * @return  The content of the log message that should be written.  It may be
420   *          {@code null} or empty if no message should be written.  It may
421   *          optionally include line breaks if the log message should span
422   *          multiple lines.
423   */
424  public CharSequence logAbandonResult(
425                           final CompletedOperationContext opContext,
426                           final AbandonRequest request,
427                           final GenericResult result)
428  {
429    // No log message will be generated by default.
430    return null;
431  }
432
433
434
435  /**
436   * Logs a message about an add request received from a client.
437   *
438   * @param  opContext  The operation context for the add operation.
439   * @param  request    The add request that was received.
440   *
441   * @return  The content of the log message that should be written.  It may be
442   *          {@code null} or empty if no message should be written.  It may
443   *          optionally include line breaks if the log message should span
444   *          multiple lines.
445   */
446  public CharSequence logAddRequest(final OperationContext opContext,
447                                    final AddRequest request)
448  {
449    // No log message will be generated by default.
450    return null;
451  }
452
453
454
455  /**
456   * Logs a message about an add request that will be forwarded to another
457   * server.
458   *
459   * @param  opContext  The operation context for the add operation.
460   * @param  request    The add request that was received.
461   * @param  target     Information about the server to which the request will
462   *                    be forwarded.
463   *
464   * @return  The content of the log message that should be written.  It may be
465   *          {@code null} or empty if no message should be written.  It may
466   *          optionally include line breaks if the log message should span
467   *          multiple lines.
468   */
469  public CharSequence logAddForward(final OperationContext opContext,
470                                    final AddRequest request,
471                                    final ForwardTarget target)
472  {
473    // No log message will be generated by default.
474    return null;
475  }
476
477
478
479  /**
480   * Logs a message about a failure encountered while attempting to forward an
481   * add request to another server.
482   *
483   * @param  opContext  The operation context for the add operation.
484   * @param  request    The add request that was received.
485   * @param  target     Information about the server to which the request was
486   *                    forwarded.
487   * @param  failure    The exception that was received when attempting to
488   *                    forward the request.
489   *
490   * @return  The content of the log message that should be written.  It may be
491   *          {@code null} or empty if no message should be written.  It may
492   *          optionally include line breaks if the log message should span
493   *          multiple lines.
494   */
495  public CharSequence logAddForwardFailure(final OperationContext opContext,
496                                           final AddRequest request,
497                                           final ForwardTarget target,
498                                           final LDAPException failure)
499  {
500    // No log message will be generated by default.
501    return null;
502  }
503
504
505
506  /**
507   * Logs a message about the result of processing an add request.
508   *
509   * @param  opContext  The operation context for the add operation.
510   * @param  request    The add request that was received.
511   * @param  result     The result of processing the add request.
512   *
513   * @return  The content of the log message that should be written.  It may be
514   *          {@code null} or empty if no message should be written.  It may
515   *          optionally include line breaks if the log message should span
516   *          multiple lines.
517   */
518  public CharSequence logAddResponse(final CompletedOperationContext opContext,
519                                     final AddRequest request,
520                                     final AddResult result)
521  {
522    // No log message will be generated by default.
523    return null;
524  }
525
526
527
528  /**
529   * Logs a message about the result of replication assurance processing for an
530   * add operation.
531   *
532   * @param  opContext        The operation context for the add operation.
533   * @param  request          The add request that was received.
534   * @param  result           The result of processing the add request.
535   * @param  assuranceResult  The replication assurance processing result.
536   *
537   * @return  The content of the log message that should be written.  It may be
538   *          {@code null} or empty if no message should be written.  It may
539   *          optionally include line breaks if the log message should span
540   *          multiple lines.
541   */
542  public CharSequence logAddAssuranceCompleted(
543                           final CompletedOperationContext opContext,
544                           final AddRequest request, final AddResult result,
545                           final AssuredReplicationResult assuranceResult)
546  {
547    // No log message will be generated by default.
548    return null;
549  }
550
551
552
553  /**
554   * Logs a message about a simple bind request received from a client.
555   *
556   * @param  opContext  The operation context for the bind operation.
557   * @param  request    The bind request that was received.
558   *
559   * @return  The content of the log message that should be written.  It may be
560   *          {@code null} or empty if no message should be written.  It may
561   *          optionally include line breaks if the log message should span
562   *          multiple lines.
563   */
564  public CharSequence logBindRequest(final OperationContext opContext,
565                                     final SimpleBindRequest request)
566  {
567    // No log message will be generated by default.
568    return null;
569  }
570
571
572
573  /**
574   * Logs a message about a simple bind request that will be forwarded to
575   * another server.
576   *
577   * @param  opContext  The operation context for the bind operation.
578   * @param  request    The bind request that was received.
579   * @param  target     Information about the server to which the request will
580   *                    be forwarded.
581   *
582   * @return  The content of the log message that should be written.  It may be
583   *          {@code null} or empty if no message should be written.  It may
584   *          optionally include line breaks if the log message should span
585   *          multiple lines.
586   */
587  public CharSequence logBindForward(final OperationContext opContext,
588                                     final SimpleBindRequest request,
589                                     final ForwardTarget target)
590  {
591    // No log message will be generated by default.
592    return null;
593  }
594
595
596
597  /**
598   * Logs a message about a failure encountered while attempting to forward a
599   * simple bind request to another server.
600   *
601   * @param  opContext  The operation context for the bind operation.
602   * @param  request    The bind request that was received.
603   * @param  target     Information about the server to which the request was
604   *                    forwarded.
605   * @param  failure    The exception that was received when attempting to
606   *                    forward the request.
607   *
608   * @return  The content of the log message that should be written.  It may be
609   *          {@code null} or empty if no message should be written.  It may
610   *          optionally include line breaks if the log message should span
611   *          multiple lines.
612   */
613  public CharSequence logBindForwardFailure(final OperationContext opContext,
614                                            final SimpleBindRequest request,
615                                            final ForwardTarget target,
616                                            final LDAPException failure)
617  {
618    // No log message will be generated by default.
619    return null;
620  }
621
622
623
624  /**
625   * Logs a message about the result of processing a simple bind request.
626   *
627   * @param  opContext  The operation context for the bind operation.
628   * @param  request    The bind request that was received.
629   * @param  result     The result of processing the bind request.
630   *
631   * @return  The content of the log message that should be written.  It may be
632   *          {@code null} or empty if no message should be written.  It may
633   *          optionally include line breaks if the log message should span
634   *          multiple lines.
635   */
636  public CharSequence logBindResponse(final CompletedOperationContext opContext,
637                                      final SimpleBindRequest request,
638                                      final BindResult result)
639  {
640    // No log message will be generated by default.
641    return null;
642  }
643
644
645
646  /**
647   * Logs a message about a SASL bind request received from a client.
648   *
649   * @param  opContext  The operation context for the bind operation.
650   * @param  request    The bind request that was received.
651   *
652   * @return  The content of the log message that should be written.  It may be
653   *          {@code null} or empty if no message should be written.  It may
654   *          optionally include line breaks if the log message should span
655   *          multiple lines.
656   */
657  public CharSequence logBindRequest(final OperationContext opContext,
658                                     final SASLBindRequest request)
659  {
660    // No log message will be generated by default.
661    return null;
662  }
663
664
665
666  /**
667   * Logs a message about a SASL bind request that will be forwarded to
668   * another server.
669   *
670   * @param  opContext  The operation context for the bind operation.
671   * @param  request    The bind request that was received.
672   * @param  target     Information about the server to which the request will
673   *                    be forwarded.
674   *
675   * @return  The content of the log message that should be written.  It may be
676   *          {@code null} or empty if no message should be written.  It may
677   *          optionally include line breaks if the log message should span
678   *          multiple lines.
679   */
680  public CharSequence logBindForward(final OperationContext opContext,
681                                     final SASLBindRequest request,
682                                     final ForwardTarget target)
683  {
684    // No log message will be generated by default.
685    return null;
686  }
687
688
689
690  /**
691   * Logs a message about a failure encountered while attempting to forward a
692   * SASL bind request to another server.
693   *
694   * @param  opContext  The operation context for the bind operation.
695   * @param  request    The bind request that was received.
696   * @param  target     Information about the server to which the request was
697   *                    forwarded.
698   * @param  failure    The exception that was received when attempting to
699   *                    forward the request.
700   *
701   * @return  The content of the log message that should be written.  It may be
702   *          {@code null} or empty if no message should be written.  It may
703   *          optionally include line breaks if the log message should span
704   *          multiple lines.
705   */
706  public CharSequence logBindForwardFailure(final OperationContext opContext,
707                                            final SASLBindRequest request,
708                                            final ForwardTarget target,
709                                            final LDAPException failure)
710  {
711    // No log message will be generated by default.
712    return null;
713  }
714
715
716
717  /**
718   * Logs a message about the result of processing a SASL bind request.
719   *
720   * @param  opContext  The operation context for the bind operation.
721   * @param  request    The bind request that was received.
722   * @param  result     The result of processing the bind request.
723   *
724   * @return  The content of the log message that should be written.  It may be
725   *          {@code null} or empty if no message should be written.  It may
726   *          optionally include line breaks if the log message should span
727   *          multiple lines.
728   */
729  public CharSequence logBindResponse(final CompletedOperationContext opContext,
730                                      final SASLBindRequest request,
731                                      final BindResult result)
732  {
733    // No log message will be generated by default.
734    return null;
735  }
736
737
738
739  /**
740   * Logs a message about a compare request received from a client.
741   *
742   * @param  opContext  The operation context for the compare operation.
743   * @param  request    The compare request that was received.
744   *
745   * @return  The content of the log message that should be written.  It may be
746   *          {@code null} or empty if no message should be written.  It may
747   *          optionally include line breaks if the log message should span
748   *          multiple lines.
749   */
750  public CharSequence logCompareRequest(final OperationContext opContext,
751                                        final CompareRequest request)
752  {
753    // No log message will be generated by default.
754    return null;
755  }
756
757
758
759  /**
760   * Logs a message about a compare request that will be forwarded to another
761   * server.
762   *
763   * @param  opContext  The operation context for the compare operation.
764   * @param  request    The compare request that was received.
765   * @param  target     Information about the server to which the request will
766   *                    be forwarded.
767   *
768   * @return  The content of the log message that should be written.  It may be
769   *          {@code null} or empty if no message should be written.  It may
770   *          optionally include line breaks if the log message should span
771   *          multiple lines.
772   */
773  public CharSequence logCompareForward(final OperationContext opContext,
774                                        final CompareRequest request,
775                                        final ForwardTarget target)
776  {
777    // No log message will be generated by default.
778    return null;
779  }
780
781
782
783  /**
784   * Logs a message about a failure encountered while attempting to forward a
785   * compare request to another server.
786   *
787   * @param  opContext  The operation context for the compare operation.
788   * @param  request    The compare request that was received.
789   * @param  target     Information about the server to which the request was
790   *                    forwarded.
791   * @param  failure    The exception that was received when attempting to
792   *                    forward the request.
793   *
794   * @return  The content of the log message that should be written.  It may be
795   *          {@code null} or empty if no message should be written.  It may
796   *          optionally include line breaks if the log message should span
797   *          multiple lines.
798   */
799  public CharSequence logCompareForwardFailure(final OperationContext opContext,
800                                               final CompareRequest request,
801                                               final ForwardTarget target,
802                                               final LDAPException failure)
803  {
804    // No log message will be generated by default.
805    return null;
806  }
807
808
809
810  /**
811   * Logs a message about the result of processing a compare request.
812   *
813   * @param  opContext  The operation context for the compare operation.
814   * @param  request    The compare request that was received.
815   * @param  result     The result of processing the compare request.
816   *
817   * @return  The content of the log message that should be written.  It may be
818   *          {@code null} or empty if no message should be written.  It may
819   *          optionally include line breaks if the log message should span
820   *          multiple lines.
821   */
822  public CharSequence logCompareResponse(
823                           final CompletedOperationContext opContext,
824                           final CompareRequest request,
825                           final CompareResult result)
826  {
827    // No log message will be generated by default.
828    return null;
829  }
830
831
832
833  /**
834   * Logs a message about a delete request received from a client.
835   *
836   * @param  opContext  The operation context for the delete operation.
837   * @param  request    The delete request that was received.
838   *
839   * @return  The content of the log message that should be written.  It may be
840   *          {@code null} or empty if no message should be written.  It may
841   *          optionally include line breaks if the log message should span
842   *          multiple lines.
843   */
844  public CharSequence logDeleteRequest(final OperationContext opContext,
845                                       final DeleteRequest request)
846  {
847    // No log message will be generated by default.
848    return null;
849  }
850
851
852
853  /**
854   * Logs a message about a delete request that will be forwarded to another
855   * server.
856   *
857   * @param  opContext  The operation context for the delete operation.
858   * @param  request    The delete request that was received.
859   * @param  target     Information about the server to which the request will
860   *                    be forwarded.
861   *
862   * @return  The content of the log message that should be written.  It may be
863   *          {@code null} or empty if no message should be written.  It may
864   *          optionally include line breaks if the log message should span
865   *          multiple lines.
866   */
867  public CharSequence logDeleteForward(final OperationContext opContext,
868                                       final DeleteRequest request,
869                                       final ForwardTarget target)
870  {
871    // No log message will be generated by default.
872    return null;
873  }
874
875
876
877  /**
878   * Logs a message about a failure encountered while attempting to forward a
879   * delete request to another server.
880   *
881   * @param  opContext  The operation context for the delete operation.
882   * @param  request    The delete request that was received.
883   * @param  target     Information about the server to which the request was
884   *                    forwarded.
885   * @param  failure    The exception that was received when attempting to
886   *                    forward the request.
887   *
888   * @return  The content of the log message that should be written.  It may be
889   *          {@code null} or empty if no message should be written.  It may
890   *          optionally include line breaks if the log message should span
891   *          multiple lines.
892   */
893  public CharSequence logDeleteForwardFailure(final OperationContext opContext,
894                                              final DeleteRequest request,
895                                              final ForwardTarget target,
896                                              final LDAPException failure)
897  {
898    // No log message will be generated by default.
899    return null;
900  }
901
902
903
904  /**
905   * Logs a message about the result of processing a delete request.
906   *
907   * @param  opContext  The operation context for the delete operation.
908   * @param  request    The delete request that was received.
909   * @param  result     The result of processing the delete request.
910   *
911   * @return  The content of the log message that should be written.  It may be
912   *          {@code null} or empty if no message should be written.  It may
913   *          optionally include line breaks if the log message should span
914   *          multiple lines.
915   */
916  public CharSequence logDeleteResponse(
917                           final CompletedOperationContext opContext,
918                           final DeleteRequest request,
919                           final DeleteResult result)
920  {
921    // No log message will be generated by default.
922    return null;
923  }
924
925
926
927  /**
928   * Logs a message about the result of replication assurance processing for a
929   * delete operation.
930   *
931   * @param  opContext        The operation context for the delete operation.
932   * @param  request          The delete request that was received.
933   * @param  result           The result of processing the delete request.
934   * @param  assuranceResult  The replication assurance processing result.
935   *
936   * @return  The content of the log message that should be written.  It may be
937   *          {@code null} or empty if no message should be written.  It may
938   *          optionally include line breaks if the log message should span
939   *          multiple lines.
940   */
941  public CharSequence logDeleteAssuranceCompleted(
942                           final CompletedOperationContext opContext,
943                           final DeleteRequest request,
944                           final DeleteResult result,
945                           final AssuredReplicationResult assuranceResult)
946  {
947    // No log message will be generated by default.
948    return null;
949  }
950
951
952
953  /**
954   * Logs a message about an extended request received from a client.
955   *
956   * @param  opContext  The operation context for the extended operation.
957   * @param  request    The extended request that was received.
958   *
959   * @return  The content of the log message that should be written.  It may be
960   *          {@code null} or empty if no message should be written.  It may
961   *          optionally include line breaks if the log message should span
962   *          multiple lines.
963   */
964  public CharSequence logExtendedRequest(final OperationContext opContext,
965                                         final ExtendedRequest request)
966  {
967    // No log message will be generated by default.
968    return null;
969  }
970
971
972
973  /**
974   * Logs a message about an extended request that will be forwarded to another
975   * server.
976   *
977   * @param  opContext  The operation context for the extended operation.
978   * @param  request    The extended request that was received.
979   * @param  target     Information about the server to which the request will
980   *                    be forwarded.
981   *
982   * @return  The content of the log message that should be written.  It may be
983   *          {@code null} or empty if no message should be written.  It may
984   *          optionally include line breaks if the log message should span
985   *          multiple lines.
986   */
987  public CharSequence logExtendedForward(final OperationContext opContext,
988                                         final ExtendedRequest request,
989                                         final ForwardTarget target)
990  {
991    // No log message will be generated by default.
992    return null;
993  }
994
995
996
997  /**
998   * Logs a message about a failure encountered while attempting to forward an
999   * extended request to another server.
1000   *
1001   * @param  opContext  The operation context for the extended operation.
1002   * @param  request    The extended request that was received.
1003   * @param  target     Information about the server to which the request was
1004   *                    forwarded.
1005   * @param  failure    The exception that was received when attempting to
1006   *                    forward the request.
1007   *
1008   * @return  The content of the log message that should be written.  It may be
1009   *          {@code null} or empty if no message should be written.  It may
1010   *          optionally include line breaks if the log message should span
1011   *          multiple lines.
1012   */
1013  public CharSequence logExtendedForwardFailure(
1014                           final OperationContext opContext,
1015                           final ExtendedRequest request,
1016                           final ForwardTarget target,
1017                           final LDAPException failure)
1018  {
1019    // No log message will be generated by default.
1020    return null;
1021  }
1022
1023
1024
1025  /**
1026   * Logs a message about the result of processing an extended request.
1027   *
1028   * @param  opContext  The operation context for the extended operation.
1029   * @param  request    The extended request that was received.
1030   * @param  result     The result of processing the extended request.
1031   *
1032   * @return  The content of the log message that should be written.  It may be
1033   *          {@code null} or empty if no message should be written.  It may
1034   *          optionally include line breaks if the log message should span
1035   *          multiple lines.
1036   */
1037  public CharSequence logExtendedResponse(
1038                           final CompletedOperationContext opContext,
1039                           final ExtendedRequest request,
1040                           final ExtendedResult result)
1041  {
1042    // No log message will be generated by default.
1043    return null;
1044  }
1045
1046
1047
1048  /**
1049   * Logs a message about a modify request received from a client.
1050   *
1051   * @param  opContext  The operation context for the modify operation.
1052   * @param  request    The modify request that was received.
1053   *
1054   * @return  The content of the log message that should be written.  It may be
1055   *          {@code null} or empty if no message should be written.  It may
1056   *          optionally include line breaks if the log message should span
1057   *          multiple lines.
1058   */
1059  public CharSequence logModifyRequest(final OperationContext opContext,
1060                                       final ModifyRequest request)
1061  {
1062    // No log message will be generated by default.
1063    return null;
1064  }
1065
1066
1067
1068  /**
1069   * Logs a message about a modify request that will be forwarded to another
1070   * server.
1071   *
1072   * @param  opContext  The operation context for the modify operation.
1073   * @param  request    The modify request that was received.
1074   * @param  target     Information about the server to which the request will
1075   *                    be forwarded.
1076   *
1077   * @return  The content of the log message that should be written.  It may be
1078   *          {@code null} or empty if no message should be written.  It may
1079   *          optionally include line breaks if the log message should span
1080   *          multiple lines.
1081   */
1082  public CharSequence logModifyForward(final OperationContext opContext,
1083                                       final ModifyRequest request,
1084                                       final ForwardTarget target)
1085  {
1086    // No log message will be generated by default.
1087    return null;
1088  }
1089
1090
1091
1092  /**
1093   * Logs a message about a failure encountered while attempting to forward a
1094   * modify request to another server.
1095   *
1096   * @param  opContext  The operation context for the modify operation.
1097   * @param  request    The modify request that was received.
1098   * @param  target     Information about the server to which the request was
1099   *                    forwarded.
1100   * @param  failure    The exception that was received when attempting to
1101   *                    forward the request.
1102   *
1103   * @return  The content of the log message that should be written.  It may be
1104   *          {@code null} or empty if no message should be written.  It may
1105   *          optionally include line breaks if the log message should span
1106   *          multiple lines.
1107   */
1108  public CharSequence logModifyForwardFailure(final OperationContext opContext,
1109                                              final ModifyRequest request,
1110                                              final ForwardTarget target,
1111                                              final LDAPException failure)
1112  {
1113    // No log message will be generated by default.
1114    return null;
1115  }
1116
1117
1118
1119  /**
1120   * Logs a message about the result of processing a modify request.
1121   *
1122   * @param  opContext  The operation context for the modify operation.
1123   * @param  request    The modify request that was received.
1124   * @param  result     The result of processing the modify request.
1125   *
1126   * @return  The content of the log message that should be written.  It may be
1127   *          {@code null} or empty if no message should be written.  It may
1128   *          optionally include line breaks if the log message should span
1129   *          multiple lines.
1130   */
1131  public CharSequence logModifyResponse(
1132                           final CompletedOperationContext opContext,
1133                           final ModifyRequest request,
1134                           final ModifyResult result)
1135  {
1136    // No log message will be generated by default.
1137    return null;
1138  }
1139
1140
1141
1142  /**
1143   * Logs a message about the result of replication assurance processing for a
1144   * modify operation.
1145   *
1146   * @param  opContext        The operation context for the modify operation.
1147   * @param  request          The modify request that was received.
1148   * @param  result           The result of processing the modify request.
1149   * @param  assuranceResult  The replication assurance processing result.
1150   *
1151   * @return  The content of the log message that should be written.  It may be
1152   *          {@code null} or empty if no message should be written.  It may
1153   *          optionally include line breaks if the log message should span
1154   *          multiple lines.
1155   */
1156  public CharSequence logModifyAssuranceCompleted(
1157                           final CompletedOperationContext opContext,
1158                           final ModifyRequest request,
1159                           final ModifyResult result,
1160                           final AssuredReplicationResult assuranceResult)
1161  {
1162    // No log message will be generated by default.
1163    return null;
1164  }
1165
1166
1167
1168  /**
1169   * Logs a message about a modify DN request received from a client.
1170   *
1171   * @param  opContext  The operation context for the modify DN operation.
1172   * @param  request    The modify DN request that was received.
1173   *
1174   * @return  The content of the log message that should be written.  It may be
1175   *          {@code null} or empty if no message should be written.  It may
1176   *          optionally include line breaks if the log message should span
1177   *          multiple lines.
1178   */
1179  public CharSequence logModifyDNRequest(final OperationContext opContext,
1180                                         final ModifyDNRequest request)
1181  {
1182    // No log message will be generated by default.
1183    return null;
1184  }
1185
1186
1187
1188  /**
1189   * Logs a message about a modify DN request that will be forwarded to another
1190   * server.
1191   *
1192   * @param  opContext  The operation context for the modify DN operation.
1193   * @param  request    The modify DN request that was received.
1194   * @param  target     Information about the server to which the request will
1195   *                    be forwarded.
1196   *
1197   * @return  The content of the log message that should be written.  It may be
1198   *          {@code null} or empty if no message should be written.  It may
1199   *          optionally include line breaks if the log message should span
1200   *          multiple lines.
1201   */
1202  public CharSequence logModifyDNForward(final OperationContext opContext,
1203                                         final ModifyDNRequest request,
1204                                         final ForwardTarget target)
1205  {
1206    // No log message will be generated by default.
1207    return null;
1208  }
1209
1210
1211
1212  /**
1213   * Logs a message about a failure encountered while attempting to forward a
1214   * modify DN request to another server.
1215   *
1216   * @param  opContext  The operation context for the modify DN operation.
1217   * @param  request    The modify DN request that was received.
1218   * @param  target     Information about the server to which the request was
1219   *                    forwarded.
1220   * @param  failure    The exception that was received when attempting to
1221   *                    forward the request.
1222   *
1223   * @return  The content of the log message that should be written.  It may be
1224   *          {@code null} or empty if no message should be written.  It may
1225   *          optionally include line breaks if the log message should span
1226   *          multiple lines.
1227   */
1228  public CharSequence logModifyDNForwardFailure(
1229                           final OperationContext opContext,
1230                           final ModifyDNRequest request,
1231                           final ForwardTarget target,
1232                           final LDAPException failure)
1233  {
1234    // No log message will be generated by default.
1235    return null;
1236  }
1237
1238
1239
1240  /**
1241   * Logs a message about the result of processing a modify DN request.
1242   *
1243   * @param  opContext  The operation context for the modify DN operation.
1244   * @param  request    The modify DN request that was received.
1245   * @param  result     The result of processing the modify DN request.
1246   *
1247   * @return  The content of the log message that should be written.  It may be
1248   *          {@code null} or empty if no message should be written.  It may
1249   *          optionally include line breaks if the log message should span
1250   *          multiple lines.
1251   */
1252  public CharSequence logModifyDNResponse(
1253                           final CompletedOperationContext opContext,
1254                           final ModifyDNRequest request,
1255                           final ModifyDNResult result)
1256  {
1257    // No log message will be generated by default.
1258    return null;
1259  }
1260
1261
1262
1263  /**
1264   * Logs a message about the result of replication assurance processing for a
1265   * modify DN operation.
1266   *
1267   * @param  opContext        The operation context for the modify DN operation.
1268   * @param  request          The modify DN request that was received.
1269   * @param  result           The result of processing the modify DN request.
1270   * @param  assuranceResult  The replication assurance processing result.
1271   *
1272   * @return  The content of the log message that should be written.  It may be
1273   *          {@code null} or empty if no message should be written.  It may
1274   *          optionally include line breaks if the log message should span
1275   *          multiple lines.
1276   */
1277  public CharSequence logModifyDNAssuranceCompleted(
1278                           final CompletedOperationContext opContext,
1279                           final ModifyDNRequest request,
1280                           final ModifyDNResult result,
1281                           final AssuredReplicationResult assuranceResult)
1282  {
1283    // No log message will be generated by default.
1284    return null;
1285  }
1286
1287
1288
1289  /**
1290   * Logs a message about a search request received from a client.
1291   *
1292   * @param  opContext  The operation context for the search operation.
1293   * @param  request    The search request that was received.
1294   *
1295   * @return  The content of the log message that should be written.  It may be
1296   *          {@code null} or empty if no message should be written.  It may
1297   *          optionally include line breaks if the log message should span
1298   *          multiple lines.
1299   */
1300  public CharSequence logSearchRequest(final OperationContext opContext,
1301                                       final SearchRequest request)
1302  {
1303    // No log message will be generated by default.
1304    return null;
1305  }
1306
1307
1308
1309  /**
1310   * Logs a message about a search request that will be forwarded to another
1311   * server.
1312   *
1313   * @param  opContext  The operation context for the search operation.
1314   * @param  request    The search request that was received.
1315   * @param  target     Information about the server to which the request will
1316   *                    be forwarded.
1317   *
1318   * @return  The content of the log message that should be written.  It may be
1319   *          {@code null} or empty if no message should be written.  It may
1320   *          optionally include line breaks if the log message should span
1321   *          multiple lines.
1322   */
1323  public CharSequence logSearchForward(final OperationContext opContext,
1324                                       final SearchRequest request,
1325                                       final ForwardTarget target)
1326  {
1327    // No log message will be generated by default.
1328    return null;
1329  }
1330
1331
1332
1333  /**
1334   * Logs a message about a failure encountered while attempting to forward a
1335   * search request to another server.
1336   *
1337   * @param  opContext  The operation context for the search operation.
1338   * @param  request    The search request that was received.
1339   * @param  target     Information about the server to which the request was
1340   *                    forwarded.
1341   * @param  failure    The exception that was received when attempting to
1342   *                    forward the request.
1343   *
1344   * @return  The content of the log message that should be written.  It may be
1345   *          {@code null} or empty if no message should be written.  It may
1346   *          optionally include line breaks if the log message should span
1347   *          multiple lines.
1348   */
1349  public CharSequence logSearchForwardFailure(final OperationContext opContext,
1350                                              final SearchRequest request,
1351                                              final ForwardTarget target,
1352                                              final LDAPException failure)
1353  {
1354    // No log message will be generated by default.
1355    return null;
1356  }
1357
1358
1359
1360  /**
1361   * Logs a message about a search result entry that was returned to the client.
1362   *
1363   * @param  opContext  The operation context for the search operation.
1364   * @param  request    The search request that was received.
1365   * @param  entry      The entry that was returned.
1366   * @param  controls   The set of controls included with the entry, or an empty
1367   *                    list if there were none.
1368   *
1369   * @return  The content of the log message that should be written.  It may be
1370   *          {@code null} or empty if no message should be written.  It may
1371   *          optionally include line breaks if the log message should span
1372   *          multiple lines.
1373   */
1374  public CharSequence logSearchResultEntry(final OperationContext opContext,
1375                                           final SearchRequest request,
1376                                           final Entry entry,
1377                                           final List<Control> controls)
1378  {
1379    // No log message will be generated by default.
1380    return null;
1381  }
1382
1383
1384
1385  /**
1386   * Logs a message about a search result reference that was returned to the
1387   * client.
1388   *
1389   * @param  opContext     The operation context for the search operation.
1390   * @param  request       The search request that was received.
1391   * @param  referralURLs  The referral URLs for the reference that was
1392   *                       returned.
1393   * @param  controls      The set of controls included with the reference, or
1394   *                       an empty list if there were none.
1395   *
1396   * @return  The content of the log message that should be written.  It may be
1397   *          {@code null} or empty if no message should be written.  It may
1398   *          optionally include line breaks if the log message should span
1399   *          multiple lines.
1400   */
1401  public CharSequence logSearchResultReference(final OperationContext opContext,
1402                                               final SearchRequest request,
1403                                               final List<String> referralURLs,
1404                                               final List<Control> controls)
1405  {
1406    // No log message will be generated by default.
1407    return null;
1408  }
1409
1410
1411
1412  /**
1413   * Logs a message about the result of processing a search request.
1414   *
1415   * @param  opContext  The operation context for the search operation.
1416   * @param  request    The search request that was received.
1417   * @param  result     The result of processing the search request.
1418   *
1419   * @return  The content of the log message that should be written.  It may be
1420   *          {@code null} or empty if no message should be written.  It may
1421   *          optionally include line breaks if the log message should span
1422   *          multiple lines.
1423   */
1424  public CharSequence logSearchResultDone(
1425                           final CompletedSearchOperationContext opContext,
1426                           final SearchRequest request,
1427                           final SearchResult result)
1428  {
1429    // No log message will be generated by default.
1430    return null;
1431  }
1432
1433
1434
1435  /**
1436   * Logs a message about an unbind request received from a client.
1437   *
1438   * @param  opContext  The operation context for the unbind operation.
1439   * @param  request    The unbind request that was received.
1440   *
1441   * @return  The content of the log message that should be written.  It may be
1442   *          {@code null} or empty if no message should be written.  It may
1443   *          optionally include line breaks if the log message should span
1444   *          multiple lines.
1445   */
1446  public CharSequence logUnbindRequest(final OperationContext opContext,
1447                                       final UnbindRequest request)
1448  {
1449    // No log message will be generated by default.
1450    return null;
1451  }
1452
1453
1454
1455  /**
1456   * Logs a message about an intermediate response that was returned to the
1457   * client.
1458   *
1459   * @param  opContext             The operation context for the associated
1460   *                               operation.
1461   * @param  intermediateResponse  The intermediate response that was returned.
1462   *
1463   * @return  The content of the log message that should be written.  It may be
1464   *          {@code null} or empty if no message should be written.  It may
1465   *          optionally include line breaks if the log message should span
1466   *          multiple lines.
1467   */
1468  public CharSequence logIntermediateResponse(final OperationContext opContext,
1469                           final IntermediateResponse intermediateResponse)
1470  {
1471    // No log message will be generated by default.
1472    return null;
1473  }
1474
1475
1476
1477  /**
1478   * Writes a message to the access logger to indicate that the Directory Proxy
1479   * Server will attempt to perform entry rebalancing by migrating a subtree
1480   * from one backend set to another.
1481   *
1482   * @param  rebalancingOperationID  The unique ID assigned to the entry
1483   *                                 balancing operation.
1484   * @param  triggerOperation        The operation that triggered the entry
1485   *                                 rebalancing.  It may be {@code null} if the
1486   *                                 rebalancing operation wasn't triggered by a
1487   *                                 client request.
1488   * @param  baseDN                  The base DN of the subtree to migrate.
1489   * @param  sizeLimit               The maximum number of entries to migrate.
1490   * @param  sourceBackendSetName    The name of the backend set containing the
1491   *                                 subtree to migrate.
1492   * @param  sourceAddress           The address of the server from which the
1493   *                                 source entries will be read.
1494   * @param  sourcePort              The port of the server from which the
1495   *                                 source entries will be read.
1496   * @param  targetBackendSetName    The name of the backend set to which the
1497   *                                 subtree will be migrated.
1498   * @param  targetAddress           The address of the server to which the
1499   *                                 subtree will be migrated.
1500   * @param  targetPort              The port of the server to which the subtree
1501   *                                 will be migrated.
1502   *
1503   * @return  The content of the log message that should be written.  It may be
1504   *          {@code null} or empty if no message should be written.  It may
1505   *          optionally include line breaks if the log message should span
1506   *          multiple lines.
1507   */
1508  public CharSequence logEntryRebalancingRequest(
1509                           final long rebalancingOperationID,
1510                           final OperationContext triggerOperation,
1511                           final String baseDN, final int sizeLimit,
1512                           final String sourceBackendSetName,
1513                           final String sourceAddress, final int sourcePort,
1514                           final String targetBackendSetName,
1515                           final String targetAddress, final int targetPort)
1516  {
1517    // No log message will be generated by default.
1518    return null;
1519  }
1520
1521
1522
1523  /**
1524   * Writes a message to the access logger to indicate that the Directory Proxy
1525   * Server will attempt to perform entry rebalancing by migrating a subtree
1526   * from one backend set to another.
1527   *
1528   * @param  rebalancingOperationID  The unique ID assigned to the entry
1529   *                                 balancing operation.
1530   * @param  triggerOperation        The operation that triggered the entry
1531   *                                 rebalancing.  It may be {@code null} if the
1532   *                                 rebalancing operation wasn't triggered by a
1533   *                                 client request.
1534   * @param  baseDN                  The base DN of the subtree to migrate.
1535   * @param  sizeLimit               The maximum number of entries to migrate.
1536   * @param  sourceBackendSetName    The name of the backend set containing the
1537   *                                 subtree to migrate.
1538   * @param  sourceAddress           The address of the server from which the
1539   *                                 source entries will be read.
1540   * @param  sourcePort              The port of the server from which the
1541   *                                 source entries will be read.
1542   * @param  targetBackendSetName    The name of the backend set to which the
1543   *                                 subtree will be migrated.
1544   * @param  targetAddress           The address of the server to which the
1545   *                                 subtree will be migrated.
1546   * @param  targetPort              The port of the server to which the subtree
1547   *                                 will be migrated.
1548   * @param  moveSubtreeResult       An object with information about the result
1549   *                                 of the subtree move processing.
1550   *
1551   * @return  The content of the log message that should be written.  It may be
1552   *          {@code null} or empty if no message should be written.  It may
1553   *          optionally include line breaks if the log message should span
1554   *          multiple lines.
1555   */
1556  public CharSequence logEntryRebalancingResult(
1557                           final long rebalancingOperationID,
1558                           final OperationContext triggerOperation,
1559                           final String baseDN, final int sizeLimit,
1560                           final String sourceBackendSetName,
1561                           final String sourceAddress, final int sourcePort,
1562                           final String targetBackendSetName,
1563                           final String targetAddress, final int targetPort,
1564                           final MoveSubtreeResult moveSubtreeResult)
1565  {
1566    // No log message will be generated by default.
1567    return null;
1568  }
1569
1570
1571
1572  /**
1573   * {@inheritDoc}
1574   */
1575  public Map<List<String>,String> getExamplesArgumentSets()
1576  {
1577    return Collections.emptyMap();
1578  }
1579}