EchoThingTask


1   /**
2    * $Id: EchoThingTask.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.starters;
30  
31  import  java.io.ByteArrayOutputStream  ;
32  import  java.io.File  ;
33  import  java.io.FileOutputStream  ;
34  import  java.io.IOException  ;
35  import  java.io.OutputStream  ;
36  
37  import  org.apache.tools.ant.BuildException;
38  import  org.apache.tools.ant.Project;
39  
40  import  com.idaremedia.antx.helpers.Strings;
41  import  com.idaremedia.antx.parameters.InformationSaver;
42  
43  /**
44   * Skeleton for a helper task that displays some internal single AntX variable or
45   * single data type without using the extended AntX display registry mechanism. Note
46   * that starting with AntX 0.4, {@linkplain com.idaremedia.antx.print.DisplayStrategy
47   * DisplayStrategies} are the preferred display mechanism for AntX types. If an
48   * Echo*Task is written, it must use the type's display strategy implementation
49   * to ensure it remains in-sync.
50   *
51   * @since    JWare/AntX 0.2
52   * @author   ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
53   * @version  0.5
54   * @.safety  single
55   * @.group   impl,helper
56   **/
57  
58  public abstract class EchoThingTask extends MsgTask
59      implements InformationSaver
60  {
61      /**
62       * Platform-specific newline.
63       **/
64      protected static final String   NL= Strings.NL;
65  
66  
67  
68      /**
69       * Initializes new CV-labeled EchoThingTask.
70       * @param iam CV-label (non-null)
71       **/
72      protected EchoThingTask(String   iam)
73      {
74          super(iam);
75      }
76  
77  // ---------------------------------------------------------------------------------------
78  // Public build parameters:
79  // ---------------------------------------------------------------------------------------
80  
81      /**
82       * Sets the target file path for this echo task's generated
83       * output. If the path is relative, the output file will be
84       * determined relative to this task's project's base directory.
85       * @param outputFile the output file's path (non-null)
86       **/
87      public void setToFile(String   outputFile)
88      {
89          require_(outputFile!=null,"setToFil- nonzro file");
90          m_toFile= getProject().resolveFile(outputFile);
91      }
92  
93  
94  
95      /**
96       * Sets the target file for this echo task's generated output.
97       * The file reference is used as-is.
98       * @param outputFile the output file (non-null)
99       * @since JWare/AntX 0.4
100      **/
101     public final void setToProjectFile(File   outputFile)
102     {
103         require_(outputFile!=null,"setToProjFile- nonzro file");
104         m_toFile = outputFile;
105     }
106 
107 
108     /**
109      * Returns this task's target file for output. Returns
110      * <i>null</i> if never set.
111      * @since JWare/AntX 0.4
112      **/
113     public final String   getToFilePath()
114     {
115         File   f = getToFile();
116         return f!=null ? f.getPath() : null;
117     }
118 
119 
120     /**
121      * Returns this task's target file for output. Returns
122      * <i>null</i> if never set.
123      **/
124     public File   getToFile()
125     {
126         return m_toFile;
127     }
128 
129 
130     /**
131      * Marks whether this task should try to append its new information
132      * to its output stream.
133      * @param append <i>true</i> if should try to append
134      **/
135     public void setAppend(boolean append)
136     {
137         m_tryAppend= append;
138     }
139 
140 
141     /**
142      * Returns <i>true</i> if this task will try to append any new
143      * information to an existing output sink. By default is <i>false</i>.
144      **/
145     public final boolean willTryAppend()
146     {
147         return m_tryAppend;
148     }
149 
150 // ---------------------------------------------------------------------------------------
151 // Implementation helpers:
152 // ---------------------------------------------------------------------------------------
153 
154     /**
155      * Initializes the reference id of this task's thing.
156      **/
157     protected final void setThingRefId(String   refId)
158     {
159         require_(refId!=null,"setrefId- nonzro refid");
160         m_refId = refId;
161     }
162 
163 
164     /**
165      * Returns this task's thing reference id; can be <i>null</i>
166      * if never set. Required for task to execute properly.
167      **/
168     protected final String   getThingRefId()
169     {
170         return m_refId;
171     }
172 
173 
174     /**
175      * Returns the parameter name of this task's thing refid.
176      * Used in diagnostic messages.
177      * @since JWare/AntX 0.4
178      **/
179     protected String   getThingRefParameterName()
180     {
181         return "refid";//backward compatible
182     }
183 
184 
185     /**
186      * Returns the actual thing instance echoed by this task. Never
187      * returns <i>null</i>.
188      * @param ofKind thing's required class (non-null)
189      * @param msgid id of error message used if reference invalid
190      * @throws BuildException if refid undefined or not a a valid thing
191      **/
192     protected Object   getReferencedThing(Class   ofKind, String   msgid)
193         throws BuildException
194     {
195         require_(ofKind!=null,"getRefTing- nonzro clas");
196         String   refid = getThingRefId();
197         if (msgid==null) {
198             return getReferencedObject(null,refid,ofKind);
199         }
200         Object   object = getProject().getReference(refid);
201         if (!ofKind.isInstance(object)) {
202             String   ermsg = uistrs().get(msgid,refid);
203             log(ermsg, Project.MSG_ERR);
204             throw new BuildException(ermsg,getLocation());
205         }
206         return object;
207     }
208 
209 
210     /**
211      * Ensures we're in a valid target/project and have a defined
212      * thing reference id. Subclasses must ensure the referenced thing
213      * is of the expected type.
214      * @see #getReferencedThing
215      **/
216     protected void verifyCanExecute_(String   calr)
217     {
218         super.verifyCanExecute_(calr);
219 
220         if (getThingRefId()==null) {
221             String   ermsg = uistrs().get("task.needs.this.attr",
222                                         getTaskName(),getThingRefParameterName());
223             log(ermsg, Project.MSG_ERR);
224             throw new BuildException(ermsg, getLocation());
225         }
226     }
227 
228 
229     /**
230      * Returns an output stream suitable for this task. The returned
231      * stream is the raw output stream, <em>not</em> a buffered stream.
232      **/
233     protected OutputStream   getOutputStream()
234     {
235         File   f = getToFile();
236         if (f!=null) {
237             try {
238                 return new FileOutputStream  (f.getPath(), willTryAppend());
239             } catch(IOException   ioX) {
240                 String   ermsg = uistrs().get("task.echo.unable.use.file",f.getPath(),
241                                             ioX.getMessage());
242                 log(ermsg,Project.MSG_WARN);
243             }
244         }
245         return new ByteArrayOutputStream  (1024);
246     }
247 
248 
249     /**
250      * Returns <i>true</i> if this task should try to echo the given
251      * output stream to the Ant runtime's logging system.
252      **/
253     protected boolean tryAntLog(OutputStream   os)
254     {
255         return (os instanceof ByteArrayOutputStream  );
256     }
257 
258 
259     /**
260      * Returns the information from the given stream to log to the
261      * Ant logging system. By default if the stream is a byte buffer,
262      * returns the entire contents; otherwise returns the empty string.
263      **/
264     protected String   getAntLogString(OutputStream   os)
265     {
266         if (os instanceof ByteArrayOutputStream  ) {
267             return ((ByteArrayOutputStream  )os).toString();
268         }
269         return "";
270     }
271 
272 
273     /**
274      * Echoes this task's referenced thing iff execution conditions
275      * have been met. Subclass should implement the {@linkplain #echoThing
276      * echoThing} method.
277      * @throws BuildException if invalid refid or a file I/O
278      *         error occurs.
279      * @see #echoThing
280      **/
281     public void execute() throws BuildException
282     {
283         verifyCanExecute_("execute");
284 
285         if (testIfCondition() && testUnlessCondition()) {
286             echoThing();
287         }
288     }
289 
290 
291     /**
292      * Actual task echoing work; subclass must provide.
293      * @throws BuildException if invalid refid or a file I/O
294      *         error occurs.
295      **/
296     protected abstract void echoThing() throws BuildException;
297 
298 
299 
300     private String   m_refId;
301     private File   m_toFile;
302     private boolean m_tryAppend;//NB:false=>overwrite existin'
303 }
304 
305 /* end-of-EchoThingTask.java */
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags