lucene-java-3.5.0/lucene/src/java/org/apache/lucene/util/TwoPhaseCommit.java

   1 package org.apache.lucene.util;
   2
   3 import java.io.IOException;
   4 import java.util.Map;
   5
   6 /**
   7  * Licensed to the Apache Software Foundation (ASF) under one or more
   8  * contributor license agreements.  See the NOTICE file distributed with
   9  * this work for additional information regarding copyright ownership.
  10  * The ASF licenses this file to You under the Apache License, Version 2.0
  11  * (the "License"); you may not use this file except in compliance with
  12  * the License.  You may obtain a copy of the License at
  13  *
  14  *     http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  * Unless required by applicable law or agreed to in writing, software
  17  * distributed under the License is distributed on an "AS IS" BASIS,
  18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  * See the License for the specific language governing permissions and
  20  * limitations under the License.
  21  */
  22
  23 /**
  24  * An interface for implementations that support 2-phase commit. You can use
  25  * {@link TwoPhaseCommitTool} to execute a 2-phase commit algorithm over several
  26  * {@link TwoPhaseCommit}s.
  27  *
  28  * @lucene.experimental
  29  */
  30 public interface TwoPhaseCommit {
  31
  32   /**
  33    * The first stage of a 2-phase commit. Implementations should do as much work
  34    * as possible in this method, but avoid actual committing changes. If the
  35    * 2-phase commit fails, {@link #rollback()} is called to discard all changes
  36    * since last successful commit.
  37    */
  38   public void prepareCommit() throws IOException;
  39
  40   /**
  41    * Like {@link #commit()}, but takes an additional commit data to be included
  42    * w/ the commit.
  43    * <p>
  44    * <b>NOTE:</b> some implementations may not support any custom data to be
  45    * included w/ the commit and may discard it altogether. Consult the actual
  46    * implementation documentation for verifying if this is supported.
  47    *
  48    * @see #prepareCommit()
  49    */
  50   public void prepareCommit(Map<String, String> commitData) throws IOException;
  51
  52   /**
  53    * The second phase of a 2-phase commit. Implementations should ideally do
  54    * very little work in this method (following {@link #prepareCommit()}, and
  55    * after it returns, the caller can assume that the changes were successfully
  56    * committed to the underlying storage.
  57    */
  58   public void commit() throws IOException;
  59
  60   /**
  61    * Like {@link #commit()}, but takes an additional commit data to be included
  62    * w/ the commit.
  63    *
  64    * @see #commit()
  65    * @see #prepareCommit(Map)
  66    */
  67   public void commit(Map<String, String> commitData) throws IOException;
  68
  69   /**
  70    * Discards any changes that have occurred since the last commit. In a 2-phase
  71    * commit algorithm, where one of the objects failed to {@link #commit()} or
  72    * {@link #prepareCommit()}, this method is used to roll all other objects
  73    * back to their previous state.
  74    */
  75   public void rollback() throws IOException;
  76
  77 }