org.opendaylight.mdsal.dom.api

Interface DOMDataTreeCommitCohort

All Known Implementing Classes:

BindingDOMDataTreeCommitCohortAdapter

@Beta
public interface DOMDataTreeCommitCohort

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

DOMDataTreeCommitCohorts 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 committed data.

Implementation requirements

Correctness assumptions

Implementation SHOULD use only the DOMDataTreeCandidate instances and provided SchemaContext 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 DOMDataBroker or DOMDataCommitCoordinator Note that this may be enforced by some implementations of DOMDataTreeCommitCohortRegistry and such calls may fail.

Correct model usage

If implementation is performing YANG-model driven validation implementation SHOULD use provided schema context. Any other instance of SchemaContext obtained by other means, may not be valid for the associated DOMDataTreeCandidates and it may lead to incorrect validation or processing of provided data.

DataTreeCandidate assumptions

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

Usage patterns

Data Tree Validator

Validator is implementation, which only validates DOMDataTreeCandidate instances and does not retain any state derived from edited data - does not care if a DOMDataTreeCandidate was rejected afterwards or transaction was cancelled. Implementation may opt-out from receiving preCommit(), commit(), abort() callbacks by returning PostCanCommitStep.NOOP.

Author:

Tony Tkacik

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	DOMDataTreeCommitCohort.DataValidationFailedExceptionMapper An ExceptionMapper that translates an Exception to a DataValidationFailedException.

Method Summary

Modifier and Type	Method and Description
@NonNull com.google.common.util.concurrent.FluentFuture<PostCanCommitStep>	canCommit(@NonNull Object txId, @NonNull org.opendaylight.yangtools.yang.model.api.SchemaContext ctx, @NonNull Collection<DOMDataTreeCandidate> candidates) Validates the supplied data tree modifications and associates the cohort-specific steps with data broker transaction.

Method Detail

canCommit

@NonNull com.google.common.util.concurrent.FluentFuture<PostCanCommitStep> canCommit(@NonNull Object txId,
                                                                                     @NonNull org.opendaylight.yangtools.yang.model.api.SchemaContext ctx,
                                                                                     @NonNull Collection<DOMDataTreeCandidate> candidates)

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 DOMDataTreeCommitCohortRegistry 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.

candidates - Data Tree candidates to be validated and committed.

ctx - Schema Context to which Data Tree candidate should conform.

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 DOMDataTreeCandidate instance did not pass validation. Users are encouraged to use more specific subclasses of this exception to provide additional information about validation failure reason.