public interface 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.
| 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.
|
UUID 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.
<T,U> CompletableFuture<U> send(T message)
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.
T - The message type.U - The reply type.message - The message to send.NullPointerException - if message is nullIllegalStateException - if not called from a Catalyst thread<T,U> Connection handler(Class<T> type, MessageHandler<T,U> handler)
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.
T - The message type.U - The reply type.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.NullPointerException - if type is nullIllegalStateException - if not called from a Catalyst threadListener<Throwable> exceptionListener(Consumer<Throwable> listener)
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.
listener - The exception listener.NullPointerException - if listener is nullListener<Connection> closeListener(Consumer<Connection> listener)
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.
listener - The close listener.NullPointerException - if listener is nullCompletableFuture<Void> close()
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.
Copyright © 2013–2015. All rights reserved.