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