org.opendaylight.mdsal.binding.api.query.QueryExpression Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mdsal-binding-api Show documentation
The newest version!
/*
 * Copyright (c) 2020 PANTHEON.tech, s.r.o. 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.mdsal.binding.api.query;

import com.google.common.annotations.Beta;
import org.opendaylight.yangtools.binding.DataObject;
import org.opendaylight.yangtools.concepts.Immutable;

/**
 * An opaque query expression. A query execution results in a {@link QueryResult}, which is composed of zero or more
 * objects of the same type. Implementations of this interface are expected to be effectively-immutable and therefore
 * thread-safe and reusable.
 *
 * While this interface does not expose any useful methods, it represents a well-defined concept, which is composed
 * of three distinct parts:
 * 

 *   root path, which defines the subtree on which the expression is executed
 *   select path, which is a strict subset of the root path and defines which objects should be selected
 *   a set of predicates, which are to be evaluated on selected objects
 * 
 * When the expression is evaluated, its QueryResult will contain only those selected objects which also match all
 * predicates in the expression.
 *
 * For the purposes of illustration of how these three parts work together, let's imagine the following simple model:
 * 
 *   module foo {
 *     list foo {
 *       key name;
 *
 *       leaf name {
 *         type string;
 *       }
 *
 *       leaf alias {
 *         type string;
 *       }
 *
 *       container bar {
 *         list baz {
 *           key id;
 *
 *           leaf id {
 *             type uint64;
 *           }
 *
 *           leaf value {
 *             type string;
 *           }
 *         }
 *       }
 *     }
 *   }
 * 
 *
 * We have two nested lists, each having two leaves -- one addressable as a key, one a plain property. There is
 * a number of different queries we could perform on such a model:
 * 

 *   select all {@code baz}es which have {@code value="foo"}
 *   select all {@code baz}es under {@code foo[name="xyzzy"]}, which have {@code value="foo"}
 *   select all {@code foo}s which have {@code alias="xyzzy"}
 *   select all {@code foo}s which have {@code alias="xyzzy"} and contain a {@code baz[value="foo"]}
 * 
 *
 * Note how the first and second options differ in what is being searched:
 * 

 *   search for all {@code baz} entries needs to traverse all {@code foo} entries
 *   search for all {@code baz} entries for {@code foo[name="xyzzy"]} needs to traverse only a single
 *       directly-addressable entry.
 * 
 * The distinction here is made by selecting different root paths: the first will specify the entire {@code foo} list,
 * while the second will select a specific {@code foo} entry.
 *
 * @param  Result object type
 */
@Beta
public interface QueryExpression extends Immutable {
    // Nothing else
}