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 *      Portions Copyright 2013-2023 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 * PingAuthorize 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   * @deprecated  See the trace log-related methods in {@link ServerContext}.
055   */
056  @Deprecated()
057  boolean isTraceMessageLoggable();
058
059
060
061  /**
062   * Writes a message to the server trace log publishers. Sensitive information
063   * must not be included in the contents of the message.
064   * <p>
065   * Trace log messages should be used in methods that are called when
066   * processing an incoming request. The trace log will automatically
067   * include request identifiers in the log messages so that all log
068   * messages about a request can be correlated.
069   * <p>
070   * You can use the <i>search-logs</i> command-line tool on the trace log
071   * file to extract only the messages logged by your extension.
072   *
073   * @param  message    The message to be logged. It must not be
074   *                    {@code null}.
075   *
076   * @deprecated  See the trace log-related methods in {@link ServerContext}.
077   */
078  @Deprecated()
079  void logTraceMessage(final String message);
080
081
082
083  /**
084   * Writes a message to the server trace log publishers, including key value
085   * pairs to be logged with the message. Sensitive information
086   * must not be included in the contents of the message or the key value
087   * pairs.
088   * <p>
089   * Trace log messages should be used in methods that are called when
090   * processing an incoming request. The trace log will automatically
091   * include request identifiers in the log messages so that all log
092   * messages about a request can be correlated.
093   * <p>
094   * You can use the <i>search-logs</i> command-line tool on the trace log
095   * file to extract only the messages logged by your extension.
096   *
097   * @param  message    The message to be logged. It must not be
098   *                    {@code null}.
099   * @param  keyValues  Keys and values that are to be logged with
100   *                    key=value. It may be {@code null}.
101   *
102   * @deprecated  See the trace log-related methods in {@link ServerContext}.
103   */
104  @Deprecated()
105  void logTraceMessage(final String message,
106                       final Map<String, String> keyValues);
107}