opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitHandler.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.controller.md.sal.common.api.data;
   9
  10 import com.google.common.util.concurrent.CheckedFuture;
  11 import org.opendaylight.yangtools.concepts.Path;
  12
  13 /**
  14  * User-supplied participant in three-phase commit of transaction for configuration data tree.
  15  *
  16  * <p>
  17  * Client-supplied implementation of commit handler for subtree, which
  18  * is responsible for processing CAN-COMMIT phase of three-phase commit protocol
  19  * and return CommitCohort, which provides access to additional transitions
  20  * such as PRE-COMMIT, COMMIT and ABORT.
  21  *
  22  * @param <P>
  23  *            Type of path (subtree identifier), which represents location in
  24  *            tree
  25  * @param <D>
  26  *            Type of data (payload), which represents data payload
  27  */
  28 @Deprecated
  29 public interface AsyncConfigurationCommitHandler<P extends Path<P>, D> {
  30
  31     /**
  32      * Requests a can commit phase
  33      *
  34      * <p>
  35      * Implementations SHOULD NOT do any blocking operation during
  36      * processing this callback.
  37      *
  38      * <b>Implementation Notes</b>
  39      * <ul>
  40      * <li>Implementation are REQUIRED to use <code>request</code> object for any data related access</li>
  41      * <li>Implementations SHOULD NOT use any other state stored outside configuration subtree for validation</li>
  42      * <li>Validation should happen asynchronously, outside callback call by updating returned {@link CheckedFuture}
  43      *     object.</li>
  44      * <li>If validation (CAN_COMMIT) phase:
  45      * <ul>
  46      * <li><b>is successful</b> - invocation of {@link CheckedFuture#checkedGet()} on returned future MUST
  47      *     return {@link AsyncConfigurationCommitCohort} associated with request.</li>
  48      * <li><b>is unsuccessful</b> - invocation of {@link CheckedFuture#checkedGet()} must throw instance
  49      *     of {@link DataValidationFailedException}
  50      * with human readable explanaition of error condition.
  51      * </li>
  52      * </ul>
  53      * </li>
  54      * </ul>
  55      * @param request
  56      *            Commit Request submitted by client, which contains
  57      *            information about modifications and read-only view as
  58      *            if transaction happened.
  59      * @return CheckedFuture which contains client-supplied implementation of {@link AsyncConfigurationCommitCohort}
  60      *         associated with submitted request, if can commit phase is
  61      *         successful, if can commit was unsuccessful, future must fail with
  62      *         {@link TransactionCommitFailedException} exception.
  63      */
  64     CheckedFuture<AsyncConfigurationCommitCohort<P, D>, DataValidationFailedException> canCommit(
  65             ConfigurationCommitRequest<P, D> request);
  66
  67     /**
  68      * Commit Request as was submitted by client code
  69      *
  70      * <p>
  71      * Commit Request contains list view of created / updated / removed
  72      * path and read-only view of proposed client transaction,
  73      * which may be used to retrieve modified or referenced data.
  74      *
  75      *
  76      * @param <P>
  77      *            Type of path (subtree identifier), which represents location
  78      *            in tree
  79      * @param <D>
  80      *            Type of data (payload), which represents data payload
  81      */
  82     interface ConfigurationCommitRequest<P extends Path<P>, D> {
  83
  84         /**
  85          * Read-only transaction which provides access only to configuration
  86          * data tree as if submitted transaction successfully happened and
  87          * no other concurrent modifications happened between allocation
  88          * of client transactions and write of client transactions.
  89          *
  90          * <p>
  91          * Implementations of Commit Handlers are REQUIRED to use this
  92          * read-only view to access any data from configuration data tree,
  93          * in order to capture them as preconditions for this transaction.
  94          *
  95          * @return Read-only transaction which provides access only to configuration
  96          *     data tree as if submitted transaction successfully happened
  97          */
  98         AsyncReadTransaction<P, D> getReadOnlyView();
  99
 100         /**
 101          * Returns iteration of paths, to data which was introduced by this transaction.
 102          *
 103          * @return Iteration of paths, which was introduced by this transaction.
 104          */
 105         Iterable<P> getCreatedPaths();
 106
 107         /**
 108          * Returns iteration of paths, to data which was updated by this transaction.
 109          *
 110          * @return Iteration of paths, which was updated by this transaction.
 111          */
 112         Iterable<P> getUpdatedPaths();
 113
 114         /**
 115          * Returns iteration of paths, to data which was removed by this transaction.
 116          *
 117          * @return Iteration of paths, which was removed by this transaction.
 118          */
 119         Iterable<P> getRemovedPaths();
 120     }
 121
 122 }