org.jenkinsci.remoting.protocol

Class ApplicationLayer<T>

java.lang.Object

org.jenkinsci.remoting.protocol.ApplicationLayer<T>

Type Parameters:

T - the application specific API.

All Implemented Interfaces:

ProtocolLayer, ProtocolLayer.Recv

Direct Known Subclasses:

ChannelApplicationLayer

public abstract class ApplicationLayer<T>
extends Object
implements ProtocolLayer, ProtocolLayer.Recv

The highest ProtocolLayer in a ProtocolStack. This layer is responsible for translating the protocol stack into the application specific API.

Since:

FIXME

Nested Class Summary

Nested classes/interfaces inherited from interface org.jenkinsci.remoting.protocol.ProtocolLayer

ProtocolLayer.Recv, ProtocolLayer.Send

Field Summary

Fields inherited from interface org.jenkinsci.remoting.protocol.ProtocolLayer

EMPTY_BUFFER, UTF_8

Constructor Summary

Constructors

Constructor and Description
ApplicationLayer()

Method Summary

Modifier and Type	Method and Description
void	doCloseRead() SPI: Implementations of ApplicationLayer should use this method to request that the read path of the ProtocolStack be closed.
void	doCloseWrite() SPI: Implementations of ApplicationLayer should use this method to request that the write path of the ProtocolStack be closed.
abstract T	get() SPI: Returns the application specific API instance.
void	init(ProtocolStack.Ptr ptr) Initializes the layer with its ProtocolStack.Ptr.
abstract boolean	isReadOpen() SPI: Implementations of ApplicationLayer must ensure this method either returns true while the application specific API instance (get()) is accepting data via onRead(ByteBuffer) or returns false once it is permanently closed to incoming data.
boolean	isRecvOpen() Tracks if this layer is accepting received data via ProtocolLayer.Recv.onRecv(ByteBuffer).
boolean	isWriteOpen() SPI: Implementations of ApplicationLayer should use method to detect if the ProtocolStack is open for writing via write(ByteBuffer) or has been closed.
abstract void	onRead(ByteBuffer data) SPI: Callback on data being received from the protocol stack.
abstract void	onReadClosed(IOException cause) Callback on the lower layer's source of data being closed.
void	onRecv(ByteBuffer data) Callback on data being received from the lower layer.
void	onRecvClosed(IOException cause) Callback on the lower layer's source of data being closed.
protected ProtocolStack<?>	stack() Accessor for the ProtocolStack that we are bound to.
void	write(ByteBuffer data) SPI: Implementations of ApplicationLayer should use this method to write data through the ProtocolStack.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jenkinsci.remoting.protocol.ProtocolLayer

start

Constructor Detail

ApplicationLayer

public ApplicationLayer()

Method Detail

get

public abstract T get()

SPI: Returns the application specific API instance.

Returns:

the application specific API instance.

isReadOpen

public abstract boolean isReadOpen()

SPI: Implementations of ApplicationLayer must ensure this method either returns true while the application specific API instance (get()) is accepting data via onRead(ByteBuffer) or returns false once it is permanently closed to incoming data. If the application specific API instance is temporarily not accepting data then this method should return true and the implementation is responsible for caching the data submitted in calls to onRead(ByteBuffer) Once this method returns false it must always return false and can be assumed to behave in this way.

Returns:

true if the application specific API instance (get() is accepting data via onRead(ByteBuffer)

onRead

public abstract void onRead(@Nonnull
                            ByteBuffer data)
                     throws IOException

SPI: Callback on data being received from the protocol stack.

Parameters:

data - the data received. Any data consumed from the ByteBuffer can be assumed as processed. Any data not consumed from the ByteBuffer will be the responsibility of the caller to resubmit in subsequent calls.

Throws:

IOException - if there was an error during processing of the received data.

onReadClosed

public abstract void onReadClosed(IOException cause)
                           throws IOException

Callback on the lower layer's source of data being closed.

Parameters:

cause - the cause of the lower layer being closed or null.

Throws:

IOException - if there was an error during the processing of the close notification.

init

public final void init(@Nonnull
                       ProtocolStack.Ptr ptr)
                throws IOException

Initializes the layer with its ProtocolStack.Ptr. All lower layers in the stack will be initialized before a call to this method. All layers in a stack will be initialized before a call to ProtocolLayer.start().

Specified by:

init in interface ProtocolLayer

Parameters:

ptr - the position of this layer in the stack.

Throws:

IOException - if something goes wrong.

isWriteOpen

public final boolean isWriteOpen()

SPI: Implementations of ApplicationLayer should use method to detect if the ProtocolStack is open for writing via write(ByteBuffer) or has been closed. Once this method returns false it will always return false and can be assumed to behave in this way.

Returns:

true if the ProtocolStack is open for writing via write(ByteBuffer).

write

public final void write(@Nonnull
                        ByteBuffer data)
                 throws IOException

SPI: Implementations of ApplicationLayer should use this method to write data through the ProtocolStack.

Parameters:

data - the data to write. Any data consumed from the ByteBuffer can be assumed as processed. Any data not consumed from the ByteBuffer will be the responsibility of the caller to resubmit in subsequent calls.

Throws:

IOException - if there was an error during processing of the data.

doCloseWrite

public final void doCloseWrite()
                        throws IOException

SPI: Implementations of ApplicationLayer should use this method to request that the write path of the ProtocolStack be closed. Depending on the nature of the NetworkLayer this may force closed the read path (e.g. if the backing transport is using a SocketChannel).

Throws:

IOException - if there was an error during the closing of the write path.

doCloseRead

public final void doCloseRead()
                       throws IOException

SPI: Implementations of ApplicationLayer should use this method to request that the read path of the ProtocolStack be closed. Depending on the nature of the NetworkLayer this may force closed the write path (e.g. if the backing transport is using a SocketChannel).

Throws:

IOException - if there was an error during the closing of the read path.

stack

@Nullable
protected ProtocolStack<?> stack()

Accessor for the ProtocolStack that we are bound to.

Returns:

the ProtocolStack that we are bound to or null if we are not currently bound to a stack.

onRecv

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final void onRecv(@Nonnull
                                                                                                 ByteBuffer data)
                                                                                          throws IOException

Callback on data being received from the lower layer.

Specified by:

onRecv in interface ProtocolLayer.Recv

Parameters:

data - the data received. Any data consumed from the ByteBuffer can be assumed as processed. Any data not consumed from the ByteBuffer will be the responsibility of the caller to resubmit in subsequent calls.

Throws:

IOException - if there was an error during processing of the received data.

onRecvClosed

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final void onRecvClosed(IOException cause)
                                                                                                throws IOException

Callback on the lower layer's source of data being closed.

Specified by:

onRecvClosed in interface ProtocolLayer.Recv

Parameters:

cause - the cause of the lower layer being closed or null.

Throws:

IOException - if there was an error during the processing of the close notification.

isRecvOpen

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final boolean isRecvOpen()

Tracks if this layer is accepting received data via ProtocolLayer.Recv.onRecv(ByteBuffer). Once this method returns false it must always return false and can be assumed to behave in this way.

Specified by:

isRecvOpen in interface ProtocolLayer.Recv

Returns:

true if accepting received data via ProtocolLayer.Recv.onRecv(ByteBuffer).