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