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