Package hudson.remoting

Class Pipe

  • All Implemented Interfaces:
    ErrorPropagatingOutputStream, Serializable, SerializableOnlyOverRemoting
    public final class Pipe
extends Object
implements SerializableOnlyOverRemoting, ErrorPropagatingOutputStream
    Pipe for the remote Callable and the local program to talk to each other.

    There are two kinds of pipes. One is for having a local system write to a remote system, and the other is for having a remote system write to a local system. Use the different versions of the create method to create the appropriate kind of pipes.

    Once created, Pipe can be sent to the remote system as a part of a serialization of Callable between Channels. Once re-instantiated on the remote Channel, pipe automatically connects back to the local instance and perform necessary set up.

    The local and remote system can then call getIn() and getOut() to read/write bytes.

    Pipe can be only written by one system and read by the other system. It is an error to send one Pipe to two remote Channels, or send one Pipe to the same Channel twice.

    Usage

     final Pipe p = Pipe.createLocalToRemote();

 channel.callAsync(new Callable() {
   public Object call() {
     InputStream in = p.getIn();
     ... read from in ...
   }
 });

 OutputStream out = p.getOut();
 ... write to out ...
    Similarly, for remote to local pipe, 
     final Pipe p = Pipe.createRemoteToLocal();

 channel.callAsync(new Callable() {
   public Object call() {
     OutputStream out = p.getOut();
     ... write to out ...
   }
 });

 InputStream in = p.getIn();
 ... read from in ...

    Implementation Note

    For better performance, Pipe uses lower-level Command abstraction to send data, instead of typed proxy object. This allows the writer to send data without blocking until the arrival of the data is confirmed.

    Author:
    Kohsuke Kawaguchi
    See Also:
    Serialized Form