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;
018
019import java.io.Serializable;
020import java.util.Collection;
021import java.util.Locale;
022import java.util.Objects;
023import java.util.concurrent.ConcurrentHashMap;
024import java.util.concurrent.ConcurrentMap;
025
026import org.apache.logging.log4j.spi.StandardLevel;
027import org.apache.logging.log4j.util.Strings;
028
029/**
030 * Levels used for identifying the severity of an event. Levels are organized from most specific to least:
031 * <ul>
032 * <li>{@link #OFF} (most specific, no logging)</li>
033 * <li>{@link #FATAL} (most specific, little data)</li>
034 * <li>{@link #ERROR}</li>
035 * <li>{@link #WARN}</li>
036 * <li>{@link #INFO}</li>
037 * <li>{@link #DEBUG}</li>
038 * <li>{@link #TRACE} (least specific, a lot of data)</li>
039 * <li>{@link #ALL} (least specific, all data)</li>
040 * </ul>
041 *
042 * Typically, configuring a level in a filter or on a logger will cause logging events of that level and those that are
043 * more specific to pass through the filter. A special level, {@link #ALL}, is guaranteed to capture all levels when
044 * used in logging configurations.
045 */
046public final class Level implements Comparable<Level>, Serializable {
047
048    /**
049     * No events will be logged.
050     */
051    public static final Level OFF;
052
053    /**
054     * A severe error that will prevent the application from continuing.
055     */
056    public static final Level FATAL;
057
058    /**
059     * An error in the application, possibly recoverable.
060     */
061    public static final Level ERROR;
062
063    /**
064     * An event that might possible lead to an error.
065     */
066    public static final Level WARN;
067
068    /**
069     * An event for informational purposes.
070     */
071    public static final Level INFO;
072
073    /**
074     * A general debugging event.
075     */
076    public static final Level DEBUG;
077
078    /**
079     * A fine-grained debug message, typically capturing the flow through the application.
080     */
081    public static final Level TRACE;
082
083    /**
084     * All events should be logged.
085     */
086    public static final Level ALL;
087
088    /**
089     * @since 2.1
090     */
091    public static final String CATEGORY = "Level";
092
093    private static final ConcurrentMap<String, Level> LEVELS = new ConcurrentHashMap<>(); // SUPPRESS CHECKSTYLE
094
095    private static final long serialVersionUID = 1581082L;
096
097    static {
098        OFF = new Level("OFF", StandardLevel.OFF.intLevel());
099        FATAL = new Level("FATAL", StandardLevel.FATAL.intLevel());
100        ERROR = new Level("ERROR", StandardLevel.ERROR.intLevel());
101        WARN = new Level("WARN", StandardLevel.WARN.intLevel());
102        INFO = new Level("INFO", StandardLevel.INFO.intLevel());
103        DEBUG = new Level("DEBUG", StandardLevel.DEBUG.intLevel());
104        TRACE = new Level("TRACE", StandardLevel.TRACE.intLevel());
105        ALL = new Level("ALL", StandardLevel.ALL.intLevel());
106    }
107
108    private final String name;
109    private final int intLevel;
110    private final StandardLevel standardLevel;
111
112    private Level(final String name, final int intLevel) {
113        if (Strings.isEmpty(name)) {
114            throw new IllegalArgumentException("Illegal null or empty Level name.");
115        }
116        if (intLevel < 0) {
117            throw new IllegalArgumentException("Illegal Level int less than zero.");
118        }
119        this.name = name;
120        this.intLevel = intLevel;
121        this.standardLevel = StandardLevel.getStandardLevel(intLevel);
122        if (LEVELS.putIfAbsent(name, this) != null) {
123            throw new IllegalStateException("Level " + name + " has already been defined.");
124        }
125    }
126
127    /**
128     * Gets the integral value of this Level.
129     *
130     * @return the value of this Level.
131     */
132    public int intLevel() {
133        return this.intLevel;
134    }
135
136    /**
137     * Gets the standard Level values as an enum.
138     *
139     * @return an enum of the standard Levels.
140     */
141    public StandardLevel getStandardLevel() {
142        return standardLevel;
143    }
144
145    /**
146     * Compares this level against the levels passed as arguments and returns true if this level is in between the given
147     * levels.
148     *
149     * @param minLevel The minimum level to test.
150     * @param maxLevel The maximum level to test.
151     * @return True true if this level is in between the given levels
152     * @since 2.4
153     */
154    public boolean isInRange(final Level minLevel, final Level maxLevel) {
155        return this.intLevel >= minLevel.intLevel && this.intLevel <= maxLevel.intLevel;
156    }
157
158    /**
159     * Compares this level against the level passed as an argument and returns true if this level is the same or is less
160     * specific.
161     * <p>
162     * Concretely, {@link #TRACE} is less specific than {@link #DEBUG}, which is less specific than {@link #INFO},
163     * etc., until {@link #FATAL}, and finally {@link #OFF}, which is the most specific standard level.
164     * The least specific level is {@link #ALL}.
165     * </p>
166     *
167     * @param level The level to test.
168     * @return True if this level Level is less specific or the same as the given Level.
169     */
170    public boolean isLessSpecificThan(final Level level) {
171        return this.intLevel >= level.intLevel;
172    }
173
174    /**
175     * Compares this level against the level passed as an argument and returns true if this level is the same or is more
176     * specific.
177     * <p>
178     * Concretely, {@link #FATAL} is more specific than {@link #ERROR}, which is more specific than {@link #WARN},
179     * etc., until {@link #TRACE}, and finally {@link #ALL}, which is the least specific standard level.
180     * The most specific level is {@link #OFF}.
181     * </p>
182     *
183     * @param level The level to test.
184     * @return True if this level Level is more specific or the same as the given Level.
185     */
186    public boolean isMoreSpecificThan(final Level level) {
187        return this.intLevel <= level.intLevel;
188    }
189
190    @Override
191    @SuppressWarnings("CloneDoesntCallSuperClone")
192    // CHECKSTYLE:OFF
193    public Level clone() throws CloneNotSupportedException {
194        throw new CloneNotSupportedException();
195    }
196    // CHECKSTYLE:ON
197
198    @Override
199    public int compareTo(final Level other) {
200        return intLevel < other.intLevel ? -1 : (intLevel > other.intLevel ? 1 : 0);
201    }
202
203    @Override
204    public boolean equals(final Object other) {
205        return other instanceof Level && other == this;
206    }
207
208    public Class<Level> getDeclaringClass() {
209        return Level.class;
210    }
211
212    @Override
213    public int hashCode() {
214        return this.name.hashCode();
215    }
216
217    /**
218     * Gets the symbolic name of this Level. Equivalent to calling {@link #toString()}.
219     *
220     * @return the name of this Level.
221     */
222    public String name() {
223        return this.name;
224    }
225
226    @Override
227    public String toString() {
228        return this.name;
229    }
230
231    /**
232     * Retrieves an existing Level or creates on if it didn't previously exist.
233     *
234     * @param name The name of the level.
235     * @param intValue The integer value for the Level. If the level was previously created this value is ignored.
236     * @return The Level.
237     * @throws java.lang.IllegalArgumentException if the name is null or intValue is less than zero.
238     */
239    public static Level forName(final String name, final int intValue) {
240        final Level level = LEVELS.get(name);
241        if (level != null) {
242            return level;
243        }
244        try {
245            return new Level(name, intValue);
246        } catch (final IllegalStateException ex) {
247            // The level was added by something else so just return that one.
248            return LEVELS.get(name);
249        }
250    }
251
252    /**
253     * Return the Level associated with the name or null if the Level cannot be found.
254     *
255     * @param name The name of the Level.
256     * @return The Level or null.
257     */
258    public static Level getLevel(final String name) {
259        return LEVELS.get(name);
260    }
261
262    /**
263     * Converts the string passed as argument to a level. If the conversion fails, then this method returns
264     * {@link #DEBUG}.
265     *
266     * @param sArg The name of the desired Level.
267     * @return The Level associated with the String.
268     */
269    public static Level toLevel(final String sArg) {
270        return toLevel(sArg, Level.DEBUG);
271    }
272
273    /**
274     * Converts the string passed as argument to a level. If the conversion fails, then this method returns the value of
275     * <code>defaultLevel</code>.
276     *
277     * @param name The name of the desired Level.
278     * @param defaultLevel The Level to use if the String is invalid.
279     * @return The Level associated with the String.
280     */
281    public static Level toLevel(final String name, final Level defaultLevel) {
282        if (name == null) {
283            return defaultLevel;
284        }
285        final Level level = LEVELS.get(name.toUpperCase(Locale.ENGLISH));
286        return level == null ? defaultLevel : level;
287    }
288
289    /**
290     * Return an array of all the Levels that have been registered.
291     *
292     * @return An array of Levels.
293     */
294    public static Level[] values() {
295        final Collection<Level> values = Level.LEVELS.values();
296        return values.toArray(new Level[values.size()]);
297    }
298
299    /**
300     * Return the Level associated with the name.
301     *
302     * @param name The name of the Level to return.
303     * @return The Level.
304     * @throws java.lang.NullPointerException if the Level name is {@code null}.
305     * @throws java.lang.IllegalArgumentException if the Level name is not registered.
306     */
307    public static Level valueOf(final String name) {
308        Objects.requireNonNull(name, "No level name given.");
309        final String levelName = name.toUpperCase(Locale.ENGLISH);
310        final Level level = LEVELS.get(levelName);
311        if (level != null) {
312            return level;
313        }
314        throw new IllegalArgumentException("Unknown level constant [" + levelName + "].");
315    }
316
317    /**
318     * Returns the enum constant of the specified enum type with the specified name. The name must match exactly an
319     * identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
320     *
321     * @param enumType the {@code Class} object of the enum type from which to return a constant
322     * @param name the name of the constant to return
323     * @param <T> The enum type whose constant is to be returned
324     * @return the enum constant of the specified enum type with the specified name
325     * @throws java.lang.IllegalArgumentException if the specified enum type has no constant with the specified name, or
326     *             the specified class object does not represent an enum type
327     * @throws java.lang.NullPointerException if {@code enumType} or {@code name} are {@code null}
328     * @see java.lang.Enum#valueOf(Class, String)
329     */
330    public static <T extends Enum<T>> T valueOf(final Class<T> enumType, final String name) {
331        return Enum.valueOf(enumType, name);
332    }
333
334    // for deserialization
335    protected Object readResolve() {
336        return Level.valueOf(this.name);
337    }
338}