opendaylight/sal/yang-prototype/sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/data/DataBrokerService.java

   1 /*
   2  * Copyright (c) 2013 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.controller.sal.binding.api.data;
   9
  10 import java.util.concurrent.Future;
  11
  12 import org.opendaylight.controller.sal.binding.api.BindingAwareService;
  13 import org.opendaylight.controller.sal.common.DataStoreIdentifier;
  14 import org.opendaylight.yangtools.yang.binding.DataRoot;
  15 import org.opendaylight.yangtools.yang.common.RpcResult;
  16
  17 /**
  18  * DataBrokerService provides unified access to the data stores available in the
  19  * system.
  20  *
  21  *
  22  * @see DataConsumerService
  23  */
  24 public interface DataBrokerService extends BindingAwareService {
  25
  26     /**
  27      * Returns a data from specified Data Store.
  28      *
  29      * Returns all the data visible to the consumer from specified Data Store.
  30      *
  31      * @param <T>
  32      *            Interface generated from YANG module representing root of data
  33      * @param store
  34      *            Identifier of the store, from which will be data retrieved
  35      * @return data visible to the consumer
  36      */
  37     <T extends DataRoot> T getData(DataStoreIdentifier store, Class<T> rootType);
  38
  39     /**
  40      * Returns a filtered subset of data from specified Data Store.
  41      *
  42      * <p>
  43      * The filter is modeled as an hierarchy of Java TOs starting with
  44      * implementation of {@link DataRoot} representing data root. The semantics
  45      * of the filter tree is the same as filter semantics defined in the NETCONF
  46      * protocol for rpc operations <code>get</code> and <code>get-config</code>
  47      * in Section 6 of RFC6241.
  48      *
  49      *
  50      * @see http://tools.ietf.org/html/rfc6241#section-6
  51      * @param <T>
  52      *            Interface generated from YANG module representing root of data
  53      * @param store
  54      *            Identifier of the store, from which will be data retrieved
  55      * @param filter
  56      *            Data tree filter similar to the NETCONF filter
  57      * @return
  58      */
  59     <T extends DataRoot> T getData(DataStoreIdentifier store, T filter);
  60
  61     /**
  62      * Returns a candidate data which are not yet commited.
  63      *
  64      *
  65      * @param <T>
  66      *            Interface generated from YANG module representing root of data
  67      * @param store
  68      *            Identifier of the store, from which will be data retrieved
  69      * @return
  70      */
  71     <T extends DataRoot> T getCandidateData(DataStoreIdentifier store, Class<T> rootType);
  72
  73     /**
  74      * Returns a filtered subset of candidate data from specified Data Store.
  75      *
  76      * <p>
  77      * The filter is modeled as an hierarchy of {@link Node} starting with
  78      * {@link CompositeNode} representing data root. The semantics of the filter
  79      * tree is the same as filter semantics defined in the NETCONF protocol for
  80      * rpc operations <code>get</code> and <code>get-config</code> in Section 6
  81      * of RFC6241.
  82      *
  83      *
  84      * @see http://tools.ietf.org/html/rfc6241#section-6
  85      * @param <T>
  86      *            Interface generated from YANG module representing root of data
  87      * @param store
  88      *            Identifier of the store, from which will be data retrieved
  89      * @param filter
  90      *            A filter data root
  91      * @return
  92      */
  93     <T extends DataRoot> T getCandidateData(DataStoreIdentifier store, T filter);
  94
  95     /**
  96      *
  97      * @param <T>
  98      *            Interface generated from YANG module representing root of data
  99      * @param store
 100      *            Identifier of the store, in which will be the candidate data
 101      *            modified
 102      * @param changeSet
 103      *            Modification of data tree.
 104      * @return Result object containing the modified data tree if the operation
 105      *         was successful, otherwise list of the encountered errors.
 106      */
 107     RpcResult<DataRoot> editCandidateData(DataStoreIdentifier store, DataRoot changeSet);
 108
 109     /**
 110      * Initiates a two-phase commit of candidate data.
 111      *
 112      * <p>
 113      * The {@link Consumer} could initiate a commit of candidate data
 114      *
 115      * <p>
 116      * The successful commit changes the state of the system and may affect
 117      * several components.
 118      *
 119      * <p>
 120      * The effects of successful commit of data are described in the
 121      * specifications and YANG models describing the {@link Provider} components
 122      * of controller. It is assumed that {@link Consumer} has an understanding
 123      * of this changes.
 124      *
 125      *
 126      * @see DataCommitHandler for further information how two-phase commit is
 127      *      processed.
 128      * @param store
 129      *            Identifier of the store, where commit should occur.
 130      * @return Result of the commit, containing success information or list of
 131      *         encountered errors, if commit was not successful.
 132      */
 133     Future<RpcResult<Void>> commit(DataStoreIdentifier store);
 134 }