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