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