1 /*
   2  * Copyright 2004 Sun Microsystems, Inc.  All Rights Reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package com.sun.mirror.util;
  27 
  28 
  29 import java.util.ArrayList;
  30 import java.util.Collection;
  31 
  32 import com.sun.mirror.declaration.Declaration;
  33 import com.sun.mirror.declaration.Modifier;
  34 
  35 import static com.sun.mirror.declaration.Modifier.*;
  36 
  37 
  38 /**
  39  * A filter for selecting just the items of interest
  40  * from a collection of declarations.
  41  * The filter is said to <i>select</i> or to <i>match</i> those declarations.
  42  * Filters can be created in several ways:
  43  * by the static methods described below,
  44  * by negating or composing existing filters,
  45  * or by subclasses that implement arbitrary matching rules.
  46  *
  47  * <p> A subclass can create an arbitrary filter simply by implementing
  48  * the {@link #matches(Declaration)} method.
  49  *
  50  * <p> Examples.
  51  * <p> Selecting the <tt>public</tt> declarations from a collection:
  52  * <blockquote><pre>
  53  *     result = FILTER_PUBLIC.filter(decls);            </pre></blockquote>
  54  * Selecting class declarations (including enums):
  55  * <blockquote><pre>
  56  *     classFilter = DeclarationFilter.getFilter(ClassDeclaration.class);
  57  *     result = classFilter.filter(decls);              </pre></blockquote>
  58  * Selecting class declarations but excluding enums:
  59  * <blockquote><pre>
  60  *     enumFilter = DeclarationFilter.getFilter(EnumDeclaration.class);
  61  *     compoundFilter = classFilter.and(enumFilter.not());
  62  *     result = compoundFilter.filter(decls);           </pre></blockquote>
  63  * Selecting declarations named "Bob":
  64  * <blockquote><pre>
  65  *     nameFilter = new DeclarationFilter() {
  66  *                      public boolean matches(Declaration d) {
  67  *                          return d.getSimpleName().equals("Bob");
  68  *                      }
  69  *                  };
  70  *     result = nameFilter.filter(decls);               </pre></blockquote>
  71  *
  72  * @deprecated All components of this API have been superseded by the
  73  * standardized annotation processing API.  The replacement for the
  74  * functionality of this class is {@link
  75  * javax.lang.model.util.ElementFilter}.
  76  *
  77  * @author Joseph D. Darcy
  78  * @author Scott Seligman
  79  * @since 1.5
  80  */
  81 @Deprecated
  82 @SuppressWarnings("deprecation")
  83 public class DeclarationFilter {
  84 
  85     // Predefined filters for convenience.
  86 
  87     /**
  88      * A filter that selects only <tt>public</tt> declarations.
  89      */
  90     public static final DeclarationFilter FILTER_PUBLIC =
  91             new AccessFilter(PUBLIC);
  92 
  93     /**
  94      * A filter that selects only <tt>protected</tt> declarations.
  95      */
  96     public static final DeclarationFilter FILTER_PROTECTED =
  97             new AccessFilter(PROTECTED);
  98 
  99     /**
 100      * A filter that selects only <tt>public</tt> or <tt>protected</tt>
 101      * declarations.
 102      */
 103     public static final DeclarationFilter FILTER_PUBLIC_OR_PROTECTED =
 104             new AccessFilter(PUBLIC, PROTECTED);
 105 
 106     /**
 107      * A filter that selects only package-private (<i>default</i>)
 108      * declarations.
 109      */
 110     public static final DeclarationFilter FILTER_PACKAGE =
 111             new AccessFilter();
 112 
 113     /**
 114      * A filter that selects only <tt>private</tt> declarations.
 115      */
 116     public static final DeclarationFilter FILTER_PRIVATE =
 117             new AccessFilter(PRIVATE);
 118 
 119 
 120     /**
 121      * Constructs an identity filter:  one that selects all declarations.
 122      */
 123     public DeclarationFilter() {
 124     }
 125 
 126 
 127 
 128     // Methods to create a filter.
 129 
 130     /**
 131      * Returns a filter that selects declarations containing all of a
 132      * collection of modifiers.
 133      *
 134      * @param mods  the modifiers to match (non-null)
 135      * @return a filter that matches declarations containing <tt>mods</tt>
 136      */
 137     public static DeclarationFilter getFilter(
 138                                              final Collection<Modifier> mods) {
 139         return new DeclarationFilter() {
 140             public boolean matches(Declaration d) {
 141                 return d.getModifiers().containsAll(mods);
 142             }
 143         };
 144     }
 145 
 146     /**
 147      * Returns a filter that selects declarations of a particular kind.
 148      * For example, there may be a filter that selects only class
 149      * declarations, or only fields.
 150      * The filter will select declarations of the specified kind,
 151      * and also any subtypes of that kind; for example, a field filter
 152      * will also select enum constants.
 153      *
 154      * @param kind  the kind of declarations to select
 155      * @return a filter that selects declarations of a particular kind
 156      */
 157     public static DeclarationFilter getFilter(
 158                                      final Class<? extends Declaration> kind) {
 159         return new DeclarationFilter() {
 160             public boolean matches(Declaration d) {
 161                 return kind.isInstance(d);
 162             }
 163         };
 164     }
 165 
 166     /**
 167      * Returns a filter that selects those declarations selected
 168      * by both this filter and another.
 169      *
 170      * @param f  filter to be composed with this one
 171      * @return a filter that selects those declarations selected by
 172      *          both this filter and another
 173      */
 174     public DeclarationFilter and(DeclarationFilter f) {
 175         final DeclarationFilter f1 = this;
 176         final DeclarationFilter f2 = f;
 177         return new DeclarationFilter() {
 178             public boolean matches(Declaration d) {
 179                 return f1.matches(d) && f2.matches(d);
 180             }
 181         };
 182     }
 183 
 184     /**
 185      * Returns a filter that selects those declarations selected
 186      * by either this filter or another.
 187      *
 188      * @param f  filter to be composed with this one
 189      * @return a filter that selects those declarations selected by
 190      *          either this filter or another
 191      */
 192     public DeclarationFilter or(DeclarationFilter f) {
 193         final DeclarationFilter f1 = this;
 194         final DeclarationFilter f2 = f;
 195         return new DeclarationFilter() {
 196             public boolean matches(Declaration d) {
 197                 return f1.matches(d) || f2.matches(d);
 198             }
 199         };
 200     }
 201 
 202     /**
 203      * Returns a filter that selects those declarations not selected
 204      * by this filter.
 205      *
 206      * @return a filter that selects those declarations not selected
 207      * by this filter
 208      */
 209     public DeclarationFilter not() {
 210         return new DeclarationFilter() {
 211             public boolean matches(Declaration d) {
 212                 return !DeclarationFilter.this.matches(d);
 213             }
 214         };
 215     }
 216 
 217 
 218 
 219     // Methods to apply a filter.
 220 
 221     /**
 222      * Tests whether this filter matches a given declaration.
 223      * The default implementation always returns <tt>true</tt>;
 224      * subclasses should override this.
 225      *
 226      * @param decl  the declaration to match
 227      * @return <tt>true</tt> if this filter matches the given declaration
 228      */
 229     public boolean matches(Declaration decl) {
 230         return true;
 231     }
 232 
 233     /**
 234      * Returns the declarations matched by this filter.
 235      * The result is a collection of the same type as the argument;
 236      * the {@linkplain #filter(Collection, Class) two-parameter version}
 237      * of <tt>filter</tt> offers control over the result type.
 238      *
 239      * @param <D>    type of the declarations being filtered
 240      * @param decls  declarations being filtered
 241      * @return the declarations matched by this filter
 242      */
 243     public <D extends Declaration> Collection<D> filter(Collection<D> decls) {
 244         ArrayList<D> res = new ArrayList<D>(decls.size());
 245         for (D d : decls) {
 246             if (matches(d)) {
 247                 res.add(d);
 248             }
 249         }
 250         return res;
 251     }
 252 
 253     /**
 254      * Returns the declarations matched by this filter, with the result
 255      * being restricted to declarations of a given kind.
 256      * Similar to the simpler
 257      * {@linkplain #filter(Collection) single-parameter version}
 258      * of <tt>filter</tt>, but the result type is specified explicitly.
 259      *
 260      * @param <D>      type of the declarations being returned
 261      * @param decls    declarations being filtered
 262      * @param resType  type of the declarations being returned --
 263      *                  the reflective view of <tt>D</tt>
 264      * @return the declarations matched by this filter, restricted to those
 265      *                  of the specified type
 266      */
 267     public <D extends Declaration> Collection<D>
 268             filter(Collection<? extends Declaration> decls, Class<D> resType) {
 269         ArrayList<D> res = new ArrayList<D>(decls.size());
 270         for (Declaration d : decls) {
 271             if (resType.isInstance(d) && matches(d)) {
 272                 res.add(resType.cast(d));
 273             }
 274         }
 275         return res;
 276     }
 277 
 278 
 279 
 280     /*
 281      * A filter based on access modifiers.
 282      */
 283     private static class AccessFilter extends DeclarationFilter {
 284 
 285         // The first access modifier to filter on, or null if we're looking
 286         // for declarations with no access modifiers.
 287         private Modifier mod1 = null;
 288 
 289         // The second access modifier to filter on, or null if none.
 290         private Modifier mod2 = null;
 291 
 292         // Returns a filter that matches declarations with no access
 293         // modifiers.
 294         AccessFilter() {
 295         }
 296 
 297         // Returns a filter that matches m.
 298         AccessFilter(Modifier m) {
 299             mod1 = m;
 300         }
 301 
 302         // Returns a filter that matches either m1 or m2.
 303         AccessFilter(Modifier m1, Modifier m2) {
 304             mod1 = m1;
 305             mod2 = m2;
 306         }
 307 
 308         public boolean matches(Declaration d) {
 309             Collection<Modifier> mods = d.getModifiers();
 310             if (mod1 == null) { // looking for package private
 311                 return !(mods.contains(PUBLIC) ||
 312                          mods.contains(PROTECTED) ||
 313                          mods.contains(PRIVATE));
 314             }
 315             return mods.contains(mod1) &&
 316                    (mod2 == null || mods.contains(mod2));
 317         }
 318     }
 319 }