Package org.apache.qpid.proton.engine
Interface Transport
- All Superinterfaces:
Endpoint
,Extendable
- All Known Subinterfaces:
ProtonJTransport
,TransportInternal
- All Known Implementing Classes:
TransportImpl
Operates on the entities in the associated Connection
by accepting and producing binary AMQP output, potentially
layered within SASL and/or SSL.
After a connection is bound with bind(Connection)
, the methods for accepting and producing
output are typically repeatedly called. See the specific methods for details of their legal usage.
Processing the input data received from another AMQP container.
getInputBuffer()
- Write data into input buffer
processInput()
- Check the result, e.g. by calling
TransportResult.checkIsOk()
Getting the output data to send to another AMQP container:
getOutputBuffer()
- Read output from output buffer
outputConsumed()
The following methods on the byte buffers returned by getInputBuffer()
and getOutputBuffer()
must not be called:
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
static final int
static final int
the lower bound for the agreed maximum frame size (in bytes).static final int
static final int
static final int
static final int
static final int
-
Method Summary
Modifier and TypeMethodDescriptionvoid
bind
(Connection connection) int
capacity()
void
void
int
Gets the local channel-max value to be advertised to the remote peerlong
long
int
Get a buffer that can be used to write input data into the transport.int
Get the maximum frame size for the transportint
Get a read-only byte buffer containing the transport's pending output.int
Gets the remote value of channel-max, as advertised by the peer on its Open frame.int
int
head()
int
input
(byte[] bytes, int offset, int size) Deprecated.boolean
isClosed()
boolean
int
output
(byte[] dest, int offset, int size) Deprecated.usegetOutputBuffer()
andoutputConsumed()
insteadvoid
Informs the transport that the output buffer returned bygetOutputBuffer()
is finished with, allowing implementation-dependent steps to be performed such as reclaiming buffer space.int
pending()
void
pop
(int bytes) void
process()
Tell the transport to process the data written to the input buffer.sasl()
Signal the transport to expect SASL frames used to establish a SASL layer prior to performing the AMQP protocol version negotiation.void
setChannelMax
(int channelMax) Set the local value of channel-max, to be advertised to the peer on the Open frame emitted by the transport.void
setEmitFlowEventOnSend
(boolean emitFlowEventOnSend) Configure whether a synthetic Flow event should be emitted when messages are sent, reflecting a change in the credit level on the link that may prompt other action.void
setIdleTimeout
(int timeout) void
setInitialRemoteMaxFrameSize
(int size) Allows overriding the initial remote-max-frame-size to a value greater than the default 512bytes.void
setMaxFrameSize
(int size) void
setOutboundFrameSizeLimit
(int size) Set an upper limit on the size of outgoing frames that will be sent to the peer.Equivalent tossl(SslDomain, SslPeerDetails)
but passing null for SslPeerDetails, meaning no SNI detail is sent, hostname verification isn't supported etc when connecting.ssl
(SslDomain sslDomain, SslPeerDetails sslPeerDetails) Wrap this transport's output and input to apply SSL encryption and decryption respectively.tail()
long
tick
(long nowMillis) Prompt the transport to perform work such as idle-timeout/heartbeat handling, and return an absolute deadline in milliseconds that tick must again be called by/at, based on the provided current time in milliseconds, to ensure the periodic work is carried out as necessary.void
trace
(int levels) void
unbind()
Methods inherited from interface org.apache.qpid.proton.engine.Endpoint
close, free, getContext, getLocalState, getRemoteCondition, getRemoteState, open, setCondition, setContext
Methods inherited from interface org.apache.qpid.proton.engine.Extendable
attachments
-
Field Details
-
TRACE_OFF
static final int TRACE_OFF- See Also:
-
TRACE_RAW
static final int TRACE_RAW- See Also:
-
TRACE_FRM
static final int TRACE_FRM- See Also:
-
TRACE_DRV
static final int TRACE_DRV- See Also:
-
DEFAULT_MAX_FRAME_SIZE
static final int DEFAULT_MAX_FRAME_SIZE- See Also:
-
MIN_MAX_FRAME_SIZE
static final int MIN_MAX_FRAME_SIZEthe lower bound for the agreed maximum frame size (in bytes).- See Also:
-
SESSION_WINDOW
static final int SESSION_WINDOW- See Also:
-
END_OF_STREAM
static final int END_OF_STREAM- See Also:
-
-
Method Details
-
trace
void trace(int levels) -
bind
-
unbind
void unbind() -
capacity
int capacity() -
tail
ByteBuffer tail() -
process
- Throws:
TransportException
-
close_tail
void close_tail() -
pending
int pending() -
head
ByteBuffer head() -
pop
void pop(int bytes) -
close_head
void close_head() -
isClosed
boolean isClosed() -
input
Deprecated.usegetInputBuffer()
andprocessInput()
instead.Processes the provided input.- Parameters:
bytes
- input bytes for consumptionoffset
- the offset within bytes where input beginssize
- the number of bytes available for input- Returns:
- the number of bytes consumed
- Throws:
TransportException
- if the input is invalid, if the transport is already in an error state, or if the input is empty (unless the remote connection is already closed)
-
getInputBuffer
ByteBuffer getInputBuffer()Get a buffer that can be used to write input data into the transport. Once the client has finished putting into the input buffer,processInput()
must be called. Successive calls to this method are not guaranteed to return the same object. OnceprocessInput()
is called the buffer must not be used.- Throws:
TransportException
- if the transport is already in an invalid state
-
processInput
TransportResult processInput()Tell the transport to process the data written to the input buffer. If the returned result indicates failure, the transport will not accept any more input. Specifically, any subsequentprocessInput()
calls on this object will throw an exception.- Returns:
- the result of processing the data, which indicates success or failure.
- See Also:
-
output
Deprecated.usegetOutputBuffer()
andoutputConsumed()
insteadHas the transport produce up to size bytes placing the result into dest beginning at position offset.- Parameters:
dest
- array for output bytesoffset
- the offset within bytes where output beginssize
- the maximum number of bytes to be output- Returns:
- the number of bytes written
-
getOutputBuffer
ByteBuffer getOutputBuffer()Get a read-only byte buffer containing the transport's pending output. Once the client has finished getting from the output buffer,outputConsumed()
must be called. Successive calls to this method are not guaranteed to return the same object. OnceoutputConsumed()
is called the buffer must not be used. If the transport's state changes AFTER calling this method, this will not be reflected in the output buffer. -
outputConsumed
void outputConsumed()Informs the transport that the output buffer returned bygetOutputBuffer()
is finished with, allowing implementation-dependent steps to be performed such as reclaiming buffer space. -
sasl
Signal the transport to expect SASL frames used to establish a SASL layer prior to performing the AMQP protocol version negotiation. This must first be performed before the transport is used for processing. Subsequent invocations will return the sameSasl
object.- Throws:
IllegalStateException
- if transport processing has already begun prior to initial invocation
-
ssl
Wrap this transport's output and input to apply SSL encryption and decryption respectively. This method is expected to be called at most once. A subsequent invocation will return the sameSsl
object, regardless of the parameters supplied.- Parameters:
sslDomain
- the SSL settings to usesslPeerDetails
- peer details, used for SNI, hostname verification, etc when connecting. May be null.- Returns:
- an
Ssl
object representing the SSL session. - Throws:
IllegalArgumentException
- if the sslDomain requests hostname verification but sslPeerDetails are null.IllegalStateException
- if the sslDomain has not been initialised.
-
ssl
Equivalent tossl(SslDomain, SslPeerDetails)
but passing null for SslPeerDetails, meaning no SNI detail is sent, hostname verification isn't supported etc when connecting.- Throws:
IllegalArgumentException
- if the sslDomain requests hostname verification.IllegalStateException
- if the sslDomain has not been initialised.
-
getMaxFrameSize
int getMaxFrameSize()Get the maximum frame size for the transport- Returns:
- the maximum frame size
-
setMaxFrameSize
void setMaxFrameSize(int size) -
getRemoteMaxFrameSize
int getRemoteMaxFrameSize() -
setInitialRemoteMaxFrameSize
void setInitialRemoteMaxFrameSize(int size) Allows overriding the initial remote-max-frame-size to a value greater than the default 512bytes. The value set will be used until such time as the Open frame arrives from the peer and populates the remote max frame size. This method must be called before beforesasl()
in order to influence SASL behaviour.- Parameters:
size
- the remote frame size to use
-
getChannelMax
int getChannelMax()Gets the local channel-max value to be advertised to the remote peer- Returns:
- the local channel-max value
- See Also:
-
setChannelMax
void setChannelMax(int channelMax) Set the local value of channel-max, to be advertised to the peer on the Open frame emitted by the transport. The remote peers advertised channel-max can be observed usinggetRemoteChannelMax()
.- Parameters:
channelMax
- the local channel-max to advertise to the peer, in range [0 - 2^16).- Throws:
IllegalArgumentException
- if the value supplied is outside range [0 - 2^16).
-
getRemoteChannelMax
int getRemoteChannelMax()Gets the remote value of channel-max, as advertised by the peer on its Open frame. The local peers advertised channel-max can be observed usinggetChannelMax()
.- Returns:
- the remote channel-max value
-
getCondition
ErrorCondition getCondition()- Specified by:
getCondition
in interfaceEndpoint
- Returns:
- the local endpoint error, or null if there is none
-
setIdleTimeout
void setIdleTimeout(int timeout) - Parameters:
timeout
- local idle timeout in milliseconds
-
getIdleTimeout
int getIdleTimeout()- Returns:
- local idle timeout in milliseconds
-
getRemoteIdleTimeout
int getRemoteIdleTimeout()- Returns:
- remote idle timeout in milliseconds
-
tick
long tick(long nowMillis) Prompt the transport to perform work such as idle-timeout/heartbeat handling, and return an absolute deadline in milliseconds that tick must again be called by/at, based on the provided current time in milliseconds, to ensure the periodic work is carried out as necessary. A returned deadline of 0 indicates there is no periodic work necessitating tick be called, e.g. because neither peer has defined an idle-timeout value. The provided milliseconds time values can be fromSystem.currentTimeMillis()
or derived fromSystem.nanoTime()
, noting that for the later in particular that the returned deadline could be a different sign than the given time, and (if non-zero) the returned deadline should have the current time originally provided subtracted from it in order to establish a relative time delay to the next deadline.- Parameters:
nowMillis
- the current time in milliseconds- Returns:
- the absolute deadline in milliseconds to next call tick by/at, or 0 if there is none.
-
getFramesInput
long getFramesInput() -
getFramesOutput
long getFramesOutput() -
setEmitFlowEventOnSend
void setEmitFlowEventOnSend(boolean emitFlowEventOnSend) Configure whether a synthetic Flow event should be emitted when messages are sent, reflecting a change in the credit level on the link that may prompt other action. Defaults to true.- Parameters:
emitFlowEventOnSend
- true if a flow event should be emitted, false otherwise
-
isEmitFlowEventOnSend
boolean isEmitFlowEventOnSend() -
setOutboundFrameSizeLimit
void setOutboundFrameSizeLimit(int size) Set an upper limit on the size of outgoing frames that will be sent to the peer. Allows constraining the transport not to emit Transfer frames over a given size even when the peers max frame size allows it. Must be set before receiving the peers Open frame to have effect.- Parameters:
size
- the size limit to apply
-
getOutboundFrameSizeLimit
int getOutboundFrameSizeLimit()
-
getInputBuffer()
andprocessInput()
instead.