parser/rfc8040-parser-support/src/main/java/org/opendaylight/yangtools/rfc8040/parser/YangDataStatementSupport.java

   1 /*
   2  * Copyright (c) 2017 Pantheon Technologies, 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.rfc8040.parser;
   9
  10 import static com.google.common.base.Verify.verify;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.collect.ImmutableList;
  14 import java.util.stream.Collectors;
  15 import org.opendaylight.yangtools.rfc8040.model.api.YangDataEffectiveStatement;
  16 import org.opendaylight.yangtools.rfc8040.model.api.YangDataStatement;
  17 import org.opendaylight.yangtools.rfc8040.model.api.YangDataStatements;
  18 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  19 import org.opendaylight.yangtools.yang.model.api.YangStmtMapping;
  20 import org.opendaylight.yangtools.yang.model.api.meta.DeclarationReference;
  21 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  22 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  23 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
  24 import org.opendaylight.yangtools.yang.model.api.stmt.DataTreeEffectiveStatement;
  25 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeEffectiveStatement;
  26 import org.opendaylight.yangtools.yang.model.api.stmt.UsesEffectiveStatement;
  27 import org.opendaylight.yangtools.yang.parser.api.YangParserConfiguration;
  28 import org.opendaylight.yangtools.yang.parser.spi.meta.AbstractStringStatementSupport;
  29 import org.opendaylight.yangtools.yang.parser.spi.meta.BoundStmtCtx;
  30 import org.opendaylight.yangtools.yang.parser.spi.meta.EffectiveStmtCtx.Current;
  31 import org.opendaylight.yangtools.yang.parser.spi.meta.InvalidSubstatementException;
  32 import org.opendaylight.yangtools.yang.parser.spi.meta.MissingSubstatementException;
  33 import org.opendaylight.yangtools.yang.parser.spi.meta.StmtContext.Mutable;
  34 import org.opendaylight.yangtools.yang.parser.spi.meta.SubstatementValidator;
  35 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
  36
  37 @Beta
  38 public final class YangDataStatementSupport
  39         extends AbstractStringStatementSupport<YangDataStatement, YangDataEffectiveStatement> {
  40     // As per RFC8040 page 81:
  41     //
  42     //    The substatements of this extension MUST follow the
  43     //    'data-def-stmt' rule in the YANG ABNF.
  44     //
  45     // As per RFC7950 page 185:
  46     //
  47     //    data-def-stmt = container-stmt /
  48     //                    leaf-stmt /
  49     //                    leaf-list-stmt /
  50     //                    list-stmt /
  51     //                    choice-stmt /
  52     //                    anydata-stmt /
  53     //                    anyxml-stmt /
  54     //                    uses-stmt
  55     //
  56     // The cardinality is not exactly constrained, but the entirety of substatements are required to resolve to a single
  57     // XML document (page 80). This is enforced when we arrive at full declaration.
  58     private static final SubstatementValidator VALIDATOR = SubstatementValidator.builder(YangDataStatements.YANG_DATA)
  59         .addAny(YangStmtMapping.CONTAINER)
  60         .addAny(YangStmtMapping.LEAF)
  61         .addAny(YangStmtMapping.LEAF_LIST)
  62         .addAny(YangStmtMapping.LIST)
  63         .addAny(YangStmtMapping.CHOICE)
  64         .addAny(YangStmtMapping.ANYDATA)
  65         .addAny(YangStmtMapping.ANYXML)
  66         .addAny(YangStmtMapping.USES)
  67         .build();
  68
  69     public YangDataStatementSupport(final YangParserConfiguration config) {
  70         super(YangDataStatements.YANG_DATA, StatementPolicy.reject(), config, VALIDATOR);
  71     }
  72
  73     @Override
  74     public void onStatementAdded(final Mutable<String, YangDataStatement, YangDataEffectiveStatement> ctx) {
  75         // as per https://tools.ietf.org/html/rfc8040#section-8,
  76         // yang-data is ignored unless it appears as a top-level statement
  77         if (ctx.coerceParentContext().getParentContext() != null) {
  78             ctx.setUnsupported();
  79         }
  80     }
  81
  82     @Override
  83     public void onFullDefinitionDeclared(final Mutable<String, YangDataStatement, YangDataEffectiveStatement> ctx) {
  84         // If we are declared in an illegal place, this becomes a no-op
  85         if (!ctx.isSupportedToBuildEffective()) {
  86             return;
  87         }
  88
  89         // Run SubstatementValidator-based validation first
  90         super.onFullDefinitionDeclared(ctx);
  91
  92         // Support for 'operations' container semantics. For this we need to recognize when the model at hand matches
  93         // RFC8040 ietf-restconf module. In ordered to do that we hook onto this particular definition:
  94         //
  95         //   rc:yang-data yang-api {
  96         //     uses restconf;
  97         //   }
  98         //
  99         // If we find it, we hook an inference action which performs the next step when the module is fully declared.
 100         if ("yang-api".equals(ctx.argument())) {
 101             final var stmts = ctx.declaredSubstatements();
 102             if (stmts.size() == 1) {
 103                 final var stmt = stmts.iterator().next();
 104                 if (stmt.producesEffective(UsesEffectiveStatement.class) && "restconf".equals(stmt.rawArgument())) {
 105                     // The rc:yang-data shape matches, but we are not sure about the module identity, that needs to be
 106                     // done later multiple stages, the first one being initiated through this call.
 107                     OperationsValidateModuleAction.applyTo(ctx.coerceParentContext());
 108                 }
 109             }
 110         }
 111     }
 112
 113     @Override
 114     public boolean isIgnoringIfFeatures() {
 115         return true;
 116     }
 117
 118     @Override
 119     public boolean isIgnoringConfig() {
 120         return true;
 121     }
 122
 123     @Override
 124     protected YangDataStatement createDeclared(final BoundStmtCtx<String> ctx,
 125             final ImmutableList<DeclaredStatement<?>> substatements) {
 126         return new YangDataStatementImpl(ctx.getRawArgument(), substatements);
 127     }
 128
 129     @Override
 130     protected YangDataStatement attachDeclarationReference(final YangDataStatement stmt,
 131             final DeclarationReference reference) {
 132         return new RefYangDataStatement(stmt, reference);
 133     }
 134
 135     @Override
 136     protected YangDataEffectiveStatement createEffective(final Current<String, YangDataStatement> stmt,
 137             final ImmutableList<? extends EffectiveStatement<?, ?>> substatements) {
 138         // RFC8040 page 80 requires that:
 139         //    It MUST contain data definition statements
 140         //    that result in exactly one container data node definition.
 141         //    An instance of a YANG data template can thus be translated
 142         //    into an XML instance document, whose top-level element
 143         //    corresponds to the top-level container.
 144         //
 145         // We validate this additional constraint when we arrive at the effective model, with the view that
 146         // 'container data node definition' is really meant to say 'XML element'.
 147         //
 148         // This really boils down to the requirement to have a single schema tree substatement, which needs to either
 149         // be a data tree statement or a choice statement.
 150         final var schemaSub = substatements.stream()
 151             .filter(SchemaTreeEffectiveStatement.class::isInstance)
 152             .map(SchemaTreeEffectiveStatement.class::cast)
 153             .collect(Collectors.toUnmodifiableList());
 154         final DataSchemaNode child;
 155         switch (schemaSub.size()) {
 156             case 0:
 157                 throw new MissingSubstatementException(stmt, "yang-data requires at least one substatement");
 158             case 1:
 159                 final SchemaTreeEffectiveStatement<?> substmt = schemaSub.get(0);
 160                 SourceException.throwIf(
 161                     !(substmt instanceof ChoiceEffectiveStatement) && !(substmt instanceof DataTreeEffectiveStatement),
 162                     stmt, "%s is not a recognized container data node definition", substmt);
 163                 verify(substmt instanceof DataSchemaNode, "Unexpected single child %s", substmt);
 164                 child = (DataSchemaNode) substmt;
 165                 break;
 166             default:
 167                 throw new InvalidSubstatementException(stmt,
 168                     "yang-data requires exactly one container data node definition, found %s", schemaSub);
 169         }
 170
 171         return new YangDataEffectiveStatementImpl(stmt, substatements, child);
 172     }
 173 }