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