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