hudson.remoting

Class AbstractByteBufferCommandTransport

java.lang.Object

hudson.remoting.CommandTransport

hudson.remoting.AbstractByteBufferCommandTransport

public abstract class AbstractByteBufferCommandTransport
extends CommandTransport

A CommandTransport that uses ByteBuffer rather than byte[].

Since:

3.0

Nested Class Summary

Nested classes/interfaces inherited from class hudson.remoting.CommandTransport

CommandTransport.CommandReceiver

Constructor Summary

Constructors

Constructor and Description
AbstractByteBufferCommandTransport()

Method Summary

Modifier and Type	Method and Description
protected Channel	getChannel() Gets the channel.
void	receive(ByteBuffer data) Handle receiving some data.
void	setFrameSize(int transportFrameSize) Set the frame size.
void	setup(Channel channel, CommandTransport.CommandReceiver receiver) Starts the transport.
void	terminate(IOException e) Indicates that the endpoint has encountered a problem.
protected abstract void	write(ByteBuffer header, ByteBuffer data) Write the packet.
void	write(Command cmd, boolean last) Called by Channel to send one command to the other side.

Methods inherited from class hudson.remoting.CommandTransport

closeRead, closeWrite, getRemoteCapability

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractByteBufferCommandTransport

public AbstractByteBufferCommandTransport()

Method Detail

write

protected abstract void write(ByteBuffer header,
                              ByteBuffer data)
                       throws IOException

Write the packet.

Parameters:

header - the header to write.

data - the data to write.

Throws:

IOException - if the data could not be written.

receive

public final void receive(@NonNull
                          ByteBuffer data)
                   throws IOException,
                          InterruptedException

Handle receiving some data.

Parameters:

data - the data that has been received.

Throws:

IOException - if something goes wrong during the receive.

InterruptedException - if interrupted during the receive.

setFrameSize

public void setFrameSize(int transportFrameSize)

Set the frame size.

Parameters:

transportFrameSize - the new frame size (must be in the range 1-Short.MAX_VALUE).

getChannel

@Nullable
protected Channel getChannel()

Gets the channel.

Returns:

the channel.

setup

public final 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 CommandTransport.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 CommandTransport.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 CommandTransport.closeRead() to shutdown the reader side.

Specified by:

setup in class CommandTransport

write

public final 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.)

Specified by:

write in class CommandTransport

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 CommandTransport.write(Command, boolean).

Throws:

IOException

terminate

public void terminate(IOException e)

Indicates that the endpoint has encountered a problem. This tells the transport that it shouldn't expect future invocation of receive(ByteBuffer), and it'll abort the communication.