From 5abd1a0fffa9d5c272c5efb750e37b62e63541fc Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Mon, 7 Sep 2015 23:55:23 +0200 Subject: [PATCH] BUG-3876: Add XPath interfaces This patch introduces the basic set of interfaces implemented by XPath evaluation providers. Change-Id: Ib4f766844f635ec1d6cdd582208547e7c63edc56 Signed-off-by: Robert Varga --- .../api/schema/xpath/LazyXPathExpression.java | 58 +++++++++++++++++++ .../xpath/LazyXPathExpressionException.java | 33 +++++++++++ .../xpath/OptimizableXPathExpression.java | 34 +++++++++++ .../api/schema/xpath/PrefixConverters.java | 58 +++++++++++++++++++ .../xpath/RelocatableXPathExpression.java | 28 +++++++++ .../api/schema/xpath/XPathBooleanResult.java | 18 ++++++ .../data/api/schema/xpath/XPathDocument.java | 25 ++++++++ .../api/schema/xpath/XPathExpression.java | 58 +++++++++++++++++++ .../api/schema/xpath/XPathNodesetResult.java | 20 +++++++ .../api/schema/xpath/XPathNumberResult.java | 18 ++++++ .../data/api/schema/xpath/XPathResult.java | 31 ++++++++++ .../api/schema/xpath/XPathSchemaContext.java | 42 ++++++++++++++ .../xpath/XPathSchemaContextFactory.java | 41 +++++++++++++ .../api/schema/xpath/XPathStringResult.java | 18 ++++++ 14 files changed, 482 insertions(+) create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpression.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpressionException.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/OptimizableXPathExpression.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/PrefixConverters.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/RelocatableXPathExpression.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathBooleanResult.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathDocument.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathExpression.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNodesetResult.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNumberResult.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathResult.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContext.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContextFactory.java create mode 100644 yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathStringResult.java diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpression.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpression.java new file mode 100644 index 0000000000..e174bb4154 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpression.java @@ -0,0 +1,58 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import com.google.common.base.Optional; +import com.google.common.util.concurrent.CheckedFuture; +import java.util.concurrent.Future; +import javax.annotation.Nonnull; +import javax.xml.xpath.XPathExpressionException; +import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier; + +/** + * Asynchronous interface to evaluation. It is functionally the same as an XPathExpression, but allows for asynchronous + * execution of evaluation of the expression. + * + * FIXME: Whether or not the resulting XPathResult can perform blocking calls is up for grabs, but implementations are + * definitely allowed to perform things like on-demand data transformation from foreign object and data models. + * + * @deprecated PREVIEW API. DO NOT IMPLEMENT YET AS THIS NEEDS TO BE VALIDATED FOR USE IN CLIENT APPLICATIONS. + * APPLICATIONS WILLING TO USE THIS API PLEASE CONTACT + * yangtools-dev. + */ +@Beta +@Deprecated +public interface LazyXPathExpression { + /** + * Evaluate this expression at the specified path in a document. If evaluation succeeds, it will return an + * {@link XPathResult} at some point it the future. If it fails to match anything, it {@link Future#get()} will + * return {@link Optional#absent()}. + * + * FIXME: The amount of overhead an implementation can incur on the user as data from the resulting + * {@link XPathResult} is being accessed is left UNDEFINED. + * + * Specifically, the user is expected to store each result returned directly or indirectly in a local + * variable instead of repeated calls to the result's methods, as these may incur CPU processing overhead. + * + * Furthermore all method invocations can throw {@link LazyXPathExpressionException}, which the users are + * expected to handle gracefully. RESILIENT USERS ARE EXPECTED TO CATCH {@link LazyXPathExpressionException} + * AND RECOVER IN THE SAME MANNER THEY WOULD IF AN {@link XPathExpressionException} WOULD HAVE BEEN THROWN. + * + * [ FIXME: would it be appropriate to allow implementations to SneakyThrow {@link XPathExpressionException} + * and not introduce a RuntimeExpcetion ? ] + * + * @param document {@link XPathDocument} on which evaluation should take place + * @param path Path to the node on which to evaluate the expression + * @return An optional {@link XPathResult} + * @throws NullPointerException if any of the arguments are null + * @throws IllegalArgumentException if the path does not match the path at which this expression was compiled + */ + CheckedFuture>, XPathExpressionException> evaluateLazily( + @Nonnull XPathDocument document, @Nonnull YangInstanceIdentifier path); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpressionException.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpressionException.java new file mode 100644 index 0000000000..5cd2f6fccc --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/LazyXPathExpressionException.java @@ -0,0 +1,33 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.xml.xpath.XPathExpressionException; + +/** + * The runtime counterpart of {@link XPathExpressionException}. Can occur only when the user is accessing any state + * created from the user's invocation to the {@link LazyXPathExpression} API. + * + * @deprecated PREVIEW API. DO NOT IMPLEMENT YET AS THIS NEEDS TO BE VALIDATED FOR USE IN CLIENT APPLICATIONS. + * APPLICATIONS WILLING TO USE THIS API PLEASE CONTACT + * yangtools-dev. + */ +@Beta +@Deprecated +public class LazyXPathExpressionException extends RuntimeException { + private static final long serialVersionUID = 1L; + + public LazyXPathExpressionException(final String message) { + super(message); + } + + public LazyXPathExpressionException(final String message, final Throwable cause) { + super(message, cause); + } +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/OptimizableXPathExpression.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/OptimizableXPathExpression.java new file mode 100644 index 0000000000..506d977b6b --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/OptimizableXPathExpression.java @@ -0,0 +1,34 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; + +/** + * Interface implemented by {@link XPathExpression}s which can be further optimized for execution efficiency at the + * expense of additional processing being performed on them. The decision to optimize a particular expression is left + * to the user's discretion. + * + * Implementations supporting profile-driven and similar optimizations which depend on data being gathered during + * evaluation should not implement this interface, but rather perform these optimizations transparently behind the + * scenes. That implies the users can expect those optimizations not interfering with the user's ability to evaluate + * the expression. + */ +@Beta +public interface OptimizableXPathExpression extends XPathExpression { + /** + * Perform optimization of this expression. If an implementation supports different levels of optimization, it + * should return an {@link OptimizableXPathExpression} as a result of progressing optimizations for as long as + * it determines further processing can result in execution benefits. Note this expression is expected to remain + * unchanged. + * + * @return An optimized version of this expression. + */ + @Nonnull XPathExpression optimizeExpression(); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/PrefixConverters.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/PrefixConverters.java new file mode 100644 index 0000000000..8c3ecf7123 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/PrefixConverters.java @@ -0,0 +1,58 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import com.google.common.base.Converter; +import com.google.common.base.Preconditions; +import com.google.common.collect.ImmutableBiMap; +import com.google.common.collect.ImmutableBiMap.Builder; +import com.google.common.collect.Maps; +import javax.annotation.Nonnull; +import javax.xml.xpath.XPathExpressionException; +import org.opendaylight.yangtools.yang.common.QNameModule; +import org.opendaylight.yangtools.yang.model.api.Module; +import org.opendaylight.yangtools.yang.model.api.ModuleImport; +import org.opendaylight.yangtools.yang.model.api.SchemaContext; + +/** + * A set of utility functions for dealing with common types of namespace mappings. + */ +@Beta +public final class PrefixConverters { + private PrefixConverters() { + throw new UnsupportedOperationException(); + } + + /** + * Create a prefix {@link Converter} for {@link XPathExpressionException} defined in a particular YANG + * {@link Module} .Instantiation requires establishing how a module's imports are mapped to actual modules + * and their namespaces. This information is cached and used for improved lookups. + * + * @param ctx A SchemaContext + * @param module Module in which the XPath is defined + * @return A new Converter + */ + public static @Nonnull Converter create(final SchemaContext ctx, final Module module) { + // Always check for null ctx + Preconditions.checkNotNull(ctx, "Schema context may not be null"); + + // Use immutable map builder for detection of duplicates (which should never occur) + final Builder b = ImmutableBiMap.builder(); + b.put(module.getPrefix(), module.getQNameModule()); + + for (ModuleImport i : module.getImports()) { + final Module mod = ctx.findModuleByName(i.getModuleName(), i.getRevision()); + Preconditions.checkArgument(mod != null, "Unsatisfied import of %s by module %s", i, module); + + b.put(i.getPrefix(), mod.getQNameModule()); + } + + return Maps.asConverter(b.build()); + } +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/RelocatableXPathExpression.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/RelocatableXPathExpression.java new file mode 100644 index 0000000000..3f0663e68a --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/RelocatableXPathExpression.java @@ -0,0 +1,28 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; +import org.opendaylight.yangtools.yang.model.api.SchemaPath; + +/** + * Interface implemented by {@link XPathExpression}s which can be recompiled to execute more efficiently at a + * at a different {@link SchemaPath} than they were originally compiled at. This can result in the expression being + * moved either up or down in a SchemaPath tree, usually closer to their {@link #getApexPath()}. + */ +@Beta +public interface RelocatableXPathExpression extends XPathExpression { + /** + * Return a new XPathExpression relocated to a SchemaPath of the implementation's choosing. Note that + * {@link #getApexPath()} must not change during this operation. + * + * @return A new XPathExpression instance. + */ + @Nonnull XPathExpression relocateExpression(); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathBooleanResult.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathBooleanResult.java new file mode 100644 index 0000000000..f4a9d5cd44 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathBooleanResult.java @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; + +/** + * An {@link XPathResult} containing a Boolean. + */ +@Beta +public interface XPathBooleanResult extends XPathResult { + +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathDocument.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathDocument.java new file mode 100644 index 0000000000..2cb9cfbfbf --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathDocument.java @@ -0,0 +1,25 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +/** + * The notion of a document, modeled as a {@link NormalizedNode}. + */ +@Beta +public interface XPathDocument { + /** + * Return the root node of this document. + * + * @return This document's root node. + */ + @Nonnull NormalizedNode getRootNode(); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathExpression.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathExpression.java new file mode 100644 index 0000000000..17df596146 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathExpression.java @@ -0,0 +1,58 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import com.google.common.base.Optional; +import javax.annotation.Nonnull; +import javax.xml.xpath.XPathExpressionException; +import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier; +import org.opendaylight.yangtools.yang.model.api.SchemaPath; + +/** + * A compiled XPath expression. Each instance is bound to a particular {@link XPathSchemaContext} and may not be + * evaluated on {@link XPathDocument}s from other context. + */ +@Beta +public interface XPathExpression { + /** + * Evaluate this expression at the specified path in a document. If evaluation succeeds, it will return an + * {@link XPathResult}. If it fails to match anything, it will return {@link Optional#absent()}. Implementations + * of this method are expected to perform complete evaluation such that accessing data via the resulting + * {@link XPathResult} will not incur large overhead. + * + * @param document {@link XPathDocument} on which evaluation should take place + * @param path Path to the node on which to evaluate the expression + * @return An optional {@link XPathResult} + * @throws NullPointerException if any of the arguments are null + * @throws XPathExpressionException if the expression cannot be evaluated + * @throws IllegalArgumentException if the path does not match the path at which this expression was compiled + */ + Optional> evaluate(@Nonnull XPathDocument document, @Nonnull YangInstanceIdentifier path) + throws XPathExpressionException; + + /** + * Return the evaluation context SchemaPath of this expression. This is corresponds to the SchemaPath at which this + * expression was compiled at, or relocated to via {@link RelocatableXPathExpression#relocateExpression()}. + * + * @return The evaluation {@link SchemaPath} + */ + @Nonnull SchemaPath getEvaluationPath(); + + /** + * Return the SchemaPath of the topmost node which affects the result of evaluation of this expression. This + * information is useful for large evolving documents (such as + * {@link org.opendaylight.yangtools.yang.data.api.schema.tree.DataTree} implementations) to minimize the frequency + * of evaluation. The apex can be either logically higher or lower in the SchemaPath tree than + * {@link #getEvaluationPath()}. + * + * @return The apex node evaluation of this expression can reference, or {@link SchemaPath#ROOT} if it cannot + * cannot be conclusively determined. + */ + @Nonnull SchemaPath getApexPath(); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNodesetResult.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNodesetResult.java new file mode 100644 index 0000000000..09d6742295 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNodesetResult.java @@ -0,0 +1,20 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import java.util.Collection; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +/** + * An {@link XPathResult} containing a set of nodes. + */ +@Beta +public interface XPathNodesetResult extends XPathResult>> { + +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNumberResult.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNumberResult.java new file mode 100644 index 0000000000..ce3a71423d --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathNumberResult.java @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; + +/** + * An {@link XPathResult} containing a Number. + */ +@Beta +public interface XPathNumberResult extends XPathResult { + +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathResult.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathResult.java new file mode 100644 index 0000000000..48c5c5e874 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathResult.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; + +/** + * Base interface for various things an XPath evaluation can return. + * + * @param type of returned value + * + * FIXME: do we want to support all the modes of + * DOM XPath ? + * The default DataTree (yang-data-impl) implementation can support ORDERED_NODE_SNAPSHOT_TYPE. The clustered + * datastore may want to implement ORDERED_NODE_ITERATOR_TYPE (via iterators). + */ +@Beta +public interface XPathResult { + /** + * Get the value contained in this result. + * + * @return Result value + */ + @Nonnull T getValue(); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContext.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContext.java new file mode 100644 index 0000000000..335a5ed529 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContext.java @@ -0,0 +1,42 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; +import javax.xml.xpath.XPathExpressionException; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; +import org.opendaylight.yangtools.yang.model.api.SchemaPath; + +/** + * A schema-informed XPath context. It supports creation of {@link XPathDocument}s, which are bound to + * a particular root node. + */ +@Beta +public interface XPathSchemaContext { + /** + * Compile an XPath expression for execution on {@link XPathDocument}s produced by this context. + * + * @param xpath XPath expression to compile + * @param schemaPath Schema path of the node at which this expression is expected to be evaluated + * @return A compiled XPath expression + * @throws XPathExpressionException if the provided expression is invalid, either syntactically or by referencing + * namespaces unknown to this schema context. + */ + @Nonnull XPathExpression compileExpression(@Nonnull String xpath, @Nonnull SchemaPath schemaPath) + throws XPathExpressionException; + + /** + * Create a new document context. + * + * @param documentRoot Root node of the document + * @return A new {@link XPathDocument} on which queries may be executed. + * @throws IllegalArgumentException if the document root is not known to this schema context. + */ + @Nonnull XPathDocument createDocument(@Nonnull NormalizedNode documentRoot); +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContextFactory.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContextFactory.java new file mode 100644 index 0000000000..6725439c22 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathSchemaContextFactory.java @@ -0,0 +1,41 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.base.Converter; +import javax.annotation.Nonnull; +import javax.xml.xpath.XPathException; +import org.opendaylight.yangtools.yang.common.QNameModule; +import org.opendaylight.yangtools.yang.model.api.SchemaContext; + +/** + * A factory for obtaining {@link XPathSchemaContext}s. This is the primary entry point to an XPath evaluation + * implementation. Users are expected to resolve these via their service resolution framework, be it + * {@link java.util.ServiceLoader}, OSGi or similar. + * + * Implementations are required to support {@link java.util.ServiceLoader}. + */ +public interface XPathSchemaContextFactory { + /** + * Create an {@link XPathSchemaContext} based on a {@link SchemaContext}. This effectively binds the namespaces + * the user expects to map to YANG schema. The {@link XPathExpression} compilation, relocation and optimization + * processes can take advantage of the YANG schema provided and the prefix mappings requested by the provided + * mapper. + * + * The user must provide a prefix-to-mapping {@link Converter}, which will be used to convert any prefixes found + * in the XPath expression being compiled in the resulting context. + * + * @param context SchemaContext associated with the resulting {@link XPathSchemaContext} + * @param prefixToNamespace Prefix-to-namespace converter + * @return An {@link XPathSchemaContext} instance + * @throws IllegalArgumentException if the converter contains a namespace which does not exist in the supplied + * SchemaContext. + */ + @Nonnull XPathSchemaContext createContext(@Nonnull SchemaContext context, + Converter prefixToNamespace) throws XPathException; +} diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathStringResult.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathStringResult.java new file mode 100644 index 0000000000..75a1b92246 --- /dev/null +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/xpath/XPathStringResult.java @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.yangtools.yang.data.api.schema.xpath; + +import com.google.common.annotations.Beta; + +/** + * An {@link XPathResult} containing a String. + */ +@Beta +public interface XPathStringResult extends XPathResult { + +} -- 2.36.6