KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > starters > SimpleManagerTask


1 /**
2  * $Id: SimpleManagerTask.java 186 2007-03-16 13:42:35Z 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.starters;
30
31 import java.util.Collections JavaDoc;
32 import java.util.Iterator JavaDoc;
33 import java.util.List JavaDoc;
34 import java.util.Map JavaDoc;
35
36 import org.apache.tools.ant.BuildException;
37 import org.apache.tools.ant.Project;
38
39 import com.idaremedia.antx.AntXFixture;
40 import com.idaremedia.antx.Iteration;
41 import com.idaremedia.antx.apis.Requester;
42 import com.idaremedia.antx.helpers.InnerNameValuePair;
43 import com.idaremedia.antx.helpers.Tk;
44 import com.idaremedia.antx.parameters.FeedbackLevel;
45
46 /**
47  * Common form of an AntX manager task. Basically a single "<span class="src">action</span>"
48  * parameter is specified and action configuration is done primarily using simple nested
49  * <span class="src">&lt;parameter&gt;</span> elements. Subclasses must supply the
50  * various public "do" methods like <span class="src">doInstall</span>. In addition to the
51  * inherited <span class="src">haltiferror</span> option, this common manager task lets
52  * you control how much diagnostic feedback is generated through its
53  * <span class="src">feedback</span> option.
54  * <p/>
55  * To facilitate script readability, a simple manager task can scrub an action's name to
56  * remove human-friendly spacer characters that could never belong to an action method's
57  * name. For example, the actions "<span class="src">install-default</span>" and
58  * "<span class="src">throw error</span>" would be interpreted as
59  * "<span class="src">installdefault</span>" and "<span class="src">throwerror</span>"
60  * respectively. The matching methods would be named <span class="src">doInstallDefault</span>
61  * and <span class="src">doThrowError</span>.
62  * <p/>
63  * <b>Example Usage:</b><pre>
64  * &lt;managertask action="install"&gt; <i>//managertask is name of some subclass</i>
65  * &lt;parameter name="arg0" value="Hello"/&gt;
66  * &lt;parameter name="arg1" value="World"/&gt;
67  * &lt;managertask&gt;
68  * </pre>
69  *
70  * @since JWare/AntX 0.5
71  * @author ssmc, &copy;2004-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
72  * @version 0.5
73  * @.safety single
74  * @.group impl,helper
75  **/
76
77 public abstract class SimpleManagerTask extends ManagerTask
78 {
79     /**
80      * Initializes a new simple manager task.
81      * @param iam CV-label (non-null)
82      **/
83     protected SimpleManagerTask(String JavaDoc iam)
84     {
85         super(iam);
86     }
87
88
89
90     /**
91      * Initializes a new manager task with a default action.
92      * @param iam CV-label (non-null)
93      * @param defaultAction default action to execute (non-null)
94      * @.impl This sets the action field <em>directly</em>; the
95      * <span class="src">setAction</span> method is not called.
96      **/
97     protected SimpleManagerTask(String JavaDoc iam, String JavaDoc defaultAction)
98     {
99         super(iam);
100         m_actionName = defaultAction;
101     }
102
103
104
105     /**
106      * Sets the control action for this manager task. An inlined
107      * URI parameter can be specified after a single "&#63;" marker
108      * at end of action's name.
109      * @param action requested action's name (non-null)
110      **/
111     public void setAction(String JavaDoc action)
112     {
113         require_(action!=null,"setAction- nonzro action");
114         int i = action.indexOf("?");
115         if (i>0) {
116             String JavaDoc choice = scrub(action.substring(0,i++));
117             m_actionName = Tk.lowercaseFrom(choice);
118             if (i<action.length()) {
119                 m_uriParams = action.substring(i);
120             }
121         } else {
122             m_actionName = Tk.lowercaseFrom(scrub(action));
123         }
124     }
125
126
127
128     /**
129      * Returns the current setting for this task's action name.
130      * Will return <i>null</i> if not yet set.
131      **/
132     protected final String JavaDoc getActionName()
133     {
134         return m_actionName;
135     }
136
137
138
139     /**
140      * Returns the query string after the "&#63;" in the
141      * action's name. Will return <i>null</i> if no such string
142      * defined. The string returned is as it was entered in the
143      * action name URI; no lowercasing or other normalization is
144      * applied.
145      **/
146     protected final String JavaDoc getUriParams0()
147     {
148         return m_uriParams;
149     }
150
151
152
153     /**
154      * Adds a custom parameter to this control task. This
155      * parameter is passed to the selected action's method
156      * as a simple <span class="src">Map.Entry</span>.
157      * @param param the parameter information (non-null)
158      * @throws BuildException if parameter is not named.
159      **/
160     public void addConfiguredParameter(InnerNameValuePair param)
161     {
162         require_(param!=null,"addParam- nonzro param");
163         param.verifyNamed();
164
165         if (m_nestedParams==null) {
166             m_nestedParams = AntXFixture.newMap();
167         }
168         m_nestedParams.put(param.getName(),param.getValue());
169     }
170
171
172
173     /**
174      * Adds a placeholder parameter to this control task. Usually
175      * this method is used for dynamic nested elements which cannot
176      * be verified until the execute method is triggered.
177      * @param param to placeholder (non-null)
178      **/
179     protected final void addCheckLaterParameter(InnerNameValuePair param)
180     {
181         require_(param!=null,"addParamPlaceholder- nonzro param");
182         if (m_nestedUnverifiedParams==null){
183             m_nestedUnverifiedParams = AntXFixture.newList();
184         }
185         m_nestedUnverifiedParams.add(param);
186     }
187
188
189
190     /**
191      * Tells this task whether it should suppress feedback chatter.
192      * @param level feedback level ("normal", "loud", "quiet", etc.)
193      **/
194     public void setFeedback(String JavaDoc level)
195     {
196         m_fbLevel = FeedbackLevel.from(level);
197     }
198
199
200
201     /**
202      * Returns this task's script-supplied quiet setting. Will
203      * return {@linkplain FeedbackLevel#NORMAL NORMAL} if never
204      * set explicitly.
205      **/
206     public final FeedbackLevel getFeedbackLevel()
207     {
208         return m_fbLevel;
209     }
210
211
212
213     /**
214      * Executes the requested action passing any nested parameters
215      * as options. If no action is named and this task's haltiferror
216      * option is disabled, will issue a warning and do nothing.
217      * @throws BuildException if no action named and haltiferror is true.
218      **/
219     public void execute()
220     {
221         verifyCanExecute_("exec");
222
223         if (m_actionName!=null) {
224             Map JavaDoc args = Collections.EMPTY_MAP;
225             if (m_nestedParams!=null) {
226                 args = Collections.unmodifiableMap(m_nestedParams);
227             }
228             doAction(m_actionName,args,m_rqlink);
229         }
230     }
231
232
233
234     /**
235      * Verifies we have a specified action even if it's a default one.
236      * @throws BuildException if no action named and haltiferror is true.
237      **/
238     protected void verifyCanExecute_(String JavaDoc calr)
239     {
240         super.verifyCanExecute_(calr);
241
242         if (m_actionName==null) {
243             String JavaDoc message = Iteration.uistrs().get("task.needs.this.attr",
244                 getTaskName(), "action");
245             if (isHaltIfError()) {
246                 log(message, Project.MSG_ERR);
247                 throw new BuildException(message,getLocation());
248             }
249             //NB:*NOT* optional; always warn!
250 log(message, Project.MSG_WARN);
251         }
252
253         if (m_nestedUnverifiedParams!=null) {
254             Iterator JavaDoc itr = m_nestedUnverifiedParams.iterator();
255             while (itr.hasNext()) {
256                 addConfiguredParameter((InnerNameValuePair)itr.next());
257             }
258             m_nestedUnverifiedParams = null;//incase rerun
259 }
260     }
261
262
263
264     /**
265      * Ensures we can execute as part of a simple antlib definition
266      * with current action. Uses callback method
267      * {@linkplain #isInvalidAntlibAction}.
268      **/
269     protected final void verifyNotInAntlib()
270     {
271         //If as Antlib definition, only install operations are permitted!
272 if (getAntlibClassLoader()!=null) {//=>in Antlib always?
273 if (isInvalidAntlibAction()) {
274                 String JavaDoc ermsg = uistrs().get
275                     ("task.manager.err.illegal.operation",getActionName());
276                 log(ermsg,Project.MSG_ERR);
277                 throw new BuildException(ermsg,getLocation());
278             }
279         }
280     }
281
282
283
284     /**
285      * Returns <i>true</i> if current action cannot be performed
286      * if we are part of a simple antlib. Returns <i>false</i> by
287      * default; subclasses should override to test our action name.
288      **/
289     protected boolean isInvalidAntlibAction()
290     {
291         return false;
292     }
293
294
295
296     /**
297      * Collapses the visual spacers in an action's name. Spacers
298      * are for the script author's benefit; they are omitted from
299      * the action method's name.
300      * @param s the incoming script action string
301      * @return spacer-scrubed name (non-null)
302      **/
303     private String JavaDoc scrub(String JavaDoc s)
304     {
305         StringBuffer JavaDoc sb = new StringBuffer JavaDoc(s.length());
306         int N= s.length();
307         int i= 0;
308         while (N!=0) {
309             char c = s.charAt(i++);
310             if (i==1) {
311                 if (Character.isJavaIdentifierStart(c)) {
312                     sb.append(c);
313                 }
314             } else if (Character.isJavaIdentifierPart(c)) {
315                 sb.append(c);
316             }
317             N--;
318         }
319         return sb!=null ? sb.substring(0) : s;
320     }
321
322
323     private String JavaDoc m_actionName;
324     protected Requester m_rqlink = new Requester.ForComponent(this);
325     private String JavaDoc m_uriParams;
326     private FeedbackLevel m_fbLevel = FeedbackLevel.NORMAL;
327
328     /** This task's script-nested parameters. **/
329     protected Map JavaDoc m_nestedParams;
330     private List JavaDoc m_nestedUnverifiedParams;
331 }
332
333
334 /* end-of-SimpleManagerTask.java */
Popular Tags