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