restconf/restconf-nb/src/main/java/org/opendaylight/restconf/server/api/DatabindPath.java

   1 /*
   2  * Copyright (c) 2024 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.restconf.server.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import org.eclipse.jdt.annotation.NonNullByDefault;
  13 import org.opendaylight.restconf.api.ApiPath;
  14 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  15 import org.opendaylight.yangtools.yang.data.util.DataSchemaContext;
  16 import org.opendaylight.yangtools.yang.model.api.EffectiveStatementInference;
  17 import org.opendaylight.yangtools.yang.model.api.stmt.ActionEffectiveStatement;
  18 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
  19 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
  20 import org.opendaylight.yangtools.yang.model.api.stmt.RpcEffectiveStatement;
  21 import org.opendaylight.yangtools.yang.model.util.SchemaInferenceStack.Inference;
  22
  23 /**
  24  * An {@link ApiPath} resolved against a {@link DatabindContext}. This can be either
  25  * <ul>
  26  *   <li>a {@link Data} pointing to a datastore resource, or</li>
  27  *   <li>an {@link Rpc} pointing to a YANG {@code rpc} statement, or</li>
  28  *   <li>an {@link Action} pointing to an instantiation of a YANG {@code action} statement</li>
  29  * </ul>
  30  */
  31 @NonNullByDefault
  32 public sealed interface DatabindPath extends DatabindAware {
  33     /**
  34      * Returns the {@link EffectiveStatementInference} made by this path.
  35      *
  36      * @return the {@link EffectiveStatementInference} made by this path
  37      */
  38     Inference inference();
  39
  40     /**
  41      * A {@link DatabindPath} denoting an invocation of a YANG {@code action}.
  42      *
  43      * @param databind the {@link DatabindContext} to which this path is bound
  44      * @param inference the {@link EffectiveStatementInference} made by this path
  45      * @param instance the {@link YangInstanceIdentifier} of the instance being referenced, guaranteed to be
  46      *        non-empty
  47      * @param action the {@code action}
  48      */
  49     record Action(
  50             DatabindContext databind,
  51             Inference inference,
  52             YangInstanceIdentifier instance,
  53             ActionEffectiveStatement action) implements OperationPath, InstanceReference {
  54         public Action {
  55             requireNonNull(inference);
  56             requireNonNull(action);
  57             if (instance.isEmpty()) {
  58                 throw new IllegalArgumentException("action must be instantiated on a data resource");
  59             }
  60         }
  61
  62         @Override
  63         public InputEffectiveStatement inputStatement() {
  64             return action.input();
  65         }
  66
  67         @Override
  68         public OutputEffectiveStatement outputStatement() {
  69             return action.output();
  70         }
  71     }
  72
  73     /**
  74      * A {@link DatabindPath} denoting a datastore instance.
  75      *
  76      * @param databind the {@link DatabindContext} to which this path is bound
  77      * @param inference the {@link EffectiveStatementInference} made by this path
  78      * @param instance the {@link YangInstanceIdentifier} of the instance being referenced,
  79      *                 {@link YangInstanceIdentifier#empty()} denotes the datastore
  80      * @param schema the {@link DataSchemaContext} of the datastore instance
  81      */
  82     // FIXME: split into 'Datastore' and 'Data' with non-empty instance, so we can bind to correct
  83     //        instance-identifier semantics, which does not allow YangInstanceIdentifier.empty()
  84     record Data(
  85             DatabindContext databind,
  86             Inference inference,
  87             YangInstanceIdentifier instance,
  88             DataSchemaContext schema) implements InstanceReference {
  89         public Data {
  90             requireNonNull(inference);
  91             requireNonNull(instance);
  92             requireNonNull(schema);
  93         }
  94
  95         // FIXME: this is the 'Datastore' constructor
  96         public Data(final DatabindContext databind) {
  97             this(databind, Inference.ofDataTreePath(databind.modelContext()), YangInstanceIdentifier.of(),
  98                 databind.schemaTree().getRoot());
  99         }
 100     }
 101
 102     /**
 103      * A {@link DatabindPath} denoting an invocation of a YANG {@code rpc}.
 104      *
 105      * @param databind the {@link DatabindContext} to which this path is bound
 106      * @param inference the {@link EffectiveStatementInference} made by this path
 107      * @param rpc the {@code rpc}
 108      */
 109     record Rpc(DatabindContext databind, Inference inference, RpcEffectiveStatement rpc) implements OperationPath {
 110         public Rpc {
 111             requireNonNull(inference);
 112             requireNonNull(rpc);
 113         }
 114
 115         @Override
 116         public InputEffectiveStatement inputStatement() {
 117             return rpc.input();
 118         }
 119
 120         @Override
 121         public OutputEffectiveStatement outputStatement() {
 122             return rpc.output();
 123         }
 124     }
 125
 126     /**
 127      * An intermediate trait of {@link DatabindPath}s which are referencing a YANG data resource. This can be either
 128      * a {@link Data}, or an {@link Action}}.
 129      */
 130     sealed interface InstanceReference extends DatabindPath {
 131         /**
 132          * Returns the {@link YangInstanceIdentifier} of the instance being referenced.
 133          *
 134          * @return the {@link YangInstanceIdentifier} of the instance being referenced,
 135          *         {@link YangInstanceIdentifier#empty()} denotes the data root
 136          */
 137         YangInstanceIdentifier instance();
 138
 139         /**
 140          * Returns this reference as a {@link ServerErrorPath}.
 141          *
 142          * @return this reference as a {@link ServerErrorPath}
 143          */
 144         default ServerErrorPath toErrorPath() {
 145             return new ServerErrorPath(databind(), instance());
 146         }
 147     }
 148
 149     /**
 150      * An intermediate trait of {@link DatabindPath}s which are referencing a YANG operation. This can be either
 151      * an {@link Action}, as defined in
 152      * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-4.4.2">RFC8040 Invoke Operation Mode</a> or
 153      * an {@link Rpc}, as defined in
 154      * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.6">RFC8040 Operation Resource</a>.
 155      */
 156     sealed interface OperationPath extends DatabindPath {
 157         /**
 158          * Returns the {@code input} statement of this operation.
 159          *
 160          * @return the {@code input} statement of this operation
 161          */
 162         InputEffectiveStatement inputStatement();
 163
 164         /**
 165          * Returns the {@code output} statement of this operation.
 166          *
 167          * @return the {@code output} statement of this operation
 168          */
 169         OutputEffectiveStatement outputStatement();
 170     }
 171 }