cc.youchain.protocol.YOUChainService Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of core Show documentation
YOUChain Common library in JAVA.
There is a newer version: 1.1.5
package cc.youchain.protocol;

import java.io.IOException;
import java.util.concurrent.CompletableFuture;

import cc.youchain.protocol.core.Request;
import cc.youchain.protocol.core.Response;
import cc.youchain.protocol.websocket.events.Notification;
import io.reactivex.Flowable;

/**
 * Services API.
 */
public interface YOUChainService {

    /**
     * Perform a synchronous JSON-RPC request.
     *
     * @param request      request to perform
     * @param responseType class of a data item returned by the request
     * @param           type of a data item returned by the request
     * @return deserialized JSON-RPC response
     * @throws IOException thrown if failed to perform a request
     */
     T send(
            Request request, Class responseType) throws IOException;

    /**
     * Performs an asynchronous JSON-RPC request.
     *
     * @param request      request to perform
     * @param responseType class of a data item returned by the request
     * @param           type of a data item returned by the request
     * @return CompletableFuture that will be completed when a result is returned or if a
     * request has failed
     */
     CompletableFuture sendAsync(
            Request request, Class responseType);

    /**
     * Subscribe to a stream of notifications. A stream of notifications is opened by
     * by performing a specified JSON-RPC request and is closed by calling
     * the unsubscribe method. Different WebSocket implementations use different pair of
     * subscribe/unsubscribe methods.
     *
     * This method creates an Flowable that can be used to subscribe to new notifications.
     * When a client unsubscribes from this Flowable the service unsubscribes from
     * the underlying stream of events.
     *
     * @param request           JSON-RPC request that will be send to subscribe to a stream of
     *                          events
     * @param unsubscribeMethod method that will be called to unsubscribe from a
     *                          stream of notifications
     * @param responseType      class of incoming events objects in a stream
     * @param                type of incoming event objects
     * @return a {@link Flowable} instance that emits incoming events
     */
    > Flowable subscribe(
            Request request,
            String unsubscribeMethod,
            Class responseType);

    /**
     * Closes resources used by the service.
     *
     * @throws IOException thrown if a service failed to close all resources
     */
    void close() throws IOException;
}