KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > AssertableLibDefinition


1 /**
2  * $Id: AssertableLibDefinition.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 2004 iDare Media, Inc. All rights reserved.
4  *
5  * Originally written by iDare Media, Inc. for release into the public domain. This
6  * library, source form and binary form, is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public License (LGPL) as published
8  * by the Free Software Foundation; either version 2.1 of the License, or (at your option)
9  * any later version.<p>
10  *
11  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13  * See the GNU LGPL for more details.<p>
14  *
15  * You should have received a copy of the GNU Lesser General Public License along with this
16  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite
17  * 330, Boston, MA 02111-1307 USA. The GNU LGPL can be found online at
18  * http://www.fsf.org/copyleft/lesser.html<p>
19  *
20  * This product has been influenced by several projects within the open-source community.
21  * The JWare developers wish to acknowledge the open-source community's support. For more
22  * information regarding the open-source products used within JWare, please visit the
23  * JWare website.
24  *----------------------------------------------------------------------------------------*
25  * WEBSITE- http://www.jware.info EMAIL- inquiries@jware.info
26  *----------------------------------------------------------------------------------------*
27  **/
28
29 package com.idaremedia.antx;
30
31 import org.apache.tools.ant.BuildException;
32 import org.apache.tools.ant.Project;
33 import org.apache.tools.ant.taskdefs.AntlibDefinition;
34
35 import com.idaremedia.apis.UIStringManager;
36
37 import com.idaremedia.antx.apis.AntLibFriendly;
38 import com.idaremedia.antx.apis.ProjectDependent;
39 import com.idaremedia.antx.apis.ScriptLocatable;
40 import com.idaremedia.antx.helpers.Tk;
41
42 /**
43  * Extension of basic Ant <i>AntlibDefinition</i> that adds builtin assertions. The
44  * class's implementation is as it is because AntlibDefinition was made a class instead
45  * of an interface (oye). Our definition is therefore, painfully redundant wrt
46  * {@linkplain AssertableTask} but what can yah do&#8230;
47  *
48  * @since JWare/AntX 0.4
49  * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
50  * @version 0.5
51  * @.safety single
52  * @.group api,infra
53  * @.expects Ant 1.6
54  **/
55
56 public abstract class AssertableLibDefinition extends AntlibDefinition
57     implements ProjectDependent, ScriptLocatable, AntLibFriendly
58 {
59     /**
60      * Initializes new unlabeled definition task.
61      **/
62     protected AssertableLibDefinition()
63     {
64         super();
65         Iam_="";
66     }
67
68
69
70     /**
71      * Initializes new CV-labeled definition task.
72      * @param iam CV-label (non-null)
73      **/
74     protected AssertableLibDefinition(String JavaDoc iam)
75     {
76         super();
77         Iam_= Tk.cvlabelFrom(iam);
78     }
79
80
81
82     /**
83      * Ensures this task's {@linkplain #initonce} method is called just
84      * once. Sometimes Ant introspection mechanisms trigger mulitple calls
85      * to init. This ensure that once-only initialization code is really
86      * only called once.
87      * @since JWare/AntX 0.5
88      **/
89     public void init()
90     {
91         super.init();
92
93         if (!m_initedOnce) {
94             initonce();
95             m_initedOnce=true;
96         }
97     }
98
99
100
101     /**
102      * Initialization that must be done at most one time. Called by
103      * {@linkplain #init} once even if init is itself called multiple
104      * times.
105      * @throws BuildException if unable to initialize required bits
106      * @since JWare/AntX 0.5
107      **/
108     protected void initonce()
109     {
110     }
111
112
113
114
115     /**
116      * Ensures the verification method
117      * {@linkplain #verifyCanExecute_ verifyCanExecute_()} is called
118      * before inherited execution.
119      * @since JWare/AntX 0.5
120      */
121     public void execute()
122     {
123         verifyCanExecute_("exec");
124         super.execute();
125     }
126
127
128
129
130     /**
131      * Shortcut that returns this task's internal AntX UI strings manager.
132      * Never returns <i>null</i>.
133      * @see Iteration#uistrs
134      **/
135     public final UIStringManager uistrs()
136     {
137         return Iteration.uistrs();
138     }
139
140
141 // ---------------------------------------------------------------------------------------
142 // (AntX) Universal Task Log Conversion (make events useful):
143 // ---------------------------------------------------------------------------------------
144
145     /**
146      * Indicate this task as source of logged message.
147      **/
148     public void log(String JavaDoc msg, int msgLevel)
149     {
150         if (getProject()!=null) {
151             getProject().log(this,msg,msgLevel);
152         } else {
153             if (msgLevel >= Project.MSG_INFO) { //NB: works around bug in Task.log!
154 System.err.println(msg);
155             }
156         }
157     }
158
159 // ---------------------------------------------------------------------------------------
160 // (AntX) Universal Task Assertion Facilities:
161 // ---------------------------------------------------------------------------------------
162
163
164     /**
165      * Returns this task's CV-label. Never <i>null</i>.
166      **/
167     public final String JavaDoc cvlabel_()
168     {
169         return Iam_;
170     }
171
172
173     /**
174      * Throws assertion error if pre-condtion is not met.
175      * @param c pre-condition
176      * @param msg [optional] failure message (if not met)
177      * @throws IllegalArgumentException if condition not met
178      **/
179     protected final void require_(boolean c, String JavaDoc msg)
180     {
181         if (!c) {
182             String JavaDoc ermsg = uistrs().get("cv.require",Iam_,msg);
183             log(ermsg, Project.MSG_ERR);
184             throw new IllegalArgumentException JavaDoc(ermsg);
185         }
186     }
187
188
189     /**
190      * Throws assertion error if post-condition is not met. Used
191      * for post-condition verification.
192      * @param c post-condition
193      * @param msg [optional] failure message (if not met)
194      * @throws IllegalStateException if condition not met
195      **/
196     protected final void ensure_(boolean c, String JavaDoc msg)
197     {
198         if (!c) {
199             String JavaDoc ermsg = uistrs().get("cv.ensure",Iam_,msg);
200             log(ermsg, Project.MSG_ERR);
201             throw new IllegalStateException JavaDoc(ermsg);
202         }
203     }
204
205
206     /**
207      * Throws assertion error if condition is not met. Used for
208      * block and invariant verification.
209      * @param c condition
210      * @param msg [optional] failure message (if not met)
211      * @throws IllegalStateException if condition not met
212      **/
213     protected final void verify_(boolean c, String JavaDoc msg)
214     {
215         if (!c) {
216             String JavaDoc ermsg = uistrs().get("cv.verify",Iam_,msg);
217             log(ermsg, Project.MSG_ERR);
218             throw new IllegalStateException JavaDoc(ermsg);
219         }
220     }
221
222
223     /**
224      * Notes an unexpected but manageable problem has occured.
225      * Just logs a warning by default.
226      * @param t [optional] causing throwable
227      * @param msg caller's additional (context) message
228      **/
229     protected final void unexpected_(Throwable JavaDoc t, String JavaDoc msg)
230     {
231         String JavaDoc ermsg = uistrs().get("cv.unexpected",Iam_,msg,t);
232         log(ermsg, Project.MSG_WARN);
233     }
234
235
236     /**
237      * Verifies we're in a live project (created from build process).
238      * @throws IllegalStateException if not in project
239      **/
240     protected final void verifyInProject_(String JavaDoc calr)
241     {
242         if (getProject()==null) {
243             String JavaDoc ermsg = uistrs().get("cv.verifyInP",Iam_,calr);
244             log(ermsg, Project.MSG_ERR);
245             throw new IllegalStateException JavaDoc(ermsg);
246         }
247     }
248
249
250     /**
251      * Verifies we're in a live target and project (created from
252      * build process).
253      * @throws IllegalStateException if not in target
254      **/
255     protected final void verifyInTarget_(String JavaDoc calr)
256     {
257         if (getOwningTarget()==null) {
258             String JavaDoc ermsg = uistrs().get("cv.verifyInT",Iam_,calr);
259             log(ermsg, Project.MSG_ERR);
260             throw new IllegalStateException JavaDoc(ermsg);
261         }
262         verifyInProject_(calr);
263     }
264
265
266     /**
267      * Called by '<i>execute</i>' on entry to verify that all required
268      * options have been specified for correct execution of this task.
269      * By default just verifies this task is associated with an enclosing
270      * project.
271      * @param calr calling method (usually 'execute' or 'run')
272      * @throws IllegalStateException if improperly configured
273      * @throws BuildException if unable to execute
274      **/
275     protected void verifyCanExecute_(String JavaDoc calr)
276         throws BuildException
277     {
278         verifyInProject_(calr);
279     }
280
281
282
283     private final String JavaDoc Iam_;
284     private boolean m_initedOnce;
285 }
286
287 /* end-of-AssertableLibDefinition.java */
288
Popular Tags