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