001    // Copyright (c) 2001 Hursh Jain (http://www.mollypages.org) 
002    // The Molly framework is freely distributable under the terms of an
003    // MIT-style license. For details, see the molly pages web site at:
004    // http://www.mollypages.org/. Use, modify, have fun !
005    
006    package fc.util;
007    
008    /** 
009    This class is intended primarily for checking whether method paramaters
010    meet various pre-conditions. Throws a <tt>IllegalArgumentException</tt> in 
011    case of failure. 
012    <p>
013    ThreadSafety: This class <b>is</b> thread safe and can be used by multiple threads 
014    concurrently.
015    
016    @author   hursh jain
017    @version  1.0
018    @date   5/30/2002
019    **/
020    public final class Argcheck 
021    {
022    protected static IArgcheckFailHandler handler = new BasicArgcheckFailHandler();
023    
024    private Argcheck() { /* no instantiation */ } 
025    
026    /**
027    Checks that the specified argument is false.
028    @param  val   value to be tested  
029    **/
030    public static void isfalse(boolean val) 
031      { 
032      if (val) { 
033        fail(null); 
034        }
035      }
036    
037    /**
038    Checks that the specified argument is false.
039    @param  val   value to be tested  
040    @param  message message for the exception
041    **/
042    public static void isfalse(boolean val, String message) 
043      { 
044      if (val) {
045        fail(message);
046        }
047      }
048    
049    /**
050    Checks that the specified argument is true.
051    @param  val value to be tested  
052    **/
053    public static void istrue(boolean val)
054      { 
055      if (! val) {
056        fail(null);
057        }   
058      }
059    
060    /**
061    Checks that the specified argument is true.
062    @param  val value to be tested  
063    @param  message message for the exception
064    **/ 
065    public static void istrue(boolean val, String message)
066      { 
067      if (! val) {
068        fail(message);
069        }   
070      }
071    
072    /**
073    Checks that the specified argument is not null.
074    @param  obj value to be tested  
075    **/
076    public static void notnull(Object obj) 
077      { 
078      if (obj == null) {
079        fail(null);
080        }     
081      }
082    
083    /**
084    Checks that the specified argument is not null.
085    @param  obj value to be tested  
086    @param  message message for the exception
087    **/
088    public static void notnull(Object obj, String message)
089      { 
090      if (obj == null) {
091        fail(message);
092        }     
093      }
094    
095    /**
096    Checks that the specified argument is null.
097    @param  obj value to be tested  
098    **/
099    public static void isnull(Object obj)
100      { 
101      if (obj != null) {
102        fail(null);
103        }     
104      }
105    
106    /**
107    Checks that the specified argument is null.
108    @param  obj value to be tested  
109    @param  message message for the exception
110    **/
111    public static void isnull(Object obj, String message)
112      { 
113      if (obj != null) {
114        fail(message);
115        }     
116      }
117    
118    /**
119    Checks that the specified arguments are equal to each other by using 
120    <tt>Object.equals()</tt>.
121    @param  a first value to be tested  
122    @param  b second value to be tested 
123    **/
124    public static void isequal(Object a, Object b)
125      { 
126      isequal(a, b, null);  
127      }
128    
129    /**
130    Checks that the specified arguments are equal to each other by using 
131    <tt>Object.equals()</tt>.
132    @param  a   first value to be tested  
133    @param  b   second value to be tested 
134    @param  message message message for the exception
135    **/
136    public static void isequal(Object a, Object b, String message)
137      { 
138      /*  A     B           equals?
139      1 null    notnull   forsure no, can also check using b.equals(a)
140      2  null     null    yes, cannot check using equals
141      3  notnull    null    forsure no, can also check using a.equals(b)
142      4  notnull    notnull   have to check using equals()
143      */
144      if (a != b && a !=null && !a.equals(b)) { 
145        fail(message); 
146        }
147      }  
148    
149    
150    /**
151    Checks that the specified arguments are not equal to each other by using 
152    <tt>Object.equals()</tt>.
153    @param  a   first value to be tested  
154    @param  b   second value to be tested 
155    **/
156    public static void notequal(Object a, Object b)
157      { 
158      notequal(a,b,null);
159      }
160    
161    /**
162    Checks that the specified arguments are not equal to each other by using 
163    <tt>Object.equals()</tt>.
164    @param  a   first value to be tested  
165    @param  b   second value to be tested 
166    @param  message message message for the exception
167    **/
168    public static void notequal(Object a, Object b, String message)
169      {
170      /*  A     B           not equal ?
171      1 null    notnull   forsure yes, can also check using b.equals(a)
172      2   null    null    no, cannot check using equals
173      3   notnull   null    forsure yes ,can also check using a.equals(b)
174      4   notnull   notnull   have to check using equals()
175      */
176      if ( a == b || (a !=null && a.equals(b)) ) { 
177        fail(message);
178        }
179      }
180    
181    /** 
182    Checks to see if specified objects are the same object, that is, the
183    <b>references</b> are identical. This provides a stronger notion of 
184    equality than the <tt>Object.equals()</tt> method.
185    @param  a   first value to be tested  
186    @param  b   second value to be tested 
187    **/
188    public static void issame(Object a, Object b)
189      { 
190      if (a != b) {
191        fail(null);
192        }     
193      }
194    
195    /** 
196    Checks to see if specified objects are the same object, that is, the
197    <b>references</b> are identical. This provides a stronger notion of 
198    equality than the <tt>Object.equals()</tt> method.
199    @param  a   first value to be tested  
200    @param  b   second value to be tested 
201    @param  message message message for the exception
202    **/
203    public static void issame(Object a, Object b, String message)
204      { 
205      if (a != b) {
206        fail(message);
207        }   
208      }
209    
210    /** 
211    Checks to see if specified objects are not the same object, that is, the
212    <b>references</b> are not identical. 
213    @param  a   first value to be tested  
214    @param  b   second value to be tested 
215    **/
216    public static void notsame(Object a, Object b)
217      { 
218      if (a == b) {
219        fail(null);
220        }     
221      }
222    
223    /** 
224    Checks to see if specified objects are not the same object, that is, the
225    <b>references</b> are not identical. 
226    @param  a   first value to be tested  
227    @param  b   second value to be tested 
228    @param  message message message for the exception
229    **/
230    public static void notsame(Object a, Object b, String message)
231      { 
232      if (a == b) {
233        fail(message);
234        }     
235      }
236    
237    /**
238    Sets a different error handler.
239    @param  thehandler  the new error handler
240    @return <tt>true</tt> is successful, <tt>false</tt> otherwise
241    **/
242    public static synchronized boolean setHandler(IArgcheckFailHandler thehandler)
243      {
244      if (thehandler != null) {
245        handler = thehandler;
246        return true;
247        }
248      new Exception("Checker.setHandler(): could not set new handler because 'thehandler' paramater was null.").printStackTrace(System.err);
249      return false;
250      }
251    
252    protected static void fail(String message) {
253      handler.handle(message);
254      }
255    }           //~class Argcheck