org.opendaylight.yangtools.yang.data.api.schema.xpath

Interface LazyXPathExpression

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

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.

Method Summary

Modifier and Type	Method and Description
com.google.common.util.concurrent.ListenableFuture<Optional<? extends XPathResult<?>>>	evaluateLazily(XPathDocument document, YangInstanceIdentifier path) Deprecated. Evaluate this expression at the specified path in a document.

Method Detail

evaluateLazily

com.google.common.util.concurrent.ListenableFuture<Optional<? extends XPathResult<?>>> evaluateLazily(@Nonnull
                                                                                                      XPathDocument document,
                                                                                                      @Nonnull
                                                                                                      YangInstanceIdentifier path)

Deprecated.

Evaluate this expression at the specified path in a document. If evaluation succeeds, it will return an XPathResult at some point it the future. If it fails to match anything, it Future.get() will return Optional.empty().

FIXME: The amount of overhead an implementation can incur on the user as data from the resulting 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 LazyXPathExpressionException, which the users are expected to handle gracefully. RESILIENT USERS ARE EXPECTED TO CATCH LazyXPathExpressionException AND RECOVER IN THE SAME MANNER THEY WOULD IF AN XPathExpressionException WOULD HAVE BEEN THROWN. [ FIXME: would it be appropriate to allow implementations to SneakyThrow XPathExpressionException and not introduce a RuntimeExpcetion ? ]

Parameters:

document - XPathDocument on which evaluation should take place

path - Path to the node on which to evaluate the expression

Returns:

An optional XPathResult

Throws:

NullPointerException - if any of the arguments are null

IllegalArgumentException - if the path does not match the path at which this expression was compiled