org.spearce.jgit/src/org/spearce/jgit/dircache/BaseDirCacheEditor.java

   1 /*
   2  * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
   3  *
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or
   7  * without modification, are permitted provided that the following
   8  * conditions are met:
   9  *
  10  * - Redistributions of source code must retain the above copyright
  11  *   notice, this list of conditions and the following disclaimer.
  12  *
  13  * - Redistributions in binary form must reproduce the above
  14  *   copyright notice, this list of conditions and the following
  15  *   disclaimer in the documentation and/or other materials provided
  16  *   with the distribution.
  17  *
  18  * - Neither the name of the Git Development Community nor the
  19  *   names of its contributors may be used to endorse or promote
  20  *   products derived from this software without specific prior
  21  *   written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  24  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  25  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  26  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  28  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  29  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  30  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  35  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38 package org.spearce.jgit.dircache;
  39
  40 import java.io.IOException;
  41
  42 /**
  43  * Generic update/editing support for {@link DirCache}.
  44  * <p>
  45  * The different update strategies extend this class to provide their own unique
  46  * services to applications.
  47  */
  48 abstract class BaseDirCacheEditor {
  49         /** The cache instance this editor updates during {@link #finish()}. */
  50         protected DirCache cache;
  51
  52         /**
  53          * Entry table this builder will eventually replace into {@link #cache}.
  54          * <p>
  55          * Use {@link #fastAdd(DirCacheEntry)} or {@link #fastKeep(int, int)} to
  56          * make additions to this table. The table is automatically expanded if it
  57          * is too small for a new addition.
  58          * <p>
  59          * Typically the entries in here are sorted by their path names, just like
  60          * they are in the DirCache instance.
  61          */
  62         protected DirCacheEntry[] entries;
  63
  64         /** Total number of valid entries in {@link #entries}. */
  65         protected int entryCnt;
  66
  67         /**
  68          * Construct a new editor.
  69          *
  70          * @param dc
  71          *            the cache this editor will eventually update.
  72          * @param ecnt
  73          *            estimated number of entries the editor will have upon
  74          *            completion. This sizes the initial entry table.
  75          */
  76         protected BaseDirCacheEditor(final DirCache dc, final int ecnt) {
  77                 cache = dc;
  78                 entries = new DirCacheEntry[ecnt];
  79         }
  80
  81         /**
  82          * @return the cache we will update on {@link #finish()}.
  83          */
  84         public DirCache getDirCache() {
  85                 return cache;
  86         }
  87
  88         /**
  89          * Append one entry into the resulting entry list.
  90          * <p>
  91          * The entry is placed at the end of the entry list. The caller is
  92          * responsible for making sure the final table is correctly sorted.
  93          * <p>
  94          * The {@link #entries} table is automatically expanded if there is
  95          * insufficient space for the new addition.
  96          *
  97          * @param newEntry
  98          *            the new entry to add.
  99          */
 100         protected void fastAdd(final DirCacheEntry newEntry) {
 101                 if (entries.length == entryCnt) {
 102                         final DirCacheEntry[] n = new DirCacheEntry[(entryCnt + 16) * 3 / 2];
 103                         System.arraycopy(entries, 0, n, 0, entryCnt);
 104                         entries = n;
 105                 }
 106                 entries[entryCnt++] = newEntry;
 107         }
 108
 109         /**
 110          * Add a range of existing entries from the destination cache.
 111          * <p>
 112          * The entries are placed at the end of the entry list, preserving their
 113          * current order. The caller is responsible for making sure the final table
 114          * is correctly sorted.
 115          * <p>
 116          * This method copies from the destination cache, which has not yet been
 117          * updated with this editor's new table. So all offsets into the destination
 118          * cache are not affected by any updates that may be currently taking place
 119          * in this editor.
 120          * <p>
 121          * The {@link #entries} table is automatically expanded if there is
 122          * insufficient space for the new additions.
 123          *
 124          * @param pos
 125          *            first entry to copy from the destination cache.
 126          * @param cnt
 127          *            number of entries to copy.
 128          */
 129         protected void fastKeep(final int pos, int cnt) {
 130                 if (entryCnt + cnt > entries.length) {
 131                         final int m1 = (entryCnt + 16) * 3 / 2;
 132                         final int m2 = entryCnt + cnt;
 133                         final DirCacheEntry[] n = new DirCacheEntry[Math.max(m1, m2)];
 134                         System.arraycopy(entries, 0, n, 0, entryCnt);
 135                         entries = n;
 136                 }
 137
 138                 cache.toArray(pos, entries, entryCnt, cnt);
 139                 entryCnt += cnt;
 140         }
 141
 142         /**
 143          * Finish this builder and update the destination {@link DirCache}.
 144          * <p>
 145          * When this method completes this builder instance is no longer usable by
 146          * the calling application. A new builder must be created to make additional
 147          * changes to the index entries.
 148          * <p>
 149          * After completion the DirCache returned by {@link #getDirCache()} will
 150          * contain all modifications.
 151          * <p>
 152          * <i>Note to implementors:</i> Make sure {@link #entries} is fully sorted
 153          * then invoke {@link #replace()} to update the DirCache with the new table.
 154          */
 155         public abstract void finish();
 156
 157         /**
 158          * Update the DirCache with the contents of {@link #entries}.
 159          * <p>
 160          * This method should be invoked only during an implementation of
 161          * {@link #finish()}, and only after {@link #entries} is sorted.
 162          */
 163         protected void replace() {
 164                 if (entryCnt < entries.length / 2) {
 165                         final DirCacheEntry[] n = new DirCacheEntry[entryCnt];
 166                         System.arraycopy(entries, 0, n, 0, entryCnt);
 167                         entries = n;
 168                 }
 169                 cache.replace(entries, entryCnt);
 170         }
 171
 172         /**
 173          * Finish, write, commit this change, and release the index lock.
 174          * <p>
 175          * If this method fails (returns false) the lock is still released.
 176          * <p>
 177          * This is a utility method for applications as the finish-write-commit
 178          * pattern is very common after using a builder to update entries.
 179          *
 180          * @return true if the commit was successful and the file contains the new
 181          *         data; false if the commit failed and the file remains with the
 182          *         old data.
 183          * @throws IllegalStateException
 184          *             the lock is not held.
 185          * @throws IOException
 186          *             the output file could not be created. The caller no longer
 187          *             holds the lock.
 188          */
 189         public boolean commit() throws IOException {
 190                 finish();
 191                 cache.write();
 192                 return cache.commit();
 193         }
 194 }