OnceTask


1   /**
2    * $Id: OnceTask.java 180 2007-03-15 12:56:38Z ssmc $
3    * Copyright 2002-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 as published by the
8    * Free Software Foundation; either version 2.1 of the License, or (at your option) any
9    * 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 (GNU Lesser General Public License) 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 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.flowcontrol.call;
30  
31  import  java.util.List  ;
32  
33  import  org.apache.tools.ant.BuildException;
34  import  org.apache.tools.ant.Project;
35  
36  import  com.idaremedia.antx.AntX;
37  import  com.idaremedia.antx.AntXFixture;
38  import  com.idaremedia.antx.helpers.Tk;
39  import  com.idaremedia.antx.parameters.ExecutionMode;
40  import  com.idaremedia.antx.parameters.FixturePassthru;
41  
42  
43  /**
44   * A caller implementation that runs a set of named inlined steps or top-level targets
45   * once. This task is the internal implementation; the script-facing interface must
46   * be provided by a subclass like {@linkplain CallOnceTask}. For a looping construct
47   * around the OnceTask, see the {@linkplain ForEachTask}.
48   *
49   * @since    JWare/AntX 0.1
50   * @author   ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
51   * @version  0.5
52   * @.safety  single
53   * @.group   impl,infra
54   **/
55  
56  public abstract class OnceTask extends CallerTask
57  {
58      /**
59       * Initializes a new OnceTask.
60       **/
61      protected OnceTask()
62      {
63          super(AntX.flow+"OnceTask:");
64      }
65  
66  
67      /**
68       * Initializes a new CV-labeled OnceTask.
69       * @param iam CV-label (non-null)
70       **/
71      protected OnceTask(String   iam)
72      {
73          super(iam);
74      }
75  
76  // ---------------------------------------------------------------------------------------
77  // Optional Script-facing Parameters:
78  // ---------------------------------------------------------------------------------------
79  
80      /**
81       * Returns the fixture passthru setting to be used when this
82       * caller runs its targets. Never returns <i>null</i>;
83       * will return <span class="src">PROPERTIES</span> if
84       * not set explicitly.
85       * @since JWare/AntX 0.4
86       **/
87      public FixturePassthru getPassthruOption()
88      {
89          return FixturePassthru.PROPERTIES;
90      }
91  
92  
93      /**
94       * Returns this task's comma-delimited list of step names.
95       * Will return <i>null</i> if never set. By default, all
96       * steps must exist within the same target as this task.
97       **/
98      public String   getStepNamesList()
99      {
100         return null;
101     }
102 
103 
104     /**
105      * Returns this task's comma-delimited list of target names.
106      * Will return <i>null</i> if never set.
107      **/
108     public String   getTargetNamesList()
109     {
110         return null;
111     }
112 
113 
114     /**
115      * Returns this task's comma-delimited list of macro names.
116      * Will return <i>null</i> if never set. By default, all
117      * macro must exist within the same project as this task.
118      * @since JWare/AntX 0.5
119      **/
120     public String   getMacroNamesList()
121     {
122         return null;
123     }
124 
125 
126 
127     /**
128      * Returns this task's execution mode. Never returns <i>null</i>;
129      * will return <span class="src">ISOLATED</span> if never set.
130      * @since JWare/AntX 0.4
131      **/
132     public ExecutionMode getMode()
133     {
134         return ExecutionMode.ISOLATED;
135     }
136 
137 
138 // ---------------------------------------------------------------------------------------
139 // Execution:
140 // ---------------------------------------------------------------------------------------
141 
142     /**
143      * Returns the number of kinds-of runnables specified (basically
144      * whether one or more of steps, targets, or macros have been requested).
145      **/
146     protected int getKindOfRunnablesSpecified()
147     {
148         int N=0;
149         if (getStepNamesList()!=null)   { N++; }
150         if (getTargetNamesList()!=null) { N++; }
151         if (getMacroNamesList()!=null)  { N++; }
152         return N;
153     }
154 
155 
156     /**
157      * Ensures that either a named set of steps, targets, or macros
158      * has been specified (not both and not none).
159      * @param calr calling method's identifier
160      * @throws BuildException if verification fails
161      **/
162     protected void verifyCanExecute_(String   calr)
163     {
164         super.verifyCanExecute_(calr);
165 
166         int Nr= getKindOfRunnablesSpecified();
167 
168         if ((Nr==0) || (Nr>1)) { //only one steplist -or- targetlist -or- macrolist
169             String   ermsg = uistrs().get("flow.targets.or.steps");
170             log(ermsg,Project.MSG_ERR);
171             throw new BuildException(ermsg,getLocation());
172         }
173         
174         if (getMacroNamesList()!=null && getMode()!=ExecutionMode.LOCAL) {
175             String   ermsg = getAntXMsg("flow.macro.islocal");
176             log(ermsg,Project.MSG_ERR);
177             throw new BuildException(ermsg,getLocation());
178         }
179     }
180 
181 
182 
183     /**
184      * Returns list of configured {@linkplain TargetCaller
185      * target callers} for either the requested steps or targets.
186      * @throws BuildException if unable to create target callers
187      **/
188     protected List   copyOfOrderedTargetCallers()
189         throws BuildException
190     {
191         String   candidateNames;
192         
193         candidateNames = getStepNamesList();
194         if (candidateNames!=null) {
195             if (getMode()==ExecutionMode.LOCAL) {
196                 return createLocalTargetCallers(candidateNames,false);
197             }
198             return createStepLauncherCallers(candidateNames);
199         }
200 
201         candidateNames = getTargetNamesList();
202         if (candidateNames!=null) {
203             if (getMode()==ExecutionMode.LOCAL) {
204                 return createLocalTargetCallers(candidateNames,true);
205             }
206             return createGenericTargetCallers(candidateNames);
207         }
208 
209         candidateNames = getMacroNamesList();
210         if (candidateNames!=null) {
211             return createMacroInstanceCallers(candidateNames);
212         }
213 
214         return AntXFixture.newList();
215     }
216 
217 
218 
219     /**
220      * Prepares a list of pre-configured StepLauncherCallers to call
221      * steps defined within this task's target. Only
222      * {@linkplain InlineStep InlineStep} allowed.
223      **/
224     private List   createStepLauncherCallers(String   stepNames)
225         throws BuildException
226     {
227         String   targetName = StepLauncherCaller.findSpecialTarget(this);
228 
229         List   wanted = Tk.splitList(stepNames);//names
230         List   actual = getFilteredStepsLike(InlineStep.class,wanted);//steps
231 
232         if (wanted.size()!=actual.size()) {
233             String   ermsg = uistrs().get("flow.steplaunch.missing.Nsteps",
234                                         getOwningTarget().getName());
235             log(ermsg, Project.MSG_ERR);
236             throw new BuildException(ermsg,getLocation());
237         }
238 
239         StepLauncherCaller caller;
240         List   callers = AntXFixture.newList(wanted.size());
241         String   kindOfStep = InlineStep.class.getName();
242 
243         for (int i=0,N=wanted.size();i<N;i++) {
244             caller = StepLauncherCaller.create(this,true,targetName,
245                                                (String  )wanted.get(i),kindOfStep,
246                                                2/*allows 1-level nest in 'step'*/);
247             transferOverlayParameters(caller);
248             callers.add(caller);
249         }
250 
251         wanted.clear();
252         actual.clear();
253 
254         return callers;
255     }
256 
257 
258 
259     /**
260      * Prepares a list of pre-configured generic TargetCallers to call
261      * existing real Ant targets.
262      * @throws BuildException if a requested target does not exist
263      **/
264     private List   createGenericTargetCallers(String   targetNames)
265     {
266         List   wanted = Tk.splitList(targetNames);
267         List   callers= AntXFixture.newList(wanted.size());
268 
269         AnyTargetCaller caller;
270         String   targetName;
271 
272         for (int i=0,N=wanted.size();i<N;i++) {
273             targetName = (String  )wanted.get(i);
274             if (!targetExists(targetName)) {
275                 String   ermsg = uistrs().get("flow.steplaunch.missing.target",
276                                             targetName, getProject().getName());
277                 log(ermsg, Project.MSG_ERR);
278                 throw new BuildException(ermsg,getLocation());
279             }
280             caller = new AnyTargetCaller(this, targetName);
281             caller.setStepName(targetName);
282             transferOverlayParameters(caller);
283             callers.add(caller);
284         }
285 
286         wanted.clear();
287 
288         return callers;
289     }
290 
291 
292 
293     /**
294      * Returns a filled in list of target callers for this
295      * task's list.
296      * @throws BuildException if name list invalid or a called
297      *         target fails.
298      * @since JWare/AntX 0.4
299      */
300     private List   createLocalTargetCallers(String   nameList, boolean topLevel)
301     {
302         List   l= Tk.splitList(nameList);
303         List   callers= AntXFixture.newList(l.size());
304         String   tn;
305         LocalTargetCaller caller;
306 
307         for (int i=0,N=l.size();i<N;i++) {
308             tn = l.get(i).toString();
309             caller = new LocalTargetCaller(this);
310             if (topLevel) {
311                 caller.setTarget(tn);
312             } else {
313                 caller.setStepName(tn);
314             }
315             transferOverlayParameters(caller);
316             callers.add(caller);
317         }
318 
319         return callers;
320     }
321 
322 
323 
324 
325     /**
326      * Returns a filled in list of local macro instance callers 
327      * for this task's list.
328      * @throws BuildException if name list invalid or a called
329      *         target fails.
330      * @since JWare/AntX 0.5
331      */
332     private List   createMacroInstanceCallers(String   nameList)
333     {
334         List   l= Tk.splitList(nameList);
335         List   callers= AntXFixture.newList(l.size());
336         String   tn;
337         MacroInstanceCaller caller;
338 
339         for (int i=0,N=l.size();i<N;i++) {
340             tn = l.get(i).toString();
341             caller = new MacroInstanceCaller(this);
342             caller.setTarget(tn);
343             transferOverlayParameters(caller);
344             callers.add(caller);
345         }
346 
347         return callers;
348     }
349 }
350 /* end-of-OnceTask.java */
351
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags