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