public interface IEngine
interface
allowing implementation of customizable protocol
engines that can be used to drive EngineStreamSession
.
The idea behind a protocol engine is to capture all the complex details of a protocol implementation in a way that is decoupled from I/O operations and threading models so the implementation can only concentrate on processing of inbound and outbound byte streams.
There are following distinct phases in an engine driven session life cycle.
SessionEvent.CREATED
event is sent to the session's handler.
SessionEvent.OPENED
event is sent to the session's handler and engine can begin the
initial handshaking.
SessionEvent.READY
event is sent to the session's handler.
closeOutbound()
method or by unwrapping a closing
message that was send by the peer.
SessionEvent.CLOSED
event
is sent to the session's handler.
SessionEvent.ENDING
event
is sent to the session's handler.
Concurrency Notes: Considering the way the interface is used by the framework it is not required, in general, for an implementation to be thread safe however there is one concurrency issue to be aware of:
getDelegatedTask()
will be executed in
a separate thread what may enforce a thread-safe architecture.
Modifier and Type | Method and Description |
---|---|
void |
beginHandshake()
Initiates handshaking on this
IEngine implementation. |
void |
cleanup()
Signals that an
IEngine implementation can cleanup, if
required, its internal state (e.g. |
void |
closeInbound()
Signals that no more inbound network data will be sent to an
IEngine implementation. |
void |
closeOutbound()
Signals that no more outbound application data will be sent to an
IEngine implementation. |
Runnable |
getDelegatedTask()
Returns a delegated
Runnable task for an IEngine
implementation. |
HandshakeStatus |
getHandshakeStatus()
Returns the current handshake status for an
IEngine
implementation. |
int |
getMaxApplicationBufferSize()
Gets the current maximum size of the buffer holding application data
|
int |
getMaxNetworkBufferSize()
Gets the current maximum size of the buffer holding network data
|
int |
getMinApplicationBufferSize()
Gets the current minimum size of the buffer holding application data.
|
int |
getMinNetworkBufferSize()
Gets the current minimum size of the buffer holding network data.
|
Object |
getSession()
Returns an object representing a session in use in an
IEngine
implementation. |
void |
init()
Signals that an
IEngine implementation can initialize, if
required, its internal state (e.g. |
boolean |
isInboundDone()
Returns whether
unwrap(ByteBuffer, ByteBuffer) method
will accept any more inbound network data. |
boolean |
isOutboundDone()
Returns whether
wrap(ByteBuffer, ByteBuffer) and
wrap(ByteBuffer[], ByteBuffer) methods will produce
any more outbound network data. |
IEngineResult |
unwrap(ByteBuffer src,
ByteBuffer dst)
Attempts to encode inbound network data from a data buffer into inbound
application data.
|
IEngineResult |
wrap(ByteBuffer[] srcs,
ByteBuffer dst)
Attempts to encode outbound application data from a subsequence of data buffers
into outbound network data.
|
IEngineResult |
wrap(ByteBuffer src,
ByteBuffer dst)
Attempts to encode outbound application data from a data buffer into outbound
network data.
|
void init()
IEngine
implementation can initialize, if
required, its internal state (e.g. allocate required resources). It is
called during pre-creation phase of an engine driven session (i.e.
before the event SessionEvent.CREATED
is signaled to the session handler).void cleanup()
IEngine
implementation can cleanup, if
required, its internal state (e.g. release allocated resources). It is
called during post-ending phase of an engine driven session (i.e.
after the event SessionEvent.ENDING
is fully processed by the session handler).void beginHandshake() throws Exception
IEngine
implementation. This method
is not called by the SNF4J framework for a initial handshake, as the
initial handshake should be initiated by the wrap()
and
unwrap()
methods when they are called for the first time.
This method is never called by the SNF4J framework when another handshake
is still in progress on this engine. Any try to begin a new handshake
from an engine stream session will be silently ignored unless previously
started handshake is finished. The finishing is signaled by the
HandshakeStatus.FINISHED
status returned by the wrap
or
unwrap
method.
Exception
- if a problem was encountered while signaling the beginning of
a new handshake.boolean isOutboundDone()
wrap(ByteBuffer, ByteBuffer)
and
wrap(ByteBuffer[], ByteBuffer)
methods will produce
any more outbound network data.true
if an IEngine
implementation
will not produce any more network databoolean isInboundDone()
unwrap(ByteBuffer, ByteBuffer)
method
will accept any more inbound network data.true
if an IEngine
implementation will not
consume anymore network datacloseInbound()
void closeOutbound()
IEngine
implementation.
This method should be idempotent: if the outbound side has already been closed, this method should not do anything.
isOutboundDone()
void closeInbound() throws SessionIncidentException
IEngine
implementation.
This method should be idempotent: if the inbound side has already been closed, this method should not do anything.
SessionIncidentException
- if this engine implementation detected an incident that
should be reported to the associated session's handler (e.g.
when an engine has not received a proper close message from
the peer).isInboundDone()
int getMinApplicationBufferSize()
IEngine
implementation may use application data (i.e. the
application data wrapped in one network packet) of any size up to and
including the value returned by this method.int getMinNetworkBufferSize()
IEngine
implementation may generate network packets of any size up to and including the value
returned by this method.int getMaxApplicationBufferSize()
This method is only used by the EngineStreamSession
class.
int getMaxNetworkBufferSize()
This method is only used by the EngineStreamSession
class.
HandshakeStatus getHandshakeStatus()
IEngine
implementation.
It should never return the FINISHED
status.
Object getSession()
IEngine
implementation.UnsupportedOperationException
- if the current implementation does not
support a session.Runnable getDelegatedTask()
Runnable
task for an IEngine
implementation.
IEngine
operations may require the results of operations
that block, or may take an extended period of time to complete. This
method should be used to obtain a pending Runnable
operation
(task). Each task will be assigned a thread to perform the run operation.
The assigned thread will be created by a thread factory configured in the
selector loop that will handle the session associated with this IEngine
implementation.
A call to this method should return each pending task exactly once.
Multiple tasks can be run in parallel.
Runnable,
task, or null if none are
available.IEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst) throws Exception
Depending on the state of an IEngine
implementation, this method
can produce network data without consuming any application data (for
example, it may generate handshake data.)
If an IEngine
implementation has not yet started its initial
handshake, this method should automatically start the handshake.
srcs
- an array of ByteBuffers
containing the outbound
application datadst
- a ByteBuffer
to hold outbound network dataEngineResult
describing the result of this operation.Exception
- when a problem occurred. Once it is thrown the associated
session will be quickly closedIEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws Exception
Depending on the state of an IEngine
implementation, this method
can produce network data without consuming any application data (for
example, it may generate handshake data.)
If an IEngine
implementation has not yet started its initial
handshake, this method should automatically start the handshake.
src
- a ByteBuffer
containing the outbound
application datadst
- a ByteBuffer
to hold outbound network dataEngineResult
describing the result of this operation.Exception
- when a problem occurred. Once it is thrown the associated
session will be quickly closedIEngineResult unwrap(ByteBuffer src, ByteBuffer dst) throws Exception
Depending on the state of an IEngine
implementation, this method
can consume network data without producing any application data (for
example, it may generate handshake data.)
If an IEngine
implementation has not yet started its initial
handshake, this method should automatically start the handshake.
src
- a ByteBuffer
containing the inbound
application datadst
- a ByteBuffer
to hold inbound application dataEngineResult
describing the result of this operation.Exception
- when a problem occurred. Once it is thrown the associated
session will be quickly closedCopyright © 2017–2021 SNF4J.ORG. All rights reserved.