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.AccessLoggerConfig;
036 import com.unboundid.directory.sdk.common.internal.Reconfigurable;
037 import com.unboundid.directory.sdk.common.operation.AbandonRequest;
038 import com.unboundid.directory.sdk.common.operation.AddRequest;
039 import com.unboundid.directory.sdk.common.operation.AddResult;
040 import com.unboundid.directory.sdk.common.operation.BindResult;
041 import com.unboundid.directory.sdk.common.operation.CompareRequest;
042 import com.unboundid.directory.sdk.common.operation.CompareResult;
043 import com.unboundid.directory.sdk.common.operation.DeleteRequest;
044 import com.unboundid.directory.sdk.common.operation.DeleteResult;
045 import com.unboundid.directory.sdk.common.operation.ExtendedRequest;
046 import com.unboundid.directory.sdk.common.operation.ExtendedResult;
047 import com.unboundid.directory.sdk.common.operation.GenericResult;
048 import com.unboundid.directory.sdk.common.operation.ModifyRequest;
049 import com.unboundid.directory.sdk.common.operation.ModifyResult;
050 import com.unboundid.directory.sdk.common.operation.ModifyDNRequest;
051 import com.unboundid.directory.sdk.common.operation.ModifyDNResult;
052 import com.unboundid.directory.sdk.common.operation.SASLBindRequest;
053 import com.unboundid.directory.sdk.common.operation.SearchRequest;
054 import com.unboundid.directory.sdk.common.operation.SearchResult;
055 import com.unboundid.directory.sdk.common.operation.SimpleBindRequest;
056 import com.unboundid.directory.sdk.common.operation.UnbindRequest;
057 import com.unboundid.directory.sdk.common.types.ClientContext;
058 import com.unboundid.directory.sdk.common.types.CompletedOperationContext;
059 import com.unboundid.directory.sdk.common.types.CompletedSearchOperationContext;
060 import com.unboundid.directory.sdk.common.types.DisconnectReason;
061 import com.unboundid.directory.sdk.common.types.Entry;
062 import com.unboundid.directory.sdk.common.types.ForwardTarget;
063 import com.unboundid.directory.sdk.common.types.OperationContext;
064 import com.unboundid.directory.sdk.common.types.ServerContext;
065 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
066 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
067 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
068 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
069 import com.unboundid.ldap.sdk.Control;
070 import com.unboundid.ldap.sdk.IntermediateResponse;
071 import com.unboundid.ldap.sdk.LDAPException;
072 import com.unboundid.ldap.sdk.ResultCode;
073 import com.unboundid.ldap.sdk.unboundidds.MoveSubtreeResult;
074 import com.unboundid.util.Extensible;
075 import com.unboundid.util.ThreadSafety;
076 import com.unboundid.util.ThreadSafetyLevel;
077 import com.unboundid.util.args.ArgumentException;
078 import com.unboundid.util.args.ArgumentParser;
079
080
081
082 /**
083 * This class defines an API that must be implemented by scripted extensions
084 * which record information about interaction with clients, including
085 * connections established and received and operations requested and completed.
086 * <BR><BR>
087 * Access loggers will be invoked for the following events:
088 * <UL>
089 * <LI>Whenever a new connection is established.</LI>
090 * <LI>Whenever an existing connection is closed or terminated.</LI>
091 * <LI>Whenever an abandon, add, bind, compare, delete, extended, modify,
092 * modify DN, search, or unbind request is received.</LI>
093 * <LI>Whenever an abandon, add, bind, compare, delete, extended, modify,
094 * modify DN, or search request is forwarded to another server for
095 * processing.</LI>
096 * <LI>If a forwarded add, bind, compare, delete, extended, modify, modify DN,
097 * or search operation fails.</LI>
098 * <LI>After sending the result for an add, bind, compare, delete, extended,
099 * modify, modify DN, or search operation.</LI>
100 * <LI>After completing processing for an abandon operation.</LI>
101 * <LI>After sending a search result entry, search result reference, or
102 * intermediate response message to the client.</LI>
103 * </UL>
104 * <BR><BR>
105 * Each access logger may configured to indicate whether to include or exclude
106 * internal and/or replicated operations, and criteria may be used to provide
107 * filtered logging. This is handled automatically by the server, so individual
108 * access logger implementations do not need to attempt to perform that
109 * filtering on their own. However, they may perform additional processing if
110 * desired to further narrow the set of messages that should be logged.
111 * <BR>
112 * <H2>Configuring Groovy-Scripted Access Loggers</H2>
113 * In order to configure a scripted access logger based on this API and written
114 * in the Groovy scripting language, use a command
115 * like:
116 * <PRE>
117 * dsconfig create-log-publisher \
118 * --publisher-name "<I>{logger-name}</I>" \
119 * --type groovy-scripted-access \
120 * --set enabled:true \
121 * --set "script-class:<I>{class-name}</I>" \
122 * --set "script-argument:<I>{name=value}</I>"
123 * </PRE>
124 * where "<I>{logger-name}</I>" is the name to use for the access logger
125 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Groovy
126 * class written using this API, and "<I>{name=value}</I>" represents name-value
127 * pairs for any arguments to provide to the logger. If multiple arguments
128 * should be provided to the logger, then the
129 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be
130 * provided multiple times.
131 *
132 * @see com.unboundid.directory.sdk.common.api.AccessLogger
133 * @see com.unboundid.directory.sdk.common.api.FileBasedAccessLogger
134 * @see ScriptedFileBasedAccessLogger
135 */
136 @Extensible()
137 @DirectoryServerExtension()
138 @DirectoryProxyServerExtension(appliesToLocalContent=true,
139 appliesToRemoteContent=false)
140 @SynchronizationServerExtension(appliesToLocalContent=true,
141 appliesToSynchronizedContent=false)
142 @MetricsEngineExtension()
143 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
144 public abstract class ScriptedAccessLogger
145 implements Reconfigurable<AccessLoggerConfig>
146 {
147 /**
148 * Creates a new instance of this access logger. All access logger
149 * implementations must include a default constructor, but any initialization
150 * should generally be done in the {@code initializeAccessLogger} method.
151 */
152 public ScriptedAccessLogger()
153 {
154 // No implementation is required.
155 }
156
157
158
159 /**
160 * {@inheritDoc}
161 */
162 public void defineConfigArguments(final ArgumentParser parser)
163 throws ArgumentException
164 {
165 // No arguments will be allowed by default.
166 }
167
168
169
170 /**
171 * Initializes this access logger.
172 *
173 * @param serverContext A handle to the server context for the server in
174 * which this extension is running.
175 * @param config The general configuration for this access logger.
176 * @param parser The argument parser which has been initialized from
177 * the configuration for this access logger.
178 *
179 * @throws LDAPException If a problem occurs while initializing this
180 * access logger.
181 */
182 public void initializeAccessLogger(final ServerContext serverContext,
183 final AccessLoggerConfig config,
184 final ArgumentParser parser)
185 throws LDAPException
186 {
187 // No initialization will be performed by default.
188 }
189
190
191
192 /**
193 * Performs any cleanup which may be necessary when this access logger is to
194 * be taken out of service.
195 */
196 public void finalizeAccessLogger()
197 {
198 // No implementation is required.
199 }
200
201
202
203 /**
204 * {@inheritDoc}
205 */
206 public boolean isConfigurationAcceptable(final AccessLoggerConfig config,
207 final ArgumentParser parser,
208 final List<String> unacceptableReasons)
209 {
210 // No extended validation will be performed.
211 return true;
212 }
213
214
215
216 /**
217 * {@inheritDoc}
218 */
219 public ResultCode applyConfiguration(final AccessLoggerConfig config,
220 final ArgumentParser parser,
221 final List<String> adminActionsRequired,
222 final List<String> messages)
223 {
224 // By default, no configuration changes will be applied. If there are any
225 // arguments, then add an admin action message indicating that the extension
226 // needs to be restarted for any changes to take effect.
227 if (! parser.getNamedArguments().isEmpty())
228 {
229 adminActionsRequired.add(
230 "No configuration change has actually been applied. The new " +
231 "configuration will not take effect until this access logger " +
232 "is disabled and re-enabled or until the server is restarted.");
233 }
234
235 return ResultCode.SUCCESS;
236 }
237
238
239
240 /**
241 * Logs a message indicating that a new connection has been established.
242 *
243 * @param clientContext Information about the client connection that has
244 * been accepted.
245 */
246 public void logConnect(final ClientContext clientContext)
247 {
248 // No action will be taken by default.
249 }
250
251
252
253 /**
254 * Logs a message indicating that a connection has been closed.
255 *
256 * @param clientContext Information about the client connection that has
257 * been closed.
258 * @param disconnectReason A general reason that the connection has been
259 * closed.
260 * @param message A message with additional information about the
261 * closure. It may be {@code null} if none is
262 * available.
263 */
264 public void logDisconnect(final ClientContext clientContext,
265 final DisconnectReason disconnectReason,
266 final String message)
267 {
268 // No action will be taken by default.
269 }
270
271
272
273 /**
274 * Logs a message about security negotiation performed by a client.
275 *
276 * @param clientContext Information about the client connection on which
277 * the negotiation was completed.
278 * @param protocol The security protocol selected by the negotiation.
279 * It may be {@code null} if no protocol is available.
280 * @param cipher The cipher suite selected by the negotiation. It
281 * may be {@code null} if no cipher is available.
282 * @param properties A set of additional properties that may be included
283 * in the log message. It may be {@code null} or empty
284 * if no additional properties are needed.
285 */
286 public void logSecurityNegotiation(final ClientContext clientContext,
287 final String protocol, final String cipher,
288 final Map<String,String> properties)
289 {
290 // No action will be taken by default.
291 }
292
293
294
295 /**
296 * Logs a message about a certificate chain presented by a client.
297 *
298 * @param clientContext Information about the client that presented the
299 * certificate chain.
300 * @param certChain The certificate chain presented by the client.
301 * @param authDN The DN of the user as whom the client was
302 * automatically authenticated, or {@code null} if the
303 * client was not automatically authenticated.
304 */
305 public void logClientCertificateChain(final ClientContext clientContext,
306 final Certificate[] certChain,
307 final String authDN)
308 {
309 // No action will be taken by default.
310 }
311
312
313
314 /**
315 * Logs a message about an abandon request received from a client.
316 *
317 * @param opContext The operation context for the abandon operation.
318 * @param request The abandon request that was received.
319 */
320 public void logAbandonRequest(final OperationContext opContext,
321 final AbandonRequest request)
322 {
323 // No action will be taken by default.
324 }
325
326
327
328 /**
329 * Logs a message about an abandon request that will be forwarded to another
330 * server.
331 *
332 * @param opContext The operation context for the abandon operation.
333 * @param request The abandon request that was received.
334 * @param target Information about the server to which the request will
335 * be forwarded.
336 */
337 public void logAbandonForward(final OperationContext opContext,
338 final AbandonRequest request,
339 final ForwardTarget target)
340 {
341 // No action will be taken by default.
342 }
343
344
345
346 /**
347 * Logs a message about the result of processing an abandon request.
348 *
349 * @param opContext The operation context for the abandon operation.
350 * @param request The abandon request that was received.
351 * @param result The result of processing the abandon request.
352 */
353 public void logAbandonResult(final CompletedOperationContext opContext,
354 final AbandonRequest request,
355 final GenericResult result)
356 {
357 // No action will be taken by default.
358 }
359
360
361
362 /**
363 * Logs a message about an add request received from a client.
364 *
365 * @param opContext The operation context for the add operation.
366 * @param request The add request that was received.
367 */
368 public void logAddRequest(final OperationContext opContext,
369 final AddRequest request)
370 {
371 // No action will be taken by default.
372 }
373
374
375
376 /**
377 * Logs a message about an add request that will be forwarded to another
378 * server.
379 *
380 * @param opContext The operation context for the add operation.
381 * @param request The add request that was received.
382 * @param target Information about the server to which the request will
383 * be forwarded.
384 */
385 public void logAddForward(final OperationContext opContext,
386 final AddRequest request,
387 final ForwardTarget target)
388 {
389 // No action will be taken by default.
390 }
391
392
393
394 /**
395 * Logs a message about a failure encountered while attempting to forward an
396 * add request to another server.
397 *
398 * @param opContext The operation context for the add operation.
399 * @param request The add request that was received.
400 * @param target Information about the server to which the request was
401 * forwarded.
402 * @param failure The exception that was received when attempting to
403 * forward the request.
404 */
405 public void logAddForwardFailure(final OperationContext opContext,
406 final AddRequest request,
407 final ForwardTarget target,
408 final LDAPException failure)
409 {
410 // No action will be taken by default.
411 }
412
413
414
415 /**
416 * Logs a message about the result of processing an add request.
417 *
418 * @param opContext The operation context for the add operation.
419 * @param request The add request that was received.
420 * @param result The result of processing the add request.
421 */
422 public void logAddResponse(final CompletedOperationContext opContext,
423 final AddRequest request,
424 final AddResult result)
425 {
426 // No action will be taken by default.
427 }
428
429
430
431 /**
432 * Logs a message about a simple bind request received from a client.
433 *
434 * @param opContext The operation context for the bind operation.
435 * @param request The bind request that was received.
436 */
437 public void logBindRequest(final OperationContext opContext,
438 final SimpleBindRequest request)
439 {
440 // No action will be taken by default.
441 }
442
443
444
445 /**
446 * Logs a message about a simple bind request that will be forwarded to
447 * another server.
448 *
449 * @param opContext The operation context for the bind operation.
450 * @param request The bind request that was received.
451 * @param target Information about the server to which the request will
452 * be forwarded.
453 */
454 public void logBindForward(final OperationContext opContext,
455 final SimpleBindRequest request,
456 final ForwardTarget target)
457 {
458 // No action will be taken by default.
459 }
460
461
462
463 /**
464 * Logs a message about a failure encountered while attempting to forward a
465 * simple bind request to another server.
466 *
467 * @param opContext The operation context for the bind operation.
468 * @param request The bind request that was received.
469 * @param target Information about the server to which the request was
470 * forwarded.
471 * @param failure The exception that was received when attempting to
472 * forward the request.
473 */
474 public void logBindForwardFailure(final OperationContext opContext,
475 final SimpleBindRequest request,
476 final ForwardTarget target,
477 final LDAPException failure)
478 {
479 // No action will be taken by default.
480 }
481
482
483
484 /**
485 * Logs a message about the result of processing a simple bind request.
486 *
487 * @param opContext The operation context for the bind operation.
488 * @param request The bind request that was received.
489 * @param result The result of processing the bind request.
490 */
491 public void logBindResponse(final CompletedOperationContext opContext,
492 final SimpleBindRequest request,
493 final BindResult result)
494 {
495 // No action will be taken by default.
496 }
497
498
499
500 /**
501 * Logs a message about a SASL bind request received from a client.
502 *
503 * @param opContext The operation context for the bind operation.
504 * @param request The bind request that was received.
505 */
506 public void logBindRequest(final OperationContext opContext,
507 final SASLBindRequest request)
508 {
509 // No action will be taken by default.
510 }
511
512
513
514 /**
515 * Logs a message about a SASL bind request that will be forwarded to
516 * another server.
517 *
518 * @param opContext The operation context for the bind operation.
519 * @param request The bind request that was received.
520 * @param target Information about the server to which the request will
521 * be forwarded.
522 */
523 public void logBindForward(final OperationContext opContext,
524 final SASLBindRequest request,
525 final ForwardTarget target)
526 {
527 // No action will be taken by default.
528 }
529
530
531
532 /**
533 * Logs a message about a failure encountered while attempting to forward a
534 * SASL bind request to another server.
535 *
536 * @param opContext The operation context for the bind operation.
537 * @param request The bind request that was received.
538 * @param target Information about the server to which the request was
539 * forwarded.
540 * @param failure The exception that was received when attempting to
541 * forward the request.
542 */
543 public void logBindForwardFailure(final OperationContext opContext,
544 final SASLBindRequest request,
545 final ForwardTarget target,
546 final LDAPException failure)
547 {
548 // No action will be taken by default.
549 }
550
551
552
553 /**
554 * Logs a message about the result of processing a SASL bind request.
555 *
556 * @param opContext The operation context for the bind operation.
557 * @param request The bind request that was received.
558 * @param result The result of processing the bind request.
559 */
560 public void logBindResponse(final CompletedOperationContext opContext,
561 final SASLBindRequest request,
562 final BindResult result)
563 {
564 // No action will be taken by default.
565 }
566
567
568
569 /**
570 * Logs a message about a compare request received from a client.
571 *
572 * @param opContext The operation context for the compare operation.
573 * @param request The compare request that was received.
574 */
575 public void logCompareRequest(final OperationContext opContext,
576 final CompareRequest request)
577 {
578 // No action will be taken by default.
579 }
580
581
582
583 /**
584 * Logs a message about a compare request that will be forwarded to another
585 * server.
586 *
587 * @param opContext The operation context for the compare operation.
588 * @param request The compare request that was received.
589 * @param target Information about the server to which the request will
590 * be forwarded.
591 */
592 public void logCompareForward(final OperationContext opContext,
593 final CompareRequest request,
594 final ForwardTarget target)
595 {
596 // No action will be taken by default.
597 }
598
599
600
601 /**
602 * Logs a message about a failure encountered while attempting to forward a
603 * compare request to another server.
604 *
605 * @param opContext The operation context for the compare operation.
606 * @param request The compare request that was received.
607 * @param target Information about the server to which the request was
608 * forwarded.
609 * @param failure The exception that was received when attempting to
610 * forward the request.
611 */
612 public void logCompareForwardFailure(final OperationContext opContext,
613 final CompareRequest request,
614 final ForwardTarget target,
615 final LDAPException failure)
616 {
617 // No action will be taken by default.
618 }
619
620
621
622 /**
623 * Logs a message about the result of processing a compare request.
624 *
625 * @param opContext The operation context for the compare operation.
626 * @param request The compare request that was received.
627 * @param result The result of processing the compare request.
628 */
629 public void logCompareResponse(final CompletedOperationContext opContext,
630 final CompareRequest request,
631 final CompareResult result)
632 {
633 // No action will be taken by default.
634 }
635
636
637
638 /**
639 * Logs a message about a delete request received from a client.
640 *
641 * @param opContext The operation context for the delete operation.
642 * @param request The delete request that was received.
643 */
644 public void logDeleteRequest(final OperationContext opContext,
645 final DeleteRequest request)
646 {
647 // No action will be taken by default.
648 }
649
650
651
652 /**
653 * Logs a message about a delete request that will be forwarded to another
654 * server.
655 *
656 * @param opContext The operation context for the delete operation.
657 * @param request The delete request that was received.
658 * @param target Information about the server to which the request will
659 * be forwarded.
660 */
661 public void logDeleteForward(final OperationContext opContext,
662 final DeleteRequest request,
663 final ForwardTarget target)
664 {
665 // No action will be taken by default.
666 }
667
668
669
670 /**
671 * Logs a message about a failure encountered while attempting to forward a
672 * delete request to another server.
673 *
674 * @param opContext The operation context for the delete operation.
675 * @param request The delete request that was received.
676 * @param target Information about the server to which the request was
677 * forwarded.
678 * @param failure The exception that was received when attempting to
679 * forward the request.
680 */
681 public void logDeleteForwardFailure(final OperationContext opContext,
682 final DeleteRequest request,
683 final ForwardTarget target,
684 final LDAPException failure)
685 {
686 // No action will be taken by default.
687 }
688
689
690
691 /**
692 * Logs a message about the result of processing a delete request.
693 *
694 * @param opContext The operation context for the delete operation.
695 * @param request The delete request that was received.
696 * @param result The result of processing the delete request.
697 */
698 public void logDeleteResponse(final CompletedOperationContext opContext,
699 final DeleteRequest request,
700 final DeleteResult result)
701 {
702 // No action will be taken by default.
703 }
704
705
706
707 /**
708 * Logs a message about an extended request received from a client.
709 *
710 * @param opContext The operation context for the extended operation.
711 * @param request The extended request that was received.
712 */
713 public void logExtendedRequest(final OperationContext opContext,
714 final ExtendedRequest request)
715 {
716 // No action will be taken by default.
717 }
718
719
720
721 /**
722 * Logs a message about an extended request that will be forwarded to another
723 * server.
724 *
725 * @param opContext The operation context for the extended operation.
726 * @param request The extended request that was received.
727 * @param target Information about the server to which the request will
728 * be forwarded.
729 */
730 public void logExtendedForward(final OperationContext opContext,
731 final ExtendedRequest request,
732 final ForwardTarget target)
733 {
734 // No action will be taken by default.
735 }
736
737
738
739 /**
740 * Logs a message about a failure encountered while attempting to forward an
741 * extended request to another server.
742 *
743 * @param opContext The operation context for the extended operation.
744 * @param request The extended request that was received.
745 * @param target Information about the server to which the request was
746 * forwarded.
747 * @param failure The exception that was received when attempting to
748 * forward the request.
749 */
750 public void logExtendedForwardFailure(final OperationContext opContext,
751 final ExtendedRequest request,
752 final ForwardTarget target,
753 final LDAPException failure)
754 {
755 // No action will be taken by default.
756 }
757
758
759
760 /**
761 * Logs a message about the result of processing an extended request.
762 *
763 * @param opContext The operation context for the extended operation.
764 * @param request The extended request that was received.
765 * @param result The result of processing the extended request.
766 */
767 public void logExtendedResponse(final CompletedOperationContext opContext,
768 final ExtendedRequest request,
769 final ExtendedResult result)
770 {
771 // No action will be taken by default.
772 }
773
774
775
776 /**
777 * Logs a message about a modify request received from a client.
778 *
779 * @param opContext The operation context for the modify operation.
780 * @param request The modify request that was received.
781 */
782 public void logModifyRequest(final OperationContext opContext,
783 final ModifyRequest request)
784 {
785 // No action will be taken by default.
786 }
787
788
789
790 /**
791 * Logs a message about a modify request that will be forwarded to another
792 * server.
793 *
794 * @param opContext The operation context for the modify operation.
795 * @param request The modify request that was received.
796 * @param target Information about the server to which the request will
797 * be forwarded.
798 */
799 public void logModifyForward(final OperationContext opContext,
800 final ModifyRequest request,
801 final ForwardTarget target)
802 {
803 // No action will be taken by default.
804 }
805
806
807
808 /**
809 * Logs a message about a failure encountered while attempting to forward a
810 * modify request to another server.
811 *
812 * @param opContext The operation context for the modify operation.
813 * @param request The modify request that was received.
814 * @param target Information about the server to which the request was
815 * forwarded.
816 * @param failure The exception that was received when attempting to
817 * forward the request.
818 */
819 public void logModifyForwardFailure(final OperationContext opContext,
820 final ModifyRequest request,
821 final ForwardTarget target,
822 final LDAPException failure)
823 {
824 // No action will be taken by default.
825 }
826
827
828
829 /**
830 * Logs a message about the result of processing a modify request.
831 *
832 * @param opContext The operation context for the modify operation.
833 * @param request The modify request that was received.
834 * @param result The result of processing the modify request.
835 */
836 public void logModifyResponse(final CompletedOperationContext opContext,
837 final ModifyRequest request,
838 final ModifyResult result)
839 {
840 // No action will be taken by default.
841 }
842
843
844
845 /**
846 * Logs a message about a modify DN request received from a client.
847 *
848 * @param opContext The operation context for the modify DN operation.
849 * @param request The modify DN request that was received.
850 */
851 public void logModifyDNRequest(final OperationContext opContext,
852 final ModifyDNRequest request)
853 {
854 // No action will be taken by default.
855 }
856
857
858
859 /**
860 * Logs a message about a modify DN request that will be forwarded to another
861 * server.
862 *
863 * @param opContext The operation context for the modify DN operation.
864 * @param request The modify DN request that was received.
865 * @param target Information about the server to which the request will
866 * be forwarded.
867 */
868 public void logModifyDNForward(final OperationContext opContext,
869 final ModifyDNRequest request,
870 final ForwardTarget target)
871 {
872 // No action will be taken by default.
873 }
874
875
876
877 /**
878 * Logs a message about a failure encountered while attempting to forward a
879 * modify DN request to another server.
880 *
881 * @param opContext The operation context for the modify DN operation.
882 * @param request The modify DN request that was received.
883 * @param target Information about the server to which the request was
884 * forwarded.
885 * @param failure The exception that was received when attempting to
886 * forward the request.
887 */
888 public void logModifyDNForwardFailure(final OperationContext opContext,
889 final ModifyDNRequest request,
890 final ForwardTarget target,
891 final LDAPException failure)
892 {
893 // No action will be taken by default.
894 }
895
896
897
898 /**
899 * Logs a message about the result of processing a modify DN request.
900 *
901 * @param opContext The operation context for the modify DN operation.
902 * @param request The modify DN request that was received.
903 * @param result The result of processing the modify DN request.
904 */
905 public void logModifyDNResponse(final CompletedOperationContext opContext,
906 final ModifyDNRequest request,
907 final ModifyDNResult result)
908 {
909 // No action will be taken by default.
910 }
911
912
913
914 /**
915 * Logs a message about a search request received from a client.
916 *
917 * @param opContext The operation context for the search operation.
918 * @param request The search request that was received.
919 */
920 public void logSearchRequest(final OperationContext opContext,
921 final SearchRequest request)
922 {
923 // No action will be taken by default.
924 }
925
926
927
928 /**
929 * Logs a message about a search request that will be forwarded to another
930 * server.
931 *
932 * @param opContext The operation context for the search operation.
933 * @param request The search request that was received.
934 * @param target Information about the server to which the request will
935 * be forwarded.
936 */
937 public void logSearchForward(final OperationContext opContext,
938 final SearchRequest request,
939 final ForwardTarget target)
940 {
941 // No action will be taken by default.
942 }
943
944
945
946 /**
947 * Logs a message about a failure encountered while attempting to forward a
948 * search request to another server.
949 *
950 * @param opContext The operation context for the search operation.
951 * @param request The search request that was received.
952 * @param target Information about the server to which the request was
953 * forwarded.
954 * @param failure The exception that was received when attempting to
955 * forward the request.
956 */
957 public void logSearchForwardFailure(final OperationContext opContext,
958 final SearchRequest request,
959 final ForwardTarget target,
960 final LDAPException failure)
961 {
962 // No action will be taken by default.
963 }
964
965
966
967 /**
968 * Logs a message about a search result entry that was returned to the client.
969 *
970 * @param opContext The operation context for the search operation.
971 * @param request The search request that was received.
972 * @param entry The entry that was returned.
973 * @param controls The set of controls included with the entry, or an empty
974 * list if there were none.
975 */
976 public void logSearchResultEntry(final OperationContext opContext,
977 final SearchRequest request,
978 final Entry entry,
979 final List<Control> controls)
980 {
981 // No action will be taken by default.
982 }
983
984
985
986 /**
987 * Logs a message about a search result reference that was returned to the
988 * client.
989 *
990 * @param opContext The operation context for the search operation.
991 * @param request The search request that was received.
992 * @param referralURLs The referral URLs for the reference that was
993 * returned.
994 * @param controls The set of controls included with the reference, or
995 * an empty list if there were none.
996 */
997 public void logSearchResultReference(final OperationContext opContext,
998 final SearchRequest request,
999 final List<String> referralURLs,
1000 final List<Control> controls)
1001 {
1002 // No action will be taken by default.
1003 }
1004
1005
1006
1007 /**
1008 * Logs a message about the result of processing a search request.
1009 *
1010 * @param opContext The operation context for the search operation.
1011 * @param request The search request that was received.
1012 * @param result The result of processing the search request.
1013 */
1014 public void logSearchResultDone(
1015 final CompletedSearchOperationContext opContext,
1016 final SearchRequest request, final SearchResult result)
1017 {
1018 // No action will be taken by default.
1019 }
1020
1021
1022
1023 /**
1024 * Logs a message about an unbind request received from a client.
1025 *
1026 * @param opContext The operation context for the unbind operation.
1027 * @param request The unbind request that was received.
1028 */
1029 public void logUnbindRequest(final OperationContext opContext,
1030 final UnbindRequest request)
1031 {
1032 // No action will be taken by default.
1033 }
1034
1035
1036
1037 /**
1038 * Logs a message about an intermediate response that was returned to the
1039 * client.
1040 *
1041 * @param opContext The operation context for the associated
1042 * operation.
1043 * @param intermediateResponse The intermediate response that was returned.
1044 */
1045 public void logIntermediateResponse(final OperationContext opContext,
1046 final IntermediateResponse intermediateResponse)
1047 {
1048 // No action will be taken by default.
1049 }
1050
1051
1052
1053 /**
1054 * Writes a message to the access logger to indicate that the Directory Proxy
1055 * Server will attempt to perform entry rebalancing by migrating a subtree
1056 * from one backend set to another.
1057 *
1058 * @param rebalancingOperationID The unique ID assigned to the entry
1059 * balancing operation.
1060 * @param triggerOperation The operation that triggered the entry
1061 * rebalancing. It may be {@code null} if the
1062 * rebalancing operation wasn't triggered by a
1063 * client request.
1064 * @param baseDN The base DN of the subtree to migrate.
1065 * @param sizeLimit The maximum number of entries to migrate.
1066 * @param sourceBackendSetName The name of the backend set containing the
1067 * subtree to migrate.
1068 * @param sourceAddress The address of the server from which the
1069 * source entries will be read.
1070 * @param sourcePort The port of the server from which the
1071 * source entries will be read.
1072 * @param targetBackendSetName The name of the backend set to which the
1073 * subtree will be migrated.
1074 * @param targetAddress The address of the server to which the
1075 * subtree will be migrated.
1076 * @param targetPort The port of the server to which the subtree
1077 * will be migrated.
1078 */
1079 public void logEntryRebalancingRequest(final long rebalancingOperationID,
1080 final OperationContext triggerOperation, final String baseDN,
1081 final int sizeLimit, final String sourceBackendSetName,
1082 final String sourceAddress, final int sourcePort,
1083 final String targetBackendSetName,
1084 final String targetAddress, final int targetPort)
1085 {
1086 // No action performed by default.
1087 }
1088
1089
1090
1091 /**
1092 * Writes a message to the access logger to indicate that the Directory Proxy
1093 * Server will attempt to perform entry rebalancing by migrating a subtree
1094 * from one backend set to another.
1095 *
1096 * @param rebalancingOperationID The unique ID assigned to the entry
1097 * balancing operation.
1098 * @param triggerOperation The operation that triggered the entry
1099 * rebalancing. It may be {@code null} if the
1100 * rebalancing operation wasn't triggered by a
1101 * client request.
1102 * @param baseDN The base DN of the subtree to migrate.
1103 * @param sizeLimit The maximum number of entries to migrate.
1104 * @param sourceBackendSetName The name of the backend set containing the
1105 * subtree to migrate.
1106 * @param sourceAddress The address of the server from which the
1107 * source entries will be read.
1108 * @param sourcePort The port of the server from which the
1109 * source entries will be read.
1110 * @param targetBackendSetName The name of the backend set to which the
1111 * subtree will be migrated.
1112 * @param targetAddress The address of the server to which the
1113 * subtree will be migrated.
1114 * @param targetPort The port of the server to which the subtree
1115 * will be migrated.
1116 * @param moveSubtreeResult An object with information about the result
1117 * of the subtree move processing.
1118 */
1119 public void logEntryRebalancingResult(final long rebalancingOperationID,
1120 final OperationContext triggerOperation, final String baseDN,
1121 final int sizeLimit, final String sourceBackendSetName,
1122 final String sourceAddress, final int sourcePort,
1123 final String targetBackendSetName,
1124 final String targetAddress, final int targetPort,
1125 final MoveSubtreeResult moveSubtreeResult)
1126 {
1127 // No action performed by default.
1128 }
1129 }