net.kuujo.catalyst.transport

Interface Connection

public interface Connection

Transport connection.

This is a low-level abstraction through which clients and servers communicate with one another once connected. This is more or less a lightweight interface over sockets that supports arbitrary messages.

Messages sent over a connection must be serializable by the registered Serializer. This means that messages must implement Serializable, Externalizable, or CatalystSerializable or provide a custom TypeSerializer.

Author:

Jordan Halterman

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	close() Closes the connection.
Listener<Connection>	closeListener(Consumer<Connection> listener) Sets a close listener on the connection.
Listener<Throwable>	exceptionListener(Consumer<Throwable> listener) Sets an exception listener on the connection.
<T,U> Connection	handler(Class<T> type, MessageHandler<T,U> handler) Sets a message handler on the connection.
UUID	id() Returns the connection ID.
<T,U> CompletableFuture<U>	send(T message) Sends a message to the other side of the connection.

Method Detail

id

UUID id()

Returns the connection ID.

The connection ID is inherited from the Client that is connected. When the connection is created, the client will send its Client.id() to the Server and the connection ID will reflect the client's ID on both the client and server side.

Returns:

The connection ID.

send

<T,U> CompletableFuture<U> send(T message)

Sends a message to the other side of the connection.

The message must be serializable via the configured Serializer instance. This means it must implement Serializable, Externalizable, or CatalystSerializable or provide a custom TypeSerializer.

Note that Connections are bi-directional. That is, messages can be send either by the client or the server. All messages must have a reply, even if the reply is null. Once the reply has been received from the other side of the connection, the returned CompletableFuture will be completed.

Connection implementations must guarantee that all reply futures will be completed in the same Catalyst thread.

Type Parameters:

T - The message type.

U - The reply type.

Parameters:

message - The message to send.

Returns:

A completable future to be completed with the response.

Throws:

NullPointerException - if message is null

IllegalStateException - if not called from a Catalyst thread

handler

<T,U> Connection handler(Class<T> type,
                         MessageHandler<T,U> handler)

Sets a message handler on the connection.

The message handler will be invoked each time a message of the given type is received from the other side of the connection. All messages are classified by type, and only one MessageHandler may be registered on the connection for any given type.

The message handler must return a CompletableFuture to be completed with the message reply. The reply value must be serializable via the configured Serializer instance. This means it must implement Serializable, Externalizable, or CatalystSerializable or provide a custom TypeSerializer.

Type Parameters:

T - The message type.

U - The reply type.

Parameters:

type - The message type for which to listen. This can be any class that is serializable by the configured Serializer instance.

handler - The type-specific message handler.

Throws:

NullPointerException - if type is null

IllegalStateException - if not called from a Catalyst thread

exceptionListener

Listener<Throwable> exceptionListener(Consumer<Throwable> listener)

Sets an exception listener on the connection.

In the event of an exception in the connection, the provided listener's Consumer.accept(Object) method will be invoked. To unregister the listener, simply Listener.close() the returned Listener.

Parameters:

listener - The exception listener.

Returns:

The connection.

Throws:

NullPointerException - if listener is null

closeListener

Listener<Connection> closeListener(Consumer<Connection> listener)

Sets a close listener on the connection.

The provided listener's Consumer.accept(Object) method will be invoked when the connection is closed. Note that a close event can be triggered via close() or by the Client or Server that created the connection.

Parameters:

listener - The close listener.

Returns:

The connection.

Throws:

NullPointerException - if listener is null

close

CompletableFuture<Void> close()

Closes the connection.

Once the connection is closed, no more messages can be sent or received by the connection. Any close listeners registered on the connection will be invoked, and the returned CompletableFuture will be completed once the connection has been closed.

Returns:

A completable future to be completed once the connection is closed.