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