binding/mdsal-binding-spec-util/src/main/java/org/opendaylight/mdsal/binding/spec/reflect/BindingReflections.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.binding.spec.reflect;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11 import static com.google.common.base.Preconditions.checkState;
  12
  13 import com.google.common.annotations.Beta;
  14 import com.google.common.annotations.VisibleForTesting;
  15 import com.google.common.cache.CacheBuilder;
  16 import com.google.common.cache.CacheLoader;
  17 import com.google.common.cache.LoadingCache;
  18 import com.google.common.collect.ImmutableSet;
  19 import com.google.common.collect.ImmutableSet.Builder;
  20 import com.google.common.util.concurrent.ListenableFuture;
  21 import java.lang.reflect.Field;
  22 import java.lang.reflect.InvocationTargetException;
  23 import java.lang.reflect.Method;
  24 import java.lang.reflect.Type;
  25 import java.util.Optional;
  26 import java.util.ServiceLoader;
  27 import java.util.concurrent.TimeUnit;
  28 import java.util.regex.Matcher;
  29 import java.util.regex.Pattern;
  30 import org.checkerframework.checker.regex.qual.Regex;
  31 import org.eclipse.jdt.annotation.NonNull;
  32 import org.opendaylight.mdsal.binding.spec.naming.BindingMapping;
  33 import org.opendaylight.yangtools.util.ClassLoaderUtils;
  34 import org.opendaylight.yangtools.yang.binding.Action;
  35 import org.opendaylight.yangtools.yang.binding.Augmentable;
  36 import org.opendaylight.yangtools.yang.binding.Augmentation;
  37 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  38 import org.opendaylight.yangtools.yang.binding.BindingContract;
  39 import org.opendaylight.yangtools.yang.binding.ChildOf;
  40 import org.opendaylight.yangtools.yang.binding.DataContainer;
  41 import org.opendaylight.yangtools.yang.binding.DataObject;
  42 import org.opendaylight.yangtools.yang.binding.Notification;
  43 import org.opendaylight.yangtools.yang.binding.Rpc;
  44 import org.opendaylight.yangtools.yang.binding.RpcService;
  45 import org.opendaylight.yangtools.yang.binding.YangModelBindingProvider;
  46 import org.opendaylight.yangtools.yang.binding.YangModuleInfo;
  47 import org.opendaylight.yangtools.yang.common.QName;
  48 import org.opendaylight.yangtools.yang.common.QNameModule;
  49 import org.opendaylight.yangtools.yang.common.YangConstants;
  50 import org.slf4j.Logger;
  51 import org.slf4j.LoggerFactory;
  52
  53 public final class BindingReflections {
  54
  55     private static final long EXPIRATION_TIME = 60;
  56
  57     @Regex
  58     private static final String ROOT_PACKAGE_PATTERN_STRING =
  59             "(org.opendaylight.yang.gen.v1.[a-z0-9_\\.]*\\.(?:rev[0-9][0-9][0-1][0-9][0-3][0-9]|norev))";
  60     private static final Pattern ROOT_PACKAGE_PATTERN = Pattern.compile(ROOT_PACKAGE_PATTERN_STRING);
  61     private static final Logger LOG = LoggerFactory.getLogger(BindingReflections.class);
  62
  63     private static final LoadingCache<Class<?>, Optional<QName>> CLASS_TO_QNAME = CacheBuilder.newBuilder()
  64             .weakKeys()
  65             .expireAfterAccess(EXPIRATION_TIME, TimeUnit.SECONDS)
  66             .build(new ClassToQNameLoader());
  67
  68     private static final LoadingCache<ClassLoader, ImmutableSet<YangModuleInfo>> MODULE_INFO_CACHE =
  69             CacheBuilder.newBuilder().weakKeys().weakValues().build(
  70                 new CacheLoader<ClassLoader, ImmutableSet<YangModuleInfo>>() {
  71                     @Override
  72                     public ImmutableSet<YangModuleInfo> load(final ClassLoader key) {
  73                         return loadModuleInfos(key);
  74                     }
  75                 });
  76
  77     private BindingReflections() {
  78         // Hidden on purpose
  79     }
  80
  81     /**
  82      * Find augmentation target class from concrete Augmentation class. This method uses first generic argument of
  83      * implemented {@link Augmentation} interface.
  84      *
  85      * @param augmentation
  86      *            {@link Augmentation} subclass for which we want to determine
  87      *            augmentation target.
  88      * @return Augmentation target - class which augmentation provides additional extensions.
  89      */
  90     public static Class<? extends Augmentable<?>> findAugmentationTarget(
  91             final Class<? extends Augmentation<?>> augmentation) {
  92         final Optional<Class<Augmentable<?>>> opt = ClassLoaderUtils.findFirstGenericArgument(augmentation,
  93             Augmentation.class);
  94         return opt.orElse(null);
  95     }
  96
  97     /**
  98      * Returns a QName associated to supplied type.
  99      *
 100      * @param dataType Data type class
 101      * @return QName associated to supplied dataType. If dataType is Augmentation method does not return canonical
 102      *         QName, but QName with correct namespace revision, but virtual local name, since augmentations do not
 103      *         have name. May return null if QName is not present.
 104      */
 105     public static QName findQName(final Class<?> dataType) {
 106         return CLASS_TO_QNAME.getUnchecked(dataType).orElse(null);
 107     }
 108
 109     /**
 110      * Checks if method is RPC invocation.
 111      *
 112      * @param possibleMethod
 113      *            Method to check
 114      * @return true if method is RPC invocation, false otherwise.
 115      */
 116     public static boolean isRpcMethod(final Method possibleMethod) {
 117         return possibleMethod != null && RpcService.class.isAssignableFrom(possibleMethod.getDeclaringClass())
 118                 && ListenableFuture.class.isAssignableFrom(possibleMethod.getReturnType())
 119                 // length <= 2: it seemed to be impossible to get correct RpcMethodInvoker because of
 120                 // resolveRpcInputClass() check.While RpcMethodInvoker counts with one argument for
 121                 // non input type and two arguments for input type, resolveRpcInputClass() counting
 122                 // with zero for non input and one for input type
 123                 && possibleMethod.getParameterCount() <= 2;
 124     }
 125
 126     /**
 127      * Extracts Output class for RPC method.
 128      *
 129      * @param targetMethod method to scan
 130      * @return Optional.empty() if result type could not be get, or return type is Void.
 131      * @deprecated This method is unused and scheduled for removal
 132      */
 133     @Deprecated(since = "10.0.4", forRemoval = true)
 134     @SuppressWarnings("rawtypes")
 135     public static Optional<Class<?>> resolveRpcOutputClass(final Method targetMethod) {
 136         checkState(isRpcMethod(targetMethod), "Supplied method is not a RPC invocation method");
 137         Type futureType = targetMethod.getGenericReturnType();
 138         Type rpcResultType = ClassLoaderUtils.getFirstGenericParameter(futureType).orElse(null);
 139         Type rpcResultArgument = ClassLoaderUtils.getFirstGenericParameter(rpcResultType).orElse(null);
 140         if (rpcResultArgument instanceof Class cls && !Void.class.equals(rpcResultArgument)) {
 141             return Optional.of(cls);
 142         }
 143         return Optional.empty();
 144     }
 145
 146     /**
 147      * Extracts input class for RPC method.
 148      *
 149      * @param targetMethod method to scan
 150      * @return Optional.empty() if RPC has no input, RPC input type otherwise.
 151      * @deprecated This method is unused and scheduled for removal
 152      */
 153     @Deprecated(since = "10.0.4", forRemoval = true)
 154     @SuppressWarnings("rawtypes")
 155     public static Optional<Class<? extends DataContainer>> resolveRpcInputClass(final Method targetMethod) {
 156         for (Class clazz : targetMethod.getParameterTypes()) {
 157             if (DataContainer.class.isAssignableFrom(clazz)) {
 158                 return Optional.of(clazz);
 159             }
 160         }
 161         return Optional.empty();
 162     }
 163
 164     public static @NonNull QName getQName(final BaseIdentity identity) {
 165         return getContractQName(identity);
 166     }
 167
 168     public static @NonNull QName getQName(final Rpc<?, ?> rpc) {
 169         return getContractQName(rpc);
 170     }
 171
 172     private static @NonNull QName getContractQName(final BindingContract<?> contract) {
 173         return CLASS_TO_QNAME.getUnchecked(contract.implementedInterface())
 174             .orElseThrow(() -> new IllegalStateException("Failed to resolve QName of " + contract));
 175     }
 176
 177     /**
 178      * Returns root package name for supplied package.
 179      *
 180      * @param pkg
 181      *            Package for which find model root package.
 182      * @return Package of model root.
 183      */
 184     public static String getModelRootPackageName(final Package pkg) {
 185         return getModelRootPackageName(pkg.getName());
 186     }
 187
 188     /**
 189      * Returns root package name for supplied package name.
 190      *
 191      * @param name
 192      *            Package for which find model root package.
 193      * @return Package of model root.
 194      */
 195     public static String getModelRootPackageName(final String name) {
 196         checkArgument(name != null, "Package name should not be null.");
 197         checkArgument(name.startsWith(BindingMapping.PACKAGE_PREFIX), "Package name not starting with %s, is: %s",
 198                 BindingMapping.PACKAGE_PREFIX, name);
 199         Matcher match = ROOT_PACKAGE_PATTERN.matcher(name);
 200         checkArgument(match.find(), "Package name '%s' does not match required pattern '%s'", name,
 201                 ROOT_PACKAGE_PATTERN_STRING);
 202         return match.group(0);
 203     }
 204
 205     public static QNameModule getQNameModule(final Class<?> clz) {
 206         if (DataContainer.class.isAssignableFrom(clz) || BaseIdentity.class.isAssignableFrom(clz)
 207                 || Action.class.isAssignableFrom(clz)) {
 208             return findQName(clz).getModule();
 209         }
 210
 211         return getModuleInfo(clz).getName().getModule();
 212     }
 213
 214     /**
 215      * Returns instance of {@link YangModuleInfo} of declaring model for specific class.
 216      *
 217      * @param cls data object class
 218      * @return Instance of {@link YangModuleInfo} associated with model, from which this class was derived.
 219      */
 220     public static @NonNull YangModuleInfo getModuleInfo(final Class<?> cls) {
 221         final String packageName = getModelRootPackageName(cls.getPackage());
 222         final String potentialClassName = getModuleInfoClassName(packageName);
 223         final Class<?> moduleInfoClass;
 224         try {
 225             moduleInfoClass = cls.getClassLoader().loadClass(potentialClassName);
 226         } catch (ClassNotFoundException e) {
 227             throw new IllegalStateException("Failed to load " + potentialClassName, e);
 228         }
 229
 230         final Object infoInstance;
 231         try {
 232             infoInstance = moduleInfoClass.getMethod("getInstance").invoke(null);
 233         } catch (IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
 234             throw new IllegalStateException("Failed to get instance of " + moduleInfoClass, e);
 235         }
 236
 237         checkState(infoInstance instanceof YangModuleInfo, "Unexpected instance %s", infoInstance);
 238         return (YangModuleInfo) infoInstance;
 239     }
 240
 241     public static @NonNull String getModuleInfoClassName(final String packageName) {
 242         return packageName + "." + BindingMapping.MODULE_INFO_CLASS_NAME;
 243     }
 244
 245     /**
 246      * Check if supplied class is derived from YANG model.
 247      *
 248      * @param cls
 249      *            Class to check
 250      * @return true if class is derived from YANG model.
 251      */
 252     public static boolean isBindingClass(final Class<?> cls) {
 253         if (DataContainer.class.isAssignableFrom(cls) || Augmentation.class.isAssignableFrom(cls)) {
 254             return true;
 255         }
 256         return cls.getName().startsWith(BindingMapping.PACKAGE_PREFIX);
 257     }
 258
 259     /**
 260      * Checks if supplied method is callback for notifications.
 261      *
 262      * @param method method to check
 263      * @return true if method is notification callback.
 264      */
 265     public static boolean isNotificationCallback(final Method method) {
 266         checkArgument(method != null);
 267         if (method.getName().startsWith("on") && method.getParameterCount() == 1) {
 268             Class<?> potentialNotification = method.getParameterTypes()[0];
 269             if (isNotification(potentialNotification)
 270                     && method.getName().equals("on" + potentialNotification.getSimpleName())) {
 271                 return true;
 272             }
 273         }
 274         return false;
 275     }
 276
 277     /**
 278      * Checks is supplied class is a {@link Notification}.
 279      *
 280      * @param potentialNotification class to examine
 281      * @return True if the class represents a Notification.
 282      */
 283     @VisibleForTesting
 284     static boolean isNotification(final Class<?> potentialNotification) {
 285         checkArgument(potentialNotification != null, "potentialNotification must not be null.");
 286         return Notification.class.isAssignableFrom(potentialNotification);
 287     }
 288
 289     /**
 290      * Loads {@link YangModuleInfo} infos available on current classloader. This method is shorthand for
 291      * {@link #loadModuleInfos(ClassLoader)} with {@link Thread#getContextClassLoader()} for current thread.
 292      *
 293      * @return Set of {@link YangModuleInfo} available for current classloader.
 294      */
 295     public static @NonNull ImmutableSet<YangModuleInfo> loadModuleInfos() {
 296         return loadModuleInfos(Thread.currentThread().getContextClassLoader());
 297     }
 298
 299     /**
 300      * Loads {@link YangModuleInfo} infos available on supplied classloader.
 301      *
 302      * <p>
 303      * {@link YangModuleInfo} are discovered using {@link ServiceLoader} for {@link YangModelBindingProvider}.
 304      * {@link YangModelBindingProvider} are simple classes which holds only pointers to actual instance
 305      * {@link YangModuleInfo}.
 306      *
 307      * <p>
 308      * When {@link YangModuleInfo} is available, all dependencies are recursively collected into returning set by
 309      * collecting results of {@link YangModuleInfo#getImportedModules()}.
 310      *
 311      * <p>
 312      * Consider using {@link #cacheModuleInfos(ClassLoader)} if the classloader is known to be immutable.
 313      *
 314      * @param loader Classloader for which {@link YangModuleInfo} should be retrieved.
 315      * @return Set of {@link YangModuleInfo} available for supplied classloader.
 316      */
 317     public static @NonNull ImmutableSet<YangModuleInfo> loadModuleInfos(final ClassLoader loader) {
 318         Builder<YangModuleInfo> moduleInfoSet = ImmutableSet.builder();
 319         ServiceLoader<YangModelBindingProvider> serviceLoader = ServiceLoader.load(YangModelBindingProvider.class,
 320                 loader);
 321         for (YangModelBindingProvider bindingProvider : serviceLoader) {
 322             YangModuleInfo moduleInfo = bindingProvider.getModuleInfo();
 323             checkState(moduleInfo != null, "Module Info for %s is not available.", bindingProvider.getClass());
 324             collectYangModuleInfo(bindingProvider.getModuleInfo(), moduleInfoSet);
 325         }
 326         return moduleInfoSet.build();
 327     }
 328
 329     /**
 330      * Loads {@link YangModuleInfo} instances available on supplied {@link ClassLoader}, assuming the set of available
 331      * information does not change. Subsequent accesses may return cached values.
 332      *
 333      * <p>
 334      * {@link YangModuleInfo} are discovered using {@link ServiceLoader} for {@link YangModelBindingProvider}.
 335      * {@link YangModelBindingProvider} are simple classes which holds only pointers to actual instance
 336      * {@link YangModuleInfo}.
 337      *
 338      * <p>
 339      * When {@link YangModuleInfo} is available, all dependencies are recursively collected into returning set by
 340      * collecting results of {@link YangModuleInfo#getImportedModules()}.
 341      *
 342      * @param loader Class loader for which {@link YangModuleInfo} should be retrieved.
 343      * @return Set of {@link YangModuleInfo} available for supplied classloader.
 344      */
 345     @Beta
 346     public static @NonNull ImmutableSet<YangModuleInfo> cacheModuleInfos(final ClassLoader loader) {
 347         return MODULE_INFO_CACHE.getUnchecked(loader);
 348     }
 349
 350     private static void collectYangModuleInfo(final YangModuleInfo moduleInfo,
 351             final Builder<YangModuleInfo> moduleInfoSet) {
 352         moduleInfoSet.add(moduleInfo);
 353         for (YangModuleInfo dependency : moduleInfo.getImportedModules()) {
 354             collectYangModuleInfo(dependency, moduleInfoSet);
 355         }
 356     }
 357
 358     /**
 359      * Checks if supplied class represents RPC Input / RPC Output.
 360      *
 361      * @param targetType
 362      *            Class to be checked
 363      * @return true if class represents RPC Input or RPC Output class.
 364      */
 365     public static boolean isRpcType(final Class<? extends DataObject> targetType) {
 366         return DataContainer.class.isAssignableFrom(targetType)
 367                 && !ChildOf.class.isAssignableFrom(targetType)
 368                 && !Notification.class.isAssignableFrom(targetType)
 369                 && (targetType.getName().endsWith("Input") || targetType.getName().endsWith("Output"));
 370     }
 371
 372     private static class ClassToQNameLoader extends CacheLoader<Class<?>, Optional<QName>> {
 373
 374         @Override
 375         public Optional<QName> load(@SuppressWarnings("NullableProblems") final Class<?> key) throws Exception {
 376             return resolveQNameNoCache(key);
 377         }
 378
 379         /**
 380          * Tries to resolve QName for supplied class. Looks up for static field with name from constant
 381          * {@link BindingMapping#QNAME_STATIC_FIELD_NAME} and returns value if present. If field is not present uses
 382          * {@link #computeQName(Class)} to compute QName for missing types.
 383          */
 384         private static Optional<QName> resolveQNameNoCache(final Class<?> key) {
 385             try {
 386                 final Field field;
 387                 try {
 388                     field = key.getField(BindingMapping.QNAME_STATIC_FIELD_NAME);
 389                 } catch (NoSuchFieldException e) {
 390                     LOG.debug("{} does not have a {} field, falling back to computation", key,
 391                         BindingMapping.QNAME_STATIC_FIELD_NAME, e);
 392                     return Optional.of(computeQName(key));
 393                 }
 394
 395                 final Object obj = field.get(null);
 396                 if (obj instanceof QName qname) {
 397                     return Optional.of(qname);
 398                 }
 399             } catch (SecurityException | IllegalArgumentException | IllegalAccessException e) {
 400                 /*
 401                  * It is safe to log this this exception on debug, since this method should not fail. Only failures are
 402                  * possible if the runtime / backing is inconsistent.
 403                  */
 404                 LOG.debug("Unexpected exception during extracting QName for {}", key, e);
 405             }
 406             return Optional.empty();
 407         }
 408
 409         /**
 410          * Computes QName for supplied class. Namespace and revision are same as {@link YangModuleInfo} associated with
 411          * supplied class.
 412          *
 413          * <p>
 414          * If class is
 415          * <ul>
 416          * <li>rpc input: local name is "input".
 417          * <li>rpc output: local name is "output".
 418          * <li>augmentation: local name is "module name".
 419          * </ul>
 420          *
 421          * <p>
 422          * There is also fallback, if it is not possible to compute QName using following algorithm returns module
 423          * QName.
 424          *
 425          * @throws IllegalStateException If YangModuleInfo could not be resolved
 426          * @throws IllegalArgumentException If supplied class was not derived from YANG model.
 427          */
 428         // FIXME: Extend this algorithm to also provide QName for YANG modeled simple types.
 429         @SuppressWarnings({ "rawtypes", "unchecked" })
 430         private static QName computeQName(final Class key) {
 431             checkArgument(isBindingClass(key), "Supplied class %s is not derived from YANG.", key);
 432
 433             final QName module = getModuleInfo(key).getName();
 434             if (Augmentation.class.isAssignableFrom(key)) {
 435                 return module;
 436             } else if (isRpcType(key)) {
 437                 final String className = key.getSimpleName();
 438                 if (className.endsWith(BindingMapping.RPC_OUTPUT_SUFFIX)) {
 439                     return YangConstants.operationOutputQName(module.getModule()).intern();
 440                 }
 441
 442                 return YangConstants.operationInputQName(module.getModule()).intern();
 443             }
 444
 445             /*
 446              * Fallback for Binding types which do not have QNAME field
 447              */
 448             return module;
 449         }
 450     }
 451 }