java.lang.isolate
Class IsolateStreamBindings

java.lang.Object
  |
  +--java.lang.isolate.IsolateStreamBindings

public final class IsolateStreamBindings

extends Object

This class specifies the binding of a set of streams to a child isolate's standard streams.

Instances of this class are supplied as arguments to the constructor of a new isolate, specifying the bindings for System.in, System.out and System.err in the child. It allows input and output redirection analogous to that which would be available from the command-line had the child isolate been executed as a standalone computation within a traditional JVM.

If a closed stream is provided to any of the methods on this class or if a valid stream is provided, then closed, the error will be detected when passed to the Isolate constructor.

The following examples illustrate some of the scenarios supported. Parameters "a" and "t" in the Isolate constructor calls are simply placeholders for the String[] "mainArgs" and TransientPreferences "context" parameters respectively.

• Inheritance of streams from the creating isolate.

     java Foo
   

     Isolate foo = new Isolate("Foo", a, t, new IsolateStreamBindings());
     foo.start();
   

• Redirection of input from a file.

     java Foo < infile
   

     FileInputStream in = new FileInputStream("infile");
     Isolate foo = new Isolate("Foo", a, t, 
                    (new IsolateStreamBindings()).bindIn(in));
     foo.start();
   

• Redirection of output to a file.

     java Foo > outfile
   

     FileOutputStream out = new FileOutputStream("outfile");
     Isolate foo = new Isolate("Foo", a, t, 
                   (new IsolateStreamBindings()).bindOut(out));
     foo.start();
   

• Redirection of output to a file with append.

     java Foo >> outfile
   

     FileOutputStream out = new FileOutputStream("outfile", true);
     Isolate foo = new Isolate("Foo", a, t, 
                    (new IsolateStreamBindings()).bindOut(out));
     foo.start();
   

• Redirection of normal and error output to the same file.

     java Foo > outfile 2>&1
   

     FileOutputStream out = new FileOutputStream("outfile");
     Isolate foo = new Isolate("Foo", a, t, 
                    (new IsolateStreamBindings()).bindOut(out).bindErr(out));
     foo.start();
   

• Discarding output.

     java Foo > /dev/null
   

     Isolate foo = new Isolate("Foo", a, t, 
                    (new IsolateStreamBindings()).bindOutNull());
     foo.start();
   

• Piping between sibling isolates.

     java Foo | java Bar
   

     Pipe pipe = Pipe.open();
     Isolate foo = new Isolate("Foo", a, t, 
                    (new IsolateStreamBindings()).bindOut(pipe.sinkChannel()));
     Isolate bar = new Isolate("Bar", a, t, 
                    (new IsolateStreamBindings()).bindIn(pipe.sourceChannel()));
     foo.start();
     bar.start();
   

Since:

1.5

See Also:

Isolate.Isolate(java.lang.String, java.lang.String[], java.util.prefs.TransientPreferences, java.lang.isolate.IsolateStreamBindings)

Constructor Summary

IsolateStreamBindings()
Constructs an IsolateStreamBindings object specifying that a child isolate's initial standard streams are bound to the initial standard streams of the current isolate.

Method Summary

java.lang.isolate.IsolateStreamBindings	bindErr(FileOutputStream fileStream) Specifies that a child isolate's initial standard error stream is bound to a file.
java.lang.isolate.IsolateStreamBindings	bindErr(Pipe.SinkChannel pipeChannel) Specifies that a child isolate's initial standard error stream is bound to a pipe.
java.lang.isolate.IsolateStreamBindings	bindErr(Socket socket) Specifies that a child isolate's initial standard error stream is bound to a socket.
java.lang.isolate.IsolateStreamBindings	bindErrDefault() Specifies that a child isolate's initial standard error stream is bound to the initial standard error stream of the current isolate.
java.lang.isolate.IsolateStreamBindings	bindErrNull() Specifies that a child isolate's initial standard error stream is bound to a null output device.
java.lang.isolate.IsolateStreamBindings	bindIn(FileInputStream fileStream) Specifies that a child isolate's initial standard input stream is bound to a file stream.
java.lang.isolate.IsolateStreamBindings	bindIn(Pipe.SourceChannel pipeChannel) Specifies that a child isolate's initial standard input stream is bound to a pipe.
java.lang.isolate.IsolateStreamBindings	bindIn(Socket socket) Specifies that a child isolate's initial standard input stream is bound to a socket.
java.lang.isolate.IsolateStreamBindings	bindInDefault() Specifies that a child isolate's initial standard input stream is bound to the initial standard input stream of the current isolate.
java.lang.isolate.IsolateStreamBindings	bindInNull() Specifies that a child isolate's initial standard input stream is bound to a null input device.
java.lang.isolate.IsolateStreamBindings	bindOut(FileOutputStream fileStream) Specifies that a child isolate's initial standard output stream is bound to a file.
java.lang.isolate.IsolateStreamBindings	bindOut(Pipe.SinkChannel pipeChannel) Specifies that a child isolate's initial standard output stream is bound to a pipe.
java.lang.isolate.IsolateStreamBindings	bindOut(Socket socket) Specifies that a child isolate's initial standard output stream is bound to a socket.
java.lang.isolate.IsolateStreamBindings	bindOutDefault() Specifies that a child isolate's initial standard output stream is bound to the initial standard output stream of the current isolate.
java.lang.isolate.IsolateStreamBindings	bindOutNull() Specifies that a child isolate's initial standard output stream is bound to a null output device.

Methods inherited from class java.lang.Object

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

Constructor Detail

IsolateStreamBindings

public IsolateStreamBindings()

Constructs an IsolateStreamBindings object specifying that a child isolate's initial standard streams are bound to the initial standard streams of the current isolate.

Note that the binding is to the streams that were established when the current isolate was started. Consequently, invocations of System.setIn(), setOut(), and setErr() subsequent to the starting of the current isolate will have no effect on the stream binding for a child isolate.

Method Detail

bindInDefault

public java.lang.isolate.IsolateStreamBindings bindInDefault()

Specifies that a child isolate's initial standard input stream is bound to the initial standard input stream of the current isolate.

Note that the binding is to the stream that was established when the current isolate was started. Consequently, invocations of System.setIn() subsequent to the starting of the current isolate will have no effect on the stream binding for a child isolate.

Returns:

This IsolateStreamBindings (for method chaining)

bindInNull

public java.lang.isolate.IsolateStreamBindings bindInNull()

Specifies that a child isolate's initial standard input stream is bound to a null input device.

Reads from System.in in a child isolate will return end of file.

Returns:

This IsolateStreamBindings (for method chaining)

bindIn

public java.lang.isolate.IsolateStreamBindings bindIn(FileInputStream fileStream)

Specifies that a child isolate's initial standard input stream is bound to a file stream.

Note that because the file stream is not opened in the child isolate the child isolate's security context is not relevant. Consequently a creating isolate may treat the file stream as a capability which is handed to the child independently of the childs ability to access the associated file directly.

Apart from the difference in security context, this binding has the same effect as if the child isolate had executed. System.setIn(fileStream) prior to its first use of System.in.

Parameters:

fileStream - The file stream to bind to a child isolate's standard input stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if fileStream is null

bindIn

public java.lang.isolate.IsolateStreamBindings bindIn(Socket socket)

Specifies that a child isolate's initial standard input stream is bound to a socket.

Note that because the socket is not opened in the child isolate the child isolate's security context is not relevant. Consequently a creating isolate may treat the socket as a capability which is handed to the child independently of the childs ability to establish network connections.

Apart from the fact that the socket is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setIn(socket.getInputStream()) prior to its first use of System.in.

Parameters:

socket - The socket to bind to a child isolate's standard input stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if socket is null

bindIn

public java.lang.isolate.IsolateStreamBindings bindIn(Pipe.SourceChannel pipeChannel)

Specifies that a child isolate's initial standard input stream is bound to a pipe.

Apart from the fact that the pipe is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setIn(channels.newInputStream(pipeChannel)) prior to its first use of System.in.

Parameters:

pipeChannel - The pipe to bind to a child isolate's standard input stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if pipeChannel is null

bindOutDefault

public java.lang.isolate.IsolateStreamBindings bindOutDefault()

Specifies that a child isolate's initial standard output stream is bound to the initial standard output stream of the current isolate.

Note that the binding is to the stream that was established when the current isolate was started. Consequently, invocations of System.setOut() subsequent to the starting of the current isolate will have no effect on the stream binding for a child isolate.

Returns:

This IsolateStreamBindings (for method chaining)

bindOutNull

public java.lang.isolate.IsolateStreamBindings bindOutNull()

Specifies that a child isolate's initial standard output stream is bound to a null output device.

Writes to System.out in a child isolate will be silently discarded.

Returns:

This IsolateStreamBindings (for method chaining)

bindOut

public java.lang.isolate.IsolateStreamBindings bindOut(FileOutputStream fileStream)

Specifies that a child isolate's initial standard output stream is bound to a file.

Note that because the file stream is not opened in the child isolate, the child isolate's security context is not relevant. Consequently, a creating isolate may treat the file stream as a capability which is handed to the child independently of the child's ability to access the associated file directly.

Apart from the difference in security context, this binding has the same effect as if the child isolate had executed System.setOut(fileStream) prior to its first use of System.out.

Parameters:

fileStream - The file stream to bind to a child isolate's standard output stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if fileStream is null

bindOut

public java.lang.isolate.IsolateStreamBindings bindOut(Socket socket)

Specifies that a child isolate's initial standard output stream is bound to a socket.

Note that because the socket is not opened in the child isolate, the child isolate's security context is not relevant. Consequently, a creating isolate may treat the socket as a capability which is handed to the child independently of the child's ability to establish network connections.

Apart from the fact that the socket is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setOut(new PrintStream(socket.getOutputStream())) prior to its first use of System.out.

Parameters:

socket - The socket to bind to a child isolate's standard output stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if socket is null

bindOut

public java.lang.isolate.IsolateStreamBindings bindOut(Pipe.SinkChannel pipeChannel)

Specifies that a child isolate's initial standard output stream is bound to a pipe.

Apart from the fact that the pipe is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setOut(new PrintStream(channels.newInputStream(pipeChannel))) prior to its first use of System.out.

Parameters:

pipeChannel - The pipe to bind to a child isolate's standard output stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if pipeChannel is null

bindErrDefault

public java.lang.isolate.IsolateStreamBindings bindErrDefault()

Specifies that a child isolate's initial standard error stream is bound to the initial standard error stream of the current isolate.

Note that the binding is to the stream that was established when the current isolate was started. Consequently, invocations of System.setErr() subsequent to the starting of the current isolate will have no effect on the stream binding for a child isolate.

Returns:

This IsolateStreamBindings (for method chaining)

bindErrNull

public java.lang.isolate.IsolateStreamBindings bindErrNull()

Specifies that a child isolate's initial standard error stream is bound to a null output device.

Writes to System.err in a child isolate will be silently discarded.

Returns:

This IsolateStreamBindings (for method chaining)

bindErr

public java.lang.isolate.IsolateStreamBindings bindErr(FileOutputStream fileStream)

Specifies that a child isolate's initial standard error stream is bound to a file.

Note that because the file stream is not opened in the child isolate, the child isolate's security context is not relevant. Consequently, a creating isolate may treat the file stream as a capability which is handed to the child independently of the child's ability to access the associated file directly.

Apart from the difference in security context, this binding has the same effect as if the child isolate had executed System.setErr(fileStream) prior to its first use of System.err.

Parameters:

fileStream - The file stream to bind to a child isolate's standard error stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if fileStream is null

bindErr

public java.lang.isolate.IsolateStreamBindings bindErr(Socket socket)

Specifies that a child isolate's initial standard error stream is bound to a socket.

Note that because the socket is not opened in the child isolate, the child isolate's security context is not relevant. Consequently, a creating isolate may treat the socket as a capability which is handed to the child independently of the child's ability to establish network connections.

Apart from the fact that the socket is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setErr(new PrintStream(socket.getOutputStream())) prior to its first use of System.err.

Parameters:

socket - The socket to bind to a child isolate's standard error stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if socket is null

bindErr

public java.lang.isolate.IsolateStreamBindings bindErr(Pipe.SinkChannel pipeChannel)

Specifies that a child isolate's initial standard error stream is bound to a pipe.

Apart from the fact that the pipe is opened in the creating isolate, this binding has the same effect as if the child isolate had executed System.setErr(new PrintStream(channels.newInputStream(pipeChannel))) prior to its first use of System.err.

Parameters:

pipeChannel - The pipe to bind to a child isolate's standard error stream.

Returns:

This IsolateStreamBindings (for method chaining)

Throws:

NullPointerException - if pipeChannel is null