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-2017 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.scim2.client.ScimInterface;
031import com.unboundid.util.NotExtensible;
032import com.unboundid.util.ThreadSafety;
033import com.unboundid.util.ThreadSafetyLevel;
034
035import java.util.Map;
036
037
038
039/**
040 * This interface may be used to obtain information about the Broker
041 * in which an extension is running.
042 */
043@NotExtensible()
044@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
045public interface BrokerContext extends ServerContext
046{
047  /**
048   * Indicates whether trace log messages from extensions are loggable
049   * to any trace log publishers. This allows callers to avoid expensive
050   * message construction for messages that are not going to be logged.
051   *
052   * @return  {@code true} if trace log messages from extensions are
053   *          loggable to any trace log publishers
054   */
055  boolean isTraceMessageLoggable();
056
057
058
059  /**
060   * Writes a message to the server trace log publishers. Sensitive information
061   * must not be included in the contents of the message.
062   * <p>
063   * Trace log messages should be used in methods that are called when
064   * processing an incoming request. The trace log will automatically
065   * include request identifiers in the log messages so that all log
066   * messages about a request can be correlated.
067   * <p>
068   * You can use the <i>search-logs</i> command-line tool on the trace log
069   * file to extract only the messages logged by your extension.
070   *
071   * @param  message    The message to be logged. It must not be
072   *                    {@code null}.
073   */
074  void logTraceMessage(final String message);
075
076
077
078  /**
079   * Writes a message to the server trace log publishers, including key value
080   * pairs to be logged with the message. Sensitive information
081   * must not be included in the contents of the message or the key value
082   * pairs.
083   * <p>
084   * Trace log messages should be used in methods that are called when
085   * processing an incoming request. The trace log will automatically
086   * include request identifiers in the log messages so that all log
087   * messages about a request can be correlated.
088   * <p>
089   * You can use the <i>search-logs</i> command-line tool on the trace log
090   * file to extract only the messages logged by your extension.
091   *
092   * @param  message    The message to be logged. It must not be
093   *                    {@code null}.
094   * @param  keyValues  Keys and values that are to be logged with
095   *                    key=value. It may be {@code null}.
096   */
097  void logTraceMessage(final String message,
098                       final Map<String, String> keyValues);
099
100  /**
101   * Gets an internal implementation of the ScimInterface.
102   *
103   * @return an object that implements the ScimInterface using
104   * in-process access to the internal SCIM objects.  This implementation
105   * will not use HTTP/REST.
106   */
107  ScimInterface getInternalScimInterface();
108}