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