public abstract class CommandTransport
extends java.lang.Object
Channel
for sending and receiving commands
Channel
is internally implemented on top of a transport that satisfies
the following characteristics:
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.
Command
object, sent across
in its serialized form.
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
any CommandTransport
that provides a similar hook.
Command
Command
objects need to be serialized and deseralized in a specific environment
so that Command
s can access Channel
that's using it. Because of this,
a transport needs to use Command.writeTo(Channel, ObjectOutputStream)
and
Command.readFrom(Channel, ObjectInputStream)
.
Modifier and Type | Method and 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,
hudson.remoting.CommandTransport.CommandReceiver receiver)
Starts the transport.
|
public abstract Capability getRemoteCapability() throws java.io.IOException
Before two channels can talk to each other,
java.io.IOException
public abstract void setup(Channel channel, hudson.remoting.CommandTransport.CommandReceiver receiver)
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 CommandReceiver
.
This abstraction enables asynchronous processing — for example you can have a single thread
serving a large number of Channel
s via NIO.
For subtypes that prefer synchronous operation, extend from SynchronousCommandTransport
.
Channel
implements 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 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 CommandReceiver#terminate(IOException)
to initiate the abnormal
channel termination. This in turn calls closeRead()
to shutdown the reader side.
public abstract void closeWrite() throws java.io.IOException
If the Channel
aborts the communication, this method may end up invoked
asynchronously, concurrently, and multiple times. The implementation must protect
against that.
java.io.IOException
public abstract void closeRead() throws java.io.IOException
Channel.isInClosed()
can be also used to test if the command reading
should terminate.java.io.IOException
Copyright © 2012. All Rights Reserved.