Deprecate AddedByUsesAware
[yangtools.git] / model / yang-model-spi / src / main / java / org / opendaylight / yangtools / yang / model / spi / meta / 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.model.spi.meta;
9
10 import com.google.common.annotations.Beta;
11 import com.google.common.base.MoreObjects;
12 import com.google.common.base.Strings;
13 import com.google.common.collect.Collections2;
14 import com.google.common.collect.ImmutableSet;
15 import java.util.Collection;
16 import java.util.Optional;
17 import org.eclipse.jdt.annotation.NonNull;
18 import org.eclipse.jdt.annotation.NonNullByDefault;
19 import org.eclipse.jdt.annotation.Nullable;
20 import org.opendaylight.yangtools.concepts.Mutable;
21 import org.opendaylight.yangtools.yang.common.Empty;
22 import org.opendaylight.yangtools.yang.common.QName;
23 import org.opendaylight.yangtools.yang.model.api.ActionDefinition;
24 import org.opendaylight.yangtools.yang.model.api.ActionNodeContainer;
25 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
26 import org.opendaylight.yangtools.yang.model.api.AugmentationSchemaNode;
27 import org.opendaylight.yangtools.yang.model.api.AugmentationTarget;
28 import org.opendaylight.yangtools.yang.model.api.ConstraintMetaDefinition;
29 import org.opendaylight.yangtools.yang.model.api.ContainerLike;
30 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
31 import org.opendaylight.yangtools.yang.model.api.DataNodeContainer;
32 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
33 import org.opendaylight.yangtools.yang.model.api.DerivableSchemaNode;
34 import org.opendaylight.yangtools.yang.model.api.DocumentedNode;
35 import org.opendaylight.yangtools.yang.model.api.GroupingDefinition;
36 import org.opendaylight.yangtools.yang.model.api.InputSchemaNode;
37 import org.opendaylight.yangtools.yang.model.api.MandatoryAware;
38 import org.opendaylight.yangtools.yang.model.api.MustConstraintAware;
39 import org.opendaylight.yangtools.yang.model.api.MustDefinition;
40 import org.opendaylight.yangtools.yang.model.api.NotificationDefinition;
41 import org.opendaylight.yangtools.yang.model.api.NotificationNodeContainer;
42 import org.opendaylight.yangtools.yang.model.api.OperationDefinition;
43 import org.opendaylight.yangtools.yang.model.api.OutputSchemaNode;
44 import org.opendaylight.yangtools.yang.model.api.SchemaNode;
45 import org.opendaylight.yangtools.yang.model.api.Status;
46 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
47 import org.opendaylight.yangtools.yang.model.api.UnknownSchemaNode;
48 import org.opendaylight.yangtools.yang.model.api.UsesNode;
49 import org.opendaylight.yangtools.yang.model.api.WhenConditionAware;
50 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
51 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
52 import org.opendaylight.yangtools.yang.model.api.stmt.DescriptionEffectiveStatement;
53 import org.opendaylight.yangtools.yang.model.api.stmt.ErrorAppTagEffectiveStatement;
54 import org.opendaylight.yangtools.yang.model.api.stmt.ErrorMessageEffectiveStatement;
55 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
56 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
57 import org.opendaylight.yangtools.yang.model.api.stmt.ReferenceEffectiveStatement;
58 import org.opendaylight.yangtools.yang.model.api.stmt.StatusEffectiveStatement;
59 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
60 import org.opendaylight.yangtools.yang.model.api.stmt.WhenEffectiveStatement;
61 import org.opendaylight.yangtools.yang.model.spi.meta.EffectiveStatementMixins.EffectiveStatementWithFlags.FlagsBuilder;
62 import org.opendaylight.yangtools.yang.xpath.api.YangXPathExpression.QualifiedBound;
63
64 /**
65  * Mix-in interfaces providing services required by SchemaNode et al. These interfaces provide implementations, or
66  * implementation helpers based on default methods, so the correct behavior can be logically centralized.
67  */
68 @Beta
69 public final class EffectiveStatementMixins {
70     // Marker interface requiring all mixins to be derived from EffectiveStatement.
71     private interface Mixin<A, D extends DeclaredStatement<A>> extends EffectiveStatement<A, D> {
72         @SuppressWarnings("unchecked")
73         default <T> @NonNull Collection<? extends @NonNull T> filterEffectiveStatements(final Class<T> type) {
74             // Yeah, this is not nice, but saves one transformation
75             return (Collection<? extends T>) Collections2.filter(effectiveSubstatements(), type::isInstance);
76         }
77     }
78
79     /**
80      * Bridge between {@link EffectiveStatement} and {@link AugmentationTarget}.
81      *
82      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
83      * @param <D> Class representing declared version of this statement.
84      */
85     public interface AugmentationTargetMixin<A, D extends DeclaredStatement<A>>
86             extends Mixin<A, D>, AugmentationTarget {
87         @Override
88         default Collection<? extends AugmentationSchemaNode> getAvailableAugmentations() {
89             return filterEffectiveStatements(AugmentationSchemaNode.class);
90         }
91     }
92
93     /**
94      * Bridge between {@link EffectiveStatementWithFlags} and {@link AddedByUsesAware}.
95      *
96      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
97      * @param <D> Class representing declared version of this statement.
98      * @deprecated See deprecation notice in {@link AddedByUsesAware}
99      */
100     @Deprecated(since = "7.0.9")
101     public interface AddedByUsesMixin<A, D extends DeclaredStatement<A>>
102             extends EffectiveStatementWithFlags<A, D>, AddedByUsesAware {
103         @Override
104         @Deprecated(since = "7.0.9")
105         default boolean isAddedByUses() {
106             return (flags() & FlagsBuilder.ADDED_BY_USES) != 0;
107         }
108     }
109
110     /**
111      * Bridge between {@link EffectiveStatementWithFlags} and {@link ActionNodeContainer}.
112      *
113      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
114      * @param <D> Class representing declared version of this statement.
115      */
116     public interface ActionNodeContainerMixin<A, D extends DeclaredStatement<A>>
117             extends Mixin<A, D>, ActionNodeContainer {
118         @Override
119         default Collection<? extends ActionDefinition> getActions() {
120             return filterEffectiveStatements(ActionDefinition.class);
121         }
122     }
123
124     /**
125      * Bridge between {@link EffectiveStatementWithFlags} and {@link NotificationNodeContainer}.
126      *
127      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
128      * @param <D> Class representing declared version of this statement.
129      */
130     public interface NotificationNodeContainerMixin<A, D extends DeclaredStatement<A>>
131             extends Mixin<A, D>, NotificationNodeContainer {
132         @Override
133         default Collection<? extends NotificationDefinition> getNotifications() {
134             return filterEffectiveStatements(NotificationDefinition.class);
135         }
136     }
137
138     /**
139      * Bridge between {@link EffectiveStatementWithFlags} and {@link MustConstraintAware}.
140      *
141      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
142      * @param <D> Class representing declared version of this statement.
143      */
144     public interface MustConstraintMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, MustConstraintAware {
145         @Override
146         default Collection<? extends @NonNull MustDefinition> getMustConstraints() {
147             return filterEffectiveStatements(MustDefinition.class);
148         }
149     }
150
151     /**
152      * Bridge between {@link EffectiveStatementWithFlags} and {@link CopyableNode}.
153      *
154      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
155      * @param <D> Class representing declared version of this statement.
156      */
157     public interface CopyableMixin<A, D extends DeclaredStatement<A>> extends AddedByUsesMixin<A, D>, CopyableNode {
158         @Override
159         default boolean isAugmenting() {
160             return (flags() & FlagsBuilder.AUGMENTING) != 0;
161         }
162     }
163
164     /**
165      * Bridge between {@link EffectiveStatementWithFlags} and {@link DataNodeContainer}.
166      *
167      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
168      * @param <D> Class representing declared version of this statement.
169      */
170     public interface DataNodeContainerMixin<A, D extends DeclaredStatement<A>> extends DataNodeContainer, Mixin<A, D> {
171         @Override
172         default Collection<? extends TypeDefinition<?>> getTypeDefinitions() {
173             return filterTypeDefinitions(this);
174         }
175
176         @Override
177         default Collection<? extends DataSchemaNode> getChildNodes() {
178             return filterEffectiveStatements(DataSchemaNode.class);
179         }
180
181         @Override
182         default Collection<? extends GroupingDefinition> getGroupings() {
183             return filterEffectiveStatements(GroupingDefinition.class);
184         }
185
186         @Override
187         default Collection<? extends UsesNode> getUses() {
188             return filterEffectiveStatements(UsesNode.class);
189         }
190     }
191
192     /**
193      * Bridge between {@link EffectiveStatementWithFlags} and {@link DataSchemaNode}.
194      *
195      * @param <D> Class representing declared version of this statement.
196      */
197     public interface DataSchemaNodeMixin<D extends DeclaredStatement<QName>>
198             extends DataSchemaNode, CopyableMixin<QName, D>, SchemaNodeMixin<D>, WhenConditionMixin<QName, D> {
199         @Override
200         default Optional<Boolean> effectiveConfig() {
201             final int fl = flags() & FlagsBuilder.MASK_CONFIG;
202             switch (fl) {
203                 case FlagsBuilder.CONFIG_FALSE:
204                     return Optional.of(Boolean.FALSE);
205                 case FlagsBuilder.CONFIG_TRUE:
206                     return Optional.of(Boolean.TRUE);
207                 case FlagsBuilder.CONFIG_UNDEF:
208                     return Optional.empty();
209                 default:
210                     throw new IllegalStateException("Unhandled effective config flags " + fl);
211             }
212         }
213     }
214
215     /**
216      * Bridge between {@link EffectiveStatementWithFlags} and {@link DocumentedNode}.
217      *
218      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
219      * @param <D> Class representing declared version of this statement.
220      */
221     public interface DocumentedNodeMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, DocumentedNode {
222         /**
223          * Bridge between {@link EffectiveStatementWithFlags} and
224          * {@link org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus}.
225          *
226          * @param <A> Argument type ({@link Empty} if statement does not have argument.)
227          * @param <D> Class representing declared version of this statement.
228          */
229         interface WithStatus<A, D extends DeclaredStatement<A>>
230                 extends EffectiveStatementWithFlags<A, D>, DocumentedNodeMixin<A, D>, DocumentedNode.WithStatus {
231             @Override
232             default Status getStatus() {
233                 final int status = flags() & FlagsBuilder.MASK_STATUS;
234                 switch (status) {
235                     case FlagsBuilder.STATUS_CURRENT:
236                         return Status.CURRENT;
237                     case FlagsBuilder.STATUS_DEPRECATED:
238                         return Status.DEPRECATED;
239                     case FlagsBuilder.STATUS_OBSOLETE:
240                         return Status.OBSOLETE;
241                     default:
242                         throw new IllegalStateException("Illegal status " + status);
243                 }
244             }
245         }
246
247         @Override
248         default Optional<String> getDescription() {
249             return findFirstEffectiveSubstatementArgument(DescriptionEffectiveStatement.class);
250         }
251
252         @Override
253         default Optional<String> getReference() {
254             return findFirstEffectiveSubstatementArgument(ReferenceEffectiveStatement.class);
255         }
256
257         @Override
258         default Collection<? extends UnknownSchemaNode> getUnknownSchemaNodes() {
259             return filterEffectiveStatements(UnknownSchemaNode.class);
260         }
261     }
262
263     /**
264      * Bridge between {@link EffectiveStatementWithFlags} and {@link ConstraintMetaDefinition}.
265      *
266      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
267      * @param <D> Class representing declared version of this statement.
268      */
269     public interface ConstraintMetaDefinitionMixin<A, D extends DeclaredStatement<A>> extends DocumentedNodeMixin<A, D>,
270             ConstraintMetaDefinition {
271         @Override
272         default Optional<String> getErrorAppTag() {
273             return findFirstEffectiveSubstatementArgument(ErrorAppTagEffectiveStatement.class);
274         }
275
276         @Override
277         default Optional<String> getErrorMessage() {
278             return findFirstEffectiveSubstatementArgument(ErrorMessageEffectiveStatement.class);
279         }
280     }
281
282     /**
283      * Bridge between {@link EffectiveStatementWithFlags} and {@link MandatoryAware}.
284      *
285      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
286      * @param <D> Class representing declared version of this statement.
287      */
288     public interface MandatoryMixin<A, D extends DeclaredStatement<A>>
289             extends EffectiveStatementWithFlags<A, D>, MandatoryAware {
290         @Override
291         default boolean isMandatory() {
292             return (flags() & FlagsBuilder.MANDATORY) != 0;
293         }
294     }
295
296     /**
297      * Bridge between {@link EffectiveStatementWithFlags} and {@code presence} statement.
298      *
299      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
300      * @param <D> Class representing declared version of this statement.
301      */
302     public interface PresenceMixin<A, D extends DeclaredStatement<A>> extends EffectiveStatementWithFlags<A, D> {
303         default boolean presence() {
304             return (flags() & FlagsBuilder.PRESENCE) != 0;
305         }
306     }
307
308     /**
309      * Bridge between {@link EffectiveStatementWithFlags} and {@link SchemaNode}.
310      *
311      * @param <D> Class representing declared version of this statement.
312      */
313     public interface SchemaNodeMixin<D extends DeclaredStatement<QName>>
314             extends DocumentedNodeMixin.WithStatus<QName, D>, SchemaNode {
315         @Override
316         default QName getQName() {
317             return argument();
318         }
319     }
320
321     /**
322      * Bridge between {@link EffectiveStatementWithFlags} and {@link UnknownSchemaNode}.
323      *
324      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
325      * @param <D> Class representing declared version of this statement.
326      */
327     public interface UnknownSchemaNodeMixin<A, D extends DeclaredStatement<A>>
328             extends DocumentedNodeMixin.WithStatus<A, D>, CopyableMixin<A, D>, UnknownSchemaNode {
329         @Override
330         default String getNodeParameter() {
331             return Strings.nullToEmpty(getDeclared().rawArgument());
332         }
333     }
334
335     /**
336      * Bridge between {@link EffectiveStatementWithFlags} and {@code ordered-by} statement.
337      *
338      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
339      * @param <D> Class representing declared version of this statement.
340      */
341     public interface UserOrderedMixin<A, D extends DeclaredStatement<A>> extends EffectiveStatementWithFlags<A, D> {
342         default boolean userOrdered() {
343             return (flags() & FlagsBuilder.USER_ORDERED) != 0;
344         }
345     }
346
347     /**
348      * Helper used to locate the effective {@code when} statement and exposing its argument as per
349      * {@link WhenConditionAware}.
350      *
351      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
352      * @param <D> Class representing declared version of this statement.
353      */
354     public interface WhenConditionMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, WhenConditionAware {
355         @Override
356         default Optional<QualifiedBound> getWhenCondition() {
357             return findFirstEffectiveSubstatementArgument(WhenEffectiveStatement.class);
358         }
359     }
360
361     /**
362      * Helper bridge for operation containers ({@code input} and {@code output}).
363      *
364      * @param <D> Class representing declared version of this statement.
365      */
366     public interface OperationContainerMixin<D extends DeclaredStatement<QName>>
367             extends ContainerLike, DocumentedNodeMixin.WithStatus<QName, D>, DataNodeContainerMixin<QName, D>,
368                     MustConstraintMixin<QName, D>, WhenConditionMixin<QName, D>, AugmentationTargetMixin<QName, D>,
369                     SchemaNodeMixin<D>, CopyableMixin<QName, D> {
370         @Override
371         default Optional<ActionDefinition> findAction(final QName qname) {
372             return Optional.empty();
373         }
374
375         @Override
376         default Optional<NotificationDefinition> findNotification(final QName qname) {
377             return Optional.empty();
378         }
379
380         @Override
381         default Collection<? extends ActionDefinition> getActions() {
382             return ImmutableSet.of();
383         }
384
385         @Override
386         default Collection<? extends NotificationDefinition> getNotifications() {
387             return ImmutableSet.of();
388         }
389
390         @Override
391         default Optional<Boolean> effectiveConfig() {
392             return Optional.empty();
393         }
394
395         default String defaultToString() {
396             return MoreObjects.toStringHelper(this).add("qname", getQName()).toString();
397         }
398     }
399
400     /**
401      * Helper bridge for {@code anydata} and {@code anyxml} opaque data.
402      *
403      * @param <D> Class representing declared version of this statement.
404      */
405     public interface OpaqueDataSchemaNodeMixin<D extends DeclaredStatement<QName>, S extends DerivableSchemaNode<S>>
406             extends DerivableSchemaNode<S>, DataSchemaNodeMixin<D>, DocumentedNodeMixin.WithStatus<QName, D>,
407                     MandatoryMixin<QName, D>, MustConstraintMixin<QName, D>, WhenConditionMixin<QName, D> {
408         @Override
409         default QName getQName() {
410             return argument();
411         }
412     }
413
414     /**
415      * Helper bridge for {@code rpc} and {@code action} operations.
416      *
417      * @param <D> Class representing declared version of this statement.
418      */
419     public interface OperationDefinitionMixin<D extends DeclaredStatement<QName>>
420             extends SchemaNodeMixin<D>, OperationDefinition {
421         @Override
422         default Collection<? extends @NonNull TypeDefinition<?>> getTypeDefinitions() {
423             return filterTypeDefinitions(this);
424         }
425
426         @Override
427         default Collection<? extends @NonNull GroupingDefinition> getGroupings() {
428             return filterEffectiveStatements(GroupingDefinition.class);
429         }
430
431         @Override
432         default InputSchemaNode getInput() {
433             return findAsContainer(this, InputEffectiveStatement.class, InputSchemaNode.class);
434         }
435
436         @Override
437         default OutputSchemaNode getOutput() {
438             return findAsContainer(this, OutputEffectiveStatement.class, OutputSchemaNode.class);
439         }
440     }
441
442     /**
443      * Support interface for various mixins. Implementations are required to store 32bits worth of flags, which are
444      * globally assigned to sub-interfaces -- thus providing storage for many low-cardinality properties.
445      *
446      * @param <A> Argument type ({@link Empty} if statement does not have argument.)
447      * @param <D> Class representing declared version of this statement.
448      */
449     public interface EffectiveStatementWithFlags<A, D extends DeclaredStatement<A>> extends Mixin<A, D> {
450         /**
451          * Return flags associated with this statements. Flags can be built using {@link FlagsBuilder}.
452          *
453          * @return Flag field value (32 bits).
454          */
455         int flags();
456
457         @NonNullByDefault
458         final class FlagsBuilder implements Mutable {
459             // We still have 23 flags remaining
460             static final int STATUS_CURRENT       = 0x0001;
461             static final int STATUS_DEPRECATED    = 0x0002;
462             static final int STATUS_OBSOLETE      = 0x0003;
463             static final int MASK_STATUS          = 0x0003;
464
465             static final int MANDATORY            = 0x0004;
466
467             static final int AUGMENTING           = 0x0010;
468             @Deprecated(since = "7.0.9")
469             static final int ADDED_BY_USES        = 0x0020;
470             private static final int MASK_HISTORY = 0x0030;
471
472             static final int USER_ORDERED         = 0x0040;
473             static final int PRESENCE             = 0x0080;
474
475             static final int CONFIG_UNDEF         = 0x0100;
476             static final int CONFIG_FALSE         = 0x0200;
477             static final int CONFIG_TRUE          = 0x0300;
478             static final int MASK_CONFIG          = CONFIG_TRUE;
479
480             private int flags;
481
482             public FlagsBuilder setConfiguration(final @Nullable Boolean config) {
483                 final int fl;
484                 if (config != null) {
485                     fl = config ? CONFIG_TRUE : CONFIG_FALSE;
486                 } else {
487                     fl = CONFIG_UNDEF;
488                 }
489                 flags = flags & ~MASK_CONFIG | fl;
490                 return this;
491             }
492
493             public FlagsBuilder setHistory(final CopyableNode history) {
494                 flags = flags & ~MASK_HISTORY
495                     | (history.isAugmenting() ? AUGMENTING : 0) | (history.isAddedByUses() ? ADDED_BY_USES : 0);
496                 return this;
497             }
498
499             public FlagsBuilder setMandatory(final boolean mandatory) {
500                 if (mandatory) {
501                     flags |= MANDATORY;
502                 } else {
503                     flags &= ~MANDATORY;
504                 }
505                 return this;
506             }
507
508             public FlagsBuilder setPresence(final boolean presence) {
509                 if (presence) {
510                     flags |= PRESENCE;
511                 } else {
512                     flags &= ~PRESENCE;
513                 }
514                 return this;
515             }
516
517             public FlagsBuilder setStatus(final Status status) {
518                 final int bits;
519                 switch (status) {
520                     case CURRENT:
521                         bits = STATUS_CURRENT;
522                         break;
523                     case DEPRECATED:
524                         bits = STATUS_DEPRECATED;
525                         break;
526                     case OBSOLETE:
527                         bits = STATUS_OBSOLETE;
528                         break;
529                     default:
530                         throw new IllegalStateException("Unhandled status " + status);
531                 }
532
533                 flags = flags & ~MASK_STATUS | bits;
534                 return this;
535             }
536
537             public FlagsBuilder setUserOrdered(final boolean userOrdered) {
538                 if (userOrdered) {
539                     flags |= USER_ORDERED;
540                 } else {
541                     flags &= ~USER_ORDERED;
542                 }
543                 return this;
544             }
545
546             public int toFlags() {
547                 return flags;
548             }
549         }
550     }
551
552     private EffectiveStatementMixins() {
553     }
554
555     static <T extends ContainerLike> T findAsContainer(final EffectiveStatement<?, ?> stmt,
556             final Class<? extends EffectiveStatement<QName, ?>> type, final Class<T> target) {
557         return target.cast(stmt.findFirstEffectiveSubstatement(type).get());
558     }
559
560     static Collection<? extends @NonNull TypeDefinition<?>> filterTypeDefinitions(final Mixin<?, ?> stmt) {
561         return Collections2.transform(stmt.filterEffectiveStatements(TypedefEffectiveStatement.class),
562             TypedefEffectiveStatement::getTypeDefinition);
563     }
564
565     public static int historyAndStatusFlags(final CopyableNode history,
566             final Collection<? extends EffectiveStatement<?, ?>> substatements) {
567         return new FlagsBuilder()
568                 .setHistory(history)
569                 .setStatus(substatements.stream()
570                     .filter(StatusEffectiveStatement.class::isInstance)
571                     .findAny()
572                     .map(stmt -> ((StatusEffectiveStatement) stmt).argument())
573                     .orElse(Status.CURRENT))
574                 .toFlags();
575     }
576 }