bookkeeper-server/src/main/java/org/apache/bookkeeper/client/api/WriteHandle.java

/**
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF 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 org.apache.bookkeeper.client.api;

import io.netty.buffer.ByteBuf;
import io.netty.buffer.Unpooled;
import java.nio.ByteBuffer;
import java.util.concurrent.CompletableFuture;

import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public;
import org.apache.bookkeeper.common.annotation.InterfaceStability.Unstable;
import org.apache.bookkeeper.common.concurrent.FutureUtils;

/**
 * Provide write access to a ledger.
 *
 * @see WriteAdvHandle
 *
 * @since 4.6
 */
@Public
@Unstable
public interface WriteHandle extends ReadHandle, ForceableHandle {

    /**
     * Add entry asynchronously to an open ledger.
     *
     * @param data a bytebuf to be written. The bytebuf's reference count will be decremented by 1 after the
     *             completable future is returned
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @return an handle to the result, in case of success it will return the id of the newly appended entry
     */
    CompletableFuture<Long> appendAsync(ByteBuf data);

    /**
     * Add entry synchronously to an open ledger.
     *
     * @param data a bytebuf to be written. The bytebuf's reference count will be decremented by 1 after the
     *             call completes.
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @return the id of the newly appended entry
     */
    default long append(ByteBuf data) throws BKException, InterruptedException {
        return FutureUtils.<Long, BKException>result(appendAsync(data), BKException.HANDLER);
    }

    /**
     * Add entry asynchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *            do not reuse the buffer, bk-client will release it appropriately.
     * @return an handle to the result, in case of success it will return the id of the newly appended entry
     */
    default CompletableFuture<Long> appendAsync(ByteBuffer data) {
        return appendAsync(Unpooled.wrappedBuffer(data));
    }

    /**
     * Add entry synchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @return the id of the newly appended entry
     */
    default long append(ByteBuffer data) throws BKException, InterruptedException {
        return append(Unpooled.wrappedBuffer(data));
    }

    /**
     * Add an entry asynchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @return a completable future represents the add result, in case of success the future returns the entry id
     *         of this newly appended entry
     */
    default CompletableFuture<Long> appendAsync(byte[] data) {
        return appendAsync(Unpooled.wrappedBuffer(data));
    }

    /**
     * Add an entry synchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @return the entry id of this newly appended entry
     */
    default long append(byte[] data) throws BKException, InterruptedException {
        return append(Unpooled.wrappedBuffer(data));
    }

    /**
     * Add an entry asynchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @param offset the offset in the bytes array
     * @param length the length of the bytes to be appended
     * @return a completable future represents the add result, in case of success the future returns the entry id
     *         of this newly appended entry
     */
    default CompletableFuture<Long> appendAsync(byte[] data, int offset, int length) {
        return appendAsync(Unpooled.wrappedBuffer(data, offset, length));
    }

    /**
     * Add an entry synchronously to an open ledger.
     *
     * @param data array of bytes to be written
     *             do not reuse the buffer, bk-client will release it appropriately.
     * @param offset the offset in the bytes array
     * @param length the length of the bytes to be appended
     * @return the entry id of this newly appended entry
     */
    default long append(byte[] data, int offset, int length) throws BKException, InterruptedException {
        return append(Unpooled.wrappedBuffer(data, offset, length));
    }

    /**
     * Get the entry id of the last entry that has been enqueued for addition (but
     * may not have possibly been persisted to the ledger).
     *
     * @return the entry id of the last entry pushed or -1 if no entry has been pushed
     */
    long getLastAddPushed();

    /**
     * Asynchronous close the write handle, any adds in flight will return errors.
     *
     * <p>Closing a ledger will ensure that all clients agree on what the last
     * entry of the ledger is. Once the ledger has been closed, all reads from the
     * ledger will return the same set of entries.
     *
     * <p>The close operation can error if it finds conflicting metadata when it
     * tries to write to the metadata store. On close, the metadata state is set to
     * closed and lastEntry and length of the ledger are fixed in the metadata. A
     * conflict occurs if the metadata in the metadata store has a different value for
     * the lastEntry or length. If another process has updated the metadata, setting it
     * to closed, but have fixed the lastEntry and length to the same values as this
     * process is trying to write, the operation completes successfully.
     *
     * @return an handle to access the result of the operation
     */
    @Override
    CompletableFuture<Void> closeAsync();

    /**
     * Synchronous close the write handle, any adds in flight will return errors.
     *
     * <p>Closing a ledger will ensure that all clients agree on what the last
     * entry of the ledger is. Once the ledger has been closed, all reads from the
     * ledger will return the same set of entries.
     *
     * <p>The close operation can error if it finds conflicting metadata when it
     * tries to write to the metadata store. On close, the metadata state is set to
     * closed and lastEntry and length of the ledger are fixed in the metadata. A
     * conflict occurs if the metadata in the metadata store has a different value for
     * the lastEntry or length. If another process has updated the metadata, setting it
     * to closed, but have fixed the lastEntry and length to the same values as this
     * process is trying to write, the operation completes successfully.
     */
    @Override
    default void close() throws BKException, InterruptedException {
        FutureUtils.<Void, BKException>result(closeAsync(), BKException.HANDLER);
    }
}