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 /**
  16  * An XPath expression.
  17  *
  18  * @author Robert Varga
  19  */
  20 @Beta
  21 public interface YangXPathExpression extends Immutable {
  22     /**
  23      * Return the root {@link YangExpr}.
  24      *
  25      * @return Root expression.
  26      */
  27     YangExpr getRootExpr();
  28
  29     /**
  30      * Return the {@link YangXPathMathMode} used in this expression. All {@link YangNumberExpr} objects used by this
  31      * expression are expected to be handled by this mode's {@link YangXPathMathSupport}.
  32      *
  33      * @return YangXPathMathMode
  34      */
  35     YangXPathMathMode getMathMode();
  36
  37     /**
  38      * Attempt to interpret a {@link YangLiteralExpr} referenced by this expression as a {@link QName}. This method
  39      * is required to perform late value binding of the expression when the literal needs to be interpreted as
  40      * a reference to an {@code identity}.
  41      *
  42      * <p>
  43      * The syntax of expr is required to conform to
  44      * <a href="https://www.w3.org/TR/REC-xml-names/#NT-QName">XML QName format</a>, as further restricted by
  45      * <a href="https://tools.ietf.org/html/rfc7950#section-9.10.3">YANG {@code identityref} Lexical Representation</a>.
  46      *
  47      * <p>
  48      * Unfortunately we do not know when a literal will need to be interpreted in this way, as that can only be known
  49      * at evaluation.
  50      *
  51      * @param expr Literal to be reinterpreted
  52      * @return YangQNameExpr result of interpretation
  53      * @throws XPathExpressionException when the literal cannot be interpreted as a QName
  54      */
  55     YangQNameExpr interpretAsQName(YangLiteralExpr expr) throws XPathExpressionException;
  56
  57     // FIXME: this really should be YangInstanceIdentifier without AugmentationIdentifier. Implementations are
  58     //        strongly encouraged to validate it as such.
  59     YangLocationPath interpretAsInstanceIdentifier(YangLiteralExpr expr) throws XPathExpressionException;
  60 }