yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/YangNamespaceContext.java

   1 /*
   2  * Copyright (c) 2019 Pantheon Technologies, s.r.o.  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.common;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11
  12 import com.google.common.annotations.Beta;
  13 import java.io.Serializable;
  14 import java.util.Optional;
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.opendaylight.yangtools.concepts.Immutable;
  17
  18 /**
  19  * Interface for mapping between {@link String} prefixes and {@link QNameModule} namespaces. The conceptual model
  20  * matches prefix mapping inside a YANG {@code module} as defined through the use of {@code prefix} and {@code import}
  21  * statements and detailed in <a href="https://tools.ietf.org/html/rfc7950#section-7.1.4">RFC7950 Section 7.1.4</a>.
  22  *
  23  * <p>
  24  * Each namespace context has a set of prefix/namespace mappings. A namespace can be bound to multiple prefixes at the
  25  * same time.
  26  *
  27  * @author Robert Varga
  28  */
  29 @Beta
  30 public interface YangNamespaceContext extends Immutable, Serializable {
  31     /**
  32      * Return QNameModule to which a particular prefix is bound.
  33      *
  34      * @param prefix Prefix to look up
  35      * @return QNameModule bound to specified prefix
  36      * @throws NullPointerException if {@code prefix} is null
  37      */
  38     @NonNull Optional<QNameModule> findNamespaceForPrefix(String prefix);
  39
  40     /**
  41      * Return a prefix to which a particular QNameModule is bound. If a namespace is bound to multiple prefixes, it is
  42      * left unspecified which of those prefixes is returned.
  43      *
  44      * @param namespace QNameModule to look up
  45      * @return Prefix to which the QNameModule is bound
  46      * @throws NullPointerException if {@code module} is null
  47      */
  48     @NonNull Optional<String> findPrefixForNamespace(QNameModule namespace);
  49
  50     /**
  51      * Create a {@link QName} by resolving a prefix against currently-bound prefixes and combining it with specified
  52      * local name.
  53      *
  54      * @param prefix Namespace prefix
  55      * @param localName QName local name
  56      * @return A QName.
  57      * @throws NullPointerException if any argument is null
  58      * @throws IllegalArgumentException if {@code localName} does not conform to local name requirements or if the
  59      *                                  prefix is not bound in this context.
  60      */
  61     default @NonNull QName createQName(final String prefix, final String localName) {
  62         final Optional<QNameModule> namespace = findNamespaceForPrefix(prefix);
  63         checkArgument(namespace.isPresent(), "Prefix %s is not bound", prefix);
  64         return QName.create(namespace.get(), localName);
  65     }
  66 }