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 * http://www.opensource.org/licenses/cddl1.php.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file. If applicable, add the following below this CDDL HEADER,
016 * with the fields enclosed by brackets "[]" replaced with your own
017 * identifying information:
018 *      Portions Copyright [yyyy] [name of copyright owner]
019 *
020 * CDDL HEADER END
021 *
022 *
023 *      Copyright 2013-2021 Ping Identity Corporation
024 */
025package com.unboundid.directory.sdk.broker.types;
026
027
028
029import com.unboundid.directory.sdk.common.types.ServerContext;
030import com.unboundid.util.NotExtensible;
031import com.unboundid.util.ThreadSafety;
032import com.unboundid.util.ThreadSafetyLevel;
033
034import java.util.Map;
035
036
037
038/**
039 * This interface may be used to obtain information about the
040 * Data Governance Server in which an extension is running.
041 */
042@NotExtensible()
043@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
044public interface BrokerContext extends ServerContext
045{
046  /**
047   * Indicates whether trace log messages from extensions are loggable
048   * to any trace log publishers. This allows callers to avoid expensive
049   * message construction for messages that are not going to be logged.
050   *
051   * @return  {@code true} if trace log messages from extensions are
052   *          loggable to any trace log publishers
053   */
054  boolean isTraceMessageLoggable();
055
056
057
058  /**
059   * Writes a message to the server trace log publishers. Sensitive information
060   * must not be included in the contents of the message.
061   * <p>
062   * Trace log messages should be used in methods that are called when
063   * processing an incoming request. The trace log will automatically
064   * include request identifiers in the log messages so that all log
065   * messages about a request can be correlated.
066   * <p>
067   * You can use the <i>search-logs</i> command-line tool on the trace log
068   * file to extract only the messages logged by your extension.
069   *
070   * @param  message    The message to be logged. It must not be
071   *                    {@code null}.
072   */
073  void logTraceMessage(final String message);
074
075
076
077  /**
078   * Writes a message to the server trace log publishers, including key value
079   * pairs to be logged with the message. Sensitive information
080   * must not be included in the contents of the message or the key value
081   * pairs.
082   * <p>
083   * Trace log messages should be used in methods that are called when
084   * processing an incoming request. The trace log will automatically
085   * include request identifiers in the log messages so that all log
086   * messages about a request can be correlated.
087   * <p>
088   * You can use the <i>search-logs</i> command-line tool on the trace log
089   * file to extract only the messages logged by your extension.
090   *
091   * @param  message    The message to be logged. It must not be
092   *                    {@code null}.
093   * @param  keyValues  Keys and values that are to be logged with
094   *                    key=value. It may be {@code null}.
095   */
096  void logTraceMessage(final String message,
097                       final Map<String, String> keyValues);
098}