/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache license, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the license for the specific language governing permissions and
 * limitations under the license.
 */
package org.apache.logging.log4j.core;

import java.util.List;

import org.apache.logging.log4j.core.config.Property;
import org.apache.logging.log4j.core.impl.ContextDataInjectorFactory;
import org.apache.logging.log4j.core.impl.ThreadContextDataInjector;
import org.apache.logging.log4j.util.ReadOnlyStringMap;
import org.apache.logging.log4j.util.StringMap;

Responsible for initializing the context data of LogEvents. Context data is data that is set by the application to be
included in all subsequent log events.

The source of the context data is implementation-specific. The default source for context data is the ThreadContext.
 In some asynchronous models, work may be delegated to several threads, while conceptually this work shares the same context. In such models, storing context data in ThreadLocal variables is not convenient or desirable. Users can configure the ContextDataInjectorFactory to provide custom ContextDataInjector objects, in order to initialize log events with context data from any arbitrary context. 
 When providing a custom ContextDataInjector, be aware that the ContextDataInjectorFactory may be invoked multiple times and the various components in Log4j that need access to context data may each have their own instance of ContextDataInjector. This includes the object(s) that populate log events, but also various lookups and filters that look at context data to determine whether an event should be logged. 

Implementors should take particular note of how the different methods in the interface have different thread-safety
guarantees to enable optimal performance.

See Also:
StringMap
ReadOnlyStringMap
ContextDataInjectorFactory
ThreadContext
ThreadContextDataInjector
Since:
2.7/**
 * Responsible for initializing the context data of LogEvents. Context data is data that is set by the application to be
 * included in all subsequent log events.
 * <p>
 * The source of the context data is implementation-specific. The default source for context data is the ThreadContext.
 * </p><p>
 * In some asynchronous models, work may be delegated to several threads, while conceptually this work shares the same
 * context. In such models, storing context data in {@code ThreadLocal} variables is not convenient or desirable.
 * Users can configure the {@code ContextDataInjectorFactory} to provide custom {@code ContextDataInjector} objects,
 * in order to initialize log events with context data from any arbitrary context.
 * </p><p>
 * When providing a custom {@code ContextDataInjector}, be aware that the {@code ContextDataInjectorFactory} may be
 * invoked multiple times and the various components in Log4j that need access to context data may each have their own
 * instance of {@code ContextDataInjector}.
 * This includes the object(s) that populate log events, but also various lookups and filters that look at
 * context data to determine whether an event should be logged.
 * </p><p>
 * Implementors should take particular note of how the different methods in the interface have different thread-safety
 * guarantees to enable optimal performance.
 * </p>
 *
 * @see StringMap
 * @see ReadOnlyStringMap
 * @see ContextDataInjectorFactory
 * @see org.apache.logging.log4j.ThreadContext
 * @see ThreadContextDataInjector
 * @since 2.7
 */
public interface ContextDataInjector {
    
Returns a StringMap object initialized with the specified properties and the appropriate context data. The returned value may be the specified parameter or a different object. 

This method will be called for each log event to initialize its context data and implementors should take
care to make this method as performant as possible while preserving at least the following thread-safety
guarantee.

Thread-safety note: The returned object can safely be passed off to another thread: future changes in the
underlying context data will not be reflected in the returned object.

Example implementation:

public StringMap injectContextData(List properties, StringMap reusable) {
    if (properties == null || properties.isEmpty()) {
        // assume context data is stored in a copy-on-write data structure that is safe to pass to another thread
        return (StringMap) rawContextData();
    }
    // first copy configuration properties into the result
    ThreadContextDataInjector.copyProperties(properties, reusable);
    // then copy context data key-value pairs (may overwrite configuration properties)
    reusable.putAll(rawContextData());
    return reusable;
}

Params:
properties – Properties from the log4j configuration to be added to the resulting ReadOnlyStringMap. May be null or empty
reusable – a StringMap instance that may be reused to avoid creating temporary objects
See Also:
ThreadContextDataInjector.copyProperties(List<Property>, StringMap)
Returns:
a StringMap instance initialized with the specified properties and the appropriate context data. The returned value may be the specified parameter or a different object./**
     * Returns a {@code StringMap} object initialized with the specified properties and the appropriate
     * context data. The returned value may be the specified parameter or a different object.
     * <p>
     * This method will be called for each log event to initialize its context data and implementors should take
     * care to make this method as performant as possible while preserving at least the following thread-safety
     * guarantee.
     * </p><p>
     * Thread-safety note: The returned object can safely be passed off to another thread: future changes in the
     * underlying context data will not be reflected in the returned object.
     * </p><p>
     * Example implementation:
     * </p>
     * <pre>
     * public StringMap injectContextData(List<Property> properties, StringMap reusable) {
     *     if (properties == null || properties.isEmpty()) {
     *         // assume context data is stored in a copy-on-write data structure that is safe to pass to another thread
     *         return (StringMap) rawContextData();
     *     }
     *     // first copy configuration properties into the result
     *     ThreadContextDataInjector.copyProperties(properties, reusable);
     *
     *     // then copy context data key-value pairs (may overwrite configuration properties)
     *     reusable.putAll(rawContextData());
     *     return reusable;
     * }
     * </pre>
     *
     * @param properties Properties from the log4j configuration to be added to the resulting ReadOnlyStringMap. May be
     *          {@code null} or empty
     * @param reusable a {@code StringMap} instance that may be reused to avoid creating temporary objects
     * @return a {@code StringMap} instance initialized with the specified properties and the appropriate
     *          context data. The returned value may be the specified parameter or a different object.
     * @see ThreadContextDataInjector#copyProperties(List, StringMap)
     */
    StringMap injectContextData(final List<Property> properties, final StringMap reusable);

    
Returns a ReadOnlyStringMap object reflecting the current state of the context. Configuration properties are not included in the result. 

This method may be called multiple times for each log event by Filters and Lookups and implementors should take
care to make this method as performant as possible while preserving at least the following thread-safety
guarantee.

Thread-safety note: The returned object can only be safely used in the current thread. Changes in the
underlying context may or may not be reflected in the returned object, depending on the context data source and
the implementation of this method. It is not safe to pass the returned object to another thread.

Returns:
a ReadOnlyStringMap object reflecting the current state of the context, may not return null/**
     * Returns a {@code ReadOnlyStringMap} object reflecting the current state of the context. Configuration properties
     * are not included in the result.
     * <p>
     * This method may be called multiple times for each log event by Filters and Lookups and implementors should take
     * care to make this method as performant as possible while preserving at least the following thread-safety
     * guarantee.
     * </p><p>
     * Thread-safety note: The returned object can only be safely used <em>in the current thread</em>. Changes in the
     * underlying context may or may not be reflected in the returned object, depending on the context data source and
     * the implementation of this method. It is not safe to pass the returned object to another thread.
     * </p>
     * @return a {@code ReadOnlyStringMap} object reflecting the current state of the context, may not return {@code null}
     */
    ReadOnlyStringMap rawContextData();
}