data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/MountPointContext.java

   1 /*
   2  * Copyright (c) 2019 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.data.api.schema;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Optional;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.opendaylight.yangtools.rfc8528.model.api.MountPointLabel;
  14 import org.opendaylight.yangtools.yang.model.api.EffectiveModelContextProvider;
  15
  16 /**
  17  * A context of either an explicit (RFC8528 Schema Mount instance) or implicit (system root). It encapsulates a data
  18  * {@link org.opendaylight.yangtools.yang.model.api.EffectiveModelContext} and information resident in
  19  * {@code schema-mounts} within this hierarchy.
  20  *
  21  * <p>
  22  * Note this interface should be part of yang-data-api, as it really defines how a NormalizedNode-containerized data
  23  * operates w.r.t. mount points. Further evolution is expected.
  24  */
  25 /*
  26  * FIXME: 7.0.0: consider yang-data-api integration
  27  *
  28  * The above note does not give the subject enough attention. RFC8528 redefines the YANG data metamodel is significant
  29  * ways in that it ties it with RFC8525/RFC7895. The content of 'schema-mounts' is critical to interpreting
  30  * inter-mountpoint data, notably in XML/JSON parsers, which need to be able to correctly infer their mode of
  31  * encapsulation (nested mount points).
  32  *
  33  * Integration with DataTree is questionable here, as MountPointNode has enough information for InMemoryDataTree to
  34  * operate efficiently -- all it needs to is switch the resolution root.
  35  *
  36  * On the other hand, requiring that a YANG data world is identified by MountPointIdentifer (which is QName) adds
  37  * interpretation flexibility to SchemaContext which is currently hard-coded. For example operations which require
  38  * encapsulation of an entire tree have to assume that a SchemaContext has a NodeIdentifier which it uses for the name
  39  * of its top-level node. MountPointIdentifier solves this, as it can easily be converted to a unique world identifier.
  40  *
  41  * That allows, for example NETCONF to specify the root data identifier, properly matching the data it receives from
  42  * the device to the native datastore format. Rehosting root identifier means rehosting top-level nodes of
  43  * a ContainerNode, which is a simple and relatively-inexpensive operation (i.e. O(N) where N is the number of
  44  * top-level nodes).
  45  *
  46  * To support this case, MountPointContext really wants to be Identifiable<MountPointIdentifier>, where it would also
  47  * provide a 'default NodeIdentifier getRootIdentifier()' method. In PathArgument contexts, MountPointIdentifier is
  48  * directly usable anyway.
  49  *
  50  * 6.0.0-timeframe review:
  51  *
  52  * The idea with Identifiable is not really that grand, as it goes against our desire to peel identifiers from nodes,
  53  * as detailed in YANGTOOLS-1074. This will end up meaning that the root of a NormalizedNode tree does not have to have
  54  * an identifier and very much can live on its own -- solving both the SchemaContext name problem as well as NETCONF
  55  * interoperability.
  56  */
  57 @Beta
  58 public interface MountPointContext extends EffectiveModelContextProvider {
  59     /**
  60      * Attempt to acquire a {@link MountPointContextFactory} to resolve schemas for the purposes of interpreting
  61      * this mount point. An empty result indicates the mount point is not attached.
  62      *
  63      * @param label Mount point label, as defined via the use of {@code mount-point} statement
  64      * @return An optional handler for mount point data
  65      * @throws NullPointerException if label is null
  66      */
  67     Optional<MountPointContextFactory> findMountPoint(@NonNull MountPointLabel label);
  68 }