--- /dev/null
+/*
+ * 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
+ * <a href="mailto:yangtools-dev@lists.opendaylight.org">yangtools-dev</a>.
+ */
+@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<Optional<? extends XPathResult<?>>, XPathExpressionException> evaluateLazily(
+ @Nonnull XPathDocument document, @Nonnull YangInstanceIdentifier path);
+}
--- /dev/null
+/*
+ * 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
+ * <a href="mailto:yangtools-dev@lists.opendaylight.org">yangtools-dev</a>.
+ */
+@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);
+ }
+}
--- /dev/null
+/*
+ * 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();
+}
--- /dev/null
+/*
+ * 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<String, QNameModule> 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<String, QNameModule> 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());
+ }
+}
--- /dev/null
+/*
+ * 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();
+}
--- /dev/null
+/*
+ * 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<Boolean> {
+
+}
--- /dev/null
+/*
+ * 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();
+}
--- /dev/null
+/*
+ * 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<? extends XPathResult<?>> 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();
+}
--- /dev/null
+/*
+ * 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<Collection<NormalizedNode<?, ?>>> {
+
+}
--- /dev/null
+/*
+ * 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<Number> {
+
+}
--- /dev/null
+/*
+ * 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 <T> type of returned value
+ *
+ * FIXME: do we want to support all the modes of
+ * <a href="http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html#XPathResultType">DOM XPath</a> ?
+ * 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<T> {
+ /**
+ * Get the value contained in this result.
+ *
+ * @return Result value
+ */
+ @Nonnull T getValue();
+}
--- /dev/null
+/*
+ * 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);
+}
--- /dev/null
+/*
+ * 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<String, QNameModule> prefixToNamespace) throws XPathException;
+}
--- /dev/null
+/*
+ * 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<String> {
+
+}
Code Review / yangtools.git / commitdiff