org.spearce.jgit/src/org/spearce/jgit/treewalk/filter/TreeFilter.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.treewalk.filter;
  39
  40 import java.io.IOException;
  41
  42 import org.spearce.jgit.errors.IncorrectObjectTypeException;
  43 import org.spearce.jgit.errors.MissingObjectException;
  44 import org.spearce.jgit.revwalk.filter.AndRevFilter;
  45 import org.spearce.jgit.revwalk.filter.NotRevFilter;
  46 import org.spearce.jgit.revwalk.filter.OrRevFilter;
  47 import org.spearce.jgit.treewalk.TreeWalk;
  48
  49 /**
  50  * Selects interesting tree entries during walking.
  51  * <p>
  52  * This is an abstract interface. Applications may implement a subclass, or use
  53  * one of the predefined implementations already available within this package.
  54  * <p>
  55  * Unless specifically noted otherwise a TreeFilter implementation is not thread
  56  * safe and may not be shared by different TreeWalk instances at the same time.
  57  * This restriction allows TreeFilter implementations to cache state within
  58  * their instances during {@link #include(TreeWalk)} if it is beneficial to
  59  * their implementation. Deep clones created by {@link #clone()} may be used to
  60  * construct a thread-safe copy of an existing filter.
  61  *
  62  * <p>
  63  * <b>Path filters:</b>
  64  * <ul>
  65  * <li>Matching pathname: {@link PathFilter}</li>
  66  * </ul>
  67  *
  68  * <p>
  69  * <b>Difference filters:</b>
  70  * <ul>
  71  * <li>Only select differences: {@link #ANY_DIFF}.</li>
  72  * </ul>
  73  *
  74  * <p>
  75  * <b>Boolean modifiers:</b>
  76  * <ul>
  77  * <li>AND: {@link AndRevFilter}</li>
  78  * <li>OR: {@link OrRevFilter}</li>
  79  * <li>NOT: {@link NotRevFilter}</li>
  80  * </ul>
  81  */
  82 public abstract class TreeFilter {
  83         /** Selects all tree entries. */
  84         public static final TreeFilter ALL = new TreeFilter() {
  85                 @Override
  86                 public boolean include(final TreeWalk walker) {
  87                         return true;
  88                 }
  89
  90                 @Override
  91                 public boolean shouldBeRecursive() {
  92                         return false;
  93                 }
  94
  95                 @Override
  96                 public TreeFilter clone() {
  97                         return this;
  98                 }
  99
 100                 @Override
 101                 public String toString() {
 102                         return "ALL";
 103                 }
 104         };
 105
 106         /**
 107          * Selects only tree entries which differ between at least 2 trees.
 108          * <p>
 109          * This filter also prevents a TreeWalk from recursing into a subtree if all
 110          * parent trees have the identical subtree at the same path. This
 111          * dramatically improves walk performance as only the changed subtrees are
 112          * entered into.
 113          * <p>
 114          * If this filter is applied to a walker with only one tree it behaves like
 115          * {@link #ALL}, or as though the walker was matching a virtual empty tree
 116          * against the single tree it was actually given. Applications may wish to
 117          * treat such a difference as "all names added".
 118          */
 119         public static final TreeFilter ANY_DIFF = new TreeFilter() {
 120                 private static final int baseTree = 0;
 121
 122                 @Override
 123                 public boolean include(final TreeWalk walker) {
 124                         final int n = walker.getTreeCount();
 125                         if (n == 1) // Assume they meant difference to empty tree.
 126                                 return true;
 127
 128                         final int m = walker.getRawMode(baseTree);
 129                         for (int i = 1; i < n; i++)
 130                                 if (walker.getRawMode(i) != m || !walker.idEqual(i, baseTree))
 131                                         return true;
 132                         return false;
 133                 }
 134
 135                 @Override
 136                 public boolean shouldBeRecursive() {
 137                         return false;
 138                 }
 139
 140                 @Override
 141                 public TreeFilter clone() {
 142                         return this;
 143                 }
 144
 145                 @Override
 146                 public String toString() {
 147                         return "ANY_DIFF";
 148                 }
 149         };
 150
 151         /**
 152          * Create a new filter that does the opposite of this filter.
 153          *
 154          * @return a new filter that includes tree entries this filter rejects.
 155          */
 156         public TreeFilter negate() {
 157                 return NotTreeFilter.create(this);
 158         }
 159
 160         /**
 161          * Determine if the current entry is interesting to report.
 162          * <p>
 163          * This method is consulted for subtree entries even if
 164          * {@link TreeWalk#isRecursive()} is enabled. The consultation allows the
 165          * filter to bypass subtree recursion on a case-by-case basis, even when
 166          * recursion is enabled at the application level.
 167          *
 168          * @param walker
 169          *            the walker the filter needs to examine.
 170          * @return true if the current entry should be seen by the application;
 171          *         false to hide the entry.
 172          * @throws MissingObjectException
 173          *             an object the filter needs to consult to determine its answer
 174          *             does not exist in the Git repository the walker is operating
 175          *             on. Filtering this current walker entry is impossible without
 176          *             the object.
 177          * @throws IncorrectObjectTypeException
 178          *             an object the filter needed to consult was not of the
 179          *             expected object type. This usually indicates a corrupt
 180          *             repository, as an object link is referencing the wrong type.
 181          * @throws IOException
 182          *             a loose object or pack file could not be read to obtain data
 183          *             necessary for the filter to make its decision.
 184          */
 185         public abstract boolean include(TreeWalk walker)
 186                         throws MissingObjectException, IncorrectObjectTypeException,
 187                         IOException;
 188
 189         /**
 190          * Does this tree filter require a recursive walk to match everything?
 191          * <p>
 192          * If this tree filter is matching on full entry path names and its pattern
 193          * is looking for a '/' then the filter would require a recursive TreeWalk
 194          * to accurately make its decisions. The walker is not required to enable
 195          * recursive behavior for any particular filter, this is only a hint.
 196          *
 197          * @return true if the filter would like to have the walker recurse into
 198          *         subtrees to make sure it matches everything correctly; false if
 199          *         the filter does not require entering subtrees.
 200          */
 201         public abstract boolean shouldBeRecursive();
 202
 203         /**
 204          * Clone this tree filter, including its parameters.
 205          * <p>
 206          * This is a deep clone. If this filter embeds objects or other filters it
 207          * must also clone those, to ensure the instances do not share mutable data.
 208          *
 209          * @return another copy of this filter, suitable for another thread.
 210          */
 211         public abstract TreeFilter clone();
 212
 213         @Override
 214         public String toString() {
 215                 String n = getClass().getName();
 216                 int lastDot = n.lastIndexOf('.');
 217                 if (lastDot >= 0) {
 218                         n = n.substring(lastDot + 1);
 219                 }
 220                 return n.replace('$', '.');
 221         }
 222 }