Class MathematicaTask

  • All Implemented Interfaces:
    PacketListener, java.util.EventListener

    public class MathematicaTask
    extends org.apache.tools.ant.Task
    implements PacketListener
    MathematicaTask is an Ant task that allows you to call Mathematica from Ant build files. Ant (http://ant.apache.org) is a popular Java-based build tool.

    You can run Mathematica as a processing step in your build, call Mathematica testing functions, or any other operations you desire. Because MathematicaTask lets you call back into Ant from Mathematica (e.g., to execute other tasks, set/read properties, or log messages), you can use Mathematica as a scripting language for Ant.

    To use the <mathematica> task, you must include a taskdef line in your build.xml file like the following examples:

     <!-- If JLink.jar is on your system CLASSPATH: -->
     <taskdef name="mathematica" classname="com.wolfram.jlink.util.MathematicaTask"/>
    
     <!-- If JLink.jar is NOT on your system CLASSPATH: -->
     <taskdef name="mathematica" classname="com.wolfram.jlink.util.MathematicaTask"
               classpath="/full/path/to/JLink.jar"/> 

    Attributes

    Attribute Description Required
    exe The path to the Wolfram kernel to launch Either exe or cmdline must be specified
    args Non-MathLink command-line arguments to pass to the Wolfram kernel. Used only with the exe attribute. No
    cmdline The full set of MathLink command-line args to use to connect to the kernel Either exe or cmdline must be specified
    runfile The path to a .m file to be run when the kernel is launched. This is convenient when you want to specify some or all of the code in a file instead of directly in the task. No
    fresh Whether to start a fresh kernel for this task (if a previously-used kernel is running, it will be quit first) No, defaults to false
    quit Whether to force the kernel to quit immediately after this task finishes No, defaults to false
    timeout The maximum number of seconds to allow for the computation. If not finished, the kernel will be killed. No, defaults to Integer.MAX_VALUE
    timeoutproperty The name of a property to set if the timeout expires. The named property will be set to true. No
    failonerror Whether a MathLink error (unlikely) or a timeout should cause the build to fail. No, defaults to true

    You have two ways of specifying how to launch or connect to the Mathematica kernel. Most users will use the exe parameter, which specifies the path to the kernel to launch. In rare cases you might need more control over how the kernel is launched, or you might want to connect to an already-running kernel (not launched by Ant). In such cases, you can use the cmdline parameter, which lets you specify a full set of command-line MathLink arguments (e.g., "-linkmode connect -linkname 1234 -linkprotocol tcpip").

    Calling back to Ant

    Your Mathematica code can use the following functions to call back into Ant:
    Function Description
    AntTask["taskname", taskattributes] Execute the given task, with optional attributes set in the form of "attrname"->"value" rules.
    AntProperty["propertyname"] Returns the string value of the specified Ant property.
    AntSetProperty["propertyname", "value"] Sets the value of the specified Ant property.
    AntReference["refId"] Lookup the corresponding object by its id (such as a defined <path> element from its id atribute). Unlike AntProperty, which always returns a string, AntReference returns a JavaObject expression; to use it in your Mathematica code you will have to inspect the Ant API docs for the particular class.
    AntLog["message"] Write the given message to the Ant log.
    AntFail["message"] Abort the Mathematica code and cause the Ant build to fail with the given message.
    Ant["objectName"] General-purpose function for obtaining a reference to a specified Ant object. The allowed object names are "Project", "Target", "Task", and "Location". Use this function when you want to make direct calls into the Ant API. The other Mathematica functions listed above are convenience functions that are implemented using the Ant[] function.

    Examples

    The examples below assume that you have a mathExe property defined that gives the path to the kernel to launch. Here are typical definitions of that property for various operating systems:
     <!-- Windows -->
     <property name="mathExe", value="c:/program files/wolfram research/mathematica/12.2/mathkernel"/>
    
     <!-- Linux, Unix ('math' is typically on PATH) -->
     <property name="mathExe", value="math"/>
    
     <!-- Mac OS/X -->
     <property name="mathExe", value="/Applications/Mathematica.app/Contents/MacOS/MathKernel"/>
    This simple example loads a package and calls a function. It uses AntFail to make the Ant build fail if a testing function does not succeed.
        <target name="runMathTests">
          <mathematica exe="${mathExe}">
            <![CDATA[
               Get["MyTestPackage`"];
               result = CallTestFunction[];
               If[!TrueQ[result],
                  AntFail["Mathematica test function failed"]
               ]
            ]]>
          </mathematica>
        </target> 
    This example demonstrates the use of AntProperty to obtain the value of an Ant property as a string in your Mathematica code.
        <property name="codeDir" value="${basedir}/MyCodeDir">
    
        <target name="propertyExample">
          <mathematica exe="${mathExe}">
            <![CDATA[
               Get[ToFileName[AntProperty["codeDir"], "SuperPackage.m"]];
               ...
            ]]>
          </mathematica>
        </target> 
    This example demonstrates the use of AntReference to bring a list of directories defined in a <path> element into your Mathematica code. In this case, AntReference returns an Ant Path object, the methods for which are described in the Ant API docs:
        <path id="mathPath">
           ... dirsets, pathelements, etc.
        </path>
    
        <target name="refExample">
          <mathematica exe="${mathExe}">
            <![CDATA[
               mathPathDirs = AntReference["mathPath"]@list[];
               $Path = Join[mathPathDirs, $Path];
               ...
            ]]>
          </mathematica>
        </target> 
    This example shows how to call the Ant <echo> task from Mathematica code (this is just a simple task example--there are easier ways to have Mathematica output appear in the console, including simply calling Print[]):
        <target name="scriptingExample">
          <mathematica exe="${mathExe}">
            <![CDATA[
               For[i = 0, i < 10, i++,
                  AntTask["echo", "message"->ToString[i^2]]
               ]
            ]]>
          </mathematica>
        </target> 
    Since:
    3.1
    • Field Summary

      • Fields inherited from class org.apache.tools.ant.Task

        description, location, target, taskName, taskType, wrapper
      • Fields inherited from class org.apache.tools.ant.ProjectComponent

        project
    • Constructor Summary

      Constructors 
      Constructor Description
      MathematicaTask()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addText​(java.lang.String code)  
      protected void closeKernel()  
      void execute()
      Execute
      protected KernelLink initKernel()  
      protected void killTimeoutThread​(com.wolfram.jlink.util.MathematicaTask.TimeoutThread timeoutThread)  
      boolean packetArrived​(PacketArrivedEvent evt)
       
      void setArgs​(java.lang.String args)  
      void setCmdline​(java.lang.String cmdLine)  
      void setExe​(java.lang.String exe)
      Attribute Setters
      void setFail​(java.lang.String msg)  
      void setFailonerror​(boolean failOnError)  
      void setFresh​(boolean fresh)  
      void setQuit​(boolean quit)  
      void setRunfile​(java.lang.String runFile)  
      void setTimeout​(int seconds)  
      void setTimeoutproperty​(java.lang.String timeoutProperty)  
      protected com.wolfram.jlink.util.MathematicaTask.TimeoutThread startTimeoutThread()  
      • Methods inherited from class org.apache.tools.ant.Task

        getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
      • Methods inherited from class org.apache.tools.ant.ProjectComponent

        getProject, setProject
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • MathematicaTask

        public MathematicaTask()
    • Method Detail

      • setExe

        public void setExe​(java.lang.String exe)
        Attribute Setters
      • setArgs

        public void setArgs​(java.lang.String args)
      • setCmdline

        public void setCmdline​(java.lang.String cmdLine)
      • setFresh

        public void setFresh​(boolean fresh)
      • setQuit

        public void setQuit​(boolean quit)
      • setRunfile

        public void setRunfile​(java.lang.String runFile)
      • setTimeout

        public void setTimeout​(int seconds)
      • setTimeoutproperty

        public void setTimeoutproperty​(java.lang.String timeoutProperty)
      • setFailonerror

        public void setFailonerror​(boolean failOnError)
      • addText

        public void addText​(java.lang.String code)
      • setFail

        public void setFail​(java.lang.String msg)
      • execute

        public void execute()
                     throws org.apache.tools.ant.BuildException
        Execute
        Overrides:
        execute in class org.apache.tools.ant.Task
        Throws:
        org.apache.tools.ant.BuildException
      • closeKernel

        protected void closeKernel()
      • startTimeoutThread

        protected com.wolfram.jlink.util.MathematicaTask.TimeoutThread startTimeoutThread()
      • killTimeoutThread

        protected void killTimeoutThread​(com.wolfram.jlink.util.MathematicaTask.TimeoutThread timeoutThread)