Package 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:
3.0

  • Constructor Details

    • ApplicationLayer

      public ApplicationLayer()

  • Method Details

    • 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(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(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(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).