Locals


1   /**
2    * $Id: Locals.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.flowcontrol.wrap;
30  
31  import  java.util.Collections  ;
32  import  java.util.Iterator  ;
33  import  java.util.List  ;
34  import  java.util.Map  ;
35  
36  import  org.apache.tools.ant.BuildException;
37  import  org.apache.tools.ant.Location;
38  import  org.apache.tools.ant.Project;
39  
40  import  com.idaremedia.antx.AntX;
41  import  com.idaremedia.antx.AntXFixture;
42  import  com.idaremedia.antx.AssertableTask;
43  import  com.idaremedia.antx.apis.Nameable;
44  import  com.idaremedia.antx.apis.Requester;
45  
46  
47  /**
48   * Collection of fixture elements that should be either preserved by or limited to
49   * an isolated task set. Variables are inherited from the enclosing context by
50   * default; you must explicit unset pre-existing variables by setting the 
51   * <span class="src">inherit</span> parameter <i>false</i>. Properties are <em>not</em>
52   * inherited by default; you must explicitly copy pre-existing properties by
53   * setting the <span class="src">inherit</span> parameter <i>true</i>. When default
54   * values are assigned to local properties, these properties act as overlayed values
55   * that replace any pre-existing settings unconditionally.
56   * <p/>
57   * Locals are applied en-masse at once. This means a local's definition cannot depend
58   * on another local's definition since it's not guaranteed that the source item will
59   * be initialized first. Of course locals can depend on pre-existing fixture values
60   * including macro attribute values.
61   * <p/>
62   * <b>Example Usage:</b><pre>
63   *    &lt;macrodef name="fubar"&gt;
64   *       &lt;attribute name="all" default="no"/&gt;
65   *       &lt;sequential&gt;
66   *          &lt;<b>locals name="fubar.locals"</b>&gt;
67   *             &lt;property name="generate"/&gt;
68   *             &lt;property name="allowtests" value="@{all}"/&gt;
69   *          &lt;/locals&gt;
70   *          ...
71   *          &lt;isolate block="fubar.locals"&gt;
72   *              &lt;do if="allowtests"&gt;
73   *                 ...
74   *              &lt;condition property="generate"&gt;
75   *                 ...
76   *          &lt;/isolate&gt;
77   *       &lt;/sequential&gt;
78   *    &lt;/macrodef&gt;
79   * </pre>
80   *
81   * @since     JWare/AntX 0.5
82   * @author    ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
83   * @version   0.5
84   * @.safety   single
85   * @.group    api,helper
86   * @see       IsolatedTaskSet
87   * @.impl     Because this whole notion of macro locals (and scoping in general)
88   *            is destined to appear in Ant at some point, most of this class's API
89   *            is kept package-private to ease transition to whatever becomes the
90   *            standard Ant mechanism.
91   **/
92  
93  public final class Locals extends AssertableTask implements Nameable
94  {
95      /**
96       * Initialize a new locals bucket. This item's name is
97       * defaulted to <span class="src">_macrolocals_</span>.
98       **/
99      public Locals()
100     {
101         super(AntX.flow+"Locals:");
102     }
103 
104 
105 
106     /**
107      * Marks this locals declaration as a blocking definition
108      * or not. If blocking this locals items should be removed
109      * from the enclosing project's context when the bubble
110      * exits.
111      * @param denied <i>true</i> if our items should be removed.
112      **/
113     final void setBlocking(boolean denied)
114     {
115         m_isDenied = denied;
116     }
117 
118 
119 
120     /**
121      * Returns <i>true</i> if this local's items should be removed
122      * from the enclosing bubble's context before it exits.
123      **/
124     boolean isBlocking()
125     {
126         return m_isDenied;
127     }
128 
129 
130 
131     /**
132      * Sets this locals name so it can be referenced by a
133      * bubble or net component.
134      * @param name this locals handle (non-null)
135      * @.sideeffect Will install this locals into the project's
136      *   reference table using this name.
137      */
138     public void setName(String   name)
139     {
140         require_(name!=null,"setName- nonzro name");
141         m_name = name;
142     }
143 
144 
145     /**
146      * Returns this locals item's name. Will never return
147      * <i>null</i>; defaults to <span class="src">_macrolocals</span>.
148      */
149     public final String   getName()
150     {
151         return m_name;
152     }
153 
154 
155 
156     /**
157      * Sets default inherit option for all of this local's
158      * contained items. Individual items can override this 
159      * setting.
160      * @param inherit <i>true</i> to inherit
161      **/
162     public void setInherit(boolean inherit)
163     {
164         m_inherit = inherit ? Boolean.TRUE : Boolean.FALSE;
165     }
166 
167 
168 
169     /**
170      * Returns this local's inherit flag setting. Will return
171      * <i>null</i> if never set explicitly.
172      **/
173     public final Boolean   getInheritFlag()
174     {
175         return m_inherit;
176     }
177 
178 
179 
180     /**
181      * Returns a local item's inherit flag setting. Will return
182      * <i>null</i> if neither the item not this bucket has 
183      * an explicit setting.
184      **/
185     public final Boolean   getInheritFlag(ConditionalLocal local)
186     {
187         Boolean   f = local.getInheritFlag();
188         if (f==null) {
189             f = getInheritFlag();
190         }
191         return f;
192     }
193 
194 
195 
196     /**
197      * Adds a new property item to this locals bucket.
198      * @return the new item
199      **/
200     public Object   createProperty()
201     {
202         if (m_propertyItems==null) {
203             m_propertyItems = AntXFixture.newList();
204         }
205         return newItem(m_propertyItems);
206     }
207 
208 
209 
210     /**
211      * Adds a new variable item to this locals bucket.
212      * @return the new item
213      **/
214     public Object   createVariable()
215     {
216         if (m_variableItems==null) {
217             m_variableItems = AntXFixture.newList();
218         }
219         return newItem(m_variableItems);
220     }
221 
222 
223 
224     /**
225      * Common synonym for {@linkplain #createVariable}.
226      * @return the new item
227      **/
228     public final Object   createVar()
229     {
230         return createVariable();
231     }
232 
233 
234 
235     /**
236      * Ensures all local items have been named (at least). Values
237      * are not required for local declarations.
238      * @param calr execution method (non-null)
239      **/
240     protected void verifyCanExecute_(String   calr)
241     {
242         super.verifyCanExecute_(calr);
243         try {
244             verifyNamed(m_propertyItems);
245             verifyNamed(m_variableItems);
246             //verifyNamed(m_referenceItems);
247         } catch(BuildException bX) {
248             log(bX.getMessage(),Project.MSG_ERR);
249             if (bX.getLocation()==Location.UNKNOWN_LOCATION) {
250                 bX = new BuildException(bX,getLocation());
251             }
252             throw bX;
253         }
254     }
255 
256 
257     /**
258      * Ensures this locals item and all of its nested items are
259      * named. Once verified, will install this locals into its
260      * project's reference table using its name as the key.
261      * @throws BuildException if another locals object already exists
262      *     with same handle.
263      * @throws BuildException if this object or any of its nested
264      *     items are improperly named (or unnamed).
265      */
266     public void execute()
267     {
268         verifyCanExecute_("exec");
269 
270         Map   ht = getProject().getReferences();
271         synchronized(ht) {
272             if (ht.containsKey(getName())) {
273                 String   error = getAntXMsg("flow.locals.exists",getName());
274                 log(error,Project.MSG_ERR);
275                 throw new BuildException(error,getLocation());
276             }
277             ht.put(getName(),this);
278         }
279     }
280 
281 
282 
283     /**
284      * Removes this locals item from the project's reference table. This 
285      * method should be called immediately after a locals reference
286      * is assigned to a bubble or net. This method does
287      * <em>nothing</em> if this locals object is not installed.
288      * @param clnt feedback controls.
289      * @return <i>true</i> if removed from projects reference table.
290      **/
291     public final boolean uninstall(Requester clnt)
292     {
293         boolean ok=true;
294         Map   ht = getProject().getReferences();
295         synchronized(ht) {
296             Object   o = ht.get(getName());
297             if (o==this) {
298                 ht.remove(getName());
299             } else {
300                 String   warning = getAntXMsg("flow.locals.not.installed",getName());
301                 clnt.problem(warning,Project.MSG_WARN);
302                 ok = false;
303             }
304         }
305         return ok;
306     }
307 
308 
309 
310     List   getProperties()
311     {
312         return m_propertyItems;
313     }
314 
315 
316     List   getVariableNames()
317     {
318         return getItemNames(m_variableItems);
319     }
320 
321 
322     List   getVariables()
323     {
324         return m_variableItems;
325     }
326 
327 
328     boolean hasVariables()
329     {
330         return m_variableItems!=null;
331     }
332     
333     
334     private ConditionalLocal newItem(List   list)
335     {
336         ConditionalLocal item = new ConditionalLocal();
337         list.add(item);
338         return item;
339     }
340 
341 
342     private List   getItemNames(List   from)
343     {
344         List   l = Collections.EMPTY_LIST;
345         if (from!=null) {
346             synchronized(from) {
347                 l = AntXFixture.newList(from.size());
348                 for (int i=0,N=from.size();i<N;i++) {
349                     ConditionalLocal local = (ConditionalLocal)from.get(i);
350                     if (local.isEnabled()) {
351                         l.add(local.getName());
352                     }
353                 }
354             }
355         }
356         return l;
357     }
358 
359     
360     private void verifyNamed(List   from)
361     {
362         if (from!=null) {
363             synchronized(from) {
364                 Iterator   itr= from.iterator();
365                 while (itr.hasNext()) {
366                     ConditionalLocal local = (ConditionalLocal)itr.next();
367                     local.verifyNamed();
368                 }
369             }
370         }
371     }
372 
373 
374     private String   m_name = "_macrolocals_";
375     private boolean m_isDenied;
376     private List   m_propertyItems,m_variableItems;
377     private Boolean   m_inherit;
378 }
379 
380 /* end-of-Locals.java */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags