org.jenkinsci.remoting.protocol

Class FilterLayer

java.lang.Object

org.jenkinsci.remoting.protocol.FilterLayer

All Implemented Interfaces:

ProtocolLayer, ProtocolLayer.Recv, ProtocolLayer.Send

Direct Known Subclasses:

AckFilterLayer, AgentProtocolClientFilterLayer, ConnectionHeadersFilterLayer, SSLEngineFilterLayer

public abstract class FilterLayer
extends Object
implements ProtocolLayer, ProtocolLayer.Send, ProtocolLayer.Recv

An intermediate ProtocolLayer in a ProtocolStack. This layer can be responsible for

• Filtering the data stream
• Initial handshaking
• Transforming the data stream, e.g. encryption
• Monitoring the data stream
• etc.

Since:

3.0

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
FilterLayer()

Method Summary

Modifier and Type	Method and Description
protected void	abort(IOException cause) The FilterLayer implementation calls this to signify that a critical error in the stack has occurred and that the stack should be torn down and closed.
protected void	completed() The FilterLayer implementation calls this to signify that it is now a no-op layer in both directions and can be removed from the ProtocolStack
void	doCloseSend() Notify the lower layer that it should close.
abstract void	doSend(ByteBuffer data) SPI: Sends data to the lower layer.
protected void	flushRecv(ByteBufferQueue queue) Flushes the supplied ByteBufferQueue to next()'s ProtocolStack.Ptr.onRecv(ByteBuffer).
protected void	flushSend(ByteBufferQueue queue) Flushes the supplied ByteBufferQueue to next()'s ProtocolStack.Ptr.doSend(ByteBuffer) This method is especially helpful for FilterLayer implementations that are involved in initial handshaking as they will need to queue up data until the handshake is completed and then flush the data to the remainder of the stack.
void	init(ProtocolStack.Ptr ptr) Initializes the layer with its ProtocolStack.Ptr.
boolean	isRecvOpen() Tracks if this layer is accepting received data via ProtocolLayer.Recv.onRecv(ByteBuffer).
boolean	isSendOpen() Tracks if this layer is submitting data to be sent via ProtocolLayer.Send.doSend(ByteBuffer).
protected ProtocolStack.Ptr	next() Accessor for the next layers in the ProtocolStack.
abstract void	onRecv(ByteBuffer data) SPI: 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	start() Starts this layer.

Methods inherited from class java.lang.Object

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

Constructor Detail

FilterLayer

public FilterLayer()

Method Detail

init

@OverridingMethodsMustInvokeSuper
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.

start

public void start()
           throws IOException

Starts this layer. All layers in the stack will be initialized before a call to this method. All lower layers in the stack will have been started before this layer is started.

Specified by:

start in interface ProtocolLayer

Throws:

IOException - if something goes wrong.

completed

protected final void completed()

The FilterLayer implementation calls this to signify that it is now a no-op layer in both directions and can be removed from the ProtocolStack

abort

protected final void abort(@Nonnull
                           IOException cause)

The FilterLayer implementation calls this to signify that a critical error in the stack has occurred and that the stack should be torn down and closed.

Parameters:

cause - the root cause to report.

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.

next

@Nullable
protected ProtocolStack.Ptr next()

Accessor for the next layers in the ProtocolStack.

Returns:

our ProtocolStack.Ptr or null if we are not currently bound to a stack.

flushRecv

protected final void flushRecv(ByteBufferQueue queue)
                        throws IOException

Flushes the supplied ByteBufferQueue to next()'s ProtocolStack.Ptr.onRecv(ByteBuffer). This method is especially helpful for FilterLayer implementations that are involved in initial handshaking as they will need to queue up data until the handshake is completed and then flush the data to the remainder of the stack.

Parameters:

queue - the data to receive.

Throws:

IOException - if there is an I/O error during the receive.

flushSend

protected final void flushSend(ByteBufferQueue queue)
                        throws IOException

Flushes the supplied ByteBufferQueue to next()'s ProtocolStack.Ptr.doSend(ByteBuffer) This method is especially helpful for FilterLayer implementations that are involved in initial handshaking as they will need to queue up data until the handshake is completed and then flush the data to the remainder of the stack.

Parameters:

queue - the data to send.

Throws:

IOException - if there is an I/O error during the receive.

onRecv

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

SPI: 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

@OverridingMethodsMustInvokeSuper
public 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

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

doSend

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

SPI: Sends data to the lower layer.

Specified by:

doSend in interface ProtocolLayer.Send

Parameters:

data - the data to send. 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.

doCloseSend

@OverridingMethodsMustInvokeSuper
public void doCloseSend()
                                                   throws IOException

Notify the lower layer that it should close. Callers to this method are assumed to have already called ProtocolLayer.Recv.onRecvClosed(IOException) for any upper layers.

Specified by:

doCloseSend in interface ProtocolLayer.Send

Throws:

IOException - if there was an error closing the lower layer.

isSendOpen

public boolean isSendOpen()

Tracks if this layer is submitting data to be sent via ProtocolLayer.Send.doSend(ByteBuffer). Once this method returns false it must always return false and can be assumed to behave in this way.

Specified by:

isSendOpen in interface ProtocolLayer.Send

Returns:

true if submitting data to be sent via ProtocolLayer.Send.doSend(ByteBuffer).