com.pushtechnology.diffusion.client.callbacks.Registration Maven / Gradle / Ivy

Go to download
/*******************************************************************************
 * Copyright (c) 2023 DiffusionData Ltd., All Rights Reserved.
 *
 * Use is subject to license terms.
 *
 * NOTICE: All information contained herein is, and remains the
 * property of Push Technology. The intellectual and technical
 * concepts contained herein are proprietary to Push Technology and
 * may be covered by U.S. and Foreign Patents, patents in process, and
 * are protected by trade secret or copyright law.
 *******************************************************************************/
package com.pushtechnology.diffusion.client.callbacks;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;

import com.pushtechnology.diffusion.client.session.SessionClosedException;

/**
 * A reference to a registered handler.
 * 
 * Such a handler reference is provided whenever a handler with a server side
 * presence is registered.
 *
 * @author DiffusionData Limited
 * @since 5.1
 */
public interface Registration {

    /**
     * Request that the handler is unregistered from the server.
     * 

     * After the handler is unregistered, the handler's {@code onClose} method
     * will be called.
     *
     * 

     * A handler can only be unregistered once. A given instance will return the
     * same CompletableFuture if this method is called more than once.
     *
     * @return a CompletableFuture that completes when a response is received
     *         from the server.
     *
     *         

     *         If the task completes successfully, the CompletableFuture result
     *         will be null. The result type is any rather than Void to provide
     *         forward compatibility with future iterations of this API that may
     *         provide a non-null result with a more specific result type.
     *
     *         

     *         Otherwise, the CompletableFuture will complete exceptionally with
     *         a {@link CompletionException}. Common reasons for failure, listed
     *         by the exception reported as the
     *         {@link CompletionException#getCause() cause}, include:
     *
     *         

     *         {@link SessionClosedException} – if the session is
     *         closed.
     *         
     */
    CompletableFuture close();
}