Package org.apache.commons.launcher

Class LaunchTask

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class LaunchTask
extends org.apache.tools.ant.Task
    A class that eliminates the need for a batch or shell script to launch a Java class. Some situations where elimination of a batch or shell script may be desirable are:
    • You want to avoid having to determining where certain application paths are e.g. your application's home directory, etc. Determining this dynamically in a Windows batch scripts is very tricky on some versions of Windows or when softlinks are used on Unix platforms.
    • You want to avoid having to handle native file and path separators or native path quoting issues.
    • You need to enforce certain system properties e.g. java.endorsed.dirs when running with JDK 1.4.
    • You want to allow users to pass in custom JVM arguments or system properties without having to parse and reorder arguments in your script. This can be tricky and/or messy in batch and shell scripts.
    • You want to bootstrap system properties from a configuration file instead hard-coding them in your batch and shell scripts.
    • You want to provide localized error messages which is very tricky to do in batch and shell scripts.
    Author:
    Patrick Luby

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ARG_PROP_NAME
      The argument property name.
      static java.lang.String TASK_NAME
      The name of this task.

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

        target, taskName, taskType, wrapper

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

        description, location, project

    • Constructor Summary

      Constructors 
      Constructor Description
      LaunchTask()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addArg​(ConditionalArgument arg)
      Add a nested arg element.
      void addArgset​(ArgumentSet set)
      Add a nested argset element.
      void addJvmarg​(ConditionalArgument jvmArg)
      Add a nested jvmarg element.
      void addJvmargset​(JVMArgumentSet set)
      Add a nested jvmargset element.
      void addSysproperty​(ConditionalVariable var)
      Add a nested sysproperty element.
      void addSyspropertyset​(SysPropertySet set)
      Add a nested syspropertyset element.
      org.apache.tools.ant.types.Path createClasspath()
      Create a nested classpath element.
      org.apache.tools.ant.types.Path createFilterclasspath()
      Create a nested filter classpath element.
      void execute()
      Construct a Java command and execute it using the settings that Ant parsed from the Launcher's XML file.
      static java.lang.Process[] getChildProcesses()
      Get the synchronous child processes for all instances of this class.
      void setAppendoutput​(boolean appendOutput)
      Set the appendOutput flag.
      void setClassname​(java.lang.String mainClassName)
      Set the class name.
      void setClasspath​(org.apache.tools.ant.types.Path classpath)
      Set the classpath.
      void setClasspathref​(org.apache.tools.ant.types.Reference ref)
      Adds a reference to a classpath defined elsewhere.
      void setDebug​(boolean debug)
      Set the debug flag.
      void setDisplayminimizedwindow​(boolean displayMinimizedWindow)
      Set the displayMinimizedWindow flag.
      void setDisposeminimizedwindow​(boolean disposeMinimizedWindow)
      Set the disposeMinimizedWindow flag.
      void setFailonerror​(boolean failOnError)
      Set the failOnError flag.
      void setFilterclassname​(java.lang.String filterClassName)
      Set the filter class name.
      void setFilterclasspath​(org.apache.tools.ant.types.Path filterClasspath)
      Set the filter class' classpath.
      void setMinimizedwindowicon​(java.io.File minimizedWindowIcon)
      Set the icon file for the minimized window that will be displayed in the Windows taskbar.
      void setMinimizedwindowtitle​(java.lang.String minimizedWindowTitle)
      Set the title for the minimized window that will be displayed in the Windows taskbar.
      void setOutput​(java.io.File outputFile)
      Set the file that the child JVM's System.out and System.err will be redirected to.
      void setPrint​(boolean print)
      Set the print flag.
      void setRedirectoutput​(boolean redirect)
      Set the redirect flag.
      void setRequiretools​(boolean requireTools)
      Set the requireTools flag.
      void setUseargs​(boolean useArgs)
      Set the useArgs flag.
      void setUsesystemin​(boolean useSystemIn)
      Set the useSystemIn flag.
      void setWaitforchild​(boolean waitForChild)
      Set the waitForChild flag.

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

        bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

      • Methods inherited from class org.apache.tools.ant.ProjectComponent

        clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • ARG_PROP_NAME

        public static final java.lang.String ARG_PROP_NAME
        The argument property name.
        See Also:
        Constant Field Values

      • TASK_NAME

        public static final java.lang.String TASK_NAME
        The name of this task.
        See Also:
        Constant Field Values

    • Constructor Detail

      • LaunchTask

        public LaunchTask()

    • Method Detail

      • getChildProcesses

        public static java.lang.Process[] getChildProcesses()
        Get the synchronous child processes for all instances of this class.
        Returns:
        the instances of this class.

      • addArg

        public void addArg​(ConditionalArgument arg)
        Add a nested arg element. Note that Ant will not invoke the specified arg object's setter methods until after Ant invokes this method so processing of the specified arg object is handled in the execute() method.
        Parameters:
        arg - the arg element

      • addArgset

        public void addArgset​(ArgumentSet set)
        Add a nested argset element.
        Parameters:
        set - the argset element

      • addJvmarg

        public void addJvmarg​(ConditionalArgument jvmArg)
        Add a nested jvmarg element. Note that Ant will not invoke the specified jvmarg object's setter methods until after Ant invokes this method so processing of the specified jvmarg object is handled in the execute() method.
        Parameters:
        jvmArg - the jvmarg element

      • addJvmargset

        public void addJvmargset​(JVMArgumentSet set)
        Add a nested jvmargset element.
        Parameters:
        set - the jvmargset element

      • addSysproperty

        public void addSysproperty​(ConditionalVariable var)
        Add a nested sysproperty element. Note that Ant will not invoke the specified sysproperty object's setter methods until after Ant invokes this method so processing of the specified sysproperty object is handled in the execute() method.
        Parameters:
        var - the sysproperty element

      • addSyspropertyset

        public void addSyspropertyset​(SysPropertySet set)
        Add a nested syspropertyset element.
        Parameters:
        set - the syspropertyset element

      • createClasspath

        public org.apache.tools.ant.types.Path createClasspath()
        Create a nested classpath element.
        Returns:
        the Path object that contains all nested classpath elements

      • createFilterclasspath

        public org.apache.tools.ant.types.Path createFilterclasspath()
        Create a nested filter classpath element.
        Returns:
        the Path object that contains all nested filter classpath elements

      • execute

        public void execute()
             throws org.apache.tools.ant.BuildException
        Construct a Java command and execute it using the settings that Ant parsed from the Launcher's XML file. This method is called by the Ant classes.
        Overrides:
        execute in class org.apache.tools.ant.Task
        Throws:
        org.apache.tools.ant.BuildException - if there is a configuration or other error

      • setUseargs

        public void setUseargs​(boolean useArgs)
        Set the useArgs flag. Setting this flag to true will cause this task to append all of the command line arguments used to start the Launcher.start(String[]) method to the arguments passed to the child JVM.
        Parameters:
        useArgs - the useArgs flag

      • setUsesystemin

        public void setUsesystemin​(boolean useSystemIn)
        Set the useSystemIn flag. Setting this flag to false will cause this task to not read System.in. This will cause the child JVM to never receive any bytes when it reads System.in. Setting this flag to false is useful in some Unix environments where processes cannot be put in the background when they read System.in.
        Parameters:
        useSystemIn - the useSystemIn flag

      • setWaitforchild

        public void setWaitforchild​(boolean waitForChild)
        Set the waitForChild flag. Setting this flag to true will cause this task to wait for the child JVM to finish executing before the task completes. Setting this flag to false will cause this task to complete immediately after it starts the execution of the child JVM. Setting it false emulates the "&" background operator in most Unix shells and is most of set to false when launching server or GUI applications.
        Parameters:
        waitForChild - the waitForChild flag

      • setClassname

        public void setClassname​(java.lang.String mainClassName)
        Set the class name.
        Parameters:
        mainClassName - the class to execute main(String[])

      • setClasspath

        public void setClasspath​(org.apache.tools.ant.types.Path classpath)
        Set the classpath.
        Parameters:
        classpath - the classpath

      • setClasspathref

        public void setClasspathref​(org.apache.tools.ant.types.Reference ref)
        Adds a reference to a classpath defined elsewhere.
        Parameters:
        ref - reference to the classpath

      • setDebug

        public void setDebug​(boolean debug)
        Set the debug flag. Setting this flag to true will cause this task to run the child JVM using the JDB debugger.
        Parameters:
        debug - the debug flag

      • setDisplayminimizedwindow

        public void setDisplayminimizedwindow​(boolean displayMinimizedWindow)
        Set the displayMinimizedWindow flag. Note that this flag has no effect on non-Windows platforms. On Windows platform, setting this flag to true will cause a minimized window to be displayed in the Windows task bar while the child process is executing. This flag is usually set to true for server applications that also have their "waitForChild" attribute set to false via the setWaitforchild(boolean) method.
        Parameters:
        displayMinimizedWindow - true if a minimized window should be displayed in the Windows task bar while the child process is executing

      • setDisposeminimizedwindow

        public void setDisposeminimizedwindow​(boolean disposeMinimizedWindow)
        Set the disposeMinimizedWindow flag. Note that this flag has no effect on non-Windows platforms. On Windows platform, setting this flag to true will cause any minimized window that is display by setting the "displayMinimizedWindow" attribute to true via the setDisplayminimizedwindow(boolean) to be automatically disposed of when the child JVM's main(String[]) returns. This flag is normally used for applications that don't explicitly call System.exit(int). If an application does not explicitly call System.exit(int), an minimized windows need to be disposed of for the child JVM to exit.
        Parameters:
        disposeMinimizedWindow - true if a minimized window in the Windows taskbar should be automatically disposed of after the child JVM's main(String[]) returns

      • setFailonerror

        public void setFailonerror​(boolean failOnError)
        Set the failOnError flag.
        Parameters:
        failOnError - true if the launch process should stop if the child JVM returns an exit value other than 0

      • setFilterclassname

        public void setFilterclassname​(java.lang.String filterClassName)
        Set the filter class name.
        Parameters:
        filterClassName - the class that implements the LaunchFilter interface

      • setFilterclasspath

        public void setFilterclasspath​(org.apache.tools.ant.types.Path filterClasspath)
        Set the filter class' classpath.
        Parameters:
        classpath - the classpath for the filter class

      • setMinimizedwindowtitle

        public void setMinimizedwindowtitle​(java.lang.String minimizedWindowTitle)
        Set the title for the minimized window that will be displayed in the Windows taskbar. Note that this property has no effect on non-Windows platforms.
        Parameters:
        minimizedWindowTitle - the title to set for any minimized window that is displayed in the Windows taskbar

      • setMinimizedwindowicon

        public void setMinimizedwindowicon​(java.io.File minimizedWindowIcon)
        Set the icon file for the minimized window that will be displayed in the Windows taskbar. Note that this property has no effect on non-Windows platforms.
        Parameters:
        minimizedWindowIcon - the icon file to use for any minimized window that is displayed in the Windows taskbar

      • setOutput

        public void setOutput​(java.io.File outputFile)
        Set the file that the child JVM's System.out and System.err will be redirected to. Output will only be redirected if the redirect flag is set to true via the setRedirectoutput(boolean) method.
        Parameters:
        outputFile - a File to redirect System.out and System.err to

      • setPrint

        public void setPrint​(boolean print)
        Set the print flag. Setting this flag to true will cause the full child JVM command to be printed to System.out.
        Parameters:
        print - the print flag

      • setAppendoutput

        public void setAppendoutput​(boolean appendOutput)
        Set the appendOutput flag. Setting this flag to true will cause the child JVM to append System.out and System.err to the file specified by the setOutput(File) method. Setting this flag to false will cause the child to overwrite the file.
        Parameters:
        appendOutput - true if output should be appended to the output file

      • setRedirectoutput

        public void setRedirectoutput​(boolean redirect)
        Set the redirect flag. Setting this flag to true will cause the child JVM's System.out and System.err to be redirected to file set using the setOutput(File) method. Setting this flag to false will cause no redirection.
        Parameters:
        redirect - true if System.out and System.err should be redirected

      • setRequiretools

        public void setRequiretools​(boolean requireTools)
        Set the requireTools flag. Setting this flag to true will cause the JVM's tools.jar to be added to the child JVM's classpath. This sets an explicit requirement that the user use a JDK instead of a JRE. Setting this flag to false explicitly allows the user to use a JRE.
        Parameters:
        redirect - true if a JDK is required and false if only a JRE is required