yang/yang-parser-rfc7950/src/main/java/org/opendaylight/yangtools/yang/parser/rfc7950/stmt/EffectiveStatementMixins.java

   1 /*
   2  * Copyright (c) 2020 PANTHEON.tech, s.r.o. 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.yangtools.yang.parser.rfc7950.stmt;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.base.MoreObjects;
  12 import com.google.common.collect.Collections2;
  13 import com.google.common.collect.ImmutableSet;
  14 import java.util.Collection;
  15 import java.util.Optional;
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18 import org.opendaylight.yangtools.concepts.Mutable;
  19 import org.opendaylight.yangtools.yang.common.QName;
  20 import org.opendaylight.yangtools.yang.model.api.ActionDefinition;
  21 import org.opendaylight.yangtools.yang.model.api.ActionNodeContainer;
  22 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
  23 import org.opendaylight.yangtools.yang.model.api.AugmentationSchemaNode;
  24 import org.opendaylight.yangtools.yang.model.api.AugmentationTarget;
  25 import org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode;
  26 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
  27 import org.opendaylight.yangtools.yang.model.api.DataNodeContainer;
  28 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  29 import org.opendaylight.yangtools.yang.model.api.DocumentedNode;
  30 import org.opendaylight.yangtools.yang.model.api.GroupingDefinition;
  31 import org.opendaylight.yangtools.yang.model.api.MandatoryAware;
  32 import org.opendaylight.yangtools.yang.model.api.MustConstraintAware;
  33 import org.opendaylight.yangtools.yang.model.api.MustDefinition;
  34 import org.opendaylight.yangtools.yang.model.api.NotificationDefinition;
  35 import org.opendaylight.yangtools.yang.model.api.NotificationNodeContainer;
  36 import org.opendaylight.yangtools.yang.model.api.RevisionAwareXPath;
  37 import org.opendaylight.yangtools.yang.model.api.SchemaNode;
  38 import org.opendaylight.yangtools.yang.model.api.Status;
  39 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
  40 import org.opendaylight.yangtools.yang.model.api.UnknownSchemaNode;
  41 import org.opendaylight.yangtools.yang.model.api.UsesNode;
  42 import org.opendaylight.yangtools.yang.model.api.WhenConditionAware;
  43 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  44 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  45 import org.opendaylight.yangtools.yang.model.api.stmt.DescriptionEffectiveStatement;
  46 import org.opendaylight.yangtools.yang.model.api.stmt.ReferenceEffectiveStatement;
  47 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
  48 import org.opendaylight.yangtools.yang.model.api.stmt.WhenEffectiveStatement;
  49 import org.opendaylight.yangtools.yang.parser.spi.meta.CopyHistory;
  50 import org.opendaylight.yangtools.yang.parser.spi.meta.CopyType;
  51
  52 /**
  53  * Mix-in interfaces providing services required by SchemaNode et al. These interfaces provide implementations, or
  54  * implementation helpers based on default methods, so the correct behavior can be logically centralized.
  55  */
  56 @Beta
  57 public final class EffectiveStatementMixins {
  58     // Marker interface requiring all mixins to be derived from EffectiveStatement.
  59     private interface Mixin<A, D extends DeclaredStatement<A>> extends EffectiveStatement<A, D> {
  60         @SuppressWarnings("unchecked")
  61         default <T> Collection<? extends T> filterEffectiveStatements(final Class<T> type) {
  62             // Yeah, this is not nice, but saves one transformation
  63             return (Collection<? extends T>) Collections2.filter(effectiveSubstatements(), type::isInstance);
  64         }
  65     }
  66
  67     /**
  68      * Bridge between {@link EffectiveStatement} and {@link AugmentationTarget}.
  69      *
  70      * @param <A> Argument type ({@link Void} if statement does not have argument.)
  71      * @param <D> Class representing declared version of this statement.
  72      */
  73     public interface AugmentationTargetMixin<A, D extends DeclaredStatement<A>>
  74             extends Mixin<A, D>, AugmentationTarget {
  75         @Override
  76         default Collection<? extends AugmentationSchemaNode> getAvailableAugmentations() {
  77             return filterEffectiveStatements(AugmentationSchemaNode.class);
  78         }
  79     }
  80
  81     /**
  82      * Bridge between {@link EffectiveStatementWithFlags} and {@link AddedByUsesAware}.
  83      *
  84      * @param <A> Argument type ({@link Void} if statement does not have argument.)
  85      * @param <D> Class representing declared version of this statement.
  86      */
  87     public interface AddedByUsesMixin<A, D extends DeclaredStatement<A>>
  88             extends EffectiveStatementWithFlags<A, D>, AddedByUsesAware {
  89         @Override
  90         default boolean isAddedByUses() {
  91             return (flags() & FlagsBuilder.ADDED_BY_USES) != 0;
  92         }
  93     }
  94
  95     /**
  96      * Bridge between {@link EffectiveStatementWithFlags} and {@link ActionNodeContainer}.
  97      *
  98      * @param <A> Argument type ({@link Void} if statement does not have argument.)
  99      * @param <D> Class representing declared version of this statement.
 100      */
 101     public interface ActionNodeContainerMixin<A, D extends DeclaredStatement<A>>
 102             extends Mixin<A, D>, ActionNodeContainer {
 103         @Override
 104         default Collection<? extends ActionDefinition> getActions() {
 105             return filterEffectiveStatements(ActionDefinition.class);
 106         }
 107     }
 108
 109     /**
 110      * Bridge between {@link EffectiveStatementWithFlags} and {@link NotificationNodeContainer}.
 111      *
 112      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 113      * @param <D> Class representing declared version of this statement.
 114      */
 115     public interface NotificationNodeContainerMixin<A, D extends DeclaredStatement<A>>
 116             extends Mixin<A, D>, NotificationNodeContainer {
 117         @Override
 118         default Collection<? extends NotificationDefinition> getNotifications() {
 119             return filterEffectiveStatements(NotificationDefinition.class);
 120         }
 121     }
 122
 123     /**
 124      * Bridge between {@link EffectiveStatementWithFlags} and {@link MustConstraintAware}.
 125      *
 126      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 127      * @param <D> Class representing declared version of this statement.
 128      */
 129     public interface MustConstraintMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, MustConstraintAware {
 130         @Override
 131         default Collection<? extends MustDefinition> getMustConstraints() {
 132             return filterEffectiveStatements(MustDefinition.class);
 133         }
 134     }
 135
 136     /**
 137      * Bridge between {@link EffectiveStatementWithFlags} and {@link CopyableNode}.
 138      *
 139      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 140      * @param <D> Class representing declared version of this statement.
 141      */
 142     public interface CopyableMixin<A, D extends DeclaredStatement<A>> extends AddedByUsesMixin<A, D>, CopyableNode {
 143         @Override
 144         default boolean isAugmenting() {
 145             return (flags() & FlagsBuilder.AUGMENTING) != 0;
 146         }
 147     }
 148
 149     /**
 150      * Bridge between {@link EffectiveStatementWithFlags} and {@link DataNodeContainer}.
 151      *
 152      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 153      * @param <D> Class representing declared version of this statement.
 154      */
 155     public interface DataNodeContainerMixin<A, D extends DeclaredStatement<A>> extends DataNodeContainer, Mixin<A, D> {
 156         @Override
 157         default Collection<? extends TypeDefinition<?>> getTypeDefinitions() {
 158             // TODO: the cast here is needed to work around Java 11 javac type inference issue
 159             return Collections2.transform(filterEffectiveStatements(TypedefEffectiveStatement.class),
 160                 TypedefEffectiveStatement::getTypeDefinition);
 161         }
 162
 163         @Override
 164         default Collection<? extends DataSchemaNode> getChildNodes() {
 165             return filterEffectiveStatements(DataSchemaNode.class);
 166         }
 167
 168         @Override
 169         default Collection<? extends GroupingDefinition> getGroupings() {
 170             return filterEffectiveStatements(GroupingDefinition.class);
 171         }
 172
 173         @Override
 174         default Collection<? extends UsesNode> getUses() {
 175             return filterEffectiveStatements(UsesNode.class);
 176         }
 177     }
 178
 179     /**
 180      * Bridge between {@link EffectiveStatementWithFlags} and {@link DataSchemaNode}.
 181      *
 182      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 183      * @param <D> Class representing declared version of this statement.
 184      */
 185     public interface DataSchemaNodeMixin<A, D extends DeclaredStatement<A>>
 186             extends DataSchemaNode, CopyableMixin<A, D>, SchemaNodeMixin<A, D>, WhenConditionMixin<A, D> {
 187         @Override
 188         default boolean isConfiguration() {
 189             return (flags() & FlagsBuilder.CONFIGURATION) != 0;
 190         }
 191     }
 192
 193     /**
 194      * Bridge between {@link EffectiveStatementWithFlags} and {@link DocumentedNode}.
 195      *
 196      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 197      * @param <D> Class representing declared version of this statement.
 198      */
 199     public interface DocumentedNodeMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, DocumentedNode {
 200         /**
 201          * Bridge between {@link EffectiveStatementWithFlags} and
 202          * {@link org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus}.
 203          *
 204          * @param <A> Argument type ({@link Void} if statement does not have argument.)
 205          * @param <D> Class representing declared version of this statement.
 206          */
 207         interface WithStatus<A, D extends DeclaredStatement<A>>
 208                 extends EffectiveStatementWithFlags<A, D>, DocumentedNodeMixin<A, D>, DocumentedNode.WithStatus {
 209             @Override
 210             default Status getStatus() {
 211                 final int status = flags() & FlagsBuilder.MASK_STATUS;
 212                 switch (status) {
 213                     case FlagsBuilder.STATUS_CURRENT:
 214                         return Status.CURRENT;
 215                     case FlagsBuilder.STATUS_DEPRECATED:
 216                         return Status.DEPRECATED;
 217                     case FlagsBuilder.STATUS_OBSOLETE:
 218                         return Status.OBSOLETE;
 219                     default:
 220                         throw new IllegalStateException("Illegal status " + status);
 221                 }
 222             }
 223         }
 224
 225         @Override
 226         default Optional<String> getDescription() {
 227             return findFirstEffectiveSubstatementArgument(DescriptionEffectiveStatement.class);
 228         }
 229
 230         @Override
 231         default Optional<String> getReference() {
 232             return findFirstEffectiveSubstatementArgument(ReferenceEffectiveStatement.class);
 233         }
 234
 235         @Override
 236         default Collection<? extends UnknownSchemaNode> getUnknownSchemaNodes() {
 237             return filterEffectiveStatements(UnknownSchemaNode.class);
 238         }
 239     }
 240
 241     /**
 242      * Bridge between {@link EffectiveStatementWithFlags} and {@link MandatoryAware}.
 243      *
 244      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 245      * @param <D> Class representing declared version of this statement.
 246      */
 247     public interface MandatoryMixin<A, D extends DeclaredStatement<A>>
 248             extends EffectiveStatementWithFlags<A, D>, MandatoryAware {
 249         @Override
 250         default boolean isMandatory() {
 251             return (flags() & FlagsBuilder.MANDATORY) != 0;
 252         }
 253     }
 254
 255     /**
 256      * Bridge between {@link EffectiveStatementWithFlags} and {@code presence} statement.
 257      *
 258      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 259      * @param <D> Class representing declared version of this statement.
 260      */
 261     public interface PresenceMixin<A, D extends DeclaredStatement<A>> extends EffectiveStatementWithFlags<A, D> {
 262         default boolean presence() {
 263             return (flags() & FlagsBuilder.PRESENCE) != 0;
 264         }
 265     }
 266
 267     /**
 268      * Bridge between {@link EffectiveStatementWithFlags} and {@link SchemaNode}.
 269      *
 270      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 271      * @param <D> Class representing declared version of this statement.
 272      */
 273     public interface SchemaNodeMixin<A, D extends DeclaredStatement<A>>
 274             extends DocumentedNodeMixin.WithStatus<A, D>, SchemaNode {
 275         @Override
 276         default QName getQName() {
 277             return getPath().getLastComponent();
 278         }
 279     }
 280
 281     /**
 282      * Bridge between {@link EffectiveStatementWithFlags} and {@code ordered-by} statement.
 283      *
 284      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 285      * @param <D> Class representing declared version of this statement.
 286      */
 287     public interface UserOrderedMixin<A, D extends DeclaredStatement<A>> extends EffectiveStatementWithFlags<A, D> {
 288         default boolean userOrdered() {
 289             return (flags() & FlagsBuilder.USER_ORDERED) != 0;
 290         }
 291     }
 292
 293     /**
 294      * Helper used to locate the effective {@code when} statement and exposing its argument as per
 295      * {@link WhenConditionAware}.
 296      *
 297      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 298      * @param <D> Class representing declared version of this statement.
 299      */
 300     public interface WhenConditionMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, WhenConditionAware {
 301         @Override
 302         default Optional<RevisionAwareXPath> getWhenCondition() {
 303             return findFirstEffectiveSubstatementArgument(WhenEffectiveStatement.class);
 304         }
 305     }
 306
 307     /**
 308      * Helper bridge for operation containers ({@code input} and {@code output}).
 309      *
 310      * @param <D> Class representing declared version of this statement.
 311      */
 312     @Beta
 313     public interface OperationContainerMixin<D extends DeclaredStatement<QName>>
 314             extends ContainerSchemaNode, DocumentedNodeMixin.WithStatus<QName, D>, DataNodeContainerMixin<QName, D>,
 315                     MustConstraintMixin<QName, D>, WhenConditionMixin<QName, D>, AugmentationTargetMixin<QName, D>,
 316                     CopyableMixin<QName, D> {
 317         @Override
 318         default @NonNull QName argument() {
 319             return getPath().getLastComponent();
 320         }
 321
 322         @Override
 323         default QName getQName() {
 324             return argument();
 325         }
 326
 327         @Override
 328         default Optional<ActionDefinition> findAction(final QName qname) {
 329             return Optional.empty();
 330         }
 331
 332         @Override
 333         default Optional<NotificationDefinition> findNotification(final QName qname) {
 334             return Optional.empty();
 335         }
 336
 337         @Override
 338         default Collection<? extends ActionDefinition> getActions() {
 339             return ImmutableSet.of();
 340         }
 341
 342         @Override
 343         default Collection<? extends NotificationDefinition> getNotifications() {
 344             return ImmutableSet.of();
 345         }
 346
 347         @Override
 348         default boolean isConfiguration() {
 349             return false;
 350         }
 351
 352         @Override
 353         default boolean isPresenceContainer() {
 354             // FIXME: this should not really be here
 355             return false;
 356         }
 357
 358         default String defaultToString() {
 359             return MoreObjects.toStringHelper(this).add("path", getPath()).toString();
 360         }
 361     }
 362
 363     /**
 364      * Support interface for various mixins. Implementations are required to store 32bits worth of flags, which are
 365      * globally assigned to sub-interfaces -- thus providing storage for many low-cardinality properties.
 366      *
 367      * @param <A> Argument type ({@link Void} if statement does not have argument.)
 368      * @param <D> Class representing declared version of this statement.
 369      */
 370     public interface EffectiveStatementWithFlags<A, D extends DeclaredStatement<A>> extends Mixin<A, D> {
 371         /**
 372          * Return flags assicated with this statements. Flags can be built using {@link FlagsBuilder}.
 373          *
 374          * @return Flag field value (32 bits).
 375          */
 376         int flags();
 377
 378         @NonNullByDefault
 379         final class FlagsBuilder implements Mutable {
 380             // We still have 24 flags remaining
 381             static final int STATUS_CURRENT       = 0x0001;
 382             static final int STATUS_DEPRECATED    = 0x0002;
 383             static final int STATUS_OBSOLETE      = 0x0003;
 384             static final int MASK_STATUS          = 0x0003;
 385
 386             static final int CONFIGURATION        = 0x0004;
 387             static final int MANDATORY            = 0x0008;
 388
 389             static final int AUGMENTING           = 0x0010;
 390             static final int ADDED_BY_USES        = 0x0020;
 391             private static final int MASK_HISTORY = 0x0030;
 392
 393             static final int USER_ORDERED         = 0x0040;
 394             static final int PRESENCE             = 0x0080;
 395
 396             private int flags;
 397
 398             public FlagsBuilder setConfiguration(final boolean config) {
 399                 if (config) {
 400                     flags |= CONFIGURATION;
 401                 } else {
 402                     flags &= ~CONFIGURATION;
 403                 }
 404                 return this;
 405             }
 406
 407             public FlagsBuilder setHistory(final CopyHistory history) {
 408                 int bits;
 409                 if (history.contains(CopyType.ADDED_BY_USES_AUGMENTATION)) {
 410                     bits = AUGMENTING | ADDED_BY_USES;
 411                 } else {
 412                     bits = 0;
 413                     if (history.contains(CopyType.ADDED_BY_AUGMENTATION)) {
 414                         bits |= AUGMENTING;
 415                     }
 416                     if (history.contains(CopyType.ADDED_BY_USES)) {
 417                         bits |= ADDED_BY_USES;
 418                     }
 419                 }
 420
 421                 flags = flags & ~MASK_HISTORY | bits;
 422                 return this;
 423             }
 424
 425             public FlagsBuilder setMandatory(final boolean mandatory) {
 426                 if (mandatory) {
 427                     flags |= MANDATORY;
 428                 } else {
 429                     flags &= ~MANDATORY;
 430                 }
 431                 return this;
 432             }
 433
 434             public FlagsBuilder setPresence(final boolean presence) {
 435                 if (presence) {
 436                     flags |= PRESENCE;
 437                 } else {
 438                     flags &= ~PRESENCE;
 439                 }
 440                 return this;
 441             }
 442
 443             public FlagsBuilder setStatus(final Status status) {
 444                 final int bits;
 445                 switch (status) {
 446                     case CURRENT:
 447                         bits = STATUS_CURRENT;
 448                         break;
 449                     case DEPRECATED:
 450                         bits = STATUS_DEPRECATED;
 451                         break;
 452                     case OBSOLETE:
 453                         bits = STATUS_DEPRECATED;
 454                         break;
 455                     default:
 456                         throw new IllegalStateException("Unhandled status " + status);
 457                 }
 458
 459                 flags = flags & ~MASK_STATUS | bits;
 460                 return this;
 461             }
 462
 463             public FlagsBuilder setUserOrdered(final boolean userOrdered) {
 464                 if (userOrdered) {
 465                     flags |= USER_ORDERED;
 466                 } else {
 467                     flags &= ~USER_ORDERED;
 468                 }
 469                 return this;
 470             }
 471
 472             public int toFlags() {
 473                 return flags;
 474             }
 475         }
 476     }
 477 }