2 * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others. All rights reserved.
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
8 package org.opendaylight.yangtools.yang.model.spi.meta;
10 import static com.google.common.base.Verify.verifyNotNull;
12 import com.google.common.annotations.Beta;
13 import com.google.common.base.Strings;
14 import com.google.common.collect.Collections2;
15 import com.google.common.collect.ImmutableSet;
16 import java.util.Collection;
17 import java.util.Optional;
18 import org.eclipse.jdt.annotation.NonNull;
19 import org.eclipse.jdt.annotation.NonNullByDefault;
20 import org.eclipse.jdt.annotation.Nullable;
21 import org.opendaylight.yangtools.concepts.Mutable;
22 import org.opendaylight.yangtools.yang.common.Empty;
23 import org.opendaylight.yangtools.yang.common.QName;
24 import org.opendaylight.yangtools.yang.model.api.ActionDefinition;
25 import org.opendaylight.yangtools.yang.model.api.ActionNodeContainer;
26 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
27 import org.opendaylight.yangtools.yang.model.api.AugmentationSchemaNode;
28 import org.opendaylight.yangtools.yang.model.api.AugmentationTarget;
29 import org.opendaylight.yangtools.yang.model.api.ConstraintMetaDefinition;
30 import org.opendaylight.yangtools.yang.model.api.ContainerLike;
31 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
32 import org.opendaylight.yangtools.yang.model.api.DataNodeContainer;
33 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
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.UserOrderedAware;
49 import org.opendaylight.yangtools.yang.model.api.UsesNode;
50 import org.opendaylight.yangtools.yang.model.api.WhenConditionAware;
51 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
52 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
53 import org.opendaylight.yangtools.yang.model.api.stmt.DescriptionEffectiveStatement;
54 import org.opendaylight.yangtools.yang.model.api.stmt.ErrorAppTagEffectiveStatement;
55 import org.opendaylight.yangtools.yang.model.api.stmt.ErrorMessageEffectiveStatement;
56 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
57 import org.opendaylight.yangtools.yang.model.api.stmt.OrderedByAwareEffectiveStatement;
58 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
59 import org.opendaylight.yangtools.yang.model.api.stmt.ReferenceEffectiveStatement;
60 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
61 import org.opendaylight.yangtools.yang.model.api.stmt.WhenEffectiveStatement;
62 import org.opendaylight.yangtools.yang.xpath.api.YangXPathExpression.QualifiedBound;
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.
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);
80 * Bridge between {@link EffectiveStatement} and {@link AugmentationTarget}.
82 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
83 * @param <D> Class representing declared version of this statement.
85 public interface AugmentationTargetMixin<A, D extends DeclaredStatement<A>>
86 extends Mixin<A, D>, AugmentationTarget {
88 default Collection<? extends AugmentationSchemaNode> getAvailableAugmentations() {
89 return filterEffectiveStatements(AugmentationSchemaNode.class);
94 * Bridge between {@link EffectiveStatementWithFlags} and {@link AddedByUsesAware}.
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}
100 @Deprecated(since = "7.0.9", forRemoval = true)
101 public interface AddedByUsesMixin<A, D extends DeclaredStatement<A>>
102 extends EffectiveStatementWithFlags<A, D>, AddedByUsesAware {
104 @Deprecated(since = "7.0.9", forRemoval = true)
105 default boolean isAddedByUses() {
106 return (flags() & FlagsBuilder.ADDED_BY_USES) != 0;
111 * Bridge between {@link EffectiveStatementWithFlags} and {@link ActionNodeContainer}.
113 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
114 * @param <D> Class representing declared version of this statement.
116 public interface ActionNodeContainerMixin<A, D extends DeclaredStatement<A>>
117 extends Mixin<A, D>, ActionNodeContainer {
119 default Collection<? extends ActionDefinition> getActions() {
120 return filterEffectiveStatements(ActionDefinition.class);
125 * Bridge between {@link EffectiveStatementWithFlags} and {@link NotificationNodeContainer}.
127 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
128 * @param <D> Class representing declared version of this statement.
130 public interface NotificationNodeContainerMixin<A, D extends DeclaredStatement<A>>
131 extends Mixin<A, D>, NotificationNodeContainer {
133 default Collection<? extends NotificationDefinition> getNotifications() {
134 return filterEffectiveStatements(NotificationDefinition.class);
139 * Bridge between {@link EffectiveStatementWithFlags} and {@link MustConstraintAware}.
141 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
142 * @param <D> Class representing declared version of this statement.
144 public interface MustConstraintMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, MustConstraintAware {
146 default Collection<? extends @NonNull MustDefinition> getMustConstraints() {
147 return filterEffectiveStatements(MustDefinition.class);
152 * Bridge between {@link EffectiveStatementWithFlags} and {@link CopyableNode}.
154 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
155 * @param <D> Class representing declared version of this statement.
156 * @deprecated Scheduled for removal with {@link CopyableNode}.
158 @Deprecated(since = "8.0.0")
159 public interface CopyableMixin<A, D extends DeclaredStatement<A>> extends AddedByUsesMixin<A, D>, CopyableNode {
161 @Deprecated(since = "8.0.0")
162 default boolean isAugmenting() {
163 return (flags() & FlagsBuilder.AUGMENTING) != 0;
168 * Bridge between {@link EffectiveStatementWithFlags} and {@link DataNodeContainer}.
170 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
171 * @param <D> Class representing declared version of this statement.
173 public interface DataNodeContainerMixin<A, D extends DeclaredStatement<A>> extends DataNodeContainer, Mixin<A, D> {
175 default Collection<? extends TypeDefinition<?>> getTypeDefinitions() {
176 return filterTypeDefinitions(this);
180 default Collection<? extends DataSchemaNode> getChildNodes() {
181 return filterEffectiveStatements(DataSchemaNode.class);
185 default Collection<? extends GroupingDefinition> getGroupings() {
186 return filterEffectiveStatements(GroupingDefinition.class);
190 default Collection<? extends UsesNode> getUses() {
191 return filterEffectiveStatements(UsesNode.class);
196 * Bridge between {@link EffectiveStatementWithFlags} and {@link DataSchemaNode}.
198 * @param <D> Class representing declared version of this statement.
200 public interface DataSchemaNodeMixin<D extends DeclaredStatement<QName>>
201 extends DataSchemaNode, CopyableMixin<QName, D>, SchemaNodeMixin<D>, WhenConditionMixin<QName, D> {
203 default Optional<Boolean> effectiveConfig() {
204 final int fl = flags() & FlagsBuilder.MASK_CONFIG;
206 case FlagsBuilder.CONFIG_FALSE:
207 return Optional.of(Boolean.FALSE);
208 case FlagsBuilder.CONFIG_TRUE:
209 return Optional.of(Boolean.TRUE);
210 case FlagsBuilder.CONFIG_UNDEF:
211 return Optional.empty();
213 throw new IllegalStateException("Unhandled effective config flags " + fl);
219 * Bridge between {@link EffectiveStatementWithFlags} and {@link DocumentedNode}.
221 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
222 * @param <D> Class representing declared version of this statement.
224 public interface DocumentedNodeMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, DocumentedNode {
226 * Bridge between {@link EffectiveStatementWithFlags} and
227 * {@link org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus}.
229 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
230 * @param <D> Class representing declared version of this statement.
232 interface WithStatus<A, D extends DeclaredStatement<A>>
233 extends EffectiveStatementWithFlags<A, D>, DocumentedNodeMixin<A, D>, DocumentedNode.WithStatus {
235 default Status getStatus() {
236 final int status = flags() & FlagsBuilder.MASK_STATUS;
238 case FlagsBuilder.STATUS_CURRENT:
239 return Status.CURRENT;
240 case FlagsBuilder.STATUS_DEPRECATED:
241 return Status.DEPRECATED;
242 case FlagsBuilder.STATUS_OBSOLETE:
243 return Status.OBSOLETE;
245 throw new IllegalStateException("Illegal status " + status);
251 default Optional<String> getDescription() {
252 return findFirstEffectiveSubstatementArgument(DescriptionEffectiveStatement.class);
256 default Optional<String> getReference() {
257 return findFirstEffectiveSubstatementArgument(ReferenceEffectiveStatement.class);
261 default Collection<? extends UnknownSchemaNode> getUnknownSchemaNodes() {
262 return filterEffectiveStatements(UnknownSchemaNode.class);
267 * Bridge between {@link EffectiveStatementWithFlags} and {@link ConstraintMetaDefinition}.
269 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
270 * @param <D> Class representing declared version of this statement.
272 public interface ConstraintMetaDefinitionMixin<A, D extends DeclaredStatement<A>> extends DocumentedNodeMixin<A, D>,
273 ConstraintMetaDefinition {
275 default Optional<String> getErrorAppTag() {
276 return findFirstEffectiveSubstatementArgument(ErrorAppTagEffectiveStatement.class);
280 default Optional<String> getErrorMessage() {
281 return findFirstEffectiveSubstatementArgument(ErrorMessageEffectiveStatement.class);
286 * Bridge between {@link EffectiveStatementWithFlags} and {@link MandatoryAware}.
288 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
289 * @param <D> Class representing declared version of this statement.
291 public interface MandatoryMixin<A, D extends DeclaredStatement<A>>
292 extends EffectiveStatementWithFlags<A, D>, MandatoryAware {
294 default boolean isMandatory() {
295 return (flags() & FlagsBuilder.MANDATORY) != 0;
300 * Bridge between {@link EffectiveStatementWithFlags} and {@code presence} statement.
302 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
303 * @param <D> Class representing declared version of this statement.
305 public interface PresenceMixin<A, D extends DeclaredStatement<A>> extends EffectiveStatementWithFlags<A, D> {
306 default boolean presence() {
307 return (flags() & FlagsBuilder.PRESENCE) != 0;
312 * Bridge between {@link EffectiveStatementWithFlags} and {@link SchemaNode}.
314 * @param <D> Class representing declared version of this statement.
316 public interface SchemaNodeMixin<D extends DeclaredStatement<QName>>
317 extends DocumentedNodeMixin.WithStatus<QName, D>, SchemaNode {
319 default QName getQName() {
325 * Bridge between {@link EffectiveStatementWithFlags} and {@link UnknownSchemaNode}.
327 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
328 * @param <D> Class representing declared version of this statement.
330 public interface UnknownSchemaNodeMixin<A, D extends DeclaredStatement<A>>
331 extends DocumentedNodeMixin.WithStatus<A, D>, CopyableMixin<A, D>, UnknownSchemaNode {
333 default String getNodeParameter() {
334 return Strings.nullToEmpty(verifyNotNull(getDeclared()).rawArgument());
339 * Bridge between {@link EffectiveStatementWithFlags} and {@code ordered-by} statement.
341 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
342 * @param <D> Class representing declared version of this statement.
343 * @param <E> Class representing effective version of this statement.
345 // FIXME: 9.0.0: remove this mixin once we have a properly-cached DataTree and JSON/XML codec tree and the speed
346 // of isUserOrdered() is not really critical.
347 public interface UserOrderedAwareMixin<A, D extends DeclaredStatement<A>,
348 E extends OrderedByAwareEffectiveStatement<A, D>>
349 extends EffectiveStatementWithFlags<A, D>, UserOrderedAware<E> {
351 default boolean isUserOrdered() {
352 return (flags() & FlagsBuilder.USER_ORDERED) != 0;
357 * Helper used to locate the effective {@code when} statement and exposing its argument as per
358 * {@link WhenConditionAware}.
360 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
361 * @param <D> Class representing declared version of this statement.
363 public interface WhenConditionMixin<A, D extends DeclaredStatement<A>> extends Mixin<A, D>, WhenConditionAware {
365 default Optional<QualifiedBound> getWhenCondition() {
366 return findFirstEffectiveSubstatementArgument(WhenEffectiveStatement.class);
371 * Helper bridge for operation containers ({@code input} and {@code output}).
373 * @param <D> Class representing declared version of this statement.
375 public interface OperationContainerMixin<D extends DeclaredStatement<QName>>
376 extends ContainerLike, DocumentedNodeMixin.WithStatus<QName, D>, DataNodeContainerMixin<QName, D>,
377 MustConstraintMixin<QName, D>, WhenConditionMixin<QName, D>, AugmentationTargetMixin<QName, D>,
378 SchemaNodeMixin<D>, CopyableMixin<QName, D> {
380 default Optional<ActionDefinition> findAction(final QName qname) {
381 return Optional.empty();
385 default Optional<NotificationDefinition> findNotification(final QName qname) {
386 return Optional.empty();
390 default Collection<? extends ActionDefinition> getActions() {
391 return ImmutableSet.of();
395 default Collection<? extends NotificationDefinition> getNotifications() {
396 return ImmutableSet.of();
400 default Optional<Boolean> effectiveConfig() {
401 return Optional.empty();
406 * Helper bridge for {@code anydata} and {@code anyxml} opaque data.
408 * @param <D> Class representing declared version of this statement.
410 public interface OpaqueDataSchemaNodeMixin<D extends DeclaredStatement<QName>>
411 extends DataSchemaNodeMixin<D>, DocumentedNodeMixin.WithStatus<QName, D>, MandatoryMixin<QName, D>,
412 MustConstraintMixin<QName, D>, WhenConditionMixin<QName, D> {
414 default QName getQName() {
420 * Helper bridge for {@code rpc} and {@code action} operations.
422 * @param <D> Class representing declared version of this statement.
424 public interface OperationDefinitionMixin<D extends DeclaredStatement<QName>>
425 extends SchemaNodeMixin<D>, OperationDefinition {
427 default Collection<? extends @NonNull TypeDefinition<?>> getTypeDefinitions() {
428 return filterTypeDefinitions(this);
432 default Collection<? extends @NonNull GroupingDefinition> getGroupings() {
433 return filterEffectiveStatements(GroupingDefinition.class);
437 default InputSchemaNode getInput() {
438 return findAsContainer(this, InputEffectiveStatement.class, InputSchemaNode.class);
442 default OutputSchemaNode getOutput() {
443 return findAsContainer(this, OutputEffectiveStatement.class, OutputSchemaNode.class);
448 * Support interface for various mixins. Implementations are required to store 32bits worth of flags, which are
449 * globally assigned to sub-interfaces -- thus providing storage for many low-cardinality properties.
451 * @param <A> Argument type ({@link Empty} if statement does not have argument.)
452 * @param <D> Class representing declared version of this statement.
454 public interface EffectiveStatementWithFlags<A, D extends DeclaredStatement<A>> extends Mixin<A, D> {
456 * Return flags associated with this statements. Flags can be built using {@link FlagsBuilder}.
458 * @return Flag field value (32 bits).
463 final class FlagsBuilder implements Mutable {
464 // We still have 23 flags remaining
465 static final int STATUS_CURRENT = 0x0001;
466 static final int STATUS_DEPRECATED = 0x0002;
467 static final int STATUS_OBSOLETE = 0x0003;
468 static final int MASK_STATUS = 0x0003;
470 static final int MANDATORY = 0x0004;
472 static final int AUGMENTING = 0x0010;
473 @Deprecated(since = "7.0.9", forRemoval = true)
474 static final int ADDED_BY_USES = 0x0020;
475 private static final int MASK_HISTORY = 0x0030;
477 static final int USER_ORDERED = 0x0040;
478 static final int PRESENCE = 0x0080;
480 static final int CONFIG_UNDEF = 0x0100;
481 static final int CONFIG_FALSE = 0x0200;
482 static final int CONFIG_TRUE = 0x0300;
483 static final int MASK_CONFIG = CONFIG_TRUE;
487 public FlagsBuilder setConfiguration(final @Nullable Boolean config) {
489 if (config != null) {
490 fl = config ? CONFIG_TRUE : CONFIG_FALSE;
494 flags = flags & ~MASK_CONFIG | fl;
498 public FlagsBuilder setHistory(final CopyableNode history) {
499 flags = flags & ~MASK_HISTORY
500 | (history.isAugmenting() ? AUGMENTING : 0) | (history.isAddedByUses() ? ADDED_BY_USES : 0);
504 public FlagsBuilder setMandatory(final boolean mandatory) {
513 public FlagsBuilder setPresence(final boolean presence) {
522 public FlagsBuilder setStatus(final Status status) {
526 bits = STATUS_CURRENT;
529 bits = STATUS_DEPRECATED;
532 bits = STATUS_OBSOLETE;
535 throw new IllegalStateException("Unhandled status " + status);
538 flags = flags & ~MASK_STATUS | bits;
542 public FlagsBuilder setUserOrdered(final boolean userOrdered) {
544 flags |= USER_ORDERED;
546 flags &= ~USER_ORDERED;
551 public int toFlags() {
557 private EffectiveStatementMixins() {
561 static <T extends ContainerLike> T findAsContainer(final EffectiveStatement<?, ?> stmt,
562 final Class<? extends EffectiveStatement<QName, ?>> type, final Class<T> target) {
563 return target.cast(stmt.findFirstEffectiveSubstatement(type).get());
566 static Collection<? extends @NonNull TypeDefinition<?>> filterTypeDefinitions(final Mixin<?, ?> stmt) {
567 return Collections2.transform(stmt.filterEffectiveStatements(TypedefEffectiveStatement.class),
568 TypedefEffectiveStatement::getTypeDefinition);