ExecuteCriteria


1   /**
2    * $Id: ExecuteCriteria.java 180 2007-03-15 12:56:38Z ssmc $
3    * Copyright 2004-2005 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.condition.solo;
30  
31  import  org.apache.tools.ant.BuildException;
32  import  org.apache.tools.ant.Project;
33  
34  import  com.idaremedia.antx.AntX;
35  import  com.idaremedia.antx.ExportedProperties;
36  import  com.idaremedia.antx.FixtureComponent;
37  import  com.idaremedia.antx.NoiseLevel;
38  import  com.idaremedia.antx.apis.AntLibFriendly;
39  import  com.idaremedia.antx.apis.Responses;
40  import  com.idaremedia.antx.helpers.Tk;
41  import  com.idaremedia.antx.ownhelpers.ProjectPropertiesNet;
42  import  com.idaremedia.antx.starters.Quiet;
43  import  com.idaremedia.antx.starters.TaskSet;
44  
45  /**
46   * A reusable condition that needs more than a sequence of simplier conditions
47   * to determine whether its been met. Criteria can have two kinds of side-effects:
48   * they can initialize or modify fixture variables (required to set the outgoing
49   * result variable), and they can create or alter (indirectly) project references.
50   * <p/>
51   * A criteria is meant to be reusable and can be executed many times within a single
52   * execution iteration. Therefore, the items you nest within a criteria <em>cannot</em>
53   * rely on changing properties outside the scope of the criteria. All property
54   * additions and/or modifications are limited to the criteria's scope (and are not
55   * seen by the project once the criteria has exited). As you would expect, pre-existing
56   * and overlaid properties can be read from within the criteria.
57   * <p/>
58   * For a criteria to ever pass, you <em>must</em> set the result variable (as 
59   * defined by the <span class="src">resultvariable</span> parameter) before leaving
60   * the criteria's body.
61   * <p/>
62   * Criteria are <em>not</em> tallies or build rules. Their purpose is to be a
63   * general and reusable boolean function and their side-effects are unknown. This 
64   * (lack of) definition makes them different from the other rule types and puts them
65   * into their own category. However, their intended use as execution tests for the 
66   * various AntX flow control task(set)s makes them part of the AntX build rules
67   * framework.
68   * <p/>
69   * <b>Example Usage:</b><pre>
70   *    &lt;<b>criteria</b> id="alms-uptodate" resultvar="out:alms-uptodate"&gt;
71   *        &lt;assign var="out:alms-uptodate" value="yes"/&gt;
72   *        &lt;property name="_module.meta" value="${alms.module.dir}/.crdate"/&gt;
73   *        &lt;domatch value="${$filenotempty:@(_module.meta)}"&gt;
74   *            &lt;equals value="true"&gt;
75   *               &lt;loadfile srcFile="${repository.arms}/${alms.module}/.crdate" 
76   *                           property="_repo.crdate"/&gt;
77   *               &lt;loadfile srcFile="${_module.meta}" 
78   *                           property="_alms.crdate"/&gt;
79   *               &lt;do true="${$newerdate:@(_repo.crdate),,@(_alms.crdate)}"&gt;
80   *                  &lt;assign var="out:alms-uptodate" value="no"/&gt;
81   *               &lt;/do&gt;
82   *            &lt;/equals&gt;
83   *            &lt;otherwise&gt;
84   *               &lt;assign var="out:alms-uptodate" value="no"/&gt;
85   *            &lt;/otherwise&gt;
86   *        &lt;/domatch&gt;
87   *    &lt;/criteria&gt;
88   *
89   *    &lt;<b>criteria</b> id="docs-uptodate" resultvar="out:docs-uptodate"&gt;
90   *       &lt;require allset="src,html" msg="src and html directory defined"/&gt;
91   *       &lt;require isnotset="docs-uptodate" msg="locals not in use"/&gt;
92   *       &lt;tally trueproperty="docs-uptodate"&gt;
93   *          &lt;issettrue property="disable.apidocs"/&gt;
94   *          &lt;isnotset property="clean"/&gt;
95   *          &lt;uptodate targetfile="${html}/index.html"&gt;
96   *             &lt;srcfiles dir="${srcs}"&gt;
97   *                &lt;include name="**&#47;doc-files&#47;"/&gt;
98   *                &lt;include name="**&#47;*.java"/&gt;
99   *                &lt;include name="**&#47;package.html"/&gt;
100  *                &lt;include name="**&#47;overview.html"/&gt;
101  *                &lt;exclude name="**&#47;tests*&#47;**" unless="allapis"/&gt;
102  *                &lt;exclude name="**&#47;.*&#47;**"/&gt;
103  *             &lt;/srcfiles&gt;
104  *          &lt;/uptodate&gt;
105  *       &lt;/tally&gt;
106  *       &lt;assign var="out:docs-uptodate" fromproperty="docs-uptodate"/&gt;
107  *    &lt;/criteria&gt;
108  * </pre>
109  *
110  * @since     JWare/AntX 0.5
111  * @author    ssmc, &copy;2004-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
112  * @version   0.5
113  * @.safety   single
114  * @.group    api,infra
115  **/
116 
117 public final class ExecuteCriteria extends TaskSet
118     implements ShareableCondition, Quiet, AntLibFriendly, FixtureComponent
119 {
120     /**
121      * Initializes a new criteria instance.
122      **/
123     public ExecuteCriteria()
124     {
125         super(AntX.rules+"ExecuteCriteria:");
126     }
127 
128 
129     /**
130      * Returns {@linkplain NoiseLevel#INFO INFO} always.
131      **/
132     public NoiseLevel getFailureEffect()
133     {
134         return NoiseLevel.INFO;
135     }
136 
137 
138 //  ---------------------------------------------------------------------------------------
139 //  Parameters:
140 //  ---------------------------------------------------------------------------------------
141 
142     /**
143      * Captures this criteria's reference identifier. Will be used
144      * in feedback and other internal needs.
145      * @param id the reference handle (non-null)
146      **/
147     public void setId(String   id)
148     {
149         require_(id!=null,"setId- nonzro id");
150         m_id = id;
151     }
152 
153 
154 
155     /**
156      * Returns this criteria's reference id. Will return a default
157      * name "<span class="src">criteria</span>" if not set explicitly.
158      * Never returns <i>null</i>.
159      **/
160     public String   getId()
161     {
162         return m_id;
163     }
164 
165 
166 
167     /**
168      * Tells this criteria the result variable it should check when
169      * it is evaluated. The variable is checked <em>after</em> all
170      * nested tasks have been performed. 
171      * @param outVar the variable name (non-null)
172      **/
173     public void setResultVariable(String   outVar)
174     {
175         require_(!Tk.isWhitespace(outVar),"setRsltVar- nonzro name");
176         m_outParam = outVar;
177     }
178 
179 
180 
181     /**
182      * Synonym for {@linkplain #setResultVariable setResultVariable(&#8230;)}.
183      * @param outVar the variable name (non-null)
184      **/
185     public final void setResultVar(String   outVar)
186     {
187         setResultVariable(outVar);
188     }
189 
190 
191 
192     /**
193      * Returns this criteria's result variable. Will return 
194      * <i>null</i> if never set explicitly.
195      * @see #setResultVariable setResultVariable(&#8230;)
196      **/
197     public final String   getResultVariable()
198     {
199         return m_outParam;
200     }
201 
202 
203 //  ---------------------------------------------------------------------------------------
204 //  Evaluation:
205 //  ---------------------------------------------------------------------------------------
206 
207     /**
208      * Ensure we have been assigned a (default) result variable. This is
209      * required so we can determine the true/false result of the criteria
210      * we represent.
211      * @throws BuildException if have not been assigned a result variable. 
212      */
213     protected void verifyCanExecute_(String   calr)
214     {
215         super.verifyCanExecute_(calr);
216 
217         if (getResultVariable()==null) {
218             String   e = getAntXMsg("type.needs.this.attr",getTaskName(),"resultvariable");
219             log(e, Project.MSG_ERR);
220             throw new BuildException(e, getLocation());
221         }
222     }
223 
224 
225 
226     /**
227      * Calls this criterial nested tasks then checks the {@linkplain
228      * #setResultVar result variable} for a positive boolean string.
229      * Caller can override the prescribed result variable's name by
230      * passing in an update variable.
231      * @param calr caller (non-null)
232      * @throws BuildException if any nested task does.
233      **/
234     public boolean eval(ShareableConditionUser calr)
235     {
236         verifyCanExecute_("eval");
237 
238         String   resultVar = getResultVariable();
239         if (calr.getUpdateVariable()!=null) {
240             resultVar = calr.getUpdateVariable();
241         }
242         ExportedProperties.unset(resultVar);
243 
244         performNestedTasks();
245 
246         String   evalResult = ExportedProperties.readstring(resultVar);
247         return Tk.string2PosBool(evalResult)==Boolean.TRUE;
248     }
249 
250 
251 
252     /**
253      * Runs a new copy of nested tasks in order. The <span class="src">perform</span>
254      * message is sent to each nested task. Subclasses can override this method to
255      * decorate the central <span class="src">performIterationOfTasksList</span>
256      * method which does the heavy lifting.
257      * @throws BuildException if any nested task does.
258      **/
259     protected void performNestedTasks()
260     {
261         ProjectPropertiesNet bubble = new ProjectPropertiesNet(getId(),getProject());
262         try {
263             performIterationOfTheTasksList();
264         } finally {
265             bubble.uninstall(new Responses.LogUsing(this));
266         }
267     }
268 
269 
270 
271     /**
272      * No-op; criteria must be explicitly evaluated by other tasks.
273      **/
274     public final void execute()
275     {
276         //burp...quietly
277     }
278 
279 
280     private String   m_outParam;
281     private String   m_id = "criteria";
282 }
283 
284 /* end-of-ExecuteCriteria.java */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags