lucene-java-3.4.0/lucene/src/java/org/apache/lucene/util/VirtualMethod.java

   1 package org.apache.lucene.util;
   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 java.lang.reflect.Method;
  21 import java.util.Collections;
  22 import java.util.HashSet;
  23 import java.util.WeakHashMap;
  24 import java.util.Set;
  25
  26 /**
  27  * A utility for keeping backwards compatibility on previously abstract methods
  28  * (or similar replacements).
  29  * <p>Before the replacement method can be made abstract, the old method must kept deprecated.
  30  * If somebody still overrides the deprecated method in a non-final class,
  31  * you must keep track, of this and maybe delegate to the old method in the subclass.
  32  * The cost of reflection is minimized by the following usage of this class:</p>
  33  * <p>Define <strong>static final</strong> fields in the base class ({@code BaseClass}),
  34  * where the old and new method are declared:</p>
  35  * <pre>
  36  *  static final VirtualMethod&lt;BaseClass&gt; newMethod =
  37  *   new VirtualMethod&lt;BaseClass&gt;(BaseClass.class, "newName", parameters...);
  38  *  static final VirtualMethod&lt;BaseClass&gt; oldMethod =
  39  *   new VirtualMethod&lt;BaseClass&gt;(BaseClass.class, "oldName", parameters...);
  40  * </pre>
  41  * <p>This enforces the singleton status of these objects, as the maintenance of the cache would be too costly else.
  42  * If you try to create a second instance of for the same method/{@code baseClass} combination, an exception is thrown.
  43  * <p>To detect if e.g. the old method was overridden by a more far subclass on the inheritance path to the current
  44  * instance's class, use a <strong>non-static</strong> field:</p>
  45  * <pre>
  46  *  final boolean isDeprecatedMethodOverridden =
  47  *   oldMethod.getImplementationDistance(this.getClass()) > newMethod.getImplementationDistance(this.getClass());
  48  *
  49  *  <em>// alternatively (more readable):</em>
  50  *  final boolean isDeprecatedMethodOverridden =
  51  *   VirtualMethod.compareImplementationDistance(this.getClass(), oldMethod, newMethod) > 0
  52  * </pre>
  53  * <p>{@link #getImplementationDistance} returns the distance of the subclass that overrides this method.
  54  * The one with the larger distance should be used preferable.
  55  * This way also more complicated method rename scenarios can be handled
  56  * (think of 2.9 {@code TokenStream} deprecations).</p>
  57  *
  58  * @lucene.internal
  59  */
  60 public final class VirtualMethod<C> {
  61
  62   private static final Set<Method> singletonSet = Collections.synchronizedSet(new HashSet<Method>());
  63
  64   private final Class<C> baseClass;
  65   private final String method;
  66   private final Class<?>[] parameters;
  67   private final WeakHashMap<Class<? extends C>, Integer> cache =
  68     new WeakHashMap<Class<? extends C>, Integer>();
  69
  70   /**
  71    * Creates a new instance for the given {@code baseClass} and method declaration.
  72    * @throws UnsupportedOperationException if you create a second instance of the same
  73    *  {@code baseClass} and method declaration combination. This enforces the singleton status.
  74    * @throws IllegalArgumentException if {@code baseClass} does not declare the given method.
  75    */
  76   public VirtualMethod(Class<C> baseClass, String method, Class<?>... parameters) {
  77     this.baseClass = baseClass;
  78     this.method = method;
  79     this.parameters = parameters;
  80     try {
  81       if (!singletonSet.add(baseClass.getDeclaredMethod(method, parameters)))
  82         throw new UnsupportedOperationException(
  83           "VirtualMethod instances must be singletons and therefore " +
  84           "assigned to static final members in the same class, they use as baseClass ctor param."
  85         );
  86     } catch (NoSuchMethodException nsme) {
  87       throw new IllegalArgumentException(baseClass.getName() + " has no such method: "+nsme.getMessage());
  88     }
  89   }
  90
  91   /**
  92    * Returns the distance from the {@code baseClass} in which this method is overridden/implemented
  93    * in the inheritance path between {@code baseClass} and the given subclass {@code subclazz}.
  94    * @return 0 iff not overridden, else the distance to the base class
  95    */
  96   public synchronized int getImplementationDistance(final Class<? extends C> subclazz) {
  97     Integer distance = cache.get(subclazz);
  98     if (distance == null) {
  99       cache.put(subclazz, distance = Integer.valueOf(reflectImplementationDistance(subclazz)));
 100     }
 101     return distance.intValue();
 102   }
 103
 104   /**
 105    * Returns, if this method is overridden/implemented in the inheritance path between
 106    * {@code baseClass} and the given subclass {@code subclazz}.
 107    * <p>You can use this method to detect if a method that should normally be final was overridden
 108    * by the given instance's class.
 109    * @return {@code false} iff not overridden
 110    */
 111   public boolean isOverriddenAsOf(final Class<? extends C> subclazz) {
 112     return getImplementationDistance(subclazz) > 0;
 113   }
 114
 115   private int reflectImplementationDistance(final Class<? extends C> subclazz) {
 116     if (!baseClass.isAssignableFrom(subclazz))
 117       throw new IllegalArgumentException(subclazz.getName() + " is not a subclass of " + baseClass.getName());
 118     boolean overridden = false;
 119     int distance = 0;
 120     for (Class<?> clazz = subclazz; clazz != baseClass && clazz != null; clazz = clazz.getSuperclass()) {
 121       // lookup method, if success mark as overridden
 122       if (!overridden) {
 123         try {
 124           clazz.getDeclaredMethod(method, parameters);
 125           overridden = true;
 126         } catch (NoSuchMethodException nsme) {
 127         }
 128       }
 129
 130       // increment distance if overridden
 131       if (overridden) distance++;
 132     }
 133     return distance;
 134   }
 135
 136   /**
 137    * Utility method that compares the implementation/override distance of two methods.
 138    * @return <ul>
 139    *  <li>&gt; 1, iff {@code m1} is overridden/implemented in a subclass of the class overriding/declaring {@code m2}
 140    *  <li>&lt; 1, iff {@code m2} is overridden in a subclass of the class overriding/declaring {@code m1}
 141    *  <li>0, iff both methods are overridden in the same class (or are not overridden at all)
 142    * </ul>
 143    */
 144   public static <C> int compareImplementationDistance(final Class<? extends C> clazz,
 145     final VirtualMethod<C> m1, final VirtualMethod<C> m2)
 146   {
 147     return Integer.valueOf(m1.getImplementationDistance(clazz)).compareTo(m2.getImplementationDistance(clazz));
 148   }
 149
 150 }