View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  package org.apache.logging.log4j;
18  
19  import java.io.Serializable;
20  import java.util.Collection;
21  import java.util.Locale;
22  import java.util.Objects;
23  import java.util.concurrent.ConcurrentHashMap;
24  import java.util.concurrent.ConcurrentMap;
25  
26  import org.apache.logging.log4j.spi.StandardLevel;
27  
28  /**
29   * Levels used for identifying the severity of an event. Levels are organized from most specific to least:
30   * <ul>
31   * <li>{@link #OFF} (most specific, no logging)</li>
32   * <li>{@link #FATAL} (most specific, little data)</li>
33   * <li>{@link #ERROR}</li>
34   * <li>{@link #WARN}</li>
35   * <li>{@link #INFO}</li>
36   * <li>{@link #DEBUG}</li>
37   * <li>{@link #TRACE} (least specific, a lot of data)</li>
38   * <li>{@link #ALL} (least specific, all data)</li>
39   * </ul>
40   *
41   * Typically, configuring a level in a filter or on a logger will cause logging events of that level and those that are
42   * more specific to pass through the filter. A special level, {@link #ALL}, is guaranteed to capture all levels when
43   * used in logging configurations.
44   */
45  public final class Level implements Comparable<Level>, Serializable {
46  
47      /**
48       * No events will be logged.
49       */
50      public static final Level OFF;
51  
52      /**
53       * A severe error that will prevent the application from continuing.
54       */
55      public static final Level FATAL;
56  
57      /**
58       * An error in the application, possibly recoverable.
59       */
60      public static final Level ERROR;
61  
62      /**
63       * An event that might possible lead to an error.
64       */
65      public static final Level WARN;
66  
67      /**
68       * An event for informational purposes.
69       */
70      public static final Level INFO;
71  
72      /**
73       * A general debugging event.
74       */
75      public static final Level DEBUG;
76  
77      /**
78       * A fine-grained debug message, typically capturing the flow through the application.
79       */
80      public static final Level TRACE;
81  
82      /**
83       * All events should be logged.
84       */
85      public static final Level ALL;
86  
87      /**
88       * @since 2.1
89       */
90      public static final String CATEGORY = "Level";
91  
92      private static final ConcurrentMap<String, Level> LEVELS = new ConcurrentHashMap<>(); // SUPPRESS CHECKSTYLE
93  
94      private static final long serialVersionUID = 1581082L;
95  
96      static {
97          OFF = new Level("OFF", StandardLevel.OFF.intLevel());
98          FATAL = new Level("FATAL", StandardLevel.FATAL.intLevel());
99          ERROR = new Level("ERROR", StandardLevel.ERROR.intLevel());
100         WARN = new Level("WARN", StandardLevel.WARN.intLevel());
101         INFO = new Level("INFO", StandardLevel.INFO.intLevel());
102         DEBUG = new Level("DEBUG", StandardLevel.DEBUG.intLevel());
103         TRACE = new Level("TRACE", StandardLevel.TRACE.intLevel());
104         ALL = new Level("ALL", StandardLevel.ALL.intLevel());
105     }
106 
107     private final String name;
108     private final int intLevel;
109     private final StandardLevel standardLevel;
110 
111     private Level(final String name, final int intLevel) {
112         if (name == null || name.isEmpty()) {
113             throw new IllegalArgumentException("Illegal null Level constant");
114         }
115         if (intLevel < 0) {
116             throw new IllegalArgumentException("Illegal Level int less than zero.");
117         }
118         this.name = name;
119         this.intLevel = intLevel;
120         this.standardLevel = StandardLevel.getStandardLevel(intLevel);
121         if (LEVELS.putIfAbsent(name, this) != null) {
122             throw new IllegalStateException("Level " + name + " has already been defined.");
123         }
124     }
125 
126     /**
127      * Gets the integral value of this Level.
128      *
129      * @return the value of this Level.
130      */
131     public int intLevel() {
132         return this.intLevel;
133     }
134 
135     /**
136      * Gets the standard Level values as an enum.
137      *
138      * @return an enum of the standard Levels.
139      */
140     public StandardLevel getStandardLevel() {
141         return standardLevel;
142     }
143 
144     /**
145      * Compares this level against the levels passed as arguments and returns true if this level is in between the given
146      * levels.
147      *
148      * @param minLevel The minimum level to test.
149      * @param maxLevel The maximum level to test.
150      * @return True true if this level is in between the given levels
151      * @since 2.4
152      */
153     public boolean isInRange(final Level minLevel, final Level maxLevel) {
154         return this.intLevel >= minLevel.intLevel && this.intLevel <= maxLevel.intLevel;
155     }
156 
157     /**
158      * Compares this level against the level passed as an argument and returns true if this level is the same or is less
159      * specific.
160      *
161      * @param level The level to test.
162      * @return True if this level Level is less specific or the same as the given Level.
163      */
164     public boolean isLessSpecificThan(final Level level) {
165         return this.intLevel >= level.intLevel;
166     }
167 
168     /**
169      * Compares this level against the level passed as an argument and returns true if this level is the same or is more
170      * specific.
171      *
172      * @param level The level to test.
173      * @return True if this level Level is more specific or the same as the given Level.
174      */
175     public boolean isMoreSpecificThan(final Level level) {
176         return this.intLevel <= level.intLevel;
177     }
178 
179     @Override
180     @SuppressWarnings("CloneDoesntCallSuperClone")
181     // CHECKSTYLE:OFF
182     public Level clone() throws CloneNotSupportedException {
183         throw new CloneNotSupportedException();
184     }
185     // CHECKSTYLE:ON
186 
187     @Override
188     public int compareTo(final Level other) {
189         return intLevel < other.intLevel ? -1 : (intLevel > other.intLevel ? 1 : 0);
190     }
191 
192     @Override
193     public boolean equals(final Object other) {
194         return other instanceof Level && other == this;
195     }
196 
197     public Class<Level> getDeclaringClass() {
198         return Level.class;
199     }
200 
201     @Override
202     public int hashCode() {
203         return this.name.hashCode();
204     }
205 
206     /**
207      * Gets the symbolic name of this Level. Equivalent to calling {@link #toString()}.
208      *
209      * @return the name of this Level.
210      */
211     public String name() {
212         return this.name;
213     }
214 
215     @Override
216     public String toString() {
217         return this.name;
218     }
219 
220     /**
221      * Retrieves an existing Level or creates on if it didn't previously exist.
222      * 
223      * @param name The name of the level.
224      * @param intValue The integer value for the Level. If the level was previously created this value is ignored.
225      * @return The Level.
226      * @throws java.lang.IllegalArgumentException if the name is null or intValue is less than zero.
227      */
228     public static Level forName(final String name, final int intValue) {
229         final Level level = LEVELS.get(name);
230         if (level != null) {
231             return level;
232         }
233         try {
234             return new Level(name, intValue);
235         } catch (final IllegalStateException ex) {
236             // The level was added by something else so just return that one.
237             return LEVELS.get(name);
238         }
239     }
240 
241     /**
242      * Return the Level associated with the name or null if the Level cannot be found.
243      * 
244      * @param name The name of the Level.
245      * @return The Level or null.
246      */
247     public static Level getLevel(final String name) {
248         return LEVELS.get(name);
249     }
250 
251     /**
252      * Converts the string passed as argument to a level. If the conversion fails, then this method returns
253      * {@link #DEBUG}.
254      *
255      * @param sArg The name of the desired Level.
256      * @return The Level associated with the String.
257      */
258     public static Level toLevel(final String sArg) {
259         return toLevel(sArg, Level.DEBUG);
260     }
261 
262     /**
263      * Converts the string passed as argument to a level. If the conversion fails, then this method returns the value of
264      * <code>defaultLevel</code>.
265      *
266      * @param name The name of the desired Level.
267      * @param defaultLevel The Level to use if the String is invalid.
268      * @return The Level associated with the String.
269      */
270     public static Level toLevel(final String name, final Level defaultLevel) {
271         if (name == null) {
272             return defaultLevel;
273         }
274         final Level level = LEVELS.get(name.toUpperCase(Locale.ENGLISH));
275         return level == null ? defaultLevel : level;
276     }
277 
278     /**
279      * Return an array of all the Levels that have been registered.
280      * 
281      * @return An array of Levels.
282      */
283     public static Level[] values() {
284         final Collection<Level> values = Level.LEVELS.values();
285         return values.toArray(new Level[values.size()]);
286     }
287 
288     /**
289      * Return the Level associated with the name.
290      * 
291      * @param name The name of the Level to return.
292      * @return The Level.
293      * @throws java.lang.NullPointerException if the Level name is {@code null}.
294      * @throws java.lang.IllegalArgumentException if the Level name is not registered.
295      */
296     public static Level valueOf(final String name) {
297         Objects.requireNonNull(name, "No level name given.");
298         final String levelName = name.toUpperCase(Locale.ENGLISH);
299         final Level level = LEVELS.get(levelName);
300         if (level != null) {
301             return level;
302         }
303         throw new IllegalArgumentException("Unknown level constant [" + levelName + "].");
304     }
305 
306     /**
307      * Returns the enum constant of the specified enum type with the specified name. The name must match exactly an
308      * identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
309      *
310      * @param enumType the {@code Class} object of the enum type from which to return a constant
311      * @param name the name of the constant to return
312      * @param <T> The enum type whose constant is to be returned
313      * @return the enum constant of the specified enum type with the specified name
314      * @throws java.lang.IllegalArgumentException if the specified enum type has no constant with the specified name, or
315      *             the specified class object does not represent an enum type
316      * @throws java.lang.NullPointerException if {@code enumType} or {@code name} are {@code null}
317      * @see java.lang.Enum#valueOf(Class, String)
318      */
319     public static <T extends Enum<T>> T valueOf(final Class<T> enumType, final String name) {
320         return Enum.valueOf(enumType, name);
321     }
322 
323     // for deserialization
324     protected Object readResolve() {
325         return Level.valueOf(this.name);
326     }
327 }