content: package org.apache.lucene.index;
  
  /**
   * 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.
   */
  
  import java.io.IOException;
  import java.util.HashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.Map.Entry;
  
  import org.apache.lucene.document.Document;
  import org.apache.lucene.document.Field;
  import org.apache.lucene.document.Fieldable;
  import org.apache.lucene.document.Field.Index;
  import org.apache.lucene.document.Field.Store;
  import org.apache.lucene.index.IndexWriterConfig.OpenMode;
  import org.apache.lucene.store.Directory;
  import org.apache.lucene.store.LockObtainFailedException;
  import org.apache.lucene.util.Version;
  
  /**
   * A {@link SnapshotDeletionPolicy} which adds a persistence layer so that
   * snapshots can be maintained across the life of an application. The snapshots
   * are persisted in a {@link Directory} and are committed as soon as
   * {@link #snapshot(String)} or {@link #release(String)} is called.
   * <p>
   * <b>NOTE:</b> this class receives a {@link Directory} to persist the data into
   * a Lucene index. It is highly recommended to use a dedicated directory (and on
   * stable storage as well) for persisting the snapshots' information, and not
   * reuse the content index directory, or otherwise conflicts and index
   * corruptions will occur.
   * <p>
   * <b>NOTE:</b> you should call {@link #close()} when you're done using this
   * class for safetyness (it will close the {@link IndexWriter} instance used).
   */
  public class PersistentSnapshotDeletionPolicy extends SnapshotDeletionPolicy {
  
    // Used to validate that the given directory includes just one document w/ the
    // given ID field. Otherwise, it's not a valid Directory for snapshotting.
    private static final String SNAPSHOTS_ID = "$SNAPSHOTS_DOC$";
  
    // The index writer which maintains the snapshots metadata
    private final IndexWriter writer;
  
    /**
     * Reads the snapshots information from the given {@link Directory}. This
     * method can be used if the snapshots information is needed, however you
     * cannot instantiate the deletion policy (because e.g., some other process
     * keeps a lock on the snapshots directory).
     */
    public static Map<String, String> readSnapshotsInfo(Directory dir) throws IOException {
      IndexReader r = IndexReader.open(dir, true);
      Map<String, String> snapshots = new HashMap<String, String>();
      try {
        int numDocs = r.numDocs();
        // index is allowed to have exactly one document or 0.
        if (numDocs == 1) {
          Document doc = r.document(r.maxDoc() - 1);
          Field sid = doc.getField(SNAPSHOTS_ID);
          if (sid == null) {
            throw new IllegalStateException("directory is not a valid snapshots store!");
          }
          doc.removeField(SNAPSHOTS_ID);
          for (Fieldable f : doc.getFields()) {
            snapshots.put(f.name(), f.stringValue());
          }
        } else if (numDocs != 0) {
          throw new IllegalStateException(
              "should be at most 1 document in the snapshots directory: " + numDocs);
        }
      } finally {
        r.close();
      }
      return snapshots;
    }
    
    /**
     * {@link PersistentSnapshotDeletionPolicy} wraps another
     * {@link IndexDeletionPolicy} to enable flexible snapshotting.
     * 
     * @param primary
     *          the {@link IndexDeletionPolicy} that is used on non-snapshotted
     *          commits. Snapshotted commits, by definition, are not deleted until
     *          explicitly released via {@link #release(String)}.
     * @param dir
     *          the {@link Directory} which will be used to persist the snapshots
     *          information.
     * @param mode
     *          specifies whether a new index should be created, deleting all
     *          existing snapshots information (immediately), or open an existing
     *          index, initializing the class with the snapshots information.
     * @param matchVersion
     *          specifies the {@link Version} that should be used when opening the
     *          IndexWriter.
     */
    public PersistentSnapshotDeletionPolicy(IndexDeletionPolicy primary,
        Directory dir, OpenMode mode, Version matchVersion)
        throws CorruptIndexException, LockObtainFailedException, IOException {
      super(primary, null);
  
      // Initialize the index writer over the snapshot directory.
      writer = new IndexWriter(dir, new IndexWriterConfig(matchVersion, null).setOpenMode(mode));
      if (mode != OpenMode.APPEND) {
        // IndexWriter no longer creates a first commit on an empty Directory. So
        // if we were asked to CREATE*, call commit() just to be sure. If the
        // index contains information and mode is CREATE_OR_APPEND, it's a no-op.
        writer.commit();
      }
  
      try {
        // Initializes the snapshots information. This code should basically run
        // only if mode != CREATE, but if it is, it's no harm as we only open the
        // reader once and immediately close it.
        for (Entry<String, String> e : readSnapshotsInfo(dir).entrySet()) {
          registerSnapshotInfo(e.getKey(), e.getValue(), null);
        }
      } catch (RuntimeException e) {
        writer.close(); // don't leave any open file handles
        throw e;
      } catch (IOException e) {
        writer.close(); // don't leave any open file handles
        throw e;
      }
    }
  
    @Override
    public synchronized void onInit(List<? extends IndexCommit> commits)
    throws IOException {
      // super.onInit() needs to be called first to ensure that initialization
      // behaves as expected. The superclass, SnapshotDeletionPolicy, ensures
      // that any snapshot IDs with empty IndexCommits are released. Since this 
      // happens, this class needs to persist these changes.
      super.onInit(commits);
      persistSnapshotInfos(null, null);
    }
  
    /**
     * Snapshots the last commit using the given ID. Once this method returns, the
     * snapshot information is persisted in the directory.
     * 
     * @see SnapshotDeletionPolicy#snapshot(String)
     */
    @Override
    public synchronized IndexCommit snapshot(String id) throws IOException {
      checkSnapshotted(id);
      if (SNAPSHOTS_ID.equals(id)) {
        throw new IllegalArgumentException(id + " is reserved and cannot be used as a snapshot id");
      }
      persistSnapshotInfos(id, lastCommit.getSegmentsFileName());
      return super.snapshot(id);
    }
  
    /**
     * Deletes a snapshotted commit by ID. Once this method returns, the snapshot
     * information is committed to the directory.
     * 
     * @see SnapshotDeletionPolicy#release(String)
     */
    @Override
    public synchronized void release(String id) throws IOException {
      super.release(id);
      persistSnapshotInfos(null, null);
    }
  
    /** Closes the index which writes the snapshots to the directory. */
    public void close() throws CorruptIndexException, IOException {
      writer.close();
    }
  
    /**
     * Persists all snapshots information. If the given id and segment are not
     * null, it persists their information as well.
     */
    private void persistSnapshotInfos(String id, String segment) throws IOException {
      writer.deleteAll();
      Document d = new Document();
      d.add(new Field(SNAPSHOTS_ID, "", Store.YES, Index.NO));
      for (Entry<String, String> e : super.getSnapshots().entrySet()) {
        d.add(new Field(e.getKey(), e.getValue(), Store.YES, Index.NO));
      }
      if (id != null) {
        d.add(new Field(id, segment, Store.YES, Index.NO));
      }
      writer.addDocument(d);
      writer.commit();
    }
  
  }
  