SanityManager


1   /*
2   
3      Derby - Class org.apache.derby.iapi.services.sanity.SanityManager
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.shared.common.sanity;
23  
24  
25  import java.util.Hashtable  ;
26  import java.util.Enumeration  ;
27  
28  /**
29   * The SanityService provides assertion checking and debug
30   * control.
31   * <p>
32   * Assertions and debug checks
33   * can only be used for testing conditions that might occur
34   * in development code but not in production code.  
35   * <b>They are compiled out of production code.</b>
36   * <p>
37   * Uses of assertions should not add AssertFailure catches or
38   * throws clauses; AssertFailure is under RuntimeException
39   * in the java exception hierarchy. Our outermost system block
40   * will bring the system down when it detects an assertion
41   * failure.
42   * <p>
43   * In addition to ASSERTs in code, classes can choose to implement
44   * an isConsistent method that would be used by ASSERTs, UnitTests,
45   * and any other code wanting to check the consistency of an object.
46   * <p>
47   * Assertions are meant to be used to verify the state of the system
48   * and bring the system down if the state is not correct. Debug checks
49   * are meant to display internal information about a running system.
50   * <p>
51   * @see org.apache.derby.iapi.services.sanity.AssertFailure
52   */
53  public class SanityManager {
54      /**
55       * The build tool may be configured to alter
56       * this source file to reset the static final variables
57       * so that assertion and debug checks can be compiled out
58       * of the code.
59       */
60  
61      public static final boolean ASSERT = SanityState.ASSERT; // code should use DEBUG
62      public static final boolean DEBUG = SanityState.DEBUG;
63      
64      public static final String   DEBUGDEBUG = "DumpSanityDebug";
65      
66      /**
67       * debugStream holds a pointer to the debug stream for writing out
68       * debug messages.  It is cached at the first debug write request.
69       */
70      static private java.io.PrintWriter   debugStream = new java.io.PrintWriter  (System.err);
71      /**
72       * DebugFlags holds the values of all debug flags in
73       * the configuration file.
74       */
75      static private Hashtable   DebugFlags = new Hashtable  ();
76      /**
77       * AllDebugOn and AllDebugOff override individual flags
78       */
79      static private boolean AllDebugOn = false;
80      static private boolean AllDebugOff = false;
81  
82      //
83      // class interface
84      //
85  
86      /**
87       * ASSERT checks the condition, and if it is
88       * false, throws AssertFailure.
89       * A message about the assertion failing is
90       * printed.
91       * <p>
92       * @see org.apache.derby.iapi.services.sanity.AssertFailure
93       */
94      public static final void ASSERT(boolean mustBeTrue) {
95          if (DEBUG)
96              if (! mustBeTrue) {
97                  if (DEBUG) {
98                      AssertFailure af = new AssertFailure("ASSERT FAILED");
99                      if (DEBUG_ON("AssertFailureTrace")) {
100                         showTrace(af);
101                     }
102                     throw af;
103                 }
104                 else
105                     throw new AssertFailure("ASSERT FAILED");
106             }
107     }
108 
109     /**
110      * ASSERT checks the condition, and if it is
111      * false, throws AssertFailure. The message will
112      * be printed and included in the assertion.
113      * <p>
114      * @see org.apache.derby.iapi.services.sanity.AssertFailure
115      */
116     public static final void ASSERT(boolean mustBeTrue, String   msgIfFail) {
117         if (DEBUG)
118             if (! mustBeTrue) {
119                 if (DEBUG) {
120                     AssertFailure af = new AssertFailure("ASSERT FAILED " + msgIfFail);
121                     if (DEBUG_ON("AssertFailureTrace")) {
122                         showTrace(af);
123                     }
124                     throw af;
125                 }
126                 else
127                     throw new AssertFailure("ASSERT FAILED " + msgIfFail);
128             }
129     }
130 
131     /**
132      * THROWASSERT throws AssertFailure. This is used in cases where
133      * the caller has already detected the assertion failure (such as
134      * in the default case of a switch). This method should be used,
135      * rather than throwing AssertFailure directly, to allow us to 
136      * centralize all sanity checking.  The message argument will
137      * be printed and included in the assertion.
138      * <p>
139      * @param msgIfFail message to print with the assertion
140      *
141      * @see org.apache.derby.iapi.services.sanity.AssertFailure
142      */
143     public static final void THROWASSERT(String   msgIfFail) {
144         // XXX (nat) Hmm, should we check ASSERT here?  The caller is
145         // not expecting this function to return, whether assertions
146         // are compiled in or not.
147 
148         if (DEBUG) {
149             AssertFailure af = new AssertFailure("ASSERT FAILED " + msgIfFail);
150             if (DEBUG_ON("AssertFailureTrace")) {
151                 showTrace(af);
152             }
153             throw af;
154         }
155         else
156             throw new AssertFailure("ASSERT FAILED " + msgIfFail);
157     }
158 
159     /**
160      * THROWASSERT throws AssertFailure.
161      * This flavor will print the stack associated with the exception.
162      * The message argument will
163      * be printed and included in the assertion.
164      * <p>
165      * @param msg message to print with the assertion
166      * @param t exception to print with the assertion
167      *
168      * @see org.apache.derby.iapi.services.sanity.AssertFailure
169      */
170     public static final void THROWASSERT(String   msg, Throwable   t) {
171 
172         if (DEBUG) {
173             AssertFailure af = new AssertFailure("ASSERT FAILED " + t.toString(), t);
174             if (DEBUG_ON("AssertFailureTrace")) {
175                 showTrace(af);
176             }
177             showTrace(t);
178             throw af;
179         }
180         else {
181             showTrace(t);
182             throw new AssertFailure("ASSERT FAILED " + t.toString(), t);
183         }
184     }
185 
186     /**
187      * THROWASSERT throws AssertFailure.
188      * This flavor will print the stack associated with the exception.
189      * <p>
190      * @param t exception to print with the assertion
191      *
192      * @see org.apache.derby.iapi.services.sanity.AssertFailure
193      */
194     public static final void THROWASSERT(Throwable   t) {
195 
196         if (DEBUG) {
197             AssertFailure af = new AssertFailure("ASSERT FAILED " + t.toString(), t);
198             if (DEBUG_ON("AssertFailureTrace")) {
199                 showTrace(af);
200             }
201             showTrace(t);
202             throw af;
203         }
204         else {
205             showTrace(t);
206             throw new AssertFailure("ASSERT FAILED " + t.toString(), t);
207         }
208     }
209 
210     /**
211      * The DEBUG calls provide the ability to print information or
212      * perform actions based on whether a debug flag is set or not.
213      * debug flags are set in configurations and picked up by the
214      * sanity manager when the monitor finds them (see CONFIG below).
215      * <p>
216      * The message is output to the trace stream, so it ends up in
217      * db2j.LOG. It will include a header line of
218      *   DEBUG <flagname> OUTPUT:
219      * before the message.
220      * <p>
221      * If the debugStream stream cannot be found, the message is printed to
222      * System.out.
223      */
224     public static final void DEBUG(String   flag, String   message) {
225         if (DEBUG) {
226             if (DEBUG_ON(flag)) {
227                 DEBUG_PRINT(flag, message);
228             }
229         }
230     }
231 
232     /**
233      * This can be called directly if you want to control
234      * what is done once the debug flag has been verified --
235      * for example, if you are calling a routine that prints to
236      * the trace stream directly rather than returning a string to
237      * be printed, or if you want to perform more (or fewer!)
238      *
239      * <p>
240      * Calls to this method should be surrounded with
241      *     if (SanityManager.DEBUG) {
242      *     }
243      * so that they can be compiled out completely.
244      *
245      * @return true if the flag has been set to "true"; false
246      * if the flag is not set, or is set to something other than "true".
247      */
248     public static final boolean DEBUG_ON(String   flag) {
249         if (DEBUG) {
250             if (AllDebugOn) return true;
251             else if (AllDebugOff) return false;
252             else {
253                     Boolean   flagValue = (Boolean  ) DebugFlags.get(flag);
254                     if (! DEBUGDEBUG.equals(flag)) {
255                         if (DEBUG_ON(DEBUGDEBUG)) {
256                             DEBUG_PRINT(DEBUGDEBUG, "DEBUG_ON: Debug flag "+flag+" = "+flagValue);
257                         }
258                     }
259                     if (flagValue == null) return false;
260                     else return flagValue.booleanValue();
261             }
262         }
263         else return false;
264     }
265 
266     /**
267      * Set the named debug flag to true.
268      *
269      * <p>
270      * Calls to this method should be surrounded with
271      *     if (SanityManager.DEBUG) {
272      *     }
273      * so that they can be compiled out completely.
274      *
275      * @param flag  The name of the debug flag to set to true
276      */
277     public static final void DEBUG_SET(String   flag) {
278         if (DEBUG) {
279             if (! DEBUGDEBUG.equals(flag)) {
280                 if (DEBUG_ON(DEBUGDEBUG))
281                     DEBUG_PRINT(DEBUGDEBUG, "DEBUG_SET: Debug flag " + flag);
282             }
283 
284             DebugFlags.put(flag, Boolean.TRUE);
285         }
286     }
287 
288     /**
289      * Set the named debug flag to false.
290      *
291      * <p>
292      * Calls to this method should be surrounded with
293      *     if (SanityManager.DEBUG) {
294      *     }
295      * so that they can be compiled out completely.
296      *
297      * @param flag  The name of the debug flag to set to false
298      */
299     public static final void DEBUG_CLEAR(String   flag) {
300         if (DEBUG) {
301             if (! DEBUGDEBUG.equals(flag)) {
302                 if (DEBUG_ON(DEBUGDEBUG))
303                     DEBUG_PRINT(DEBUGDEBUG, "DEBUG_CLEAR: Debug flag " + flag);
304             }
305 
306             DebugFlags.put(flag, Boolean.FALSE);
307         }
308     }
309 
310     /**
311      * This can be used to have the SanityManager return TRUE
312      * for any DEBUG_ON check. DEBUG_CLEAR of an individual
313      * flag will appear to have no effect.
314      */
315     public static final void DEBUG_ALL_ON() {
316         if (DEBUG) {
317             AllDebugOn = true;
318             AllDebugOff = false;
319         }
320     }
321 
322     /**
323      * This can be used to have the SanityManager return FALSE
324      * for any DEBUG_ON check. DEBUG_SET of an individual
325      * flag will appear to have no effect.
326      */
327     public static final void DEBUG_ALL_OFF() {
328         if (DEBUG) {
329             AllDebugOff = true;
330             AllDebugOn = false;
331         }
332     }
333 
334     //
335     // class implementation
336     //
337 
338     static public void SET_DEBUG_STREAM(java.io.PrintWriter   pw) {
339         debugStream = pw;
340     }
341 
342     static public java.io.PrintWriter   GET_DEBUG_STREAM() {
343         return debugStream;
344     }
345 
346     static private void showTrace(AssertFailure af) {
347         af.printStackTrace();
348         java.io.PrintWriter   assertStream = GET_DEBUG_STREAM();
349 
350         assertStream.println("Assertion trace:");
351         af.printStackTrace(assertStream);
352         assertStream.flush();
353     }
354 
355     static public void showTrace(Throwable   t) {
356         java.io.PrintWriter   assertStream = GET_DEBUG_STREAM();
357 
358         assertStream.println("Exception trace: ");
359         t.printStackTrace(assertStream);
360     }
361 
362     /**
363      * The DEBUG_PRINT calls provides a convenient way to print debug
364      * information to the db2j.LOG file,  The message includes a header
365      *<p>
366      *  DEBUG <flag> OUTPUT: 
367      * before the message
368      *<p>
369      * If the debugStream stream cannot be found, the message is printed to
370      * System.out.
371      *
372      */
373     static public void DEBUG_PRINT(String   flag, String   message) {
374         java.io.PrintWriter   debugStream = GET_DEBUG_STREAM();
375 
376         debugStream.println("DEBUG "+flag+" OUTPUT: " + message);
377         debugStream.flush();
378     }
379 
380     public static void NOTREACHED() {
381         THROWASSERT("code should not be reached");
382     }
383 }
384 
385
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags