org.apache.qpid.proton.engine

Interface Transport

All Superinterfaces:

Endpoint, Extendable

All Known Subinterfaces:

ProtonJTransport

All Known Implementing Classes:

TransportImpl

public interface Transport
extends Endpoint

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.

1. getInputBuffer()
2. Write data into input buffer
3. processInput()
4. Check the result, e.g. by calling TransportResult.checkIsOk()

Getting the output data to send to another AMQP container:

1. getOutputBuffer()
2. Read output from output buffer
3. outputConsumed()

The following methods on the byte buffers returned by getInputBuffer() and getOutputBuffer() must not be called:

1. Buffer.clear()
2. ByteBuffer.compact()
3. Buffer.flip()
4. Buffer.mark()

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Transport.Factory

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_FRAME_SIZE
static int	END_OF_STREAM
static int	MIN_MAX_FRAME_SIZE the lower bound for the agreed maximum frame size (in bytes).
static int	SESSION_WINDOW
static int	TRACE_DRV
static int	TRACE_FRM
static int	TRACE_OFF
static int	TRACE_RAW

Method Summary

Methods

Modifier and Type	Method and Description
void	bind(Connection connection)
int	capacity()
void	close_head()
void	close_tail()
int	getChannelMax() Gets the local channel-max value to be advertised to the remote peer
ErrorCondition	getCondition()
long	getFramesInput()
long	getFramesOutput()
int	getIdleTimeout()
ByteBuffer	getInputBuffer() Get a buffer that can be used to write input data into the transport.
int	getMaxFrameSize() Get the maximum frame size for the transport
ByteBuffer	getOutputBuffer() Get a read-only byte buffer containing the transport's pending output.
int	getRemoteChannelMax() Gets the remote value of channel-max, as advertised by the peer on its Open frame.
int	getRemoteIdleTimeout()
int	getRemoteMaxFrameSize()
ByteBuffer	head()
int	input(byte[] bytes, int offset, int size) Deprecated. use getInputBuffer() and processInput() instead.
boolean	isClosed()
boolean	isEmitFlowEventOnSend()
int	output(byte[] dest, int offset, int size) Deprecated. use getOutputBuffer() and outputConsumed() instead
void	outputConsumed() Informs the transport that the output buffer returned by getOutputBuffer() is finished with, allowing implementation-dependent steps to be performed such as reclaiming buffer space.
int	pending()
void	pop(int bytes)
void	process()
TransportResult	processInput() Tell the transport to process the data written to the input buffer.
Sasl	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	setMaxFrameSize(int size)
Ssl	ssl(SslDomain sslDomain) As per ssl(SslDomain, SslPeerDetails) but no attempt is made to resume a previous SSL session.
Ssl	ssl(SslDomain sslDomain, SslPeerDetails sslPeerDetails) Wrap this transport's output and input to apply SSL encryption and decryption respectively.
ByteBuffer	tail()
long	tick(long now)
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 Detail

TRACE_OFF

static final int TRACE_OFF

See Also:

Constant Field Values

TRACE_RAW

static final int TRACE_RAW

See Also:

Constant Field Values

TRACE_FRM

static final int TRACE_FRM

See Also:

Constant Field Values

TRACE_DRV

static final int TRACE_DRV

See Also:

Constant Field Values

DEFAULT_MAX_FRAME_SIZE

static final int DEFAULT_MAX_FRAME_SIZE

See Also:

Constant Field Values

MIN_MAX_FRAME_SIZE

static final int MIN_MAX_FRAME_SIZE

the lower bound for the agreed maximum frame size (in bytes).

See Also:

Constant Field Values

SESSION_WINDOW

static final int SESSION_WINDOW

See Also:

Constant Field Values

END_OF_STREAM

static final int END_OF_STREAM

See Also:

Constant Field Values

Method Detail

trace

void trace(int levels)

bind

void bind(Connection connection)

unbind

void unbind()

capacity

int capacity()

tail

ByteBuffer tail()

process

void process()
             throws TransportException

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
int input(byte[] bytes,
                   int offset,
                   int size)

Deprecated. use getInputBuffer() and processInput() instead.

Processes the provided input.

Parameters:

bytes - input bytes for consumption

offset - the offset within bytes where input begins

size - 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. Once processInput() 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 subsequent processInput() calls on this object will throw an exception.

Returns:

the result of processing the data, which indicates success or failure.

See Also:

getInputBuffer()

output

@Deprecated
int output(byte[] dest,
                    int offset,
                    int size)

Deprecated. use getOutputBuffer() and outputConsumed() instead

Has the transport produce up to size bytes placing the result into dest beginning at position offset.

Parameters:

dest - array for output bytes

offset - the offset within bytes where output begins

size - 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. Once outputConsumed() 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 by getOutputBuffer() is finished with, allowing implementation-dependent steps to be performed such as reclaiming buffer space.

sasl

Sasl sasl()
          throws IllegalStateException

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 same Sasl object.

Throws:

IllegalStateException - if transport processing has already begun prior to initial invocation

ssl

Ssl ssl(SslDomain sslDomain,
      SslPeerDetails sslPeerDetails)

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 same Ssl object, regardless of the parameters supplied.

Parameters:

sslDomain - the SSL settings to use

sslPeerDetails - may be null, in which case SSL session resume will not be attempted

Returns:

an Ssl object representing the SSL session.

ssl

Ssl ssl(SslDomain sslDomain)

As per ssl(SslDomain, SslPeerDetails) but no attempt is made to resume a previous SSL session.

getMaxFrameSize

int getMaxFrameSize()

Get the maximum frame size for the transport

Returns:

the maximum frame size

setMaxFrameSize

void setMaxFrameSize(int size)

getRemoteMaxFrameSize

int getRemoteMaxFrameSize()

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

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 using getRemoteChannelMax().

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 using getChannelMax().

Returns:

the remote channel-max value

getCondition

ErrorCondition getCondition()

Specified by:

getCondition in interface Endpoint

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 now)

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