binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.binding.api;
   9
  10 import com.google.common.util.concurrent.FluentFuture;
  11 import java.util.Optional;
  12 import org.opendaylight.mdsal.common.api.AsyncReadTransaction;
  13 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
  14 import org.opendaylight.mdsal.common.api.ReadFailedException;
  15 import org.opendaylight.yangtools.yang.binding.DataObject;
  16 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  17
  18
  19 /**
  20  * A transaction that provides a stateful read-only view of the data tree.
  21  *
  22  * <p>
  23  * For more information on usage and examples, please see the documentation in
  24  *  {@link org.opendaylight.mdsal.common.api.AsyncReadTransaction}.
  25  */
  26 public interface ReadTransaction extends AsyncReadTransaction<InstanceIdentifier<?>, DataObject> {
  27
  28     /**
  29      * Reads data from the provided logical data store located at the provided path.
  30      *
  31      *<p>
  32      * If the target is a subtree, then the whole subtree is read (and will be
  33      * accessible from the returned data object).
  34      *
  35      * @param store
  36      *            Logical data store from which read should occur.
  37      * @param path
  38      *            Path which uniquely identifies subtree which client want to
  39      *            read
  40      * @return a FluentFuture containing the result of the read. The Future blocks until the
  41      *         commit operation is complete. Once complete:
  42      *         <ul>
  43      *         <li>If the data at the supplied path exists, the Future returns an Optional object
  44      *         containing the data.</li>
  45      *         <li>If the data at the supplied path does not exist, the Future returns
  46      *         Optional.empty().</li>
  47      *         <li>If the read of the data fails, the Future will fail with a
  48      *         {@link ReadFailedException} or an exception derived from ReadFailedException.</li>
  49      *         </ul>
  50      */
  51     <T extends DataObject> FluentFuture<Optional<T>> read(LogicalDatastoreType store, InstanceIdentifier<T> path);
  52 }