org.apache.lucene.util.VirtualMethod Maven / Gradle / Ivy
Show all versions of org.apache.servicemix.bundles.lucene
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.lucene.util;
import java.lang.reflect.Method;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.Collections;
import java.util.HashSet;
import java.util.Set;
/**
* A utility for keeping backwards compatibility on previously abstract methods (or similar
* replacements).
*
* Before the replacement method can be made abstract, the old method must kept deprecated. If
* somebody still overrides the deprecated method in a non-final class, you must keep track, of this
* and maybe delegate to the old method in the subclass. The cost of reflection is minimized by the
* following usage of this class:
*
*
Define static final fields in the base class ({@code BaseClass}), where the
* old and new method are declared:
*
*
* static final VirtualMethod<BaseClass> newMethod =
* new VirtualMethod<BaseClass>(BaseClass.class, "newName", parameters...);
* static final VirtualMethod<BaseClass> oldMethod =
* new VirtualMethod<BaseClass>(BaseClass.class, "oldName", parameters...);
*
*
* This enforces the singleton status of these objects, as the maintenance of the cache would be
* too costly else. If you try to create a second instance of for the same method/{@code baseClass}
* combination, an exception is thrown.
*
*
To detect if e.g. the old method was overridden by a more far subclass on the inheritance path
* to the current instance's class, use a non-static field:
*
*
* final boolean isDeprecatedMethodOverridden =
* AccessController.doPrivileged((PrivilegedAction<Boolean>) () ->
* (oldMethod.getImplementationDistance(this.getClass()) > newMethod.getImplementationDistance(this.getClass())));
*
* // alternatively (more readable):
* final boolean isDeprecatedMethodOverridden =
* AccessController.doPrivileged((PrivilegedAction<Boolean>) () ->
* VirtualMethod.compareImplementationDistance(this.getClass(), oldMethod, newMethod) > 0);
*
*
* It is important to use {@link AccessController#doPrivileged(PrivilegedAction)} for the actual
* call to get the implementation distance because the subclass may be in a different package. The
* static constructors do not need to use {@code AccessController} because it just initializes our
* own method reference. The caller should have access to all declared members in its own class.
*
*
{@link #getImplementationDistance} returns the distance of the subclass that overrides this
* method. The one with the larger distance should be used preferable. This way also more
* complicated method rename scenarios can be handled (think of 2.9 {@code TokenStream}
* deprecations).
*
* @lucene.internal
*/
public final class VirtualMethod {
private static final Set singletonSet =
Collections.synchronizedSet(new HashSet());
private final Class baseClass;
private final String method;
private final Class[] parameters;
private final ClassValue distanceOfClass =
new ClassValue() {
@Override
protected Integer computeValue(Class subclazz) {
return Integer.valueOf(reflectImplementationDistance(subclazz));
}
};
/**
* Creates a new instance for the given {@code baseClass} and method declaration.
*
* @throws UnsupportedOperationException if you create a second instance of the same {@code
* baseClass} and method declaration combination. This enforces the singleton status.
* @throws IllegalArgumentException if {@code baseClass} does not declare the given method.
*/
public VirtualMethod(Class baseClass, String method, Class... parameters) {
this.baseClass = baseClass;
this.method = method;
this.parameters = parameters;
try {
if (!singletonSet.add(baseClass.getDeclaredMethod(method, parameters)))
throw new UnsupportedOperationException(
"VirtualMethod instances must be singletons and therefore "
+ "assigned to static final members in the same class, they use as baseClass ctor param.");
} catch (NoSuchMethodException nsme) {
throw new IllegalArgumentException(
baseClass.getName() + " has no such method: " + nsme.getMessage());
}
}
/**
* Returns the distance from the {@code baseClass} in which this method is overridden/implemented
* in the inheritance path between {@code baseClass} and the given subclass {@code subclazz}.
*
* @return 0 iff not overridden, else the distance to the base class
*/
public int getImplementationDistance(final Class subclazz) {
return distanceOfClass.get(subclazz).intValue();
}
/**
* Returns, if this method is overridden/implemented in the inheritance path between {@code
* baseClass} and the given subclass {@code subclazz}.
*
* You can use this method to detect if a method that should normally be final was overridden
* by the given instance's class.
*
* @return {@code false} iff not overridden
*/
public boolean isOverriddenAsOf(final Class subclazz) {
return getImplementationDistance(subclazz) > 0;
}
int reflectImplementationDistance(final Class subclazz) {
if (!baseClass.isAssignableFrom(subclazz))
throw new IllegalArgumentException(
subclazz.getName() + " is not a subclass of " + baseClass.getName());
boolean overridden = false;
int distance = 0;
for (Class clazz = subclazz;
clazz != baseClass && clazz != null;
clazz = clazz.getSuperclass()) {
// lookup method, if success mark as overridden
if (!overridden) {
try {
clazz.getDeclaredMethod(method, parameters);
overridden = true;
} catch (
@SuppressWarnings("unused")
NoSuchMethodException nsme) {
}
}
// increment distance if overridden
if (overridden) distance++;
}
return distance;
}
/**
* Utility method that compares the implementation/override distance of two methods.
*
* @return
*
* - > 1, iff {@code m1} is overridden/implemented in a subclass of the class
* overriding/declaring {@code m2}
*
- < 1, iff {@code m2} is overridden in a subclass of the class overriding/declaring
* {@code m1}
*
- 0, iff both methods are overridden in the same class (or are not overridden at all)
*
*/
public static int compareImplementationDistance(
final Class clazz, final VirtualMethod m1, final VirtualMethod m2) {
return Integer.compare(
m1.getImplementationDistance(clazz), m2.getImplementationDistance(clazz));
}
}