Deprecation


1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.util;
17  
18  import org.apache.avalon.framework.logger.ConsoleLogger;
19  import org.apache.avalon.framework.logger.Logger;
20  import org.apache.commons.lang.enums.ValuedEnum;
21  
22  /**
23   * This class provides a special static "deprecation" logger.
24   * All deprecated code should use this logger to log messages into the 
25   * deprecation logger. This makes it easier for users to find out if they're 
26   * using deprecated stuff.
27   * <p>
28   * Additionally, it is possible to set the forbidden level of deprecation messages (default
29   * is to forbid ERROR, i.e. allow up to WARN). Messages equal to or above the forbidden level
30   * will lead to throwing a {@link DeprecationException}. Setting the forbidden level to
31   * FATAL_ERROR allows running legacy applications using deprecated features (tolerant mode), and
32   * setting the forbidden level to DEBUG will run in strict mode, forbidding all deprecations.
33   * <p>
34   * Note that according to the above, issuing a fatalError log always raises an exception, and
35   * can therefore be used when detecting old features that have been totally removed.
36   *
37   * @version $Id: Deprecation.java 157441 2005-03-14 18:03:29Z sylvain $
38   */
39  public class Deprecation {
40      
41      /**
42       * The deprecation logger.
43       */
44      public static final Logger logger = new LoggerWrapper(new ConsoleLogger());
45      
46      private static final int DEBUG_VALUE = 0;
47      private static final int INFO_VALUE = 1;
48      private static final int WARN_VALUE = 2;
49      private static final int ERROR_VALUE = 3;
50      private static final int FATAL_VALUE = 3;
51      private static final int FATAL_ERROR_VALUE = 4;
52      
53      /**
54       * Debug deprecation messages indicate features that are no more considered "current"
55       * or "best practice", but for which no removal is currently foreseen.
56       */
57      public static final LogLevel DEBUG = new LogLevel("DEBUG", DEBUG_VALUE);
58  
59      /**
60       * Info deprecation messages indicate features that are no more considered "current"
61       * or "best practice", and that will probably be removed in future releases.
62       */
63      public static final LogLevel INFO = new LogLevel("INFO", INFO_VALUE);
64  
65      /**
66       * Warning deprecation messages indicate features that will be removed in the next major
67       * version (e.g. 2.1.x --> 2.2.0). Such features should not be used if the application is
68       * planned to be migrated to newer Cocoon versions.
69       */
70      public static final LogLevel WARN = new LogLevel("WARN", WARN_VALUE);
71  
72      /**
73       * Error deprecation messages indicate features that will be removed in the next minor
74       * version (e.g. 2.1.6 --> 2.1.7). Although still functional, users are stronly invited to
75       * not use them.
76       */
77      public static final LogLevel ERROR = new LogLevel("ERROR", ERROR_VALUE);
78  
79      /**
80       * Fatal error deprecation messages indicate features that used to exist but have been removed
81       * in the current version. Logging such a message always throws a {@link DeprecationException}.
82       */
83      public static final LogLevel FATAL_ERROR = new LogLevel("FATAL_ERROR", FATAL_ERROR_VALUE);
84      
85      public static final class LogLevel extends ValuedEnum {
86          private LogLevel(String   text, int value) {
87              super(text, value);
88          }
89          
90          public static LogLevel getLevel(String   level) {
91              return (LogLevel)ValuedEnum.getEnum(LogLevel.class, level);
92          }
93      }
94  
95      public static void setLogger(Logger newLogger) {
96          // Note: the "logger" attribute is not of type LoggerWrapper so that it appears
97          // as a standard Logger in the javadocs.
98          ((LoggerWrapper)logger).setLogger(newLogger);
99      }
100     
101     public static void setForbiddenLevel(LogLevel level) {
102         // If null, reset to the default level
103         if (level == null) {
104             level = ERROR;
105         }
106         ((LoggerWrapper)logger).setForbiddenLevel(level);
107     }
108     
109     /**
110      * Wraps a logger, and throws an DeprecatedException if the message level is
111      * higher than the allowed one.
112      */
113     private static class LoggerWrapper implements Logger {
114         
115         private Logger realLogger;
116         // up to warn is allowed
117         private int forbiddenLevel = ERROR_VALUE;
118         
119         public LoggerWrapper(Logger logger) {
120             this.realLogger = logger;
121         }
122         
123         public void setLogger(Logger logger) {
124             // Unwrap a wrapped logger
125             while(logger instanceof LoggerWrapper) {
126                 logger = ((LoggerWrapper)logger).realLogger;
127             }
128             this.realLogger = logger;
129         }
130         
131         public void setForbiddenLevel(LogLevel level) {
132             this.forbiddenLevel = level.getValue();
133         }
134         
135         private void throwException(int level, String   message) {
136             if (level >= this.forbiddenLevel) {
137                 throw new DeprecationException(message);
138             }
139         }
140         
141         private boolean isThrowingException(int level) {
142             return level >= this.forbiddenLevel;
143         }
144         
145         public void debug(String   message) {
146             realLogger.debug(message);
147             throwException(DEBUG_VALUE, message);
148         }
149         public void debug(String   message, Throwable   thr) {
150             realLogger.debug(message, thr);
151             throwException(DEBUG_VALUE, message);
152         }
153         public void info(String   message) {
154             realLogger.info(message);
155             throwException(INFO_VALUE, message);
156         }
157         public void info(String   message, Throwable   thr) {
158             realLogger.info(message, thr);
159             throwException(INFO_VALUE, message);
160         }
161         public void warn(String   message) {
162             realLogger.warn(message);
163             throwException(WARN_VALUE, message);
164         }
165         public void warn(String   message, Throwable   thr) {
166             realLogger.warn(message, thr);
167             throwException(WARN_VALUE, message);
168         }
169         public void error(String   message) {
170             realLogger.error(message);
171             throwException(ERROR_VALUE, message);
172         }
173         public void error(String   message, Throwable   thr) {
174             realLogger.error(message, thr);
175             throwException(ERROR_VALUE, message);
176         }
177         public void fatalError(String   message) {
178             realLogger.fatalError(message);
179             throwException(FATAL_VALUE, message);
180         }
181         public void fatalError(String   message, Throwable   thr) {
182             realLogger.fatalError(message, thr);
183             throwException(FATAL_VALUE, message);
184         }
185         public boolean isDebugEnabled() {
186             // Enable level also if it is set to throw an exception, so that
187             // logging the message occurs, and then throws it.
188             return isThrowingException(DEBUG_VALUE) || realLogger.isDebugEnabled();
189         }
190         public boolean isInfoEnabled() {
191             return isThrowingException(INFO_VALUE) || realLogger.isInfoEnabled();
192         }
193         public boolean isWarnEnabled() {
194             return isThrowingException(WARN_VALUE) || realLogger.isWarnEnabled();
195         }
196         public boolean isErrorEnabled() {
197             return isThrowingException(ERROR_VALUE) || realLogger.isErrorEnabled();
198         }
199         public boolean isFatalErrorEnabled() {
200             return true;
201         }
202         public Logger getChildLogger(String   message) {
203             return realLogger.getChildLogger(message);
204         }
205     }
206 }
207
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags