From 7e9012b9820ed399a93d1f302dfa5c0e05583493 Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Thu, 18 Jan 2024 20:27:33 +0100 Subject: [PATCH] Rename DOMDataTreeCommitCohortRegistry to CommitCohortExtension This is a well-known extension, co-locate it with DOMDataBroker, so it is near at hand. JIRA: MDSAL-841 Change-Id: Idf71920640e4c9dc1a8e76d8bf3d4a7ac7b5fd40 Signed-off-by: Robert Varga --- ...OMDataTreeCommitCohortRegistryAdapter.java | 9 ++- ...taTreeCommitCohortRegistryAdapterTest.java | 8 +-- .../mdsal/dom/api/DOMDataBroker.java | 25 +++++++- .../dom/api/DOMDataTreeCommitCohort.java | 64 +++++++++---------- .../api/DOMDataTreeCommitCohortRegistry.java | 28 -------- .../mdsal/dom/spi/AbstractDOMDataBroker.java | 9 ++- 6 files changed, 65 insertions(+), 78 deletions(-) delete mode 100644 dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeCommitCohortRegistry.java diff --git a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapter.java b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapter.java index c31e30463f..2c25a6c9f0 100644 --- a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapter.java +++ b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapter.java @@ -10,16 +10,15 @@ package org.opendaylight.mdsal.binding.dom.adapter; import org.opendaylight.mdsal.binding.api.DataTreeCommitCohort; import org.opendaylight.mdsal.binding.api.DataTreeCommitCohortRegistry; import org.opendaylight.mdsal.binding.api.DataTreeIdentifier; -import org.opendaylight.mdsal.dom.api.DOMDataTreeCommitCohortRegistry; +import org.opendaylight.mdsal.dom.api.DOMDataBroker.CommitCohortExtension; import org.opendaylight.yangtools.concepts.Registration; import org.opendaylight.yangtools.yang.binding.Augmentation; import org.opendaylight.yangtools.yang.binding.DataObject; final class BindingDOMDataTreeCommitCohortRegistryAdapter - extends AbstractBindingAdapter implements DataTreeCommitCohortRegistry { - BindingDOMDataTreeCommitCohortRegistryAdapter(final AdapterContext codec, - final DOMDataTreeCommitCohortRegistry registry) { - super(codec, registry); + extends AbstractBindingAdapter implements DataTreeCommitCohortRegistry { + BindingDOMDataTreeCommitCohortRegistryAdapter(final AdapterContext codec, final CommitCohortExtension extension) { + super(codec, extension); } @Override diff --git a/binding/mdsal-binding-dom-adapter/src/test/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapterTest.java b/binding/mdsal-binding-dom-adapter/src/test/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapterTest.java index 02824349d0..a07bb76542 100644 --- a/binding/mdsal-binding-dom-adapter/src/test/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapterTest.java +++ b/binding/mdsal-binding-dom-adapter/src/test/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMDataTreeCommitCohortRegistryAdapterTest.java @@ -20,7 +20,7 @@ import org.opendaylight.mdsal.binding.api.DataTreeCommitCohort; import org.opendaylight.mdsal.binding.api.DataTreeIdentifier; import org.opendaylight.mdsal.binding.dom.adapter.test.util.BindingBrokerTestFactory; import org.opendaylight.mdsal.common.api.LogicalDatastoreType; -import org.opendaylight.mdsal.dom.api.DOMDataTreeCommitCohortRegistry; +import org.opendaylight.mdsal.dom.api.DOMDataBroker.CommitCohortExtension; import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.mdsal.test.binding.rev140701.Top; import org.opendaylight.yangtools.concepts.Registration; import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; @@ -28,7 +28,7 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; @ExtendWith(MockitoExtension.class) public class BindingDOMDataTreeCommitCohortRegistryAdapterTest { @Mock - private DOMDataTreeCommitCohortRegistry cohortRegistry; + private CommitCohortExtension cohortExtension; @Mock private Registration cohortRegistration; @Mock @@ -41,10 +41,10 @@ public class BindingDOMDataTreeCommitCohortRegistryAdapterTest { final var bindingTestContext = bindingBrokerTestFactory.getTestContext(); bindingTestContext.start(); - doReturn(cohortRegistration).when(cohortRegistry).registerCommitCohort(any(), any()); + doReturn(cohortRegistration).when(cohortExtension).registerCommitCohort(any(), any()); doNothing().when(cohortRegistration).close(); final var registryAdapter = new BindingDOMDataTreeCommitCohortRegistryAdapter(bindingTestContext.getCodec(), - cohortRegistry); + cohortExtension); final var dataTreeIdentifier = DataTreeIdentifier.of(LogicalDatastoreType.CONFIGURATION, InstanceIdentifier.create(Top.class)); diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java index a81b1a5bcf..6654fbdab5 100644 --- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java +++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java @@ -7,7 +7,8 @@ */ package org.opendaylight.mdsal.dom.api; -import org.eclipse.jdt.annotation.NonNull; +import org.eclipse.jdt.annotation.NonNullByDefault; +import org.opendaylight.yangtools.concepts.Registration; import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; /** @@ -41,6 +42,7 @@ import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; * Implementation Note: This interface is not intended to be implemented by users of MD-SAL, * but only to be consumed by them. */ +@NonNullByDefault public interface DOMDataBroker extends DOMService, DOMTransactionFactory { /** * Type capture of a {@link DOMService.Extension} applicable to {@link DOMDataBroker} implementations. @@ -55,7 +57,7 @@ public interface DOMDataBroker extends DOMServicePerformance implications - * {@link DOMDataTreeCommitCohort}s 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. + * {@link DOMDataTreeCommitCohort}s 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 {@link DOMDataTreeCandidate} instances and - * provided {@link EffectiveModelContext} 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 {@link DOMDataBroker} or DOMDataCommitCoordinator - * Note that this may be enforced by some implementations of {@link 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 {@link EffectiveModelContext} 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 - * {@link DOMDataTreeCandidate} being successfully committed until associated - * {@link PostCanCommitStep#preCommit()} and - * {@link org.opendaylight.mdsal.common.api.PostPreCommitStep#commit()} callback was invoked. + *

Correctness assumptions

+ * Implementation SHOULD use only the {@link DOMDataTreeCandidate} instances and provided {@link EffectiveModelContext} + * for validation purposes. + * + *

+ * Use of any other external mutable state is discouraged, implementation MUST NOT use any transaction related APIs on + * the 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 {@link DOMDataBroker} or {@link CommitCohortExtension}, + * potentially enforced through the extension 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 {@link EffectiveModelContext} obtained by other means, may not be valid for the associated + * {@link DOMDataTreeCandidate}s and it may lead to incorrect validation or processing of provided data. + * + *

DataTreeCandidate assumptions

+ * Implementation SHOULD NOT make any assumptions on a {@link DOMDataTreeCandidate} being successfully committed until + * the associated {@link PostCanCommitStep#preCommit()} and {@link PostPreCommitStep#commit()} callback was invoked. + * *

Usage patterns

*

Data Tree Validator

- * Validator is implementation, which only validates {@link DOMDataTreeCandidate} instances and does not - * retain any state derived from edited data - does not care if a {@link DOMDataTreeCandidate} was - * rejected afterwards or transaction was cancelled. - * Implementation may opt-out from receiving {@code preCommit()}, {@code commit()}, {@code abort()} - * callbacks by returning {@link PostCanCommitStep#NOOP}. - * - * @author Tony Tkacik + * Validator is implementation, which only validates {@link DOMDataTreeCandidate} instances and does not retain any + * state derived from edited data - does not care if a {@link DOMDataTreeCandidate} was rejected afterwards or + * the transaction was cancelled. Implementation may opt-out from receiving {@code preCommit()}, {@code commit()}, + * {@code abort()} callbacks by returning {@link PostCanCommitStep#NOOP}. */ // TODO: Provide example and describe more usage patterns @Beta public interface DOMDataTreeCommitCohort { - /** * Validates the supplied data tree modifications and associates the cohort-specific steps with data broker * transaction. @@ -73,7 +71,7 @@ public interface DOMDataTreeCommitCohort { * 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 {@link DOMDataTreeCommitCohortRegistry} and such calls may fail. + * implementations of {@link CommitCohortExtension} and such calls may fail. * *

* Implementation MAY opt-out from implementing other steps by returning diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeCommitCohortRegistry.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeCommitCohortRegistry.java deleted file mode 100644 index 90f9251838..0000000000 --- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeCommitCohortRegistry.java +++ /dev/null @@ -1,28 +0,0 @@ -/* - * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved. - * - * This program and the accompanying materials are made available under the - * terms of the Eclipse Public License v1.0 which accompanies this distribution, - * and is available at http://www.eclipse.org/legal/epl-v10.html - */ -package org.opendaylight.mdsal.dom.api; - -import org.eclipse.jdt.annotation.NonNullByDefault; -import org.opendaylight.yangtools.concepts.Registration; - -/** - * Commit Cohort registry for {@link DOMDataTreeWriteTransaction}. See {@link DOMDataTreeCommitCohort} for more details. - */ -@NonNullByDefault -public interface DOMDataTreeCommitCohortRegistry extends DOMDataBroker.Extension { - /** - * Register commit cohort which will participate in three-phase commit protocols of - * {@link DOMDataTreeWriteTransaction} in data broker associated with this instance of extension. - * - * @param path Subtree path on which commit cohort operates. - * @param cohort Commit cohort - * @return A {@link Registration} - * @throws NullPointerException if any argument is {@code null} - */ - Registration registerCommitCohort(DOMDataTreeIdentifier path, DOMDataTreeCommitCohort cohort); -} \ No newline at end of file diff --git a/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/AbstractDOMDataBroker.java b/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/AbstractDOMDataBroker.java index a06d63febe..92144cd068 100644 --- a/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/AbstractDOMDataBroker.java +++ b/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/AbstractDOMDataBroker.java @@ -15,7 +15,6 @@ import java.util.concurrent.atomic.AtomicLong; import org.eclipse.jdt.annotation.NonNull; import org.opendaylight.mdsal.common.api.LogicalDatastoreType; import org.opendaylight.mdsal.dom.api.DOMDataTreeChangeService; -import org.opendaylight.mdsal.dom.api.DOMDataTreeCommitCohortRegistry; import org.opendaylight.mdsal.dom.api.DOMTransactionChain; import org.opendaylight.mdsal.dom.spi.store.DOMStore; import org.opendaylight.mdsal.dom.spi.store.DOMStoreTransactionChain; @@ -44,11 +43,11 @@ public abstract class AbstractDOMDataBroker extends AbstractDOMForwardedTransact throw new IllegalStateException("Publisher for " + dsType + " data store is not available"); }); } - if (isSupported(datastores, DOMDataTreeCommitCohortRegistry.class)) { - builder.add((DOMDataTreeCommitCohortRegistry) (path, cohort) -> { + if (isSupported(datastores, CommitCohortExtension.class)) { + builder.add((CommitCohortExtension) (path, cohort) -> { final var dsType = path.datastore(); - if (getTxFactories().get(dsType) instanceof DOMDataTreeCommitCohortRegistry registry) { - return registry.registerCommitCohort(path, cohort); + if (getTxFactories().get(dsType) instanceof CommitCohortExtension extension) { + return extension.registerCommitCohort(path, cohort); } throw new IllegalStateException("Cohort registry for " + dsType + " data store is not available"); }); -- 2.36.6