Package hudson.remoting

Class CommandTransport

java.lang.Object

hudson.remoting.CommandTransport

Direct Known Subclasses:

AbstractByteArrayCommandTransport, AbstractByteBufferCommandTransport, SynchronousCommandTransport

public abstract class CommandTransport
extends Object

Lower level abstraction under Channel for sending and receiving commands

Channel is internally implemented on top of a transport that satisfies the following characteristics:

Point-to-point

Like TCP, by the time CommandTransport is used by Channel, it needs to be connected to "the other side". The write operation doesn't take the receiver address, and the read operation doesn't return the sender address. A CommandTransport talks to one and the only peer throughout its life.

Packet-oriented

Like UDP, each read/write operation acts on a single Command object, sent across in its serialized form.

Reliable and in-order

Commands that are written need to arrive in the exact same order, without any loss, or else both sides must raise an error, like TCP.

the default traditional implementation implements this on top of a TCP-like bi-directional byte stream, but Channel can work with any CommandTransport that provides a similar hook.

Serialization of Command

Command objects need to be serialized and deseralized in a specific environment so that Commands can access Channel that's using it. Because of this, a transport needs to use Command.writeTo(Channel, ObjectOutputStream) and Command.readFromObjectStream(Channel, ObjectInputStream) or Command.readFrom(Channel, byte[]).

Since:

2.13

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static interface	CommandTransport.CommandReceiver	SPI implemented by Channel so that the transport can pass the received command to Channel for processing.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CommandTransport()

Method Summary

Modifier and Type	Method	Description
abstract void	closeRead()	Called to indicate that the no further input is expected and any resources associated with reading commands should be freed.
abstract void	closeWrite()	Called to close the write side of the transport, allowing the underlying transport to be shut down.
abstract Capability	getRemoteCapability()	Abstraction of the connection hand-shaking.
abstract void	setup(Channel channel, CommandTransport.CommandReceiver receiver)	Starts the transport.
abstract void	write(Command cmd, boolean last)	Called by Channel to send one command to the other side.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandTransport

protected CommandTransport()

Method Detail

getRemoteCapability

public abstract Capability getRemoteCapability()
                                        throws IOException

Abstraction of the connection hand-shaking.

Before two channels can talk to each other,

Throws:

IOException

setup

public abstract void setup(Channel channel,
                           CommandTransport.CommandReceiver receiver)

Starts the transport. This method is called once and only once at the end of the initialization of Channel, after the getRemoteCapability() is invoked. The first purpose of this method is to provide a reference back to Channel, and the second purpose of this method is to allow CommandTransport to message pumping, where it starts receiving commands from the other side and pass them onto CommandTransport.CommandReceiver. This abstraction enables asynchronous processing — for example you can have a single thread serving a large number of Channels via NIO. For subtypes that prefer synchronous operation, extend from SynchronousCommandTransport.

Closing the read pump: Channel implements Channel.CloseCommand its own "end of command stream" marker, and therefore under the orderly shutdown scenario, it doesn't rely on the transport to provide EOF-like marker. Instead, Channel will call your closeRead() (from the same thread that invoked CommandTransport.CommandReceiver.handle(Command)) to indicate that it is done with the reading.

If the transport encounters any error from the lower layer (say, the underlying TCP/IP socket encountered a REST), then call CommandTransport.CommandReceiver.terminate(IOException) to initiate the abnormal channel termination. This in turn calls closeRead() to shutdown the reader side.

write

public abstract void write(Command cmd,
                           boolean last)
                    throws IOException

Called by Channel to send one command to the other side. Channel serializes the invocation of this method for ordering. That is, at any given point in time only one thread executes this method.

Asynchronous transport must serialize the given command object before returning from this method, as its content can be modified by the calling thread as soon as this method returns. Also, if an asynchronous transport chooses to return from this method without committing data to the network, then it is also responsible for a flow control (by blocking this method if too many commands are queueing up waiting for the network to unclog.)

Parameters:

cmd - The command object that needs to be sent. Never null. This must be serialized via Command.writeTo(Channel, ObjectOutputStream)

last - Informational flag that indicates that this is the last call of the write(Command, boolean).

Throws:

IOException

closeWrite

public abstract void closeWrite()
                         throws IOException

Called to close the write side of the transport, allowing the underlying transport to be shut down.

If the Channel aborts the communication, this method may end up invoked asynchronously, concurrently, and multiple times. The implementation must protect against that.

Throws:

IOException

closeRead

public abstract void closeRead()
                        throws IOException

Called to indicate that the no further input is expected and any resources associated with reading commands should be freed. Channel.isInClosed() can be also used to test if the command reading should terminate.

Throws:

IOException