7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util.logging;
27 import java.util.ResourceBundle;
28
29 /**
30 * The Level class defines a set of standard logging levels that
31 * can be used to control logging output. The logging Level objects
32 * are ordered and are specified by ordered integers. Enabling logging
33 * at a given level also enables logging at all higher levels.
34 * <p>
35 * Clients should normally use the predefined Level constants such
36 * as Level.SEVERE.
37 * <p>
38 * The levels in descending order are:
39 * <ul>
40 * <li>SEVERE (highest value)
41 * <li>WARNING
42 * <li>INFO
43 * <li>CONFIG
44 * <li>FINE
45 * <li>FINER
46 * <li>FINEST (lowest value)
47 * </ul>
48 * In addition there is a level OFF that can be used to turn
49 * off logging, and a level ALL that can be used to enable
50 * logging of all messages.
51 * <p>
52 * It is possible for third parties to define additional logging
53 * levels by subclassing Level. In such cases subclasses should
54 * take care to chose unique integer level values and to ensure that
55 * they maintain the Object uniqueness property across serialization
56 * by defining a suitable readResolve method.
57 *
58 * @since 1.4
59 */
60
61 public class Level implements java.io.Serializable {
62 private static java.util.ArrayList<Level> known = new java.util.ArrayList<>();
63 private static String defaultBundle = "sun.util.logging.resources.logging";
64
65 /**
66 * @serial The non-localized name of the level.
67 */
68 private final String name;
69
70 /**
71 * @serial The integer value of the level.
72 */
73 private final int value;
74
75 /**
76 * @serial The resource bundle name to be used in localizing the level name.
77 */
78 private final String resourceBundleName;
79
80 /**
81 * OFF is a special level that can be used to turn off logging.
82 * This level is initialized to <CODE>Integer.MAX_VALUE</CODE>.
83 */
84 public static final Level OFF = new Level("OFF",Integer.MAX_VALUE, defaultBundle);
85
86 /**
87 * SEVERE is a message level indicating a serious failure.
88 * <p>
89 * In general SEVERE messages should describe events that are
90 * of considerable importance and which will prevent normal
91 * program execution. They should be reasonably intelligible
92 * to end users and to system administrators.
93 * This level is initialized to <CODE>1000</CODE>.
94 */
95 public static final Level SEVERE = new Level("SEVERE",1000, defaultBundle);
96
97 /**
98 * WARNING is a message level indicating a potential problem.
99 * <p>
185 }
186
187 /**
188 * Create a named Level with a given integer value and a
189 * given localization resource name.
190 * <p>
191 * @param name the name of the Level, for example "SEVERE".
192 * @param value an integer value for the level.
193 * @param resourceBundleName name of a resource bundle to use in
194 * localizing the given name. If the resourceBundleName is null
195 * or an empty string, it is ignored.
196 * @throws NullPointerException if the name is null
197 */
198 protected Level(String name, int value, String resourceBundleName) {
199 if (name == null) {
200 throw new NullPointerException();
201 }
202 this.name = name;
203 this.value = value;
204 this.resourceBundleName = resourceBundleName;
205 synchronized (Level.class) {
206 known.add(this);
207 }
208 }
209
210 /**
211 * Return the level's localization resource bundle name, or
212 * null if no localization bundle is defined.
213 *
214 * @return localization resource bundle name
215 */
216 public String getResourceBundleName() {
217 return resourceBundleName;
218 }
219
220 /**
221 * Return the non-localized string name of the Level.
222 *
223 * @return non-localized name
224 */
225 public String getName() {
226 return name;
227 }
228
229 /**
230 * Return the localized string name of the Level, for
231 * the current default locale.
232 * <p>
233 * If no localization information is available, the
234 * non-localized name is returned.
235 *
236 * @return localized name
237 */
238 public String getLocalizedName() {
239 try {
240 ResourceBundle rb = ResourceBundle.getBundle(resourceBundleName);
241 return rb.getString(name);
242 } catch (Exception ex) {
243 return name;
244 }
245 }
246
247 /**
248 * Returns a string representation of this Level.
249 *
250 * @return the non-localized name of the Level, for example "INFO".
251 */
252 public final String toString() {
253 return name;
254 }
255
256 /**
257 * Get the integer value for this level. This integer value
258 * can be used for efficient ordering comparisons between
259 * Level objects.
260 * @return the integer value for this level.
261 */
262 public final int intValue() {
263 return value;
264 }
265
266 private static final long serialVersionUID = -8176160795706313070L;
267
268 // Serialization magic to prevent "doppelgangers".
269 // This is a performance optimization.
270 private Object readResolve() {
271 synchronized (Level.class) {
272 for (int i = 0; i < known.size(); i++) {
273 Level other = known.get(i);
274 if (this.name.equals(other.name) && this.value == other.value
275 && (this.resourceBundleName == other.resourceBundleName ||
276 (this.resourceBundleName != null &&
277 this.resourceBundleName.equals(other.resourceBundleName)))) {
278 return other;
279 }
280 }
281 // Woops. Whoever sent us this object knows
282 // about a new log level. Add it to our list.
283 known.add(this);
284 return this;
285 }
286 }
287
288 /**
289 * Parse a level name string into a Level.
290 * <p>
291 * The argument string may consist of either a level name
292 * or an integer value.
293 * <p>
294 * For example:
295 * <ul>
296 * <li> "SEVERE"
297 * <li> "1000"
298 * </ul>
299 * @param name string to be parsed
300 * @throws NullPointerException if the name is null
301 * @throws IllegalArgumentException if the value is not valid.
302 * Valid values are integers between <CODE>Integer.MIN_VALUE</CODE>
303 * and <CODE>Integer.MAX_VALUE</CODE>, and all known level names.
304 * Known names are the levels defined by this class (e.g., <CODE>FINE</CODE>,
305 * <CODE>FINER</CODE>, <CODE>FINEST</CODE>), or created by this class with
306 * appropriate package access, or new levels defined or created
307 * by subclasses.
308 *
309 * @return The parsed value. Passing an integer that corresponds to a known name
310 * (e.g., 700) will return the associated name (e.g., <CODE>CONFIG</CODE>).
311 * Passing an integer that does not (e.g., 1) will return a new level name
312 * initialized to that value.
313 */
314 public static synchronized Level parse(String name) throws IllegalArgumentException {
315 // Check that name is not null.
316 name.length();
317
318 // Look for a known Level with the given non-localized name.
319 for (int i = 0; i < known.size(); i++) {
320 Level l = known.get(i);
321 if (name.equals(l.name)) {
322 return l;
323 }
324 }
325
326 // Now, check if the given name is an integer. If so,
327 // first look for a Level with the given value and then
328 // if necessary create one.
329 try {
330 int x = Integer.parseInt(name);
331 for (int i = 0; i < known.size(); i++) {
332 Level l = known.get(i);
333 if (l.value == x) {
334 return l;
335 }
336 }
337 // Create a new Level.
338 return new Level(name, x);
339 } catch (NumberFormatException ex) {
340 // Not an integer.
341 // Drop through.
342 }
343
344 // Finally, look for a known level with the given localized name,
345 // in the current default locale.
346 // This is relatively expensive, but not excessively so.
347 for (int i = 0; i < known.size(); i++) {
348 Level l = known.get(i);
349 if (name.equals(l.getLocalizedName())) {
350 return l;
351 }
352 }
353
354 // OK, we've tried everything and failed
355 throw new IllegalArgumentException("Bad level \"" + name + "\"");
356 }
357
358 /**
359 * Compare two objects for value equality.
360 * @return true if and only if the two objects have the same level value.
361 */
362 public boolean equals(Object ox) {
363 try {
364 Level lx = (Level)ox;
365 return (lx.value == this.value);
366 } catch (Exception ex) {
367 return false;
368 }
369 }
370
371 /**
372 * Generate a hashcode.
373 * @return a hashcode based on the level value
374 */
375 public int hashCode() {
376 return this.value;
377 }
378 }
|
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util.logging;
27 import java.util.ArrayList;
28 import java.util.HashMap;
29 import java.util.List;
30 import java.util.Map;
31 import java.util.ResourceBundle;
32
33 /**
34 * The Level class defines a set of standard logging levels that
35 * can be used to control logging output. The logging Level objects
36 * are ordered and are specified by ordered integers. Enabling logging
37 * at a given level also enables logging at all higher levels.
38 * <p>
39 * Clients should normally use the predefined Level constants such
40 * as Level.SEVERE.
41 * <p>
42 * The levels in descending order are:
43 * <ul>
44 * <li>SEVERE (highest value)
45 * <li>WARNING
46 * <li>INFO
47 * <li>CONFIG
48 * <li>FINE
49 * <li>FINER
50 * <li>FINEST (lowest value)
51 * </ul>
52 * In addition there is a level OFF that can be used to turn
53 * off logging, and a level ALL that can be used to enable
54 * logging of all messages.
55 * <p>
56 * It is possible for third parties to define additional logging
57 * levels by subclassing Level. In such cases subclasses should
58 * take care to chose unique integer level values and to ensure that
59 * they maintain the Object uniqueness property across serialization
60 * by defining a suitable readResolve method.
61 *
62 * @since 1.4
63 */
64
65 public class Level implements java.io.Serializable {
66 private static String defaultBundle = "sun.util.logging.resources.logging";
67
68 /**
69 * @serial The non-localized name of the level.
70 */
71 private final String name;
72
73 /**
74 * @serial The integer value of the level.
75 */
76 private final int value;
77
78 /**
79 * @serial The resource bundle name to be used in localizing the level name.
80 */
81 private final String resourceBundleName;
82
83 // localized level name
84 private String localizedLevelName;
85
86 /**
87 * OFF is a special level that can be used to turn off logging.
88 * This level is initialized to <CODE>Integer.MAX_VALUE</CODE>.
89 */
90 public static final Level OFF = new Level("OFF",Integer.MAX_VALUE, defaultBundle);
91
92 /**
93 * SEVERE is a message level indicating a serious failure.
94 * <p>
95 * In general SEVERE messages should describe events that are
96 * of considerable importance and which will prevent normal
97 * program execution. They should be reasonably intelligible
98 * to end users and to system administrators.
99 * This level is initialized to <CODE>1000</CODE>.
100 */
101 public static final Level SEVERE = new Level("SEVERE",1000, defaultBundle);
102
103 /**
104 * WARNING is a message level indicating a potential problem.
105 * <p>
191 }
192
193 /**
194 * Create a named Level with a given integer value and a
195 * given localization resource name.
196 * <p>
197 * @param name the name of the Level, for example "SEVERE".
198 * @param value an integer value for the level.
199 * @param resourceBundleName name of a resource bundle to use in
200 * localizing the given name. If the resourceBundleName is null
201 * or an empty string, it is ignored.
202 * @throws NullPointerException if the name is null
203 */
204 protected Level(String name, int value, String resourceBundleName) {
205 if (name == null) {
206 throw new NullPointerException();
207 }
208 this.name = name;
209 this.value = value;
210 this.resourceBundleName = resourceBundleName;
211 this.localizedLevelName = resourceBundleName == null ? name : null;
212 KnownLevel.add(this);
213 }
214
215 /**
216 * Return the level's localization resource bundle name, or
217 * null if no localization bundle is defined.
218 *
219 * @return localization resource bundle name
220 */
221 public String getResourceBundleName() {
222 return resourceBundleName;
223 }
224
225 /**
226 * Return the non-localized string name of the Level.
227 *
228 * @return non-localized name
229 */
230 public String getName() {
231 return name;
232 }
233
234 /**
235 * Return the localized string name of the Level, for
236 * the current default locale.
237 * <p>
238 * If no localization information is available, the
239 * non-localized name is returned.
240 *
241 * @return localized name
242 */
243 public String getLocalizedName() {
244 return getLocalizedLevelName();
245 }
246
247 // package-private getLevelName() is used by the implementation
248 // instead of getName() to avoid calling the subclass's version
249 final String getLevelName() {
250 return this.name;
251 }
252
253 final synchronized String getLocalizedLevelName() {
254 if (localizedLevelName != null) {
255 return localizedLevelName;
256 }
257
258 try {
259 ResourceBundle rb = ResourceBundle.getBundle(resourceBundleName);
260 localizedLevelName = rb.getString(name);
261 } catch (Exception ex) {
262 localizedLevelName = name;
263 }
264 return localizedLevelName;
265 }
266
267 // Returns a mirrored Level object that matches the given name as
268 // specified in the Level.parse method. Returns null if not found.
269 //
270 // It returns the same Level object as the one returned by Level.parse
271 // method if the given name is a non-localized name or integer.
272 //
273 // If the name is a localized name, findLevel and parse method may
274 // return a different level value if there is a custom Level subclass
275 // that overrides Level.getLocalizedName() to return a different string
276 // than what's returned by the default implementation.
277 //
278 static Level findLevel(String name) {
279 if (name == null) {
280 throw new NullPointerException();
281 }
282
283 KnownLevel level;
284
285 // Look for a known Level with the given non-localized name.
286 level = KnownLevel.findByName(name);
287 if (level != null) {
288 return level.mirroredLevel;
289 }
290
291 // Now, check if the given name is an integer. If so,
292 // first look for a Level with the given value and then
293 // if necessary create one.
294 try {
295 int x = Integer.parseInt(name);
296 level = KnownLevel.findByValue(x);
297 if (level == null) {
298 // add new Level
299 Level levelObject = new Level(name, x);
300 level = KnownLevel.findByValue(x);
301 }
302 return level.mirroredLevel;
303 } catch (NumberFormatException ex) {
304 // Not an integer.
305 // Drop through.
306 }
307
308 level = KnownLevel.findByLocalizedLevelName(name);
309 if (level != null) {
310 return level.mirroredLevel;
311 }
312
313 return null;
314 }
315
316 /**
317 * Returns a string representation of this Level.
318 *
319 * @return the non-localized name of the Level, for example "INFO".
320 */
321 public final String toString() {
322 return name;
323 }
324
325 /**
326 * Get the integer value for this level. This integer value
327 * can be used for efficient ordering comparisons between
328 * Level objects.
329 * @return the integer value for this level.
330 */
331 public final int intValue() {
332 return value;
333 }
334
335 private static final long serialVersionUID = -8176160795706313070L;
336
337 // Serialization magic to prevent "doppelgangers".
338 // This is a performance optimization.
339 private Object readResolve() {
340 KnownLevel o = KnownLevel.matches(this);
341 if (o != null) {
342 return o.levelObject;
343 }
344
345 // Woops. Whoever sent us this object knows
346 // about a new log level. Add it to our list.
347 Level level = new Level(this.name, this.value, this.resourceBundleName);
348 return level;
349 }
350
351 /**
352 * Parse a level name string into a Level.
353 * <p>
354 * The argument string may consist of either a level name
355 * or an integer value.
356 * <p>
357 * For example:
358 * <ul>
359 * <li> "SEVERE"
360 * <li> "1000"
361 * </ul>
362 *
363 * @param name string to be parsed
364 * @throws NullPointerException if the name is null
365 * @throws IllegalArgumentException if the value is not valid.
366 * Valid values are integers between <CODE>Integer.MIN_VALUE</CODE>
367 * and <CODE>Integer.MAX_VALUE</CODE>, and all known level names.
368 * Known names are the levels defined by this class (e.g., <CODE>FINE</CODE>,
369 * <CODE>FINER</CODE>, <CODE>FINEST</CODE>), or created by this class with
370 * appropriate package access, or new levels defined or created
371 * by subclasses.
372 *
373 * @return The parsed value. Passing an integer that corresponds to a known name
374 * (e.g., 700) will return the associated name (e.g., <CODE>CONFIG</CODE>).
375 * Passing an integer that does not (e.g., 1) will return a new level name
376 * initialized to that value.
377 */
378 public static synchronized Level parse(String name) throws IllegalArgumentException {
379 // Check that name is not null.
380 name.length();
381
382 KnownLevel level;
383
384 // Look for a known Level with the given non-localized name.
385 level = KnownLevel.findByName(name);
386 if (level != null) {
387 return level.levelObject;
388 }
389
390 // Now, check if the given name is an integer. If so,
391 // first look for a Level with the given value and then
392 // if necessary create one.
393 try {
394 int x = Integer.parseInt(name);
395 level = KnownLevel.findByValue(x);
396 if (level == null) {
397 // add new Level
398 Level levelObject = new Level(name, x);
399 level = KnownLevel.findByValue(x);
400 }
401 return level.levelObject;
402 } catch (NumberFormatException ex) {
403 // Not an integer.
404 // Drop through.
405 }
406
407 // Finally, look for a known level with the given localized name,
408 // in the current default locale.
409 // This is relatively expensive, but not excessively so.
410 level = KnownLevel.findByLocalizedName(name);
411 if (level != null) {
412 return level.levelObject;
413 }
414
415 // OK, we've tried everything and failed
416 throw new IllegalArgumentException("Bad level \"" + name + "\"");
417 }
418
419 /**
420 * Compare two objects for value equality.
421 * @return true if and only if the two objects have the same level value.
422 */
423 public boolean equals(Object ox) {
424 try {
425 Level lx = (Level)ox;
426 return (lx.value == this.value);
427 } catch (Exception ex) {
428 return false;
429 }
430 }
431
432 /**
433 * Generate a hashcode.
434 * @return a hashcode based on the level value
435 */
436 public int hashCode() {
437 return this.value;
438 }
439
440 // KnownLevel class maintains the global list of all known levels.
441 // The API allows multiple custom Level instances of the same name/value
442 // be created. This class provides convenient methods to find a level
443 // by a given name, by a given value, or by a given localized name.
444 //
445 // KnownLevel wraps the following Level objects:
446 // 1. levelObject: standard Level object or custom Level object
447 // 2. mirroredLevel: Level object representing the level specified in the
448 // logging configuration.
449 //
450 // Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
451 // are non-final but the name and resource bundle name are parameters to
452 // the Level constructor. Use the mirroredLevel object instead of the
453 // levelObject to prevent the logging framework to execute foreign code
454 // implemented by untrusted Level subclass.
455 //
456 // Implementation Notes:
457 // If Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
458 // were final, the following KnownLevel implementation can be removed.
459 // Future API change should take this into consideration.
460 static final class KnownLevel {
461 private static Map<String, List<KnownLevel>> nameToLevels = new HashMap<>();
462 private static Map<Integer, List<KnownLevel>> intToLevels = new HashMap<>();
463 final Level levelObject; // instance of Level class or Level subclass
464 final Level mirroredLevel; // instance of Level class
465 KnownLevel(Level l) {
466 this.levelObject = l;
467 if (l.getClass() == Level.class) {
468 this.mirroredLevel = l;
469 } else {
470 this.mirroredLevel = new Level(l.name, l.value, l.resourceBundleName);
471 }
472 }
473
474 static synchronized void add(Level l) {
475 // the mirroredLevel object is always added to the list
476 // before the custom Level instance
477 KnownLevel o = new KnownLevel(l);
478 List<KnownLevel> list = nameToLevels.get(l.name);
479 if (list == null) {
480 list = new ArrayList<>();
481 nameToLevels.put(l.name, list);
482 }
483 list.add(o);
484
485 list = intToLevels.get(l.value);
486 if (list == null) {
487 list = new ArrayList<>();
488 intToLevels.put(l.value, list);
489 }
490 list.add(o);
491 }
492
493 // Returns a KnownLevel with the given non-localized name.
494 static synchronized KnownLevel findByName(String name) {
495 List<KnownLevel> list = nameToLevels.get(name);
496 if (list != null) {
497 return list.get(0);
498 }
499 return null;
500 }
501
502 // Returns a KnownLevel with the given value.
503 static synchronized KnownLevel findByValue(int value) {
504 List<KnownLevel> list = intToLevels.get(value);
505 if (list != null) {
506 return list.get(0);
507 }
508 return null;
509 }
510
511 // Returns a KnownLevel with the given localized name matching
512 // by calling the Level.getLocalizedLevelName() method (i.e. found
513 // from the resourceBundle associated with the Level object).
514 // This method does not call Level.getLocalizedName() that may
515 // be overridden in a subclass implementation
516 static synchronized KnownLevel findByLocalizedLevelName(String name) {
517 for (List<KnownLevel> levels : nameToLevels.values()) {
518 for (KnownLevel l : levels) {
519 String lname = l.levelObject.getLocalizedLevelName();
520 if (name.equals(lname)) {
521 return l;
522 }
523 }
524 }
525 return null;
526 }
527
528 // Returns a KnownLevel with the given localized name matching
529 // by calling the Level.getLocalizedName() method
530 static synchronized KnownLevel findByLocalizedName(String name) {
531 for (List<KnownLevel> levels : nameToLevels.values()) {
532 for (KnownLevel l : levels) {
533 String lname = l.levelObject.getLocalizedName();
534 if (name.equals(lname)) {
535 return l;
536 }
537 }
538 }
539 return null;
540 }
541
542 static synchronized KnownLevel matches(Level l) {
543 List<KnownLevel> list = nameToLevels.get(l.name);
544 if (list != null) {
545 for (KnownLevel level : list) {
546 Level other = level.mirroredLevel;
547 if (l.value == other.value &&
548 (l.resourceBundleName == other.resourceBundleName ||
549 (l.resourceBundleName != null &&
550 l.resourceBundleName.equals(other.resourceBundleName)))) {
551 return level;
552 }
553 }
554 }
555 return null;
556 }
557 }
558
559 }
|