Package org.forgerock.opendj.io

Interface RxSocket<M>

  • Type Parameters:
    M - The type of messages transferred by the socket.
    All Superinterfaces:
    AutoCloseable, Closeable
    All Known Subinterfaces:
    LdapSocket
    All Known Implementing Classes:
    SaslRxSocket, SslRxSocket, SwitchableRxSocket, TransformedRxSocket
    public interface RxSocket<M>
extends Closeable
    A transport agnostic reactive socket abstraction. Reactive sockets are role agnostic and may be used for implementing clients and servers. Implementations are responsible for ensuring that network data is sent and received without any additional processing and are not responsible for implementing SSL or SASL security layers.

    • Field Detail

      • LOCAL_CLOSE

        static final EOFException LOCAL_CLOSE
        Thrown by read and write when the socket is closed locally.

      • REMOTE_CLOSE

        static final EOFException REMOTE_CLOSE
        Thrown by read and write when the socket is closed remotely.

    • Method Detail

      • read

        @CheckReturnValue
Single<M> read​(Supplier<M> bufferSupplier)
        Returns a "cold" Single which will read the next message from the network each time it is subscribed. Read operations cannot be cancelled: cancelling/disposing a subscription has no effect, and will not close the underlying socket.

        Socket implementations must buffer incoming messages until they are read. Note that invoking this method multiple times returns the same Single instance. The returned Single will not allow multiple concurrent subscriptions as this will result in non-deterministic behavior. Attempts to have multiple concurrent subscriptions will result in an IllegalStateException.

        Subscribers will be notified when the socket is closed through SingleObserver.onError(Throwable) with the corresponding IOException providing the reason for the disconnection. In particular, if the socket is closed locally via close() then it will be notified with LOCAL_CLOSE, if it is closed locally via closeWithReason(java.lang.Throwable) then it will be notified using the provided exception and finally, if it is closed remotely by the peer, then it will be notified using REMOTE_CLOSE. Low-level network transports should return a SocketTimeoutException for communicating any network timeouts. Application layers may return exceptions which are more closely aligned to their APIs.

        Parameters:
        bufferSupplier - An optional buffer supplier which may be used by the transport to reduce copying between transport layers. Use null when the transport does not support buffer suppliers or if the transport should allocate its own buffer. Note that the buffer supplier may be called multiple times in order to complete a single read.
        Returns:
        A "cold" Single which will be signalled once the read operation completes or fails.

      • write

        @CheckReturnValue
Completable write​(M message)
        Returns a "cold" Completable which will write the provided message to the network each time it is subscribed. Write operations cannot be cancelled reliably, as a consequence cancelling/disposing a subscription has no effect.

        Subscribers will be notified when the socket is closed through CompletableObserver.onError(Throwable) with the corresponding IOException providing the reason for the disconnection. In particular, if the socket is closed locally via close() then it will be notified with LOCAL_CLOSE, if it is closed locally via closeWithReason(java.lang.Throwable) then it will be notified using the provided exception and finally, if it is closed remotely by the peer, then it will be notified using REMOTE_CLOSE. Low-level network transports should return a SocketTimeoutException for communicating any network timeouts. Application layers may return exceptions which are more closely aligned to their APIs.

        This method is thread-safe, atomic and ordered with respect to other write attempts. In particular, consecutive writes will be performed in the order in which they are subscribed.

        Parameters:
        message - The message to be written to the network.
        Returns:
        A "cold" Completable which will be signalled once the write operation completes or fails.

      • getLocalAddress

        InetSocketAddress getLocalAddress()
        Returns the InetSocketAddress associated with the local system. For logging purposes the local address can still be retrieved after the socket has been closed.
        Returns:
        The InetSocketAddress associated with the local system.

      • getRemoteAddress

        InetSocketAddress getRemoteAddress()
        Returns the InetSocketAddress associated with the remote system. For logging purposes the remote address can still be retrieved after the socket has been closed.
        Returns:
        The InetSocketAddress associated with the remote system.

      • close

        default void close()
        Asynchronously closes this socket. Disconnecting the socket may cause any active or future read(java.util.function.Supplier<M>) or write(M) operations to fail with an EOFException. Messages which have not yet been sent may be dropped, although implementations should generally attempt to flush any pending unwritten messages first.

        NOTE: this method returns immediately: flushing and closing will be performed in the background.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable

      • closeWithReason

        @CheckReturnValue
Completable closeWithReason​(Throwable reason)
        Returns a "hot" Completable which will close this socket when it is subscribed for the first time.

        Disconnecting the socket may cause any active or future read(java.util.function.Supplier<M>) or write(M) operations to fail with the provided Throwable. Messages which have not yet been sent may be dropped, although implementations should generally attempt to flush any pending unwritten messages first.

        NOTE: this method is idempotent. The close reason cannot be changed once it has been set.

        Parameters:
        reason - The reason which will be forwarded to any active or future read(java.util.function.Supplier<M>) or write(M) operations.
        Returns:
        A "hot" Completable which will be signalled once the socket is closed. It will never fail.