parser/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/NamespaceStmtCtx.java

   1 /*
   2  * Copyright (c) 2020 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.parser.spi.meta;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Map;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.eclipse.jdt.annotation.Nullable;
  14
  15 /**
  16  * Support work with namespace content.
  17  */
  18 // FIXME: ditch <N> parameters
  19 @Beta
  20 public interface NamespaceStmtCtx extends CommonStmtCtx {
  21     /**
  22      * Return the selected namespace.
  23      *
  24      * @param <K> namespace key type
  25      * @param <V> namespace value type
  26      * @param <N> namespace type
  27      * @param nsType namespace type class
  28      * @return Namespace contents, if available
  29      */
  30     <K, V, N extends ParserNamespace<K, V>> @Nullable Map<K, V> namespace(@NonNull N nsType);
  31
  32     /**
  33      * Return a value associated with specified key within a namespace.
  34      *
  35      * @param nsType Namespace type
  36      * @param key Key
  37      * @param <K> namespace key type
  38      * @param <V> namespace value type
  39      * @param <N> namespace type
  40      * @param <T> key type
  41      * @return Value, or null if there is no element
  42      * @throws NamespaceNotAvailableException when the namespace is not available.
  43      */
  44     <K, V, T extends K, N extends ParserNamespace<K, V>> @Nullable V namespaceItem(@NonNull N nsType, T key);
  45
  46     /**
  47      * Return the portion of specified namespace stored in this node. Depending on namespace behaviour this may or may
  48      * not represent the complete contents of the namespace as available via {@link #namespace(ParserNamespace)}.
  49      *
  50      * <p>
  51      * This partial view is useful when the need is not to perform a proper namespace lookup, but rather act on current
  52      * statement's contribution to the namespace.
  53      *
  54      * @param <K> namespace key type
  55      * @param <V> namespace value type
  56      * @param <N> namespace type
  57      * @param nsType namespace type class
  58      * @return Namespace portion stored in this node, if available
  59      */
  60     <K, V, N extends ParserNamespace<K, V>> @Nullable Map<K, V> localNamespacePortion(@NonNull N nsType);
  61
  62     /**
  63      * Return the selected namespace.
  64      *
  65      * @param <K> namespace key type
  66      * @param <V> namespace value type
  67      * @param <N> namespace type
  68      * @param nsType namespace type class
  69      * @return Namespace contents, if available
  70      */
  71     // TODO: migrate users away
  72     default <K, V, N extends ParserNamespace<K, V>> Map<K, V> getAllFromNamespace(final @NonNull N nsType) {
  73         return namespace(nsType);
  74     }
  75
  76     /**
  77      * Return a value associated with specified key within a namespace.
  78      *
  79      * @param type Namespace type
  80      * @param key Key
  81      * @param <K> namespace key type
  82      * @param <V> namespace value type
  83      * @param <N> namespace type
  84      * @param <T> key type
  85      * @return Value, or null if there is no element
  86      * @throws NamespaceNotAvailableException when the namespace is not available.
  87      */
  88     // TODO: migrate users away
  89     default <K, V, T extends K, N extends ParserNamespace<K, V>> @Nullable V getFromNamespace(
  90             final @NonNull N type, final T key) {
  91         return namespaceItem(type, key);
  92     }
  93 }