com.ibm.etcd.client.lease.LeaseClient Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of etcd-java Show documentation
etcd3 java client and utilities
There is a newer version: 0.0.24
/*
 * Copyright 2017, 2018 IBM Corp. All Rights Reserved.
 *
 * Licensed 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 com.ibm.etcd.client.lease;

import java.util.concurrent.Executor;

import com.google.common.util.concurrent.ListenableFuture;
import com.ibm.etcd.client.FluentRequest;
import com.ibm.etcd.client.lease.PersistentLease.LeaseState;
import com.ibm.etcd.api.LeaseGrantRequest;
import com.ibm.etcd.api.LeaseGrantResponse;
import com.ibm.etcd.api.LeaseKeepAliveResponse;
import com.ibm.etcd.api.LeaseLeasesResponse;
import com.ibm.etcd.api.LeaseRevokeResponse;
import com.ibm.etcd.api.LeaseTimeToLiveResponse;

import io.grpc.stub.StreamObserver;

/**
 * Lease operations
 */
public interface LeaseClient {

    interface FluentGrantRequest extends FluentRequest {
        FluentGrantRequest leaseId(long leaseId);
    }

    interface FluentMaintainRequest {
        FluentMaintainRequest leaseId(long leaseId);
        FluentMaintainRequest keepAliveFreq(int frequencySecs);
        FluentMaintainRequest minTtl(int minTtlSecs);
        FluentMaintainRequest executor(Executor executor);
        FluentMaintainRequest permanent();
        PersistentLease start();
        PersistentLease start(StreamObserver observer);
    }

    /**
     * 
     * @param leaseId
     * @param ttlSecs
     * @return future for {@link LeaseGrantResponse}
     * 
     * @deprecated use the more flexible {@link #grant(long)}
     */
    @Deprecated
    ListenableFuture create(long leaseId, long ttlSecs);

    /**
     * 
     * @param ttlSecs
     * @return future for {@link LeaseGrantResponse}
     * 
     * @deprecated use the more flexible {@link #grant(long)}
     */
    @Deprecated
    default ListenableFuture create(long ttlSecs) {
        return create(0L, ttlSecs);
    }

    /**
     * Start a fluent grant request for "one time" lease establishment. If the lease
     * is to be kept alive for some period, consider creating a {@link PersistentLease}
     * via the {@link #maintain()} method.
     * 
     * @param ttlSecs
     */
    FluentGrantRequest grant(long ttlSecs);

    /**
     * 
     * @param leaseId
     * @return future for {@link LeaseRevokeResponse}
     */
    ListenableFuture revoke(long leaseId);

    /**
     * 
     * @param leaseId
     * @param ensureWithRetries if true, the asynchronous request will be retried
     *     continuously in the background after connection failures (between back-off pauses)
     * @return future for {@link LeaseRevokeResponse}
     */
    ListenableFuture revoke(long leaseId, boolean ensureWithRetries);

    /**
     * 
     * @param leaseId
     * @param includeKeys
     * @return future for {@link LeaseTimeToLiveResponse}
     */
    ListenableFuture ttl(long leaseId, boolean includeKeys);

    /**
     * 
     * @param leaseId
     * @return future for {@link LeaseTimeToLiveResponse}
     */
    default ListenableFuture ttl(long leaseId) {
        return ttl(leaseId, false);
    }

    /**
     * 
     * @param leaseId
     * @return future for {@link LeaseKeepAliveResponse}
     */
    ListenableFuture keepAliveOnce(long leaseId);

    /**
     * List all existing leases
     * 
     * Supported in versions >= 3.3 only
     * 
     * @return future for {@link LeaseLeasesResponse}
     */
    ListenableFuture list();

    /**
     * Maintain a "persistent" lease. This will keep a lease alive indefinitely,
     * creating or recreating it if it doesn't exist. It can be cancelled/revoked
     * by closing the returned {@link PersistentLease} object.
     * 

     * Specifying a lease id is optional. If not provided it will be server-assigned.
     * The return {@link PersistentLease} is also a future, which will be completed
     * with the lease id when it is granted/confirmed.
     * 
     * NOTE sole "ownership" of the lease is assumed - i.e. the lease should
     * not be revoked elsewhere.
     * 
     */
    FluentMaintainRequest maintain();
}