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