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