Package org.apache.qpid.proton.engine

# Interface Transport

All Superinterfaces:
  `Endpoint`, `Extendable`

All Known Subinterfaces:
  `ProtonJTransport`, `TransportInternal`

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
Description
`static final class`
`Transport.Factory`

## Field Summary

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

## Method Summary

Modifier and Type
Method
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
`int`
`getOutboundFrameSizeLimit()`
`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`
`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.
`Ssl`
`ssl(SslDomain sslDomain)`
Equivalent to `ssl(SslDomain, SslPeerDetails)` but passing null for SslPeerDetails, meaning no SNI detail is sent, hostname verification isn't supported etc when connecting.
`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 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:
  - 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 Details

### 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) throws IllegalArgumentException
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` - 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

Ssl ssl(SslDomain sslDomain) throws IllegalArgumentException
Equivalent to `ssl(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 before `sasl()` 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(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 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 from `System.currentTimeMillis()` or derived from `System.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()