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