001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.io.checkpoint;
020
021import java.io.IOException;
022import java.nio.channels.ReadableByteChannel;
023import java.nio.channels.WritableByteChannel;
024
025/**
026 * The CheckpointService provides a simple API to store and retrieve the state of a task.
027 * <p>
028 * Checkpoints are assumed to be atomic, single-writer, write-once, multiple-readers, ready-many type of objects.
029 *
030 * To ensure this, any implementation of this interface must.
031 * 1) Return a CheckpointID to a client only
032 *    upon the successful {@link #commit(CheckpointWriteChannel) commit} of the checkpoint.
033 * 2) Prevent any checkpoint from being re-opened for writes.
034 * <p>
035 * Non-functional properties such as durability, availability, compression, garbage collection, and
036 * quotas are left to the implementation.
037 * <p>
038 * This API is envisioned as the basic building block for a checkpoint service, on top of which richer
039 * interfaces can be layered (e.g., frameworks providing object-serialization, checkpoint metadata and
040 * provenance, etc.)
041 */
042public interface CheckpointService {
043
044  /**
045   * Creates a checkpoint and provides a channel to write to it.
046   * The name/location of the checkpoint are unknown to the user as of this time, in fact,
047   * the CheckpointID is not released to the user until {@link #commit(CheckpointWriteChannel) commit} is called.
048   * This makes enforcing atomicity of writes easy.
049   *
050   * @return a CheckpointWriteChannel that can be used to write to the checkpoint
051   * @throws IOException
052   * @throws InterruptedException
053   */
054  CheckpointWriteChannel create() throws IOException, InterruptedException;
055
056  /**
057   * Closes an existing checkpoint for writes and returns the CheckpointID that can be later
058   * used to get the read-only access to this checkpoint.
059   *
060   * Implementation  is supposed to return the CheckpointID to the caller only on the
061   * successful completion of checkpoint to guarantee atomicity of the checkpoint.
062   *
063   * @param channel the CheckpointWriteChannel to commit
064   * @return a CheckpointID
065   * @throws IOException
066   * @throws InterruptedException
067   */
068  CheckpointID commit(CheckpointWriteChannel channel) throws IOException, InterruptedException;
069
070  /**
071   * Aborts the current checkpoint. Garbage collection choices are
072   * left to the implementation. The CheckpointID is neither generated nor released to the
073   * client so the checkpoint is not accessible.
074   *
075   * @param channel the CheckpointWriteChannel to abort
076   * @throws IOException
077   * @throws InterruptedException
078   */
079  void abort(CheckpointWriteChannel channel) throws IOException, InterruptedException;
080
081  /**
082   * Returns a reading channel to a checkpoint identified by the CheckpointID.
083   *
084   * @param checkpointId CheckpointID for the checkpoint to be opened
085   * @return a CheckpointReadChannel
086   * @throws IOException
087   * @throws InterruptedException
088   */
089  CheckpointReadChannel open(CheckpointID checkpointId) throws IOException, InterruptedException;
090
091  /**
092   * Discards an existing checkpoint identified by its CheckpointID.
093   *
094   * @param checkpointId CheckpointID for the checkpoint to be deleted
095   * @return a boolean confirming success of the deletion
096   * @throws IOException
097   * @throws InterruptedException
098   */
099  boolean delete(CheckpointID checkpointId) throws IOException, InterruptedException;
100
101  /**
102   * A channel to write to a checkpoint.
103   */
104  interface CheckpointWriteChannel extends WritableByteChannel {
105  }
106
107  /**
108   * A channel to read from a checkpoint.
109   */
110  interface CheckpointReadChannel extends ReadableByteChannel {
111  }
112}