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}