Package org.opendaylight.yangtools.yang.data.jaxen.api

Interface LazyXPathExpression

  • @Deprecated
@Beta
public 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.
    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 Detail

      • evaluateLazily

        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