| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| package io.v.v23.syncbase.nosql; |
| |
| import com.google.common.util.concurrent.ListenableFuture; |
| |
| import io.v.v23.context.VContext; |
| import io.v.v23.services.syncbase.nosql.BlobRef; |
| |
| import java.io.OutputStream; |
| |
| import javax.annotation.CheckReturnValue; |
| |
| /** |
| * Interface for writing data blobs. |
| */ |
| public interface BlobWriter { |
| /** |
| * Returns a reference to the blob being written. |
| */ |
| BlobRef getRef(); |
| |
| /** |
| * Returns an {@link OutputStream} for writing data to this blob. |
| * <p> |
| * You should be aware of the following constraints on the returned {@link OutputStream}: |
| * <p><ul> |
| * <li> it doesn't implement {@link OutputStream#flush}: the only way to ensure that the |
| * data is flushed is to call {@link OutputStream#close}. |
| * <li> if the blob is {@link #commit committed}, subsequent {@link OutputStream} |
| * {@link OutputStream#write writes} are guaranteed <strong>NOT</strong> to be applied |
| * to the blob; however, they might "succeed", i.e., they may not throw an |
| * {@link java.io.IOException}. Any subsequent {@link OutputStream#close} operation |
| * on the {@link OutputStream} are guaranteed to fail immediately. |
| * <li> likewise, if the context used to create the {@link OutputStream} is |
| * {@link io.v.v23.context.VContext#cancel canceled}, subsequent |
| * {@link OutputStream} {@link OutputStream#write writes} are guaranteed |
| * <strong>NOT</strong> to be applied to the blob; however, they might "succeed", |
| * i.e., they may not throw an {@link java.io.IOException}. Any subsequent |
| * {@link OutputStream#close} operation on the {@link OutputStream} are guaranteed |
| * to fail immediately. |
| * </ul><p> |
| * |
| * If invoked on a committed blob, it is possible for this method to "succeed", i.e., to return |
| * an {@link OutputStream}. However, the first subsequent {@link OutputStream#close} invocation |
| * on that {@link OutputStream} will fail. |
| * <p> |
| * This method may be called multiple times, e.g., to resume a failed write. If resuming a |
| * failed write, the most accurate measure of write progress is obtained by calling |
| * {@link #size}: relying on a write progress of the returned {@link OutputStream} would be |
| * a mistake (see comments about the {@link OutputStream#write write} constraints above). |
| * <p> |
| * Please be aware that {@link OutputStream} operations are blocking. |
| * |
| * @param ctx vanadium context |
| * @return an {@link OutputStream} used for writing data to this blob |
| */ |
| OutputStream stream(VContext ctx); |
| |
| /** |
| * Marks the blob as immutable. |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param ctx vanadium context |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> commit(VContext ctx); |
| |
| /** |
| * Deletes the blob locally (committed or uncommitted). |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * <p> |
| * NOT YET IMPLEMENTED. |
| * |
| * @param ctx vanadium context |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> delete(VContext ctx); |
| |
| /** |
| * Returns the {@link ListenableFuture} whose result is the size of the blob. |
| * <p> |
| * If the blob hasn't yet been {@link #commit commit}ed, returns the number of bytes |
| * written so far. |
| * <p> |
| * This is the only accurate measure of a write progress: relying on a write progress of |
| * {@link OutputStream} returned by {@link #stream} would be a mistake (see comments |
| * on {@link #stream}). |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param ctx vanadium context |
| */ |
| @CheckReturnValue |
| ListenableFuture<Long> size(VContext ctx); |
| } |