ExportedProperties


1   /**
2    * $Id: ExportedProperties.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 of the License, or (at your option) any later
9    * 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;
30  
31  import  java.util.ArrayList  ;
32  import  java.util.Collection  ;
33  import  java.util.HashMap  ;
34  import  java.util.Iterator  ;
35  import  java.util.Map  ;
36  import  java.util.Properties  ;
37  
38  import  com.idaremedia.antx.apis.ProblemHandler;
39  
40  /**
41   * Manager of a build-iteration's thread-local modifiable properties. This class is
42   * used heavily by the core {@linkplain com.idaremedia.antx.solo.ExportTask ExportTask}
43   * and {@linkplain com.idaremedia.antx.solo.ImportTask ImportTask} tasks.
44   * This class is almost always used via the various {@linkplain Iteration singleton}
45   * static APIs like {@linkplain #readstring readstring}, {@linkplain #set set},
46   * and {@linkplain #delete delete}.
47   * <p>
48   * This class administers a <em>single</em> thread-independent collection of
49   * thread-specific elements. In other words, for each property there is a single named
50   * collection of thread-specific values. This is different from how other thread-based
51   * iteration information is stored. See the {@linkplain FixtureOverlays} class for further
52   * details.
53   * <p>
54   * This class's effectiveness relies on a single instance being used. Within Ant certain
55   * tasks can create multiple class loaders hence muddying the singleton concept because
56   * class loaders are a hidden (or forgotten) link in the definition of a unique entity
57   * within a VM's object space. Soooo my advice is to use modifiable properties with care
58   * when mucking with multiple, user controlled, class loaders within a single thread.
59   *
60   * @since    JWare/AntX 0.1
61   * @author   ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
62   * @version  0.5
63   * @.safety  guarded
64   * @.group   impl,helper
65   * @see      com.idaremedia.antx.solo.ExportTask
66   * @see      PropertyHandle
67   * @see      Iteration#exportableProperties
68   **/
69  
70  public final class ExportedProperties implements FixtureCore, FixtureAdministrator
71  {
72      private static final String   IAM_ = "ExportableProperties:";
73  
74  
75  
76      /**
77       * If you really want your own set of modifiable exportable
78       * properties for something.
79       * @see Iteration#exportableProperties
80       **/
81      public ExportedProperties()
82      {
83      }
84  
85  
86  
87      /**
88       * Returns modifiable property handle for named item.
89       * @param name the property's name (non-null)
90       **/
91      public PropertyHandle getProperty(String   name)
92      {
93          AntX.require_(name!=null,IAM_,"get- nonzro name");
94  
95          synchronized(m_handles) {
96              PropertyHandle ph = (PropertyHandle)m_handles.get(name);
97              if (ph==null) {
98                  ph = new PropertyHandle();
99                  m_handles.put(name, ph);
100             }
101             return ph;
102         }
103     }
104 
105 
106 
107     /**
108      * Convenience to get(create) and set a property handle in single
109      * operation.
110      * @param name the property's name (non-null)
111      * @param valu the property's value
112      **/
113     public void putProperty(String   name, Object   valu)
114     {
115         PropertyHandle ph = getProperty(name);
116         ph.set(valu);
117     }
118 
119 
120 
121     /**
122      * Returns <i>true</i> if a property handle already exists for
123      * given name. This method does not check the property handle's
124      * contents.
125      * @param name the property's name  (non-null)
126      **/
127     public boolean knowsProperty(String   name)
128     {
129         AntX.require_(name!=null,IAM_,"check- nonzro name");
130 
131         synchronized(m_handles) {
132             return m_handles.containsKey(name);
133         }
134     }
135 
136 
137 
138     /**
139      * Convenience to read a property's value iff it's defined or
140      * return some default value. Returns <i>null</i> if the property
141      * is defined and it's current value is <i>null</i>-- will not
142      * return the default value.
143      * @param name the property's name (non-null)
144      * @param dflt default value return iff property not defined
145      **/
146     public Object   readProperty(String   name, Object   dflt)
147     {
148         AntX.require_(name!=null,IAM_,"read- nonzro name");
149 
150         synchronized(m_handles) {
151             PropertyHandle ph= (PropertyHandle)m_handles.get(name);
152             return (ph!=null) ? ph.get() : dflt;
153         }
154     }
155 
156 
157 
158     /**
159      * Convenience to clear the property handle's value in a single
160      * operation. Any existing property handle is returned (can be
161      * <i>null</i>).
162      * @param name the property's name (non-null)
163      **/
164     public PropertyHandle removeProperty(String   name)
165     {
166         AntX.require_(name!=null,IAM_,"remove- nonzro name");
167 
168         synchronized(m_handles) {
169             return (PropertyHandle)m_handles.remove(name);
170         }
171     }
172 
173 
174 
175     /**
176      * Convenience to clear a collection of properties in a single
177      * operation.
178      * @param names the collection of properties to delete (non-null)
179      * @since JWare/AntX 0.5
180      **/
181     public void removeProperties(Collection   names)
182     {
183         AntX.require_(names!=null,IAM_,"remove- nonzro names");
184 
185         synchronized(m_handles) {
186             m_handles.keySet().removeAll(names);
187         }
188     }
189 
190 
191 
192     /**
193      * Convenience to clear a collection of properties in a single
194      * operation. Only properties with names matching those in the
195      * given collection are retained.
196      * @param names the collection of properties to retain (non-null)
197      * @since JWare/AntX 0.5
198      **/
199     public void retainProperties(Collection   names)
200     {
201         AntX.require_(names!=null,IAM_,"retain- nonzro names");
202 
203         synchronized(m_handles) {
204             m_handles.keySet().retainAll(names);
205         }
206     }
207 
208 
209 
210     /**
211      * Returns detached copy of all properties in current repository. The
212      * returned Properties item is a regular key->value mapping. Useful
213      * for capturing environment diagnostics.
214      * @param existingP Properties to be updated (pass <i>null</i> for new)
215      * @since JWare/AntX 0.2
216      **/
217     public Properties   copyOfProperties(Properties   existingP)
218     {
219         if (existingP==null) {
220             existingP= new Properties  ();
221         }
222         synchronized(m_handles) {
223             Iterator   itr = m_handles.entrySet().iterator();
224             while (itr.hasNext()) {
225                 Map.Entry   mE= (Map.Entry  )itr.next();
226                 PropertyHandle ph= (PropertyHandle)mE.getValue();
227                 existingP.put(mE.getKey(),String.valueOf(ph.get()));//cvt null to "null"
228             }
229         }
230         return existingP;
231     }
232 
233 
234 
235     /**
236      * Returns detached copy of names of all properties in current 
237      * repository. The returns Collection contains property names.
238      * This is used to capture environment diagnostics and support
239      * execution bubbles.
240      * @since JWare/AntX 0.5
241      **/
242     public Collection   copyOfPropertyNames()
243     {
244         synchronized(m_handles) {
245             return new ArrayList  (m_handles.keySet());
246         }
247     }
248 
249 
250 
251     /**
252      * Clears all properties for all threads in current repository. Your
253      * application should never use this method directly; it is provided for
254      * test harness to reset the environment to a known state.
255      * @since JWare/AntX 0.4
256      **/
257     void clearProperties()
258     {
259         synchronized(m_handles) {
260             m_handles.clear();
261             m_handles = new HashMap  (111,0.8f);
262         }
263     }
264 
265 
266     /**
267      * Instance-level member fields.
268      **/
269     private HashMap   m_handles= new HashMap  (111,0.8f);
270 
271 
272 
273 //---------------------------------------------------------------------------------------------------------|
274 // Bunch of convenient utility APIs for the Iteration singleton:
275 //---------------------------------------------------------------------------------------------------------|
276 
277 
278     /**
279      * Returns a complete independent copy of the current iteration's 
280      * {@linkplain Iteration#exportableProperties exportable properties}.
281      * @since JWare/AntX 0.5
282      **/
283     public static final Properties   copy(Properties   fillin)
284     {
285         return Iteration.exportableProperties().copyOfProperties(fillin);
286     }
287 
288 
289     /**
290      * Returns <i>true</i> if the named property is defined in the
291      * current iteration's 
292      * {@linkplain Iteration#exportableProperties exportable properties}.
293      * @since JWare/AntX 0.5
294      **/
295     public static final boolean has(String   name)
296     {
297         return Iteration.exportableProperties().knowsProperty(name);
298     }
299 
300 
301     /**
302      * Returns a property from the current iteration's 
303      * {@linkplain Iteration#exportableProperties exportable properties}.
304      **/
305     public static final PropertyHandle get(String   name)
306     {
307         return Iteration.exportableProperties().getProperty(name);
308     }
309 
310 
311     /**
312      * Updates a property value in the current iteration's 
313      * {@linkplain Iteration#exportableProperties exportable properties}.
314      **/
315     public static final void set(String   name, Object   valu)
316     {
317         Iteration.exportableProperties().putProperty(name,valu);
318     }
319 
320 
321     /**
322      * Clears a property value in the current iteration's 
323      * {@linkplain Iteration#exportableProperties exportable properties}.
324      * The property is still known to the iteration. Use {@linkplain #delete
325      * delete(name)} to remove a property from the iteration.
326      * @see #delete
327      **/
328     public static final void unset(String   name)
329     {
330         Iteration.exportableProperties().putProperty(name,null);
331     }
332 
333 
334     /**
335      * Reads a property value from the current iteration's 
336      * {@linkplain Iteration#exportableProperties exportable properties}
337      * returning a default value if property not defined.
338      **/
339     public static final Object   read(String   name, Object   dflt)
340     {
341         return Iteration.exportableProperties().readProperty(name,dflt);
342     }
343 
344 
345     /**
346      * Reads a property value from the current iteration's 
347      * {@linkplain Iteration#exportableProperties exportable properties}
348      * returning a default string if property not defined.
349      **/
350     public static final String   readstring(String   name, String   dflt)
351     {
352         return (String  )Iteration.exportableProperties().readProperty(name,dflt);
353     }
354 
355 
356     /**
357      * Reads a property value from current iteration's 
358      * {@linkplain Iteration#exportableProperties exportable properties}
359      * returning <i>null</i> if property not defined.
360      **/
361     public static final Object   read(String   name)
362     {
363         return Iteration.exportableProperties().readProperty(name,null);
364     }
365 
366 
367     /**
368      * Reads a property value from current iteration's 
369      * {@linkplain Iteration#exportableProperties exportable properties}
370      * returning <i>null</i> if property not defined.
371      **/
372     public static final String   readstring(String   name)
373     {
374         return (String  )Iteration.exportableProperties().readProperty(name,null);
375     }
376 
377 
378     /**
379      * Deletes a property from the current iteration's 
380      * {@linkplain Iteration#exportableProperties exportable properties}.
381      **/
382     public static final void delete(String   name)
383     {
384         Iteration.exportableProperties().removeProperty(name);
385     }
386 
387 
388     /**
389      * Deletes a collection of properties from the current iteration's 
390      * {@linkplain Iteration#exportableProperties exportable properties}.
391      * @since JWare/AntX 0.5
392      **/
393     public static final void delete(Collection   names)
394     {
395         Iteration.exportableProperties().removeProperties(names);
396     }
397 
398 
399     /**
400      * Deletes a collection of properties from the current iteration's 
401      * {@linkplain Iteration#exportableProperties exportable properties}.
402      * Only properties with names matching those in the given collection
403      * are retained.
404      * @since JWare/AntX 0.5
405      **/
406     public static final void retain(Collection   names)
407     {
408         Iteration.exportableProperties().retainProperties(names);
409     }
410 
411 
412 //---------------------------------------------------------------------------------------------------------|
413 // Iteration reset for execution harnesses;
414 //---------------------------------------------------------------------------------------------------------|
415 
416     /**
417      * Installs fixture component cleanup method.
418      * @since JWare/AntX 0.4
419      **/
420     static {
421         AntXFixture.setKillMethod
422             (FixtureIds.VARIABLES_ADMINISTRATION,
423              new String  []{"variables","exportedproperties"},
424              new KillMethod() {
425                      public boolean kill(ProblemHandler from) {
426                          /*!*/
427                          Iteration.exportableProperties().clearProperties();
428                          return true;
429                      }
430                      public boolean kill(String   target, ProblemHandler from) {
431                          return kill(from);
432                      }
433                  }
434              );
435     }
436 }
437 
438 /* end-of-ExportedProperties.java */
439
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags