binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/DataTreeCommitCohort.java

   1 /*
   2  * Copyright (c) 2017 Pantheon Technologies s.r.o. 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
   9 package org.opendaylight.mdsal.binding.javav2.api;
  10
  11 import com.google.common.annotations.Beta;
  12 import java.util.function.BiConsumer;
  13 import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
  14 import org.opendaylight.mdsal.common.api.DataValidationFailedException;
  15 import org.opendaylight.mdsal.common.api.PostCanCommitStep;
  16
  17 /**
  18  * Commit cohort participating in commit of data modification, which can validate data tree
  19  * modifications, with option to reject supplied modification, and with callbacks describing state
  20  * of commit.
  21  *
  22  * <h2>Performance implications</h2>
  23  *
  24  * {@link DataTreeCommitCohort}s are hooked up into commit of data tree changes and MAY
  25  * negatively affect performance of data broker / store.
  26  *
  27  * <p>
  28  * Implementations of this interface are discouraged, unless you really need ability to veto data
  29  * tree changes, or to provide external state change in sync with visibility of commited data.
  30  *
  31  * <h2>Implementation requirements</h2>
  32  *
  33  * <h3>Correctness assumptions</h3> Implementation SHOULD use only provided
  34  * {@link DataTreeModification} for validation purposes.
  35  *
  36  * <p>
  37  * Use of any other external mutable state is discouraged, implementation MUST NOT use any
  38  * transaction related APIs on same data broker / data store instance during invocation of
  39  * callbacks, except ones provided as argument. Note that this MAY BE enforced by some
  40  * implementations of {@link DataBroker} or Commit coordinator
  41  *
  42  * <p>
  43  * Note that this may be enforced by some implementations of {@link DataTreeCommitCohortRegistry}
  44  * and such calls may fail.
  45  *
  46  * <h3>DataTreeCandidate assumptions</h3> Implementation SHOULD NOT make any assumptions on
  47  * {@link DataTreeModification} being successfully committed until associated
  48  * {@link PostCanCommitStep#preCommit()} and
  49  * {@link org.opendaylight.mdsal.common.api.PostPreCommitStep#commit()} callback was invoked.
  50  *
  51  * <h2>Usage patterns</h2>
  52  *
  53  * <h3>Data Tree Validator</h3>
  54  *
  55  * <p>
  56  * Validator is implementation, which only validates {@link DataTreeModification} and does not
  57  * retain any state derived from edited data - does not care if {@link DataTreeModification} was
  58  * rejected afterwards or transaction was cancelled.
  59  *
  60  * <p>
  61  * Implementation may opt-out from receiving {@code preCommit()}, {@code commit()}, {@code abort()}
  62  * callbacks by returning {@link PostCanCommitStep#NOOP}.
  63  */
  64 @Beta
  65 public interface DataTreeCommitCohort<T extends TreeNode> {
  66     /**
  67      * Performs canCommit? message in three-phase commit algorithm.
  68      *
  69      * @param txId Transaction identifier
  70      * @param modification modification of data tree
  71      * @param callback result callback
  72      */
  73     void canCommit(Object txId, DataTreeModification<T> modification,
  74         BiConsumer<DataValidationFailedException, PostCanCommitStep> callback);
  75 }