001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.apache.tools.ant.module.api;
043:
044: import java.io.IOException;
045: import java.io.OutputStream;
046: import java.util.Properties;
047: import org.apache.tools.ant.module.AntSettings;
048: import org.apache.tools.ant.module.run.TargetExecutor;
049: import org.openide.execution.ExecutorTask;
050: import org.openide.util.NbCollections;
051:
052: /**
053: * Executes an Ant target or list of targets asynchronously inside NetBeans.
054: * @since 2.15
055: */
056: final public class AntTargetExecutor {
057:
058: private final Env env;
059:
060: /** Create instance of Ant target executor for the given Ant project.
061: */
062: private AntTargetExecutor(Env env) {
063: this .env = env;
064: }
065:
066: /** Factory method for creation of AntTargetExecutor with the given environment.
067: * The factory does not clone Env what means that any change to Env will
068: * influence the factory.
069: * @param env a configuration for the executor
070: * @return an executor which can run projects with the given configuration
071: */
072: public static AntTargetExecutor createTargetExecutor(Env env) {
073: return new AntTargetExecutor(env);
074: }
075:
076: /** Execute given target(s).
077: * <p>The {@link AntProjectCookie#getFile} must not be null, since Ant can only
078: * run files present on disk.</p>
079: * <p>The returned task may be used to wait for completion of the script
080: * and check result status.</p>
081: * <p class="nonnormative">
082: * The easiest way to get the project cookie is to get a <code>DataObject</code>
083: * representing an Ant build script and to ask it for this cookie. Alternatively,
084: * you may implement the cookie interface directly, where
085: * <code>getFile</code> is critical and other methods may do nothing
086: * (returning <code>null</code> as needed).
087: * While the specification for <code>AntProjectCookie</code> says that
088: * <code>getDocument</code> and <code>getParseException</code> cannot
089: * both return <code>null</code> simultaneously, the <em>current</em>
090: * executor implementation does not care; to be safe, return an
091: * {@link UnsupportedOperationException} from <code>getParseException</code>.
092: * </p>
093: * @param antProject a representation of the project to run
094: * @param targets non-empty list of target names to run; may be null to indicate default target
095: * @return task for tracking of progress of execution
096: * @throws IOException if there is a problem running the script
097: */
098: public ExecutorTask execute(AntProjectCookie antProject,
099: String[] targets) throws IOException {
100: TargetExecutor te = new TargetExecutor(antProject, targets);
101: te.setVerbosity(env.getVerbosity());
102: te.setProperties(NbCollections.checkedMapByCopy(env
103: .getProperties(), String.class, String.class, true));
104: if (env.getLogger() == null) {
105: return te.execute();
106: } else {
107: return te.execute(env.getLogger());
108: }
109: }
110:
111: /** Class describing the environment in which the Ant target will be executed.
112: * The class can be used for customization of properties avaialble during the
113: * execution, verbosity of Ant target execution and output stream definition.
114: */
115: final public static class Env {
116:
117: private int verbosity;
118: private Properties properties;
119: private OutputStream outputStream;
120:
121: /** Create instance of Env class describing environment for Ant target execution.
122: */
123: public Env() {
124: verbosity = AntSettings.getVerbosity();
125: properties = new Properties();
126: properties.putAll(AntSettings.getProperties());
127: }
128:
129: /**
130: * Set verbosity of Ant script execution.
131: * @param v the new verbosity (e.g. {@link org.apache.tools.ant.module.spi.AntEvent#LOG_VERBOSE})
132: */
133: public void setVerbosity(int v) {
134: verbosity = v;
135: }
136:
137: /** Get verbosity of Ant script execution.
138: * @return the current verbosity (e.g. {@link org.apache.tools.ant.module.spi.AntEvent#LOG_VERBOSE})
139: */
140: public int getVerbosity() {
141: return verbosity;
142: }
143:
144: /** Set properties of Ant script execution.
145: * @param p a set of name/value pairs passed to Ant (will be cloned)
146: */
147: public synchronized void setProperties(Properties p) {
148: properties = (Properties) p.clone();
149: }
150:
151: /** Get current Ant script execution properties. The clone of
152: * real properties is returned.
153: * @return the current name/value pairs passed to Ant
154: */
155: public synchronized Properties getProperties() {
156: return (Properties) properties.clone();
157: }
158:
159: /** Set output stream into which the output of the
160: * Ant script execution will be sent. If not set
161: * the standard NetBeans output window will be used.
162: * @param outputStream a stream to send output to, or <code>null</code> to reset
163: * @see org.apache.tools.ant.module.spi.AntOutputStream
164: * @deprecated Usage of a custom output stream is not recommended, and prevents some
165: * Ant module features from working correctly.
166: */
167: @Deprecated
168: public void setLogger(OutputStream outputStream) {
169: this .outputStream = outputStream;
170: }
171:
172: /** Get output stream. If no output stream was
173: * set then null will be returned what means that standard
174: * NetBeans output window will be used.
175: * @return the output stream to which Ant output will be sent, or <code>null</code>
176: */
177: public OutputStream getLogger() {
178: return outputStream;
179: }
180:
181: }
182:
183: }
|