| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Script Task</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </head> |
| |
| <body> |
| |
| <h2><a name="script">Script</a></h2> |
| <h3>Description</h3> |
| <p>Execute a script in a |
| <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> supported language.</p> |
| <p><b>Note:</b> This task depends on external libraries not included in the Ant distribution. |
| See <a href="../install.html#librarydependencies">Library Dependencies</a> for more information.</p> |
| <p>All items (tasks, targets, etc) of the running project are |
| accessible from the script, using either their <code>name</code> or |
| <code>id</code> attributes (as long as their names are considered |
| valid Java identifiers, that is). |
| The name "project" is a pre-defined reference to the Project, which can be |
| used instead of the project name. The name "self" is a pre-defined reference to the actual |
| <script>-Task instance.<br>From these objects you have access to the Ant Java API, see the |
| <a href="../api/index.html">JavaDoc</a> (especially for |
| <a href="../api/org/apache/tools/ant/Project.html">Project</a> and |
| <a href="../api/org/apache/tools/ant/taskdefs/optional/Script.html">Script</a>) for more information.</p> |
| <p>If you are using JavaScript a good resource is <a target="_blank" href="http://www.mozilla.org/rhino/doc.html"> |
| http://www.mozilla.org/rhino/doc.html</a> as we are using their JavaScript interpreter.</p> |
| <p>Scripts can do almost anything a task written in Java could do.</p> |
| <p>Rhino provides a special construct - the <i>JavaAdapter</i>. Whith that you can |
| create an object which implements several interfaces, extends classes and for which you |
| can overwrite methods. Because this is an undocumented feature (yet), here is the link |
| to an explanation: <a href="http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&newwindow=1&frame=right&th=610d2db45c0756bd&seekm=391EEC3C.5236D929%40yahoo.com#link2"> |
| Groups@Google: "Rhino, enum.js, JavaAdapter?"</a> by Norris Boyd in the newsgroup |
| <i>netscape.public.mozilla.jseng</i>.</p> |
| |
| |
| |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">language</td> |
| <td valign="top">The programming language the script is written in. |
| Must be a supported Apache BSF language</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">src</td> |
| <td valign="top">The location of the script as a file, if not inline</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <project name="squares" default="main" basedir="."> |
| |
| <target name="setup"> |
| |
| <script language="javascript"> <![CDATA[ |
| |
| for (i=1; i<=10; i++) { |
| echo = squares.createTask("echo"); |
| main.addTask(echo); |
| echo.setMessage(i*i); |
| } |
| |
| ]]> </script> |
| |
| </target> |
| |
| <target name="main" depends="setup"/> |
| |
| </project> |
| </pre></blockquote> |
| <p>generates</p> |
| <blockquote><pre> |
| setup: |
| |
| main: |
| 1 |
| 4 |
| 9 |
| 16 |
| 25 |
| 36 |
| 49 |
| 64 |
| 81 |
| 100 |
| |
| BUILD SUCCESSFUL |
| </pre></blockquote> |
| <p>Another example, using <a href="../using.html#references">references by id</a> |
| and two different scripting languages:</p> |
| <blockquote><pre> |
| <project name="testscript" default="main"> |
| <target name="sub"> |
| <echo id="theEcho"/> |
| </target> |
| |
| <target name="sub1"> |
| <script language="netrexx"><![CDATA[ |
| theEcho.setMessage("In sub1") |
| sub.execute |
| ]]></script> |
| </target> |
| |
| <target name="sub2"> |
| <script language="javascript"><![CDATA[ |
| theEcho.setMessage("In sub2"); |
| sub.execute(); |
| ]]></script> |
| </target> |
| |
| <target name="main" depends="sub1,sub2"/> |
| </project> |
| </pre></blockquote> |
| <p>generates</p> |
| <blockquote><pre> |
| sub1: |
| In sub1 |
| |
| sub2: |
| In sub2 |
| |
| main: |
| |
| BUILD SUCCESSFUL |
| </pre></blockquote> |
| |
| <p>Now a more complex example using the Java API and the Ant API. The goal is to list the |
| filesizes of all files a <fileset/> caught.</p> |
| <blockquote><pre> |
| |
| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <project name="<font color=blue>MyProject</font>" basedir="." default="main"> |
| |
| <property name="fs.dir" value="src"/> |
| <property name="fs.includes" value="**/*.txt"/> |
| <property name="fs.excludes" value="**/*.tmp"/> |
| |
| <target name="main"> |
| <script language="javascript"> <![CDATA[ |
| |
| // import statements |
| <font color=blue>// importPackage(java.io)</font>; |
| <font color=blue>importClass(java.io.File)</font>; |
| |
| // Access to Ant-Properties by their names |
| dir = <font color=blue>project</font>.getProperty("fs.dir"); |
| includes = <font color=blue>MyProject</font>.getProperty("fs.includes"); |
| excludes = <font color=blue>self.getProject()</font> .<font color=blue>getProperty("fs.excludes")</font>; |
| |
| // Create a <fileset dir="" includes="" /> |
| fs = project.<font color=blue>createDataType("fileset")</font>; |
| fs.setDir( new File(dir) ); |
| <font color=blue>fs.setIncludes(includes)</font>; |
| fs.setExcludes(excludes); |
| |
| // Get the files (array) of that fileset |
| ds = fs.getDirectoryScanner(project); |
| srcFiles = ds.getIncludedFiles(); |
| |
| // iterate over that array |
| for (i=0; i<srcFiles.length; i++) { |
| |
| // get the values via Java API |
| var basedir = fs.getDir(project); |
| var filename = srcFiles[i]; |
| var file = <font color=blue>new File(basedir, filename)</font>; |
| var size = file.length(); |
| |
| // create and use a Task via Ant API |
| echo = MyProject.<font color=blue>createTask("echo")</font>; |
| echo.setMessage(filename + ": " + size + " byte"); |
| echo.<font color=blue>perform()</font>; |
| } |
| ]]></script> |
| </target> |
| </project> |
| </pre></blockquote> |
| <p>We want to use the Java API. Because we don´t want always typing the package signature |
| we do an import. Rhino knows two different methods for import statements: one for packages |
| and one for a single class. By default only the <i>java</i> packages are available, so |
| <i>java.lang.System</i> can be directly imported with <code>importClass/importPackage</code>. |
| For other packages you have to prefix the full classified name with <i>Package</i>. |
| For example ant´s <i>FileUtil</i> class can be imported with |
| <code>importClass(<b>Package</b>.org.apache.tools.ant.util.FileUtils)</code> |
| <br> |
| The <script> task populates the Project instance under |
| the name <i>project</i>, so we can use that reference. Another way is to use its given name |
| or getting its reference from the task itself.<br> |
| The Project provides methods for accessing and setting properties, creating DataTypes and |
| Tasks and much more.<br> |
| After creating a FileSet object we initialize that by calling its set-methods. Then we can |
| use that object like a normal Ant task (<copy> for example).<br> |
| For getting the size of a file we instantiate a <code>java.io.File</code>. So we are using |
| normal Java API here.<br> |
| Finally we use the <echo> task for producing the output. The task is not executed by |
| its execute() method, because the perform() method (implemented in Task itself) does the |
| apropriate logging before and after invoking execute(). |
| </p> |
| |
| |
| <hr> |
| <p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
