yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java

   1 /*
   2  * Copyright (c) 2018 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.xpath.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import javax.xml.xpath.XPathExpressionException;
  12 import org.opendaylight.yangtools.concepts.Immutable;
  13 import org.opendaylight.yangtools.yang.common.QName;
  14
  15 @Beta
  16 public interface YangXPathExpression extends Immutable {
  17
  18     YangExpr getRootExpr();
  19
  20     /**
  21      * Attempt to interpret a {@link YangLiteralExpr} referenced by this expression as a {@link QName}. This method
  22      * is required to perform late value binding of the expression when the literal needs to be interpreted as
  23      * a reference to an {@code identity}.
  24      *
  25      * <p>
  26      * The syntax of expr is required to conform to
  27      * <a href="https://www.w3.org/TR/REC-xml-names/#NT-QName">XML QName format</a>, as further restricted by
  28      * <a href="https://tools.ietf.org/html/rfc7950#section-9.10.3">YANG {@code identityref} Lexical Representation</a>.
  29      *
  30      * <p>
  31      * Unfortunately we do not know when a literal will need to be interpreted in this way, as that can only be known
  32      * at evaluation.
  33      *
  34      * @param expr Literal to be reinterpreted
  35      * @return QName representation of the literal
  36      * @throws XPathExpressionException when the literal cannot be interpreted as a QName
  37      */
  38     QName interpretAsQName(YangLiteralExpr expr) throws XPathExpressionException;
  39
  40     // API design: this really should be YangInstanceIdentifier without AugmentationIdentifier. Implementations are
  41     //             strongly encouraged to validate it as such.
  42     YangLocationPath interpretAsInstanceIdentifier(YangLiteralExpr expr) throws XPathExpressionException;
  43 }