001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache license, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the license for the specific language governing permissions and 015 * limitations under the license. 016 */ 017package org.apache.logging.log4j.core; 018 019import java.util.List; 020 021import org.apache.logging.log4j.core.config.Property; 022import org.apache.logging.log4j.core.impl.ContextDataInjectorFactory; 023import org.apache.logging.log4j.core.impl.ThreadContextDataInjector; 024import org.apache.logging.log4j.util.ReadOnlyStringMap; 025import org.apache.logging.log4j.util.StringMap; 026 027/** 028 * Responsible for initializing the context data of LogEvents. Context data is data that is set by the application to be 029 * included in all subsequent log events. 030 * <p> 031 * The source of the context data is implementation-specific. The default source for context data is the ThreadContext. 032 * </p><p> 033 * In some asynchronous models, work may be delegated to several threads, while conceptually this work shares the same 034 * context. In such models, storing context data in {@code ThreadLocal} variables is not convenient or desirable. 035 * Users can configure the {@code ContextDataInjectorFactory} to provide custom {@code ContextDataInjector} objects, 036 * in order to initialize log events with context data from any arbitrary context. 037 * </p><p> 038 * When providing a custom {@code ContextDataInjector}, be aware that the {@code ContextDataInjectorFactory} may be 039 * invoked multiple times and the various components in Log4j that need access to context data may each have their own 040 * instance of {@code ContextDataInjector}. 041 * This includes the object(s) that populate log events, but also various lookups and filters that look at 042 * context data to determine whether an event should be logged. 043 * </p><p> 044 * Implementors should take particular note of how the different methods in the interface have different thread-safety 045 * guarantees to enable optimal performance. 046 * </p> 047 * 048 * @see StringMap 049 * @see ReadOnlyStringMap 050 * @see ContextDataInjectorFactory 051 * @see org.apache.logging.log4j.ThreadContext 052 * @see ThreadContextDataInjector 053 * @since 2.7 054 */ 055public interface ContextDataInjector { 056 /** 057 * Returns a {@code StringMap} object initialized with the specified properties and the appropriate 058 * context data. The returned value may be the specified parameter or a different object. 059 * <p> 060 * This method will be called for each log event to initialize its context data and implementors should take 061 * care to make this method as performant as possible while preserving at least the following thread-safety 062 * guarantee. 063 * </p><p> 064 * Thread-safety note: The returned object can safely be passed off to another thread: future changes in the 065 * underlying context data will not be reflected in the returned object. 066 * </p><p> 067 * Example implementation: 068 * </p> 069 * <pre> 070 * public StringMap injectContextData(List<Property> properties, StringMap reusable) { 071 * if (properties == null || properties.isEmpty()) { 072 * // assume context data is stored in a copy-on-write data structure that is safe to pass to another thread 073 * return (StringMap) rawContextData(); 074 * } 075 * // first copy configuration properties into the result 076 * ThreadContextDataInjector.copyProperties(properties, reusable); 077 * 078 * // then copy context data key-value pairs (may overwrite configuration properties) 079 * reusable.putAll(rawContextData()); 080 * return reusable; 081 * } 082 * </pre> 083 * 084 * @param properties Properties from the log4j configuration to be added to the resulting ReadOnlyStringMap. May be 085 * {@code null} or empty 086 * @param reusable a {@code StringMap} instance that may be reused to avoid creating temporary objects 087 * @return a {@code StringMap} instance initialized with the specified properties and the appropriate 088 * context data. The returned value may be the specified parameter or a different object. 089 * @see ThreadContextDataInjector#copyProperties(List, StringMap) 090 */ 091 StringMap injectContextData(final List<Property> properties, final StringMap reusable); 092 093 /** 094 * Returns a {@code ReadOnlyStringMap} object reflecting the current state of the context. Configuration properties 095 * are not included in the result. 096 * <p> 097 * This method may be called multiple times for each log event by Filters and Lookups and implementors should take 098 * care to make this method as performant as possible while preserving at least the following thread-safety 099 * guarantee. 100 * </p><p> 101 * Thread-safety note: The returned object can only be safely used <em>in the current thread</em>. Changes in the 102 * underlying context may or may not be reflected in the returned object, depending on the context data source and 103 * the implementation of this method. It is not safe to pass the returned object to another thread. 104 * </p> 105 * @return a {@code ReadOnlyStringMap} object reflecting the current state of the context, may not return {@code null} 106 */ 107 ReadOnlyStringMap rawContextData(); 108}