org.codehaus.groovy.runtime

Class ProcessGroovyMethods

java.lang.Object

org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport

org.codehaus.groovy.runtime.ProcessGroovyMethods

public class ProcessGroovyMethods
extends DefaultGroovyMethodsSupport

This class defines new groovy methods which appear on normal JDK classes related to process management.

Static methods are used with the first parameter being the destination class, i.e. public static String reverse(String self) provides a reverse() method for String.

NOTE: While this class contains many 'public' static methods, it is primarily regarded as an internal class (its internal package name suggests this also). We value backwards compatibility of these methods when used within Groovy but value less backwards compatibility at the Java method call level. I.e. future versions of Groovy may remove or move a method call in this file but would normally aim to keep the method available from within Groovy.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ProcessGroovyMethods.ProcessRunner A Runnable which waits for a process to complete together with a notification scheme allowing another thread to wait a maximum number of seconds for the process to complete before killing it.

Nested classes/interfaces inherited from class org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport

DefaultGroovyMethodsSupport.RangeInfo

Constructor Summary

Constructors

Constructor and Description
ProcessGroovyMethods()

Method Summary

Methods

Modifier and Type	Method and Description
static void	closeStreams(java.lang.Process self) Closes all the streams associated with the process (ignoring any IOExceptions).
static java.lang.Thread	consumeProcessErrorStream(java.lang.Process self, java.lang.Appendable error) Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer.
static java.lang.Thread	consumeProcessErrorStream(java.lang.Process self, java.io.OutputStream err) Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer.
static void	consumeProcessOutput(java.lang.Process self) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static void	consumeProcessOutput(java.lang.Process self, java.lang.Appendable output, java.lang.Appendable error) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static void	consumeProcessOutput(java.lang.Process self, java.io.OutputStream output, java.io.OutputStream error) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static java.lang.Thread	consumeProcessOutputStream(java.lang.Process self, java.lang.Appendable output) Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer.
static java.lang.Thread	consumeProcessOutputStream(java.lang.Process self, java.io.OutputStream output) Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer.
static java.lang.Process	execute(java.util.List commands) Executes the command specified by the given list.
static java.lang.Process	execute(java.util.List commands, java.util.List envp, java.io.File dir) Executes the command specified by the given list, with the environment defined by envp and under the working directory dir.
static java.lang.Process	execute(java.util.List commands, java.lang.String[] envp, java.io.File dir) Executes the command specified by the given list, with the environment defined by envp and under the working directory dir.
static java.lang.Process	execute(java.lang.String self) Executes the command specified by self as a command-line process.
static java.lang.Process	execute(java.lang.String[] commandArray) Executes the command specified by the given String array.
static java.lang.Process	execute(java.lang.String[] commandArray, java.util.List envp, java.io.File dir) Executes the command specified by the String array given in the first parameter, with the environment defined by envp and under the working directory dir.
static java.lang.Process	execute(java.lang.String[] commandArray, java.lang.String[] envp, java.io.File dir) Executes the command specified by the String array given in the first parameter, with the environment defined by envp and under the working directory dir.
static java.lang.Process	execute(java.lang.String self, java.util.List envp, java.io.File dir) Executes the command specified by self with environment defined by envp and under the working directory dir.
static java.lang.Process	execute(java.lang.String self, java.lang.String[] envp, java.io.File dir) Executes the command specified by self with environment defined by envp and under the working directory dir.
static java.io.InputStream	getErr(java.lang.Process self) An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
static java.io.InputStream	getIn(java.lang.Process self) An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
static java.io.OutputStream	getOut(java.lang.Process self) An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
static java.lang.String	getText(java.lang.Process self) Read the text of the output stream of the Process.
static java.io.OutputStream	leftShift(java.lang.Process self, byte[] value) Overloads the left shift operator to provide an append mechanism to pipe into a Process
static java.io.Writer	leftShift(java.lang.Process self, java.lang.Object value) Overloads the left shift operator (<<) to provide an append mechanism to pipe data to a Process.
static java.lang.Process	or(java.lang.Process left, java.lang.Process right) Overrides the or operator to allow one Process to asynchronously pipe data to another Process.
static java.lang.Process	pipeTo(java.lang.Process left, java.lang.Process right) Allows one Process to asynchronously pipe data to another Process.
static void	waitForOrKill(java.lang.Process self, long numberOfMillis) Wait for the process to finish during a certain amount of time, otherwise stops the process.
static void	waitForProcessOutput(java.lang.Process self) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static void	waitForProcessOutput(java.lang.Process self, java.lang.Appendable output, java.lang.Appendable error) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static void	waitForProcessOutput(java.lang.Process self, java.io.OutputStream output, java.io.OutputStream error) Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
static void	withOutputStream(java.lang.Process self, Closure closure) Creates a new buffered OutputStream as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns.
static void	withWriter(java.lang.Process self, Closure closure) Creates a new BufferedWriter as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns.

Methods inherited from class org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport

cloneSimilarCollection, cloneSimilarMap, closeQuietly, closeWithWarning, createSimilarArray, createSimilarCollection, createSimilarCollection, createSimilarList, createSimilarMap, createSimilarOrDefaultCollection, createSimilarSet, normaliseIndex, sameType, subListBorders, subListBorders

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessGroovyMethods

public ProcessGroovyMethods()

Method Detail

getIn

public static java.io.InputStream getIn(java.lang.Process self)

An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

Parameters:

self - a Process instance

Returns:

the InputStream for the process

Since:

1.0

getText

public static java.lang.String getText(java.lang.Process self)
                                throws java.io.IOException

Read the text of the output stream of the Process. Closes all the streams associated with the process after retrieving the text.

Parameters:

self - a Process instance

Returns:

the text of the output

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

getErr

public static java.io.InputStream getErr(java.lang.Process self)

An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

Parameters:

self - a Process instance

Returns:

the error InputStream for the process

Since:

1.0

getOut

public static java.io.OutputStream getOut(java.lang.Process self)

An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

Parameters:

self - a Process instance

Returns:

the OutputStream for the process

Since:

1.0

leftShift

public static java.io.Writer leftShift(java.lang.Process self,
                       java.lang.Object value)
                                throws java.io.IOException

Overloads the left shift operator (<<) to provide an append mechanism to pipe data to a Process.

Parameters:

self - a Process instance

value - a value to append

Returns:

a Writer

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

leftShift

public static java.io.OutputStream leftShift(java.lang.Process self,
                             byte[] value)
                                      throws java.io.IOException

Overloads the left shift operator to provide an append mechanism to pipe into a Process

Parameters:

self - a Process instance

value - data to append

Returns:

an OutputStream

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

waitForOrKill

public static void waitForOrKill(java.lang.Process self,
                 long numberOfMillis)

Wait for the process to finish during a certain amount of time, otherwise stops the process.

Parameters:

self - a Process

numberOfMillis - the number of milliseconds to wait before stopping the process

Since:

1.0

closeStreams

public static void closeStreams(java.lang.Process self)

Closes all the streams associated with the process (ignoring any IOExceptions).

Parameters:

self - a Process

Since:

2.1

consumeProcessOutput

public static void consumeProcessOutput(java.lang.Process self)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The stream data is thrown away but blocking due to a full output buffer is avoided. Use this method if you don't care about the standard or error output and just want the process to run silently - use carefully however, because since the stream data is thrown away, it might be difficult to track down when something goes wrong. For this, two Threads are started, so this method will return immediately.

Parameters:

self - a Process

Since:

1.0

consumeProcessOutput

public static void consumeProcessOutput(java.lang.Process self,
                        java.lang.Appendable output,
                        java.lang.Appendable error)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. For this, two Threads are started, so this method will return immediately.

Parameters:

self - a Process

output - an Appendable to capture the process stdout

error - an Appendable to capture the process stderr

Since:

1.7.5

consumeProcessOutput

public static void consumeProcessOutput(java.lang.Process self,
                        java.io.OutputStream output,
                        java.io.OutputStream error)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. For this, two Threads are started, so this method will return immediately.

Parameters:

self - a Process

output - an OutputStream to capture the process stdout

error - an OutputStream to capture the process stderr

Since:

1.5.2

waitForProcessOutput

public static void waitForProcessOutput(java.lang.Process self)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The stream data is thrown away but blocking due to a full output buffer is avoided. Use this method if you don't care about the standard or error output and just want the process to run silently - use carefully however, because since the stream data is thrown away, it might be difficult to track down when something goes wrong. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the output and error streams are closed.

Parameters:

self - a Process

Since:

1.6.5

waitForProcessOutput

public static void waitForProcessOutput(java.lang.Process self,
                        java.lang.Appendable output,
                        java.lang.Appendable error)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the input, output and error streams are closed.

Parameters:

self - a Process

output - an Appendable to capture the process stdout

error - an Appendable to capture the process stderr

Since:

1.7.5

waitForProcessOutput

public static void waitForProcessOutput(java.lang.Process self,
                        java.io.OutputStream output,
                        java.io.OutputStream error)

Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the input, output and error streams are closed.

Parameters:

self - a Process

output - an OutputStream to capture the process stdout

error - an OutputStream to capture the process stderr

Since:

1.6.5

consumeProcessErrorStream

public static java.lang.Thread consumeProcessErrorStream(java.lang.Process self,
                                         java.io.OutputStream err)

Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer. The processed stream data is appended to the supplied OutputStream. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

err - an OutputStream to capture the process stderr

Returns:

the Thread

Since:

1.5.2

consumeProcessErrorStream

public static java.lang.Thread consumeProcessErrorStream(java.lang.Process self,
                                         java.lang.Appendable error)

Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer. The processed stream data is appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

error - an Appendable to capture the process stderr

Returns:

the Thread

Since:

1.7.5

consumeProcessOutputStream

public static java.lang.Thread consumeProcessOutputStream(java.lang.Process self,
                                          java.lang.Appendable output)

Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

output - an Appendable to capture the process stdout

Returns:

the Thread

Since:

1.7.5

consumeProcessOutputStream

public static java.lang.Thread consumeProcessOutputStream(java.lang.Process self,
                                          java.io.OutputStream output)

Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

output - an OutputStream to capture the process stdout

Returns:

the Thread

Since:

1.5.2

withWriter

public static void withWriter(java.lang.Process self,
              Closure closure)

Creates a new BufferedWriter as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

closure - a closure

Since:

1.5.2

withOutputStream

public static void withOutputStream(java.lang.Process self,
                    Closure closure)

Creates a new buffered OutputStream as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns. A new Thread is started, so this method will return immediately.

Parameters:

self - a Process

closure - a closure

Since:

1.5.2

pipeTo

public static java.lang.Process pipeTo(java.lang.Process left,
                       java.lang.Process right)
                                throws java.io.IOException

Allows one Process to asynchronously pipe data to another Process.

Parameters:

left - a Process instance

right - a Process to pipe output to

Returns:

the second Process to allow chaining

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.5.2

or

public static java.lang.Process or(java.lang.Process left,
                   java.lang.Process right)
                            throws java.io.IOException

Overrides the or operator to allow one Process to asynchronously pipe data to another Process.

Parameters:

left - a Process instance

right - a Process to pipe output to

Returns:

the second Process to allow chaining

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.5.1

execute

public static java.lang.Process execute(java.lang.String self)
                                 throws java.io.IOException

Executes the command specified by self as a command-line process.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

self - a command line String

Returns:

the Process which has just started for this command line representation

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

execute

public static java.lang.Process execute(java.lang.String self,
                        java.lang.String[] envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by self with environment defined by envp and under the working directory dir.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

self - a command line String to be executed.

envp - an array of Strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

execute

public static java.lang.Process execute(java.lang.String self,
                        java.util.List envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by self with environment defined by envp and under the working directory dir.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

self - a command line String to be executed.

envp - a List of Objects (converted to Strings using toString), each member of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

execute

public static java.lang.Process execute(java.lang.String[] commandArray)
                                 throws java.io.IOException

Executes the command specified by the given String array. The first item in the array is the command; the others are the parameters.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commandArray - an array of String containing the command name and parameters as separate items in the array.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

execute

public static java.lang.Process execute(java.lang.String[] commandArray,
                        java.lang.String[] envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by the String array given in the first parameter, with the environment defined by envp and under the working directory dir. The first item in the array is the command; the others are the parameters.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commandArray - an array of String containing the command name and parameters as separate items in the array.

envp - an array of Strings, each member of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.7.1

execute

public static java.lang.Process execute(java.lang.String[] commandArray,
                        java.util.List envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by the String array given in the first parameter, with the environment defined by envp and under the working directory dir. The first item in the array is the command; the others are the parameters.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commandArray - an array of String containing the command name and parameters as separate items in the array.

envp - a List of Objects (converted to Strings using toString), each member of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.7.1

execute

public static java.lang.Process execute(java.util.List commands)
                                 throws java.io.IOException

Executes the command specified by the given list. The toString() method is called for each item in the list to convert into a resulting String. The first item in the list is the command the others are the parameters.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commands - a list containing the command name and parameters as separate items in the list.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.0

execute

public static java.lang.Process execute(java.util.List commands,
                        java.lang.String[] envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by the given list, with the environment defined by envp and under the working directory dir. The first item in the list is the command; the others are the parameters. The toString() method is called on items in the list to convert them to Strings.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commands - a List containing the command name and parameters as separate items in the list.

envp - an array of Strings, each member of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.7.1

execute

public static java.lang.Process execute(java.util.List commands,
                        java.util.List envp,
                        java.io.File dir)
                                 throws java.io.IOException

Executes the command specified by the given list, with the environment defined by envp and under the working directory dir. The first item in the list is the command; the others are the parameters. The toString() method is called on items in the list to convert them to Strings.

For more control over Process construction you can use java.lang.ProcessBuilder (JDK 1.5+).

Parameters:

commands - a List containing the command name and parameters as separate items in the list.

envp - a List of Objects (converted to Strings using toString), each member of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Returns:

the Process which has just started for this command line representation.

Throws:

java.io.IOException - if an IOException occurs.

Since:

1.7.1