Package io.hekate.messaging.operation

Interface Subscribe<T>

  • Type Parameters:
    T - Message type.
    public interface Subscribe<T>
    Subscribe operation.

    This interface represents a subscribe operation of a MessagingChannel. This operation submits a single request (subscription) and expects multiple response chunks (updates) to be returned by the receiver.

    Usage Example

    Typical use of this interface is:

    1. Obtain an instance of this interface via the MessagingChannel.newSubscribe(Object) call
    2. Set options (if needed):
    3. Execute this operation via the submit(SubscribeCallback) method
    4. Await for the execution result, if needed

    
MessagingChannel<String> channel = hekate.messaging().channel("example.channel", String.class);

SubscribeFuture<String> future = channel.newSubscribe("some-message") // Some dummy message.
    .withTimeout(3, TimeUnit.SECONDS) // Timeout.
    .withAffinity("100500") // Some dummy affinity key.
    .withRetry(retry -> retry
        .whileError(err -> err.isCausedBy(IOException.class)) // Only if I/O error.
        .withFixedDelay(100) // Delay between retries.
        .maxAttempts(3) // Retry up to 3 times.
        .alwaysReRoute() // Retry on different nodes.
    )
    // Execute and listen for responses.
    .submit((err, rsp) -> {
        if (rsp.isLastPart()) {
            System.out.println("Got the last response chunk: " + rsp.payload());
        } else {
            System.out.println("Got a response chunk: " + rsp.payload());
        }
    });

// Await and print the last response.
System.out.println("Last response: " + future.get());

    Shortcut Methods

    MessagingChannel interface provides a set of synchronous and asynchronous shortcut methods for common use cases:

    • Method Detail

      • withAffinity

        Subscribe<T> withAffinity​(Object affinity)
        Affinity key.

        Specifying an affinity key ensures that all operation with the same key will always be transmitted over the same network connection and will always be processed by the same thread (if the cluster topology doesn't change).

        LoadBalancer can also make use of the affinity key in order to perform consistent routing of messages among the cluster node. For example, the default load balancer makes sure that all messages, having the same key, are always routed to the same node (unless the cluster topology doesn't change).

        Parameters:
        affinity - Affinity key.
        Returns:
        This instance.

      • withTimeout

        Subscribe<T> withTimeout​(long timeout,
                         TimeUnit unit)
        Overrides the channel's default timeout value for this operation.

        If this operation can not complete at the specified timeout then this operation will end up in a MessageTimeoutException.

        Specifying a negative or zero value disables the timeout check.

        Parameters:
        timeout - Timeout.
        unit - Unit.
        Returns:
        This instance.
        See Also:
        MessagingChannelConfig.setMessagingTimeout(long)

      • submit

        SubscribeFuture<T> submit​(SubscribeCallback<T> callback)
        Asynchronously executes this operation.
        Parameters:
        callback - Callback.
        Returns:
        Future result of this operation.

      • responses

        List<T> responses()
           throws HekateException
        Synchronously collects all response chunks.

        This method submits the subscription operation and blocks util all responses) are received. All responses will be collected into an in-memory list, hence this method should be used with caution (mostly for testing purposes).

        Returns:
        List of all partial responses and the final response.
        Throws:
        HekateException - If operation failed.