Source code

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 atomic, single-writer, write-once, multiple-readers, ready-many type of objects.
029 * This is provided by releasing the CheckpointID for a checkpoint only upon commit of the checkpoint,
030 * and by preventing a checkpoint to be re-opened for writes.
031 * <p>
032 * Non-functional properties such as durability, availability, compression, garbage collection,
033 * quotas are left to the implementation.
034 * <p>
035 * This API is envisioned as the basic building block for a checkpoint service, on top of which richer
036 * interfaces can be layered (e.g., frameworks providing object-serialization, checkpoint metadata and
037 * provenance, etc.)
038 */
039public interface CheckpointService {
040
041  /**
042   * This method creates a checkpoint and provide a channel to write to it.
043   * The name/location of the checkpoint are unknown to the user as of this time, in fact,
044   * the CheckpointID is not released to the user until commit is called. This makes enforcing
045   * atomicity of writes easy.
046   *
047   * @return a CheckpointWriteChannel that can be used to write to the checkpoint
048   * @throws IOException
049   * @throws InterruptedException
050   */
051  CheckpointWriteChannel create() throws IOException, InterruptedException;
052
053  /**
054   * Used to finalize and existing checkpoint. It returns the CheckpointID that can be later
055   * used to access (read-only) this checkpoint. This guarantees atomicity of the checkpoint.
056   *
057   * @param channel the CheckpointWriteChannel to commit
058   * @return a CheckpointID
059   * @throws IOException
060   * @throws InterruptedException
061   */
062  CheckpointID commit(CheckpointWriteChannel channel) throws IOException, InterruptedException;
063
064  /**
065   * Dual to commit, it aborts the current checkpoint. Garbage collection choices are
066   * left to the implementation. The CheckpointID is not generated nor released to the
067   * user so the checkpoint is not accessible.
068   *
069   * @param channel the CheckpointWriteChannel to abort
070   * @throws IOException
071   * @throws InterruptedException
072   */
073  void abort(CheckpointWriteChannel channel) throws IOException, InterruptedException;
074
075  /**
076   * Given a CheckpointID returns a reading channel.
077   *
078   * @param checkpointId CheckpointID for the checkpoint to be opened
079   * @return a CheckpointReadChannel
080   * @throws IOException
081   * @throws InterruptedException
082   */
083  CheckpointReadChannel open(CheckpointID checkpointId) throws IOException, InterruptedException;
084
085  /**
086   * It discards an existing checkpoint identified by its CheckpointID.
087   *
088   * @param checkpointId CheckpointID for the checkpoint to be deleted
089   * @return a boolean confirming success of the deletion
090   * @throws IOException
091   * @throws InterruptedException
092   */
093  boolean delete(CheckpointID checkpointId) throws IOException, InterruptedException;
094
095  /**
096   * A channel to write to a checkpoint.
097   */
098  interface CheckpointWriteChannel extends WritableByteChannel {
099  }
100
101  /**
102   * A channel to read from a checkpoint.
103   */
104  interface CheckpointReadChannel extends ReadableByteChannel {
105  }
106}