public abstract class CommandTransport extends 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.readFromObjectStream(Channel, ObjectInputStream)
or
Command.readFrom(Channel, byte[])
.
Modifier and Type | Class and Description |
---|---|
protected static interface |
CommandTransport.CommandReceiver
|
Modifier | Constructor and Description |
---|---|
protected |
CommandTransport() |
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,
CommandTransport.CommandReceiver receiver)
Starts the transport.
|
abstract void |
write(Command cmd,
boolean last)
Called by
Channel to send one command to the other side. |
public abstract Capability getRemoteCapability() throws IOException
Before two channels can talk to each other,
IOException
public abstract void setup(Channel channel, 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 CommandTransport.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
.
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.
public abstract void write(Command cmd, boolean last) throws IOException
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.)
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)
.IOException
public abstract void closeWrite() throws IOException
If the Channel
aborts the communication, this method may end up invoked
asynchronously, concurrently, and multiple times. The implementation must protect
against that.
IOException
public abstract void closeRead() throws IOException
Channel.isInClosed()
can be also used to test if the command reading
should terminate.IOException
Copyright © 2004–2022. All rights reserved.