binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/DataContainerCodecContext.java

   1 /*
   2  * Copyright (c) 2014 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.dom.codec.impl;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.collect.ImmutableCollection;
  14 import com.google.common.collect.ImmutableSet;
  15 import java.io.IOException;
  16 import java.lang.invoke.MethodHandles;
  17 import java.lang.invoke.VarHandle;
  18 import java.lang.reflect.Method;
  19 import java.lang.reflect.Modifier;
  20 import java.lang.reflect.ParameterizedType;
  21 import java.util.Arrays;
  22 import java.util.HashSet;
  23 import java.util.List;
  24 import java.util.Map;
  25 import java.util.Optional;
  26 import java.util.Set;
  27 import org.eclipse.jdt.annotation.NonNull;
  28 import org.eclipse.jdt.annotation.Nullable;
  29 import org.opendaylight.mdsal.binding.dom.codec.api.BindingDataObjectCodecTreeNode;
  30 import org.opendaylight.mdsal.binding.dom.codec.api.BindingNormalizedNodeCachingCodec;
  31 import org.opendaylight.mdsal.binding.dom.codec.api.BindingStreamEventWriter;
  32 import org.opendaylight.mdsal.binding.dom.codec.api.IncorrectNestingException;
  33 import org.opendaylight.mdsal.binding.dom.codec.api.MissingClassInLoadingStrategyException;
  34 import org.opendaylight.mdsal.binding.dom.codec.api.MissingSchemaException;
  35 import org.opendaylight.mdsal.binding.dom.codec.api.MissingSchemaForClassException;
  36 import org.opendaylight.mdsal.binding.model.api.Type;
  37 import org.opendaylight.mdsal.binding.runtime.api.BindingRuntimeContext;
  38 import org.opendaylight.mdsal.binding.runtime.api.CompositeRuntimeType;
  39 import org.opendaylight.mdsal.binding.runtime.api.RuntimeTypeContainer;
  40 import org.opendaylight.mdsal.binding.spec.reflect.BindingReflections;
  41 import org.opendaylight.yangtools.util.ClassLoaderUtils;
  42 import org.opendaylight.yangtools.yang.binding.Augmentation;
  43 import org.opendaylight.yangtools.yang.binding.BindingObject;
  44 import org.opendaylight.yangtools.yang.binding.DataContainer;
  45 import org.opendaylight.yangtools.yang.binding.DataObject;
  46 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument;
  47 import org.opendaylight.yangtools.yang.common.QName;
  48 import org.opendaylight.yangtools.yang.common.QNameModule;
  49 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  50 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.AugmentationIdentifier;
  51 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  52 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
  53 import org.opendaylight.yangtools.yang.data.impl.schema.ImmutableNormalizedNodeStreamWriter;
  54 import org.opendaylight.yangtools.yang.data.impl.schema.NormalizedNodeResult;
  55 import org.slf4j.Logger;
  56 import org.slf4j.LoggerFactory;
  57
  58 abstract class DataContainerCodecContext<D extends DataObject, T extends RuntimeTypeContainer> extends NodeCodecContext
  59         implements BindingDataObjectCodecTreeNode<D>  {
  60     private static final Logger LOG = LoggerFactory.getLogger(DataContainerCodecContext.class);
  61     private static final VarHandle EVENT_STREAM_SERIALIZER;
  62
  63     static {
  64         try {
  65             EVENT_STREAM_SERIALIZER = MethodHandles.lookup().findVarHandle(DataContainerCodecContext.class,
  66                 "eventStreamSerializer", DataObjectSerializer.class);
  67         } catch (NoSuchFieldException | IllegalAccessException e) {
  68             throw new ExceptionInInitializerError(e);
  69         }
  70     }
  71
  72     private final @NonNull DataContainerCodecPrototype<T> prototype;
  73
  74     // Accessed via a VarHandle
  75     @SuppressWarnings("unused")
  76     private volatile DataObjectSerializer eventStreamSerializer;
  77
  78     DataContainerCodecContext(final DataContainerCodecPrototype<T> prototype) {
  79         this.prototype = requireNonNull(prototype);
  80     }
  81
  82     public final @NonNull T getType() {
  83         return prototype.getType();
  84     }
  85
  86     @Override
  87     public final ChildAddressabilitySummary getChildAddressabilitySummary() {
  88         return prototype.getChildAddressabilitySummary();
  89     }
  90
  91     protected final QNameModule namespace() {
  92         return prototype.getNamespace();
  93     }
  94
  95     protected final CodecContextFactory factory() {
  96         return prototype.getFactory();
  97     }
  98
  99     @Override
 100     protected YangInstanceIdentifier.PathArgument getDomPathArgument() {
 101         return prototype.getYangArg();
 102     }
 103
 104     /**
 105      * Returns nested node context using supplied YANG Instance Identifier.
 106      *
 107      * @param arg Yang Instance Identifier Argument
 108      * @return Context of child
 109      * @throws IllegalArgumentException If supplied argument does not represent valid child.
 110      */
 111     @Override
 112     public abstract NodeCodecContext yangPathArgumentChild(YangInstanceIdentifier.PathArgument arg);
 113
 114     /**
 115      * Returns nested node context using supplied Binding Instance Identifier
 116      * and adds YANG instance identifiers to supplied list.
 117      *
 118      * @param arg Binding Instance Identifier Argument
 119      * @return Context of child or null if supplied {@code arg} does not represent valid child.
 120      * @throws IllegalArgumentException If supplied argument does not represent valid child.
 121      */
 122     @Override
 123     public DataContainerCodecContext<?, ?> bindingPathArgumentChild(final PathArgument arg,
 124             final List<YangInstanceIdentifier.PathArgument> builder) {
 125         final DataContainerCodecContext<?,?> child = streamChild(arg.getType());
 126         if (builder != null) {
 127             child.addYangPathArgument(arg,builder);
 128         }
 129         return child;
 130     }
 131
 132     /**
 133      * Returns deserialized Binding Path Argument from YANG instance identifier.
 134      */
 135     protected PathArgument getBindingPathArgument(final YangInstanceIdentifier.PathArgument domArg) {
 136         return bindingArg();
 137     }
 138
 139     protected final PathArgument bindingArg() {
 140         return prototype.getBindingArg();
 141     }
 142
 143     @SuppressWarnings("unchecked")
 144     @Override
 145     public final Class<D> getBindingClass() {
 146         return Class.class.cast(prototype.getBindingClass());
 147     }
 148
 149     @Override
 150     public abstract <C extends DataObject> DataContainerCodecContext<C, ?> streamChild(Class<C> childClass);
 151
 152     /**
 153      * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case, one
 154      * must issue getChild(ChoiceClass).getChild(CaseClass).
 155      *
 156      * @param childClass child class
 157      * @return Context of child or Optional.empty is supplied class is not applicable in context.
 158      */
 159     @Override
 160     public abstract <C extends DataObject> Optional<DataContainerCodecContext<C,?>> possibleStreamChild(
 161             Class<C> childClass);
 162
 163     @Override
 164     public String toString() {
 165         return getClass().getSimpleName() + " [" + prototype.getBindingClass() + "]";
 166     }
 167
 168     @Override
 169     public BindingNormalizedNodeCachingCodec<D> createCachingCodec(
 170             final ImmutableCollection<Class<? extends BindingObject>> cacheSpecifier) {
 171         if (cacheSpecifier.isEmpty()) {
 172             return new NonCachingCodec<>(this);
 173         }
 174         return new CachingNormalizedNodeCodec<>(this, ImmutableSet.copyOf(cacheSpecifier));
 175     }
 176
 177     @NonNull BindingStreamEventWriter createWriter(final NormalizedNodeStreamWriter domWriter) {
 178         return BindingToNormalizedStreamWriter.create(this, domWriter);
 179     }
 180
 181     protected final <V> @NonNull V childNonNull(final @Nullable V nullable,
 182             final YangInstanceIdentifier.PathArgument child, final String message, final Object... args) {
 183         if (nullable == null) {
 184             throw childNullException(extractName(child), message, args);
 185         }
 186         return nullable;
 187     }
 188
 189     protected final <V> @NonNull V childNonNull(final @Nullable V nullable, final QName child, final String message,
 190             final Object... args) {
 191         if (nullable == null) {
 192             throw childNullException(child, message, args);
 193         }
 194         return nullable;
 195     }
 196
 197     protected final <V> @NonNull V childNonNull(final @Nullable V nullable, final Class<?> childClass,
 198             final String message, final Object... args) {
 199         if (nullable == null) {
 200             throw childNullException(childClass, message, args);
 201         }
 202         return nullable;
 203     }
 204
 205     private IllegalArgumentException childNullException(final QName child, final String message, final Object... args) {
 206         final QNameModule module = child.getModule();
 207         if (!factory().getRuntimeContext().getEffectiveModelContext().findModule(module).isPresent()) {
 208             throw new MissingSchemaException("Module " + module + " is not present in current schema context.");
 209         }
 210         throw IncorrectNestingException.create(message, args);
 211     }
 212
 213     private IllegalArgumentException childNullException(final Class<?> childClass, final String message,
 214             final Object... args) {
 215         final BindingRuntimeContext runtimeContext = factory().getRuntimeContext();
 216         final CompositeRuntimeType schema;
 217         if (Augmentation.class.isAssignableFrom(childClass)) {
 218             schema = runtimeContext.getAugmentationDefinition(childClass.asSubclass(Augmentation.class));
 219         } else {
 220             schema = runtimeContext.getSchemaDefinition(childClass);
 221         }
 222         if (schema == null) {
 223             throw new MissingSchemaForClassException(childClass);
 224         }
 225
 226         try {
 227             runtimeContext.loadClass(Type.of(childClass));
 228         } catch (final ClassNotFoundException e) {
 229             throw new MissingClassInLoadingStrategyException(
 230                 "User supplied class " + childClass.getName() + " is not available in " + runtimeContext, e);
 231         }
 232
 233         throw IncorrectNestingException.create(message, args);
 234     }
 235
 236     private static QName extractName(final YangInstanceIdentifier.PathArgument child) {
 237         if (child instanceof AugmentationIdentifier) {
 238             final Set<QName> children = ((AugmentationIdentifier) child).getPossibleChildNames();
 239             checkArgument(!children.isEmpty(), "Augmentation without childs must not be used in data");
 240             return children.iterator().next();
 241         }
 242         return child.getNodeType();
 243     }
 244
 245     final DataObjectSerializer eventStreamSerializer() {
 246         final DataObjectSerializer existing = (DataObjectSerializer) EVENT_STREAM_SERIALIZER.getAcquire(this);
 247         return existing != null ? existing : loadEventStreamSerializer();
 248     }
 249
 250     // Split out to aid inlining
 251     private DataObjectSerializer loadEventStreamSerializer() {
 252         final DataObjectSerializer loaded = factory().getEventStreamSerializer(getBindingClass());
 253         final Object witness = EVENT_STREAM_SERIALIZER.compareAndExchangeRelease(this, null, loaded);
 254         return witness == null ? loaded : (DataObjectSerializer) witness;
 255     }
 256
 257     @Override
 258     public NormalizedNode serialize(final D data) {
 259         final NormalizedNodeResult result = new NormalizedNodeResult();
 260         // We create DOM stream writer which produces normalized nodes
 261         final NormalizedNodeStreamWriter domWriter = ImmutableNormalizedNodeStreamWriter.from(result);
 262         writeAsNormalizedNode(data, domWriter);
 263         return result.getResult();
 264     }
 265
 266     @Override
 267     public void writeAsNormalizedNode(final D data, final NormalizedNodeStreamWriter writer) {
 268         try {
 269             eventStreamSerializer().serialize(data, createWriter(writer));
 270         } catch (final IOException e) {
 271             throw new IllegalStateException("Failed to serialize Binding DTO",e);
 272         }
 273     }
 274
 275     static final <T extends NormalizedNode> @NonNull T checkDataArgument(final @NonNull Class<T> expectedType,
 276             final NormalizedNode data) {
 277         try {
 278             return expectedType.cast(requireNonNull(data));
 279         } catch (ClassCastException e) {
 280             throw new IllegalArgumentException("Expected " + expectedType.getSimpleName(), e);
 281         }
 282     }
 283
 284     // FIXME: MDSAL-780 replace this method with BindingRuntimeTypes-driven logic
 285     static final Optional<Class<? extends DataContainer>> getYangModeledReturnType(final Method method,
 286             final String prefix) {
 287         final String methodName = method.getName();
 288         if ("getClass".equals(methodName) || !methodName.startsWith(prefix) || method.getParameterCount() > 0) {
 289             return Optional.empty();
 290         }
 291
 292         final Class<?> returnType = method.getReturnType();
 293         if (DataContainer.class.isAssignableFrom(returnType)) {
 294             return optionalDataContainer(returnType);
 295         } else if (List.class.isAssignableFrom(returnType)) {
 296             return getYangModeledReturnType(method, 0);
 297         } else if (Map.class.isAssignableFrom(returnType)) {
 298             return getYangModeledReturnType(method, 1);
 299         }
 300         return Optional.empty();
 301     }
 302
 303     @SuppressWarnings("checkstyle:illegalCatch")
 304     private static Optional<Class<? extends DataContainer>> getYangModeledReturnType(final Method method,
 305             final int parameterOffset) {
 306         try {
 307             return ClassLoaderUtils.callWithClassLoader(method.getDeclaringClass().getClassLoader(),
 308                 () -> genericParameter(method.getGenericReturnType(), parameterOffset)
 309                     .flatMap(result -> result instanceof Class ? optionalCast((Class<?>) result) : Optional.empty()));
 310         } catch (Exception e) {
 311             /*
 312              * It is safe to log this this exception on debug, since this
 313              * method should not fail. Only failures are possible if the
 314              * runtime / backing.
 315              */
 316             LOG.debug("Unable to find YANG modeled return type for {}", method, e);
 317         }
 318         return Optional.empty();
 319     }
 320
 321     private static Optional<java.lang.reflect.Type> genericParameter(final java.lang.reflect.Type type,
 322             final int offset) {
 323         if (type instanceof ParameterizedType parameterized) {
 324             final var parameters = parameterized.getActualTypeArguments();
 325             if (parameters.length > offset) {
 326                 return Optional.of(parameters[offset]);
 327             }
 328         }
 329         return Optional.empty();
 330     }
 331
 332     private static Optional<Class<? extends DataContainer>> optionalCast(final Class<?> type) {
 333         return DataContainer.class.isAssignableFrom(type) ? optionalDataContainer(type) : Optional.empty();
 334     }
 335
 336
 337     // FIXME: MDSAL-780: remove this method
 338     static final Optional<Class<? extends DataContainer>> optionalDataContainer(final Class<?> type) {
 339         return Optional.of(type.asSubclass(DataContainer.class));
 340     }
 341
 342
 343     /**
 344      * Determines if two augmentation classes or case classes represents same data.
 345      *
 346      * <p>
 347      * Two augmentations or cases could be substituted only if and if:
 348      * <ul>
 349      *   <li>Both implements same interfaces</li>
 350      *   <li>Both have same children</li>
 351      *   <li>If augmentations: Both have same augmentation target class. Target class was generated for data node in a
 352      *       grouping.</li>
 353      *   <li>If cases: Both are from same choice. Choice class was generated for data node in grouping.</li>
 354      * </ul>
 355      *
 356      * <p>
 357      * <b>Explanation:</b>
 358      * Binding Specification reuses classes generated for groupings as part of normal data tree, this classes from
 359      * grouping could be used at various locations and user may not be aware of it and may use incorrect case or
 360      * augmentation in particular subtree (via copy constructors, etc).
 361      *
 362      * @param potential Class which is potential substitution
 363      * @param target Class which should be used at particular subtree
 364      * @return true if and only if classes represents same data.
 365      * @throws NullPointerException if any argument is {@code null}
 366      */
 367     // FIXME: MDSAL-785: this really should live in BindingRuntimeTypes and should not be based on reflection. The only
 368     //                   user is binding-dom-codec and the logic could easily be performed on GeneratedType instead. For
 369     //                   a particular world this boils down to a matrix, which can be calculated either on-demand or
 370     //                   when we create BindingRuntimeTypes. Achieving that will bring us one step closer to being able
 371     //                   to have a pre-compiled Binding Runtime.
 372     @SuppressWarnings({ "rawtypes", "unchecked" })
 373     static boolean isSubstitutionFor(final Class potential, final Class target) {
 374         Set<Class> subImplemented = new HashSet<>(Arrays.asList(potential.getInterfaces()));
 375         Set<Class> targetImplemented = new HashSet<>(Arrays.asList(target.getInterfaces()));
 376         if (!subImplemented.equals(targetImplemented)) {
 377             return false;
 378         }
 379         if (Augmentation.class.isAssignableFrom(potential)
 380                 && !BindingReflections.findAugmentationTarget(potential).equals(
 381                         BindingReflections.findAugmentationTarget(target))) {
 382             return false;
 383         }
 384         for (Method potentialMethod : potential.getMethods()) {
 385             if (Modifier.isStatic(potentialMethod.getModifiers())) {
 386                 // Skip any static methods, as we are not interested in those
 387                 continue;
 388             }
 389
 390             try {
 391                 Method targetMethod = target.getMethod(potentialMethod.getName(), potentialMethod.getParameterTypes());
 392                 if (!potentialMethod.getReturnType().equals(targetMethod.getReturnType())) {
 393                     return false;
 394                 }
 395             } catch (NoSuchMethodException e) {
 396                 // Counterpart method is missing, so classes could not be substituted.
 397                 return false;
 398             } catch (SecurityException e) {
 399                 throw new IllegalStateException("Could not compare methods", e);
 400             }
 401         }
 402         return true;
 403     }
 404 }