KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tools > ant > module > api > AntTargetExecutor


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.apache.tools.ant.module.api;
21
22 import java.io.IOException JavaDoc;
23 import java.io.OutputStream JavaDoc;
24 import java.util.Properties JavaDoc;
25 import org.apache.tools.ant.module.AntSettings;
26 import org.apache.tools.ant.module.run.TargetExecutor;
27 import org.openide.execution.ExecutorTask;
28 import org.openide.util.NbCollections;
29
30 /**
31  * Executes an Ant target or list of targets asynchronously inside NetBeans.
32  * @since 2.15
33  */
34 final public class AntTargetExecutor {
35
36     private final Env env;
37
38     /** Create instance of Ant target executor for the given Ant project.
39      */
40     private AntTargetExecutor(Env env) {
41         this.env = env;
42     }
43     
44     /** Factory method for creation of AntTargetExecutor with the given environment.
45      * The factory does not clone Env what means that any change to Env will
46      * influence the factory.
47      * @param env a configuration for the executor
48      * @return an executor which can run projects with the given configuration
49      */
50     public static AntTargetExecutor createTargetExecutor(Env env) {
51         return new AntTargetExecutor(env);
52     }
53     
54     /** Execute given target(s).
55      * <p>The {@link AntProjectCookie#getFile} must not be null, since Ant can only
56      * run files present on disk.</p>
57      * <p>The returned task may be used to wait for completion of the script
58      * and check result status.</p>
59      * <p class="nonnormative">
60      * The easiest way to get the project cookie is to get a <code>DataObject</code>
61      * representing an Ant build script and to ask it for this cookie. Alternatively,
62      * you may implement the cookie interface directly, where
63      * <code>getFile</code> is critical and other methods may do nothing
64      * (returning <code>null</code> as needed).
65      * While the specification for <code>AntProjectCookie</code> says that
66      * <code>getDocument</code> and <code>getParseException</code> cannot
67      * both return <code>null</code> simultaneously, the <em>current</em>
68      * executor implementation does not care; to be safe, return an
69      * {@link UnsupportedOperationException} from <code>getParseException</code>.
70      * </p>
71      * @param antProject a representation of the project to run
72      * @param targets non-empty list of target names to run; may be null to indicate default target
73      * @return task for tracking of progress of execution
74      * @throws IOException if there is a problem running the script
75      */
76     public ExecutorTask execute(AntProjectCookie antProject, String JavaDoc[] targets) throws IOException JavaDoc {
77         TargetExecutor te = new TargetExecutor(antProject, targets);
78         te.setVerbosity(env.getVerbosity());
79         te.setProperties(NbCollections.checkedMapByCopy(env.getProperties(), String JavaDoc.class, String JavaDoc.class, true));
80         if (env.getLogger() == null) {
81             return te.execute();
82         } else {
83             return te.execute(env.getLogger());
84         }
85     }
86
87     /** Class describing the environment in which the Ant target will be executed.
88      * The class can be used for customization of properties avaialble during the
89      * execution, verbosity of Ant target execution and output stream definition.
90      */
91     final public static class Env {
92
93         private int verbosity;
94         private Properties JavaDoc properties;
95         private OutputStream JavaDoc outputStream;
96
97         /** Create instance of Env class describing environment for Ant target execution.
98          */
99         public Env() {
100             verbosity = AntSettings.getVerbosity();
101             properties = new Properties JavaDoc();
102             properties.putAll(AntSettings.getProperties());
103         }
104
105         /**
106          * Set verbosity of Ant script execution.
107          * @param v the new verbosity (e.g. {@link org.apache.tools.ant.module.spi.AntEvent#LOG_VERBOSE})
108          */
109         public void setVerbosity(int v) {
110             verbosity = v;
111         }
112
113         /** Get verbosity of Ant script execution.
114          * @return the current verbosity (e.g. {@link org.apache.tools.ant.module.spi.AntEvent#LOG_VERBOSE})
115          */
116         public int getVerbosity() {
117             return verbosity;
118         }
119
120         /** Set properties of Ant script execution.
121          * @param p a set of name/value pairs passed to Ant (will be cloned)
122          */
123         public synchronized void setProperties(Properties JavaDoc p) {
124             properties = (Properties JavaDoc) p.clone();
125         }
126
127         /** Get current Ant script execution properties. The clone of
128          * real properties is returned.
129          * @return the current name/value pairs passed to Ant
130          */
131         public synchronized Properties JavaDoc getProperties() {
132             return (Properties JavaDoc)properties.clone();
133         }
134
135         /** Set output stream into which the output of the
136          * Ant script execution will be sent. If not set
137          * the standard NetBeans output window will be used.
138          * @param outputStream a stream to send output to, or <code>null</code> to reset
139          * @see org.apache.tools.ant.module.spi.AntOutputStream
140          * @deprecated Usage of a custom output stream is not recommended, and prevents some
141          * Ant module features from working correctly.
142          */
143         @Deprecated JavaDoc
144         public void setLogger(OutputStream JavaDoc outputStream) {
145             this.outputStream = outputStream;
146         }
147
148         /** Get output stream. If no output stream was
149          * set then null will be returned what means that standard
150          * NetBeans output window will be used.
151          * @return the output stream to which Ant output will be sent, or <code>null</code>
152          */
153         public OutputStream JavaDoc getLogger() {
154             return outputStream;
155         }
156
157     }
158     
159 }
160
Popular Tags