001/**
002 * Logback: the reliable, generic, fast and flexible logging framework.
003 * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
004 *
005 * This program and the accompanying materials are dual-licensed under
006 * either the terms of the Eclipse Public License v1.0 as published by
007 * the Eclipse Foundation
008 *
009 *   or (per the licensee's choosing)
010 *
011 * under the terms of the GNU Lesser General Public License version 2.1
012 * as published by the Free Software Foundation.
013 */
014package ch.qos.logback.core;
015
016import java.util.Map;
017import java.util.concurrent.ExecutorService;
018import java.util.concurrent.ScheduledExecutorService;
019import java.util.concurrent.ScheduledFuture;
020import java.util.concurrent.ThreadPoolExecutor;
021
022import ch.qos.logback.core.spi.ConfigurationEvent;
023import ch.qos.logback.core.spi.ConfigurationEventListener;
024import ch.qos.logback.core.spi.LifeCycle;
025import ch.qos.logback.core.spi.PropertyContainer;
026import ch.qos.logback.core.spi.SequenceNumberGenerator;
027import ch.qos.logback.core.status.StatusManager;
028
029/**
030 * A context is the main anchorage point of all logback components.
031 * 
032 * @author Ceki Gulcu
033 * 
034 */
035public interface Context extends PropertyContainer {
036
037    /**
038     * Return the StatusManager instance in use.
039     * 
040     * @return the {@link StatusManager} instance in use.
041     */
042    StatusManager getStatusManager();
043
044    /**
045     * A Context can act as a store for various objects used by LOGBack components.
046     * 
047     * @return The object stored under 'key'.
048     */
049    Object getObject(String key);
050
051    /**
052     * Store an object under 'key'. If no object can be found, null is returned.
053     * 
054     * @param key
055     * @param value
056     */
057    void putObject(String key, Object value);
058
059    /**
060     * Get all the properties for this context as a Map. Note that the returned cop
061     * might be a copy not the original. Thus, modifying the returned Map will have
062     * no effect (on the original.)
063     * 
064     * @return
065     */
066    // public Map<String, String> getPropertyMap();
067    /**
068     * Get the property of this context.
069     */
070    String getProperty(String key);
071
072    /**
073     * Set a property of this context.
074     */
075    void putProperty(String key, String value);
076
077    /**
078     * Get a copy of the property map
079     * 
080     * @return
081     * @since 0.9.20
082     */
083    Map<String, String> getCopyOfPropertyMap();
084
085    /**
086     * Contexts are named objects.
087     * 
088     * @return the name for this context
089     */
090    String getName();
091
092    /**
093     * The name of the context can be set only once.
094     * 
095     * @param name
096     */
097    void setName(String name);
098
099    /**
100     * The time at which this context was created, expressed in millisecond elapsed
101     * since the epoch (1.1.1970).
102     * 
103     * @return The time as measured when this class was created.
104     */
105    long getBirthTime();
106
107    /**
108     * Object used for synchronization purposes. INTENDED FOR INTERNAL USAGE.
109     */
110    Object getConfigurationLock();
111
112    /**
113     * Returns the ScheduledExecutorService for this context.
114     * 
115     * @return ScheduledExecutorService
116     * @since 1.1.7
117     */
118    // Apparently ScheduledThreadPoolExecutor has limitation where a task cannot be
119    // submitted from within a running task. ThreadPoolExecutor does not have this limitation.
120    // This causes tests failures in
121    // SocketReceiverTest.testDispatchEventForEnabledLevel and
122    // ServerSocketReceiverFunctionalTest.testLogEventFromClient.
123    ScheduledExecutorService getScheduledExecutorService();
124
125    /**
126     * Every context has an ExecutorService which be invoked to execute certain
127     * tasks in a separate thread.
128     *
129     * @return the executor for this context.
130     * @since 1.0.00 (undeprecated in 1.4.7)
131     *
132     */
133    ExecutorService getExecutorService();
134
135    /**
136     * Return an alternate {@link ExecutorService} used for one task per thread execution.
137     * @return ExecutorService
138     */
139    default ExecutorService getAlternateExecutorService() {
140        return getExecutorService();
141    }
142
143    /**
144     * Register a component that participates in the context's life cycle.
145     * <p>
146     * All components registered via this method will be stopped and removed from
147     * the context when the context is reset.
148     * 
149     * @param component the subject component
150     */
151    void register(LifeCycle component);
152
153    /**
154     * Add scheduledFuture parameter to the list of known futures.
155     *
156     * @param scheduledFuture
157     */
158    void addScheduledFuture(ScheduledFuture<?> scheduledFuture);
159
160    SequenceNumberGenerator getSequenceNumberGenerator();
161
162    void setSequenceNumberGenerator(SequenceNumberGenerator sequenceNumberGenerator);
163
164    /**
165     * Add a {@link ConfigurationEventListener} to this context.
166     *
167     * <p>Configuration events are supposed to be rare and listeners to such events rarer still.</p>
168     *
169     * <p>The propagation of {@link ConfigurationEvent configuration events} is intended for internal testing
170     * as well as some coordination between configurators.</p>
171     *
172     *
173     * @param listener
174     * @since 1.3.6/1.4.6
175     */
176    void addConfigurationEventListener(ConfigurationEventListener listener);
177
178    /**
179     * Fire {@link ConfigurationEvent} by invoking {@link #addConfigurationEventListener registered listeners}.
180     *
181     * <p>Note that it is the role of configurators to invoke this method as a context does
182     * not necessarily know when it is being configured.</p>
183     *
184     * @param configurationEvent
185     * @since 1.3.6/1.4.6
186     */
187    void fireConfigurationEvent(ConfigurationEvent configurationEvent);
188
189}