Class CommandTransport
- java.lang.Object
-
- hudson.remoting.CommandTransport
-
- Direct Known Subclasses:
AbstractByteArrayCommandTransport
,AbstractByteBufferCommandTransport
,SynchronousCommandTransport
public abstract class CommandTransport extends Object
Lower level abstraction underChannel
for sending and receiving commandsChannel
is internally implemented on top of a transport that satisfies the following characteristics:- Point-to-point
-
Like TCP, by the time
CommandTransport
is used byChannel
, 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. ACommandTransport
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
-
Command
s 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 anyCommandTransport
that provides a similar hook.Serialization of
Command
Command
objects need to be serialized and deseralized in a specific environment so thatCommand
s can accessChannel
that's using it. Because of this, a transport needs to useCommand.writeTo(Channel, ObjectOutputStream)
andCommand.readFromObjectStream(Channel, ObjectInputStream)
orCommand.readFrom(Channel, byte[])
.- Since:
- 2.13
- Author:
- Kohsuke Kawaguchi
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static interface
CommandTransport.CommandReceiver
-
Constructor Summary
Constructors Modifier Constructor Description protected
CommandTransport()
-
Method Summary
All Methods Instance Methods Abstract Methods 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 byChannel
to send one command to the other side.
-
-
-
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 ofChannel
, after thegetRemoteCapability()
is invoked. The first purpose of this method is to provide a reference back toChannel
, and the second purpose of this method is to allowCommandTransport
to message pumping, where it starts receiving commands from the other side and pass them ontoCommandTransport.CommandReceiver
. This abstraction enables asynchronous processing — for example you can have a single thread serving a large number ofChannel
s via NIO. For subtypes that prefer synchronous operation, extend fromSynchronousCommandTransport
.Closing the read pump:
Channel
implementsChannel.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 yourcloseRead()
(from the same thread that invokedCommandTransport.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 callscloseRead()
to shutdown the reader side.
-
write
public abstract void write(Command cmd, boolean last) throws IOException
Called byChannel
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 viaCommand.writeTo(Channel, ObjectOutputStream)
last
- Informational flag that indicates that this is the last call of thewrite(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
-
-