io.hekate.messaging.operation.Subscribe Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hekate-core Show documentation
Java library for cluster communications and computing.
There is a newer version: 4.1.3
/*
 * Copyright 2020 The Hekate Project
 *
 * The Hekate Project licenses this file to you under the Apache License,
 * version 2.0 (the "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */

package io.hekate.messaging.operation;

import io.hekate.messaging.Message;
import io.hekate.messaging.MessageTimeoutException;
import io.hekate.messaging.MessagingChannel;
import io.hekate.messaging.MessagingChannelConfig;
import io.hekate.messaging.MessagingFutureException;
import io.hekate.messaging.loadbalance.LoadBalancer;
import io.hekate.messaging.retry.GenericRetryConfigurer;
import java.util.List;
import java.util.concurrent.TimeUnit;

/**
 * Subscribe operation.
 *
 * 
 * This interface represents a subscribe operation of a {@link 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:
 * 
 * 
 * Obtain an instance of this interface via the {@link MessagingChannel#newSubscribe(Object)} call
 * Set options (if needed):
 * 
 * {@link #withTimeout(long, TimeUnit) Operation Timeout}
 * {@link #withAffinity(Object) Affinity Key}
 * {@link #withRetry(RequestRetryConfigurer) Retry Policy}
 * 
 * 
 * Execute this operation via the {@link #submit(SubscribeCallback)}  method
 * Await for the execution result, if needed
 * 
 *
 * 
 * ${source: messaging/MessagingServiceJavadocTest.java#subscribe_operation}
 * 
 *
 * Shortcut Methods
 * 
 * {@link MessagingChannel} interface provides a set of synchronous and asynchronous shortcut methods for common use cases:
 * 
 * 
 * {@link MessagingChannel#subscribe(Object)}
 * {@link MessagingChannel#subscribe(Object, Object)} 
 * {@link MessagingChannel#subscribeAsync(Object, SubscribeCallback)}
 * {@link MessagingChannel#subscribeAsync(Object, Object, SubscribeCallback)} 
 * 
 *
 * @param  Message type.
 */
public interface Subscribe {
    /**
     * 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).
     * 
     *
     * 
     * {@link 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).
     * 
     *
     * @param affinity Affinity key.
     *
     * @return This instance.
     */
    Subscribe withAffinity(Object affinity);

    /**
     * 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 {@link MessageTimeoutException}.
     * 
     *
     * 
     * Specifying a negative or zero value disables the timeout check.
     * 
     *
     * @param timeout Timeout.
     * @param unit Unit.
     *
     * @return This instance.
     *
     * @see MessagingChannelConfig#setMessagingTimeout(long)
     */
    Subscribe withTimeout(long timeout, TimeUnit unit);

    /**
     * Retry policy.
     *
     * @param retry Retry policy.
     *
     * @return This instance.
     *
     * @see MessagingChannelConfig#setRetryPolicy(GenericRetryConfigurer)
     */
    Subscribe withRetry(RequestRetryConfigurer retry);

    /**
     * Asynchronously executes this operation.
     *
     * @param callback Callback.
     *
     * @return Future result of this operation.
     */
    SubscribeFuture submit(SubscribeCallback callback);

    /**
     * Synchronously collects all response chunks.
     *
     * 
     * This method submits the subscription operation and blocks util all {@link Message#partialReply(Object) 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).
     * 
     *
     * @return List of all {@link Message#partialReply(Object) partial responses} and the {@link Message#reply(Object) final response}.
     *
     * @throws MessagingFutureException if the operation fails.
     * @throws InterruptedException if the current thread is interrupted.
     */
    List responses() throws InterruptedException, MessagingFutureException;
}