lucene-java-3.5.0/lucene/src/java/org/apache/lucene/index/MergePolicy.java

   1 package org.apache.lucene.index;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import org.apache.lucene.store.Directory;
  21 import org.apache.lucene.util.SetOnce;
  22 import org.apache.lucene.util.SetOnce.AlreadySetException;
  23
  24 import java.io.IOException;
  25 import java.util.List;
  26 import java.util.ArrayList;
  27 import java.util.Map;
  28
  29 /**
  30  * <p>Expert: a MergePolicy determines the sequence of
  31  * primitive merge operations.</p>
  32  *
  33  * <p>Whenever the segments in an index have been altered by
  34  * {@link IndexWriter}, either the addition of a newly
  35  * flushed segment, addition of many segments from
  36  * addIndexes* calls, or a previous merge that may now need
  37  * to cascade, {@link IndexWriter} invokes {@link
  38  * #findMerges} to give the MergePolicy a chance to pick
  39  * merges that are now required.  This method returns a
  40  * {@link MergeSpecification} instance describing the set of
  41  * merges that should be done, or null if no merges are
  42  * necessary.  When IndexWriter.forceMerge is called, it calls
  43  * {@link #findForcedMerges(SegmentInfos,int,Map)} and the MergePolicy should
  44  * then return the necessary merges.</p>
  45  *
  46  * <p>Note that the policy can return more than one merge at
  47  * a time.  In this case, if the writer is using {@link
  48  * SerialMergeScheduler}, the merges will be run
  49  * sequentially but if it is using {@link
  50  * ConcurrentMergeScheduler} they will be run concurrently.</p>
  51  *
  52  * <p>The default MergePolicy is {@link
  53  * TieredMergePolicy}.</p>
  54  *
  55  * @lucene.experimental
  56  */
  57
  58 public abstract class MergePolicy implements java.io.Closeable {
  59
  60   /** OneMerge provides the information necessary to perform
  61    *  an individual primitive merge operation, resulting in
  62    *  a single new segment.  The merge spec includes the
  63    *  subset of segments to be merged as well as whether the
  64    *  new segment should use the compound file format. */
  65
  66   public static class OneMerge {
  67
  68     SegmentInfo info;               // used by IndexWriter
  69     boolean registerDone;           // used by IndexWriter
  70     long mergeGen;                  // used by IndexWriter
  71     boolean isExternal;             // used by IndexWriter
  72     int maxNumSegments = -1;        // used by IndexWriter
  73     public long estimatedMergeBytes;       // used by IndexWriter
  74     List<SegmentReader> readers;        // used by IndexWriter
  75     List<SegmentReader> readerClones;   // used by IndexWriter
  76     public final List<SegmentInfo> segments;
  77     public final int totalDocCount;
  78     boolean aborted;
  79     Throwable error;
  80     boolean paused;
  81
  82     public OneMerge(List<SegmentInfo> segments) {
  83       if (0 == segments.size())
  84         throw new RuntimeException("segments must include at least one segment");
  85       // clone the list, as the in list may be based off original SegmentInfos and may be modified
  86       this.segments = new ArrayList<SegmentInfo>(segments);
  87       int count = 0;
  88       for(SegmentInfo info : segments) {
  89         count += info.docCount;
  90       }
  91       totalDocCount = count;
  92     }
  93
  94     /** Record that an exception occurred while executing
  95      *  this merge */
  96     synchronized void setException(Throwable error) {
  97       this.error = error;
  98     }
  99
 100     /** Retrieve previous exception set by {@link
 101      *  #setException}. */
 102     synchronized Throwable getException() {
 103       return error;
 104     }
 105
 106     /** Mark this merge as aborted.  If this is called
 107      *  before the merge is committed then the merge will
 108      *  not be committed. */
 109     synchronized void abort() {
 110       aborted = true;
 111       notifyAll();
 112     }
 113
 114     /** Returns true if this merge was aborted. */
 115     synchronized boolean isAborted() {
 116       return aborted;
 117     }
 118
 119     synchronized void checkAborted(Directory dir) throws MergeAbortedException {
 120       if (aborted) {
 121         throw new MergeAbortedException("merge is aborted: " + segString(dir));
 122       }
 123
 124       while (paused) {
 125         try {
 126           // In theory we could wait() indefinitely, but we
 127           // do 1000 msec, defensively
 128           wait(1000);
 129         } catch (InterruptedException ie) {
 130           throw new RuntimeException(ie);
 131         }
 132         if (aborted) {
 133           throw new MergeAbortedException("merge is aborted: " + segString(dir));
 134         }
 135       }
 136     }
 137
 138     synchronized public void setPause(boolean paused) {
 139       this.paused = paused;
 140       if (!paused) {
 141         // Wakeup merge thread, if it's waiting
 142         notifyAll();
 143       }
 144     }
 145
 146     synchronized public boolean getPause() {
 147       return paused;
 148     }
 149
 150     public String segString(Directory dir) {
 151       StringBuilder b = new StringBuilder();
 152       final int numSegments = segments.size();
 153       for(int i=0;i<numSegments;i++) {
 154         if (i > 0) b.append(' ');
 155         b.append(segments.get(i).toString(dir, 0));
 156       }
 157       if (info != null)
 158         b.append(" into ").append(info.name);
 159       if (maxNumSegments != -1)
 160         b.append(" [maxNumSegments=" + maxNumSegments + "]");
 161       if (aborted) {
 162         b.append(" [ABORTED]");
 163       }
 164       return b.toString();
 165     }
 166
 167     /**
 168      * Returns the total size in bytes of this merge. Note that this does not
 169      * indicate the size of the merged segment, but the input total size.
 170      * */
 171     public long totalBytesSize() throws IOException {
 172       long total = 0;
 173       for (SegmentInfo info : segments) {
 174         total += info.sizeInBytes(true);
 175       }
 176       return total;
 177     }
 178
 179     /**
 180      * Returns the total number of documents that are included with this merge.
 181      * Note that this does not indicate the number of documents after the merge.
 182      * */
 183     public int totalNumDocs() throws IOException {
 184       int total = 0;
 185       for (SegmentInfo info : segments) {
 186         total += info.docCount;
 187       }
 188       return total;
 189     }
 190   }
 191
 192   /**
 193    * A MergeSpecification instance provides the information
 194    * necessary to perform multiple merges.  It simply
 195    * contains a list of {@link OneMerge} instances.
 196    */
 197
 198   public static class MergeSpecification {
 199
 200     /**
 201      * The subset of segments to be included in the primitive merge.
 202      */
 203
 204     public final List<OneMerge> merges = new ArrayList<OneMerge>();
 205
 206     public void add(OneMerge merge) {
 207       merges.add(merge);
 208     }
 209
 210     public String segString(Directory dir) {
 211       StringBuilder b = new StringBuilder();
 212       b.append("MergeSpec:\n");
 213       final int count = merges.size();
 214       for(int i=0;i<count;i++)
 215         b.append("  ").append(1 + i).append(": ").append(merges.get(i).segString(dir));
 216       return b.toString();
 217     }
 218   }
 219
 220   /** Exception thrown if there are any problems while
 221    *  executing a merge. */
 222   public static class MergeException extends RuntimeException {
 223     private Directory dir;
 224
 225     public MergeException(String message, Directory dir) {
 226       super(message);
 227       this.dir = dir;
 228     }
 229
 230     public MergeException(Throwable exc, Directory dir) {
 231       super(exc);
 232       this.dir = dir;
 233     }
 234     /** Returns the {@link Directory} of the index that hit
 235      *  the exception. */
 236     public Directory getDirectory() {
 237       return dir;
 238     }
 239   }
 240
 241   public static class MergeAbortedException extends IOException {
 242     public MergeAbortedException() {
 243       super("merge is aborted");
 244     }
 245     public MergeAbortedException(String message) {
 246       super(message);
 247     }
 248   }
 249
 250   protected final SetOnce<IndexWriter> writer;
 251
 252   /**
 253    * Creates a new merge policy instance. Note that if you intend to use it
 254    * without passing it to {@link IndexWriter}, you should call
 255    * {@link #setIndexWriter(IndexWriter)}.
 256    */
 257   public MergePolicy() {
 258     writer = new SetOnce<IndexWriter>();
 259   }
 260
 261   /**
 262    * Sets the {@link IndexWriter} to use by this merge policy. This method is
 263    * allowed to be called only once, and is usually set by IndexWriter. If it is
 264    * called more than once, {@link AlreadySetException} is thrown.
 265    *
 266    * @see SetOnce
 267    */
 268   public void setIndexWriter(IndexWriter writer) {
 269     this.writer.set(writer);
 270   }
 271
 272   /**
 273    * Determine what set of merge operations are now necessary on the index.
 274    * {@link IndexWriter} calls this whenever there is a change to the segments.
 275    * This call is always synchronized on the {@link IndexWriter} instance so
 276    * only one thread at a time will call this method.
 277    *
 278    * @param segmentInfos
 279    *          the total set of segments in the index
 280    */
 281   public abstract MergeSpecification findMerges(SegmentInfos segmentInfos)
 282       throws CorruptIndexException, IOException;
 283
 284   /**
 285    * Determine what set of merge operations is necessary in
 286    * order to merge to <= the specified segment count. {@link IndexWriter} calls this when its
 287    * {@link IndexWriter#forceMerge} method is called. This call is always
 288    * synchronized on the {@link IndexWriter} instance so only one thread at a
 289    * time will call this method.
 290    *
 291    * @param segmentInfos
 292    *          the total set of segments in the index
 293    * @param maxSegmentCount
 294    *          requested maximum number of segments in the index (currently this
 295    *          is always 1)
 296    * @param segmentsToMerge
 297    *          contains the specific SegmentInfo instances that must be merged
 298    *          away. This may be a subset of all
 299    *          SegmentInfos.  If the value is True for a
 300    *          given SegmentInfo, that means this segment was
 301    *          an original segment present in the
 302    *          to-be-merged index; else, it was a segment
 303    *          produced by a cascaded merge.
 304    */
 305   public abstract MergeSpecification findForcedMerges(
 306           SegmentInfos segmentInfos, int maxSegmentCount, Map<SegmentInfo,Boolean> segmentsToMerge)
 307       throws CorruptIndexException, IOException;
 308
 309   /**
 310    * Determine what set of merge operations is necessary in order to expunge all
 311    * deletes from the index.
 312    *
 313    * @param segmentInfos
 314    *          the total set of segments in the index
 315    */
 316   public abstract MergeSpecification findForcedDeletesMerges(
 317       SegmentInfos segmentInfos) throws CorruptIndexException, IOException;
 318
 319   /**
 320    * Release all resources for the policy.
 321    */
 322   public abstract void close();
 323
 324   /** Returns true if a new segment (regardless of its origin) should use the compound file format. */
 325   public abstract boolean useCompoundFile(SegmentInfos segments, SegmentInfo newSegment) throws IOException;
 326 }