org.opendaylight.mdsal.binding.api

Interface DataTreeCommitCohort<T extends DataObject>

@Beta
public interface DataTreeCommitCohort<T extends DataObject>

Commit cohort participating in commit of data modification, which can validate data tree modifications, with option to reject supplied modification, and with callbacks describing state of commit.

Performance implications

DataTreeCommitCohorts are hooked up into commit of data tree changes and MAY negatively affect performance of data broker / store.

Implementations of this interface are discouraged, unless you really need ability to veto data tree changes, or to provide external state change in sync with visibility of commited data.

Implementation requirements

Correctness assumptions

Implementation SHOULD use only provided DataTreeModification for validation purposes.

Use of any other external mutable state is discouraged, implementation MUST NOT use any transaction related APIs on same data broker / data store instance during invocation of callbacks, except ones provided as argument. Note that this MAY BE enforced by some implementations of DataBroker or Commit coordinator

Note that this may be enforced by some implementations of DataTreeCommitCohortRegistry and such calls may fail.

DataTreeCandidate assumptions

Implementation SHOULD NOT make any assumptions on DataTreeModification being successfully committed until associated PostCanCommitStep.preCommit() and PostPreCommitStep.commit() callback was invoked.

Usage patterns

Data Tree Validator

Validator is implementation, which only validates DataTreeModification and does not retain any state derived from edited data - does not care if DataTreeModification was rejected afterwards or transaction was cancelled.

Implementation may opt-out from receiving preCommit(), commit(), abort() callbacks by returning PostCanCommitStep.NOOP.

TODO: Provide example and describe more usage patterns

Author:

Tony Tkacik <ttkacik@cisco.com>

Method Summary

Modifier and Type	Method and Description
@NonNull com.google.common.util.concurrent.FluentFuture<PostCanCommitStep>	canCommit(@NonNull Object txId, @NonNull Collection<DataTreeModification<T>> modifications) Validates the supplied data tree modifications and associates the cohort-specific steps with data broker transaction.

Method Detail

canCommit

@CheckReturnValue
@NonNull com.google.common.util.concurrent.FluentFuture<PostCanCommitStep> canCommit(@NonNull Object txId,
                                                                                                       @NonNull Collection<DataTreeModification<T>> modifications)

Validates the supplied data tree modifications and associates the cohort-specific steps with data broker transaction.

If DataValidationFailedException is thrown by implementation, the commit of the supplied data will be prevented, with the DataBroker transaction providing the thrown exception as the cause of failure.

Note the implementations are expected to do validation and processing asynchronous. Implementations SHOULD do processing fast, and are discouraged from blocking on any external resources. Implementation MUST NOT access any data transaction related APIs during invocation of the callback. Note that this may be enforced by some implementations of DataTreeCommitCohortRegistry and such calls may fail.

Implementation MAY opt-out from implementing other steps by returning PostCanCommitStep.NOOP. Otherwise implementation MUST return instance of PostCanCommitStep, which will be used to invoke PostPreCommitStep.commit() or ThreePhaseCommitStep.abort() based on accepting data by data broker and or other commit cohorts.

Parameters:

txId - Transaction identifier. SHOULD be used only for reporting and correlation. Implementation MUST NOT use txId for validation.

modifications - the DataTreeModifications to be validated and committed.

Returns:

a FluentFuture which will successfully complete with the user-supplied implementation of PostCanCommitStep if all candidates are valid, or a failed future with a DataValidationFailedException if and only if a provided DataTreeModification instance did not pass validation. Users are encouraged to use more specific subclasses of this exception to provide additional information about validation failure reason.