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