model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/RootEffectiveStatement.java

   1 /*
   2  * Copyright (c) 2022 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.model.api.stmt;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Collection;
  12 import java.util.Map;
  13 import java.util.Map.Entry;
  14 import java.util.Optional;
  15 import java.util.Set;
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.opendaylight.yangtools.yang.common.QNameModule;
  18 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
  19 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  20
  21 /**
  22  * Common interface capturing general layout of a top-level YANG declared statement -- either
  23  * a {@link ModuleEffectiveStatement} or a {@link SubmoduleEffectiveStatement}.
  24  *
  25  * <p>
  26  * Both these statements have a relationship to lexical and semantic interpretation of a particular YANG (or YIN) file.
  27  * The core principle is that every XML prefix is bound to a particular {@link ModuleEffectiveStatement}, exposed via
  28  * {@link #findReachableModule(String)} and {@link #reachableModules()}. The secondary effect of it is that each known
  29  * {@link QNameModule} is known under a (preferred) prefix, exposed via {@link #findNamespacePrefix(QNameModule)}.
  30  */
  31 @Beta
  32 public sealed interface RootEffectiveStatement<D extends RootDeclaredStatement>
  33         extends EffectiveStatement<Unqualified, D> permits ModuleEffectiveStatement, SubmoduleEffectiveStatement {
  34     /**
  35      * Find the {@link ModuleEffectiveStatement} statement based on {@link PrefixEffectiveStatement}s, be it direct
  36      * substatement or a substatement of a {@link ImportEffectiveStatement} substatement.
  37      *
  38      * @return prefix Imported {@link ModuleEffectiveStatement}, or absent
  39      * @throws NullPointerException if {@code prefix} is {@code null}
  40      */
  41     @NonNull Optional<ModuleEffectiveStatement> findReachableModule(@NonNull String prefix);
  42
  43     /**
  44      * Enumerate all modules reachable from this module. This is recursive relationship: every
  45      * {@link RootEffectiveStatement} is considered reachable from itself under its local prefix. Returned collection
  46      * is guaranteed not to contain more than one element with the same {@link Entry#getKey()}.
  47      *
  48      * @return All {@link ModuleEffectiveStatement}s reachable in this {@code module} or {@code submodule}, coupled with
  49      *         their preferred prefix.
  50      */
  51     @NonNull Collection<Entry<String, ModuleEffectiveStatement>> reachableModules();
  52
  53     /**
  54      * Find the preferred prefix to use with a particular namespace.
  55      *
  56      * @param namespace A bound namespace, represented as {@link QNameModule}
  57      * @return Preferred prefix, or empty
  58      * @throws NullPointerException if {@code namespace} is {@code null}
  59      */
  60     @NonNull Optional<String> findNamespacePrefix(@NonNull QNameModule namespace);
  61
  62     /**
  63      * Enumeration of all namespace-to-prefix mappings. This generally corresponds to a {@link Map#entrySet()}, but we
  64      * do not want to be bogged down by a {@link Set}.
  65      */
  66     Collection<Entry<QNameModule, String>> namespacePrefixes();
  67 }