--- /dev/null
+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 org.apache.lucene.store.Directory;
+import org.apache.lucene.util.SetOnce;
+import org.apache.lucene.util.SetOnce.AlreadySetException;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Map;
+
+/**
+ * <p>Expert: a MergePolicy determines the sequence of
+ * primitive merge operations.</p>
+ *
+ * <p>Whenever the segments in an index have been altered by
+ * {@link IndexWriter}, either the addition of a newly
+ * flushed segment, addition of many segments from
+ * addIndexes* calls, or a previous merge that may now need
+ * to cascade, {@link IndexWriter} invokes {@link
+ * #findMerges} to give the MergePolicy a chance to pick
+ * merges that are now required. This method returns a
+ * {@link MergeSpecification} instance describing the set of
+ * merges that should be done, or null if no merges are
+ * necessary. When IndexWriter.forceMerge is called, it calls
+ * {@link #findForcedMerges(SegmentInfos,int,Map)} and the MergePolicy should
+ * then return the necessary merges.</p>
+ *
+ * <p>Note that the policy can return more than one merge at
+ * a time. In this case, if the writer is using {@link
+ * SerialMergeScheduler}, the merges will be run
+ * sequentially but if it is using {@link
+ * ConcurrentMergeScheduler} they will be run concurrently.</p>
+ *
+ * <p>The default MergePolicy is {@link
+ * TieredMergePolicy}.</p>
+ *
+ * @lucene.experimental
+ */
+
+public abstract class MergePolicy implements java.io.Closeable {
+
+ /** OneMerge provides the information necessary to perform
+ * an individual primitive merge operation, resulting in
+ * a single new segment. The merge spec includes the
+ * subset of segments to be merged as well as whether the
+ * new segment should use the compound file format. */
+
+ public static class OneMerge {
+
+ SegmentInfo info; // used by IndexWriter
+ boolean registerDone; // used by IndexWriter
+ long mergeGen; // used by IndexWriter
+ boolean isExternal; // used by IndexWriter
+ int maxNumSegments = -1; // used by IndexWriter
+ public long estimatedMergeBytes; // used by IndexWriter
+ List<SegmentReader> readers; // used by IndexWriter
+ List<SegmentReader> readerClones; // used by IndexWriter
+ public final List<SegmentInfo> segments;
+ public final int totalDocCount;
+ boolean aborted;
+ Throwable error;
+ boolean paused;
+
+ public OneMerge(List<SegmentInfo> segments) {
+ if (0 == segments.size())
+ throw new RuntimeException("segments must include at least one segment");
+ // clone the list, as the in list may be based off original SegmentInfos and may be modified
+ this.segments = new ArrayList<SegmentInfo>(segments);
+ int count = 0;
+ for(SegmentInfo info : segments) {
+ count += info.docCount;
+ }
+ totalDocCount = count;
+ }
+
+ /** Record that an exception occurred while executing
+ * this merge */
+ synchronized void setException(Throwable error) {
+ this.error = error;
+ }
+
+ /** Retrieve previous exception set by {@link
+ * #setException}. */
+ synchronized Throwable getException() {
+ return error;
+ }
+
+ /** Mark this merge as aborted. If this is called
+ * before the merge is committed then the merge will
+ * not be committed. */
+ synchronized void abort() {
+ aborted = true;
+ notifyAll();
+ }
+
+ /** Returns true if this merge was aborted. */
+ synchronized boolean isAborted() {
+ return aborted;
+ }
+
+ synchronized void checkAborted(Directory dir) throws MergeAbortedException {
+ if (aborted) {
+ throw new MergeAbortedException("merge is aborted: " + segString(dir));
+ }
+
+ while (paused) {
+ try {
+ // In theory we could wait() indefinitely, but we
+ // do 1000 msec, defensively
+ wait(1000);
+ } catch (InterruptedException ie) {
+ throw new RuntimeException(ie);
+ }
+ if (aborted) {
+ throw new MergeAbortedException("merge is aborted: " + segString(dir));
+ }
+ }
+ }
+
+ synchronized public void setPause(boolean paused) {
+ this.paused = paused;
+ if (!paused) {
+ // Wakeup merge thread, if it's waiting
+ notifyAll();
+ }
+ }
+
+ synchronized public boolean getPause() {
+ return paused;
+ }
+
+ public String segString(Directory dir) {
+ StringBuilder b = new StringBuilder();
+ final int numSegments = segments.size();
+ for(int i=0;i<numSegments;i++) {
+ if (i > 0) b.append(' ');
+ b.append(segments.get(i).toString(dir, 0));
+ }
+ if (info != null)
+ b.append(" into ").append(info.name);
+ if (maxNumSegments != -1)
+ b.append(" [maxNumSegments=" + maxNumSegments + "]");
+ if (aborted) {
+ b.append(" [ABORTED]");
+ }
+ return b.toString();
+ }
+
+ /**
+ * Returns the total size in bytes of this merge. Note that this does not
+ * indicate the size of the merged segment, but the input total size.
+ * */
+ public long totalBytesSize() throws IOException {
+ long total = 0;
+ for (SegmentInfo info : segments) {
+ total += info.sizeInBytes(true);
+ }
+ return total;
+ }
+
+ /**
+ * Returns the total number of documents that are included with this merge.
+ * Note that this does not indicate the number of documents after the merge.
+ * */
+ public int totalNumDocs() throws IOException {
+ int total = 0;
+ for (SegmentInfo info : segments) {
+ total += info.docCount;
+ }
+ return total;
+ }
+ }
+
+ /**
+ * A MergeSpecification instance provides the information
+ * necessary to perform multiple merges. It simply
+ * contains a list of {@link OneMerge} instances.
+ */
+
+ public static class MergeSpecification {
+
+ /**
+ * The subset of segments to be included in the primitive merge.
+ */
+
+ public final List<OneMerge> merges = new ArrayList<OneMerge>();
+
+ public void add(OneMerge merge) {
+ merges.add(merge);
+ }
+
+ public String segString(Directory dir) {
+ StringBuilder b = new StringBuilder();
+ b.append("MergeSpec:\n");
+ final int count = merges.size();
+ for(int i=0;i<count;i++)
+ b.append(" ").append(1 + i).append(": ").append(merges.get(i).segString(dir));
+ return b.toString();
+ }
+ }
+
+ /** Exception thrown if there are any problems while
+ * executing a merge. */
+ public static class MergeException extends RuntimeException {
+ private Directory dir;
+
+ public MergeException(String message, Directory dir) {
+ super(message);
+ this.dir = dir;
+ }
+
+ public MergeException(Throwable exc, Directory dir) {
+ super(exc);
+ this.dir = dir;
+ }
+ /** Returns the {@link Directory} of the index that hit
+ * the exception. */
+ public Directory getDirectory() {
+ return dir;
+ }
+ }
+
+ public static class MergeAbortedException extends IOException {
+ public MergeAbortedException() {
+ super("merge is aborted");
+ }
+ public MergeAbortedException(String message) {
+ super(message);
+ }
+ }
+
+ protected final SetOnce<IndexWriter> writer;
+
+ /**
+ * Creates a new merge policy instance. Note that if you intend to use it
+ * without passing it to {@link IndexWriter}, you should call
+ * {@link #setIndexWriter(IndexWriter)}.
+ */
+ public MergePolicy() {
+ writer = new SetOnce<IndexWriter>();
+ }
+
+ /**
+ * Sets the {@link IndexWriter} to use by this merge policy. This method is
+ * allowed to be called only once, and is usually set by IndexWriter. If it is
+ * called more than once, {@link AlreadySetException} is thrown.
+ *
+ * @see SetOnce
+ */
+ public void setIndexWriter(IndexWriter writer) {
+ this.writer.set(writer);
+ }
+
+ /**
+ * Determine what set of merge operations are now necessary on the index.
+ * {@link IndexWriter} calls this whenever there is a change to the segments.
+ * This call is always synchronized on the {@link IndexWriter} instance so
+ * only one thread at a time will call this method.
+ *
+ * @param segmentInfos
+ * the total set of segments in the index
+ */
+ public abstract MergeSpecification findMerges(SegmentInfos segmentInfos)
+ throws CorruptIndexException, IOException;
+
+ /**
+ * Determine what set of merge operations is necessary in
+ * order to merge to <= the specified segment count. {@link IndexWriter} calls this when its
+ * {@link IndexWriter#forceMerge} method is called. This call is always
+ * synchronized on the {@link IndexWriter} instance so only one thread at a
+ * time will call this method.
+ *
+ * @param segmentInfos
+ * the total set of segments in the index
+ * @param maxSegmentCount
+ * requested maximum number of segments in the index (currently this
+ * is always 1)
+ * @param segmentsToMerge
+ * contains the specific SegmentInfo instances that must be merged
+ * away. This may be a subset of all
+ * SegmentInfos. If the value is True for a
+ * given SegmentInfo, that means this segment was
+ * an original segment present in the
+ * to-be-merged index; else, it was a segment
+ * produced by a cascaded merge.
+ */
+ public abstract MergeSpecification findForcedMerges(
+ SegmentInfos segmentInfos, int maxSegmentCount, Map<SegmentInfo,Boolean> segmentsToMerge)
+ throws CorruptIndexException, IOException;
+
+ /**
+ * Determine what set of merge operations is necessary in order to expunge all
+ * deletes from the index.
+ *
+ * @param segmentInfos
+ * the total set of segments in the index
+ */
+ public abstract MergeSpecification findForcedDeletesMerges(
+ SegmentInfos segmentInfos) throws CorruptIndexException, IOException;
+
+ /**
+ * Release all resources for the policy.
+ */
+ public abstract void close();
+
+ /** Returns true if a new segment (regardless of its origin) should use the compound file format. */
+ public abstract boolean useCompoundFile(SegmentInfos segments, SegmentInfo newSegment) throws IOException;
+}