Package org.jenkinsci.remoting.protocol

Class ProtocolStack<T>

java.lang.Object

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

Type Parameters:

T - the application specific API.

All Implemented Interfaces:

Closeable, AutoCloseable, ByteBufferPool

public class ProtocolStack<T>
extends Object
implements Closeable, ByteBufferPool

A stack of ProtocolLayer that make a network protocol. The stack will start with a NetworkLayer instance, optionally followed by a series of FilterLayer instances and terminated by a ApplicationLayer instance. Instances are created using the on(NetworkLayer) entry point, for example ProtocolStack.on(netLayer).filter(filterLayer1).filter(filterLayer2).filter(filterLayer3).build(appLayer) For this stack, the layers will be initialized and started in the following sequence:

1. NetworkLayer.init(ProtocolStack.Ptr) (netLayer)
2. FilterLayer.init(ProtocolStack.Ptr) (filterLayer1)
3. FilterLayer.init(ProtocolStack.Ptr) (filterLayer2)
4. FilterLayer.init(ProtocolStack.Ptr) (filterLayer3)
5. ApplicationLayer.init(ProtocolStack.Ptr) (appLayer)
6. NetworkLayer.start() (netLayer)
7. FilterLayer.start() (filterLayer1)
8. FilterLayer.start() (filterLayer2)
9. FilterLayer.start() (filterLayer3)
10. ProtocolLayer.start() (appLayer)

If this stack is closed via the network layer - a network initiated close - then the close will be propagated in the following sequence:

1. NetworkLayer (netLayer) detects close
2. FilterLayer.onRecvClosed(IOException) (filterLayer1)
3. FilterLayer.onRecvClosed(IOException) (filterLayer2)
4. FilterLayer.onRecvClosed(IOException) (filterLayer3)
5. FilterLayer.onRecvClosed(IOException) (appLayer)
6. FilterLayer.doCloseSend() (filterLayer3)
7. FilterLayer.doCloseSend() (filterLayer2)
8. FilterLayer.doCloseSend() (filterLayer1)
9. ProtocolLayer.Send.doCloseSend() (netLayer)

If this stack is closed via a protocol layer - a mid-stack initiated close - then the close will be propagated in the following sequence:

1. FilterLayer (filterLayer2) initiates close
2. FilterLayer.onRecvClosed(IOException) (filterLayer3)
3. FilterLayer.onRecvClosed(IOException) (appLayer)
4. FilterLayer.doCloseSend() (filterLayer3)
5. FilterLayer.doCloseSend() (filterLayer2)
6. FilterLayer.doCloseSend() (filterLayer1)
7. ProtocolLayer.Send.doCloseSend() (netLayer)
8. FilterLayer.onRecvClosed(IOException) (filterLayer1)

Since:

3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ProtocolStack.Builder	Builder for ProtocolStack instances.
static interface	ProtocolStack.Listener	Callback "interface" for changes in the state of ProtocolStack.
class	ProtocolStack.Ptr	Tracks where a ProtocolLayer is in the ProtocolStack.

Method Summary

Modifier and Type	Method	Description
ByteBuffer	acquire(int size)	Borrow a buffer from the pool.
void	addListener(ProtocolStack.Listener listener)	Adds a listener.
void	close()
boolean	equals(Object obj)
void	execute(Runnable task)	Executes the given command at some time in the future.
Future<?>	executeLater(Runnable task, long delay, TimeUnit units)	Executes a task at a future point in time.
T	get()	Gets the application specific API.
long	getHandshakingTimeout()	Gets this ProtocolStack's handshaking timeout.
TimeUnit	getHandshakingUnits()	Gets the TimeUnit of getHandshakingTimeout().
int	hashCode()
String	name()	The name of this stack to use in logging.
void	name(String name)	Updates the name of this stack to use in logging.
static ProtocolStack.Builder	on(NetworkLayer network)	Create a ProtocolStack on the supplied NetworkLayer.
void	release(ByteBuffer buffer)	Returns a buffer to the pool.
void	removeListener(ProtocolStack.Listener listener)	Removes a listener.
String	toString()
static void	waitForStart()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

on

public static ProtocolStack.Builder on(NetworkLayer network)

Create a ProtocolStack on the supplied NetworkLayer.

Parameters:

network - the NetworkLayer to build the stack on.

Returns:

the ProtocolStack.Builder.

waitForStart

public static void waitForStart()
                         throws InterruptedException

Throws:

InterruptedException

get

public T get()

Gets the application specific API.

Returns:

the application specific API.

See Also:

ApplicationLayer.get()

name

public String name()

The name of this stack to use in logging.

Returns:

the name of this stack to use in logging.

name

public void name(String name)

Updates the name of this stack to use in logging.

Parameters:

name - the new name of this stack to use in logging.

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

addListener

public void addListener(ProtocolStack.Listener listener)

Adds a listener.

Parameters:

listener - the listener.

removeListener

public void removeListener(ProtocolStack.Listener listener)

Removes a listener.

Parameters:

listener - the listener.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

execute

@OverrideMustInvoke
public void execute(Runnable task)

Executes the given command at some time in the future.

Parameters:

task - the runnable task

Throws:

RejectedExecutionException - if this task cannot be accepted for execution

NullPointerException - if task is null

executeLater

@OverrideMustInvoke
public Future<?> executeLater(Runnable task,
                              long delay,
                              TimeUnit units)

Executes a task at a future point in time. This method should not be used for timing critical scheduling, rather it is intended to be used for things such as protocol timeouts.

Parameters:

task - the task.

delay - the delay.

units - the time units for the delay.

Returns:

a Future that completes when the task has run and can be used to cancel the execution.

Throws:

RejectedExecutionException - if this task cannot be accepted for execution

NullPointerException - if task is null

getHandshakingTimeout

public long getHandshakingTimeout()

Gets this ProtocolStack's handshaking timeout.

Returns:

this ProtocolStack's handshaking timeout.

See Also:

getHandshakingUnits()

getHandshakingUnits

public TimeUnit getHandshakingUnits()

Gets the TimeUnit of getHandshakingTimeout().

Returns:

the TimeUnit of getHandshakingTimeout().

See Also:

()

acquire

public ByteBuffer acquire(int size)

Borrow a buffer from the pool.

Specified by:

acquire in interface ByteBufferPool

Parameters:

size - The minimum size and initial limit of the buffer.

Returns:

the buffer.

release

public void release(ByteBuffer buffer)

Returns a buffer to the pool.

Specified by:

release in interface ByteBufferPool

Parameters:

buffer - the buffer.