Interface Transport

All Superinterfaces:

AutoCloseable

public interface Transport
extends AutoCloseable

A single-use, ordered byte connection. It has no knowledge of MQTT packets.

All methods and listener callbacks must return promptly without waiting for I/O or capacity. Callbacks may occur inline. Received arrays transfer ownership to the listener; they must never be reused. Successful send admission transfers ownership of the array to the transport until onSent or onClosed; a rejected array remains the caller's. Neither side may mutate an admitted array. At most one send may be outstanding. Queuing, capacity limits, and admission policy belong to the caller, not the transport.

Callbacks are serialized. onConnected precedes bytes and send completions. Bytes arrive in wire order with arbitrary chunk boundaries. Each successfully written send must be reported exactly once through onSent, before onClosed, even if EOF, failure, or a close request races with write completion. Shutdown must not discard a successful write's pending notification. Completion means successful local writing, not admission or confirmation of peer receipt. The next send is allowed once onSent is invoked, including from that callback, unless closing. A single final onClosed releases any send whose write did not complete successfully instead of onSent. No callbacks follow it. Closing releases pending I/O and delayed work, including a connection that finishes after close was requested. Runtime exceptions from the factory, start, or send fail the current connection attempt or connection without closing the client permanently. The client closes any created transport. Close failures are logged and cleanup continues. Errors from the factory, start, or send remain fatal to the client.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Transport.Factory	Creates a client's transports, one for each connection; see MqttClientBuilder.transportFactory(Transport.Factory).
static interface	Transport.Listener	Receives the serialized callbacks of one transport, as Transport describes.
static enum	Transport.SendResult	The immediate admission result; only Transport.SendResult.ACCEPTED transfers buffer ownership.

Method Summary

Modifier and Type	Method	Description
void	close()	Requests shutdown.
Transport.SendResult	send(long ticket, byte[] bytes)	Starts one write without waiting.
void	start(URI endpoint, Duration timeout, Transport.Listener listener)	Starts this transport's only connection.
static Transport	tcp(String clientId)	Creates a plain TCP transport accepting only mqtt URIs (default port 1883).

Method Details

start

void start(URI endpoint,
 Duration timeout,
 Transport.Listener listener)

Starts this transport's only connection. The timeout bounds its establishment, including any TLS handshake, not subsequent reads. Implementations must reject unsupported URI schemes here with IllegalArgumentException, rather than silently use a different transport.

Parameters:

endpoint - the URI to connect to

timeout - the bound on establishing the connection

listener - the listener for this connection's callbacks

send

Transport.SendResult send(long ticket,
 byte[] bytes)

Starts one write without waiting. Call after Transport.Listener.onConnected() has been invoked and after any previous send has completed. Completion may be notified before this returns. Transport.SendResult.CLOSED includes shutdown in progress. Once started, the transport reports its cause through exactly one Transport.Listener.onClosed(Throwable) callback, which may already have arrived.

Parameters:

ticket - the caller's identifier for this send, which Transport.Listener.onSent(long) reports

bytes - the bytes to write

Returns:

the immediate admission result

Throws:

IllegalStateException -

if not yet connected or a send is outstanding, unless closing or closed

close

void close()

Requests shutdown. Safe before start, concurrent with other methods, and idempotent.

Specified by:

close in interface AutoCloseable

tcp

static Transport tcp(String clientId)

Creates a plain TCP transport accepting only mqtt URIs (default port 1883). The client identifier is used for diagnostics. Its deadlines use real time, not the scheduler passed to MqttClientBuilder.timerScheduler(TimerScheduler).

Parameters:

clientId - the client identifier

Returns:

a new transport, not yet started