-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.opendaylight.controller</groupId>
<artifactId>sal-parent</artifactId>
<version>1.1-SNAPSHOT</version>
</parent>
+
<artifactId>sal-common-api</artifactId>
+ <packaging>bundle</packaging>
+
<scm>
- <connection>scm:git:ssh://git.opendaylight.org:29418/controller.git</connection>
- <developerConnection>scm:git:ssh://git.opendaylight.org:29418/controller.git</developerConnection>
- <url>https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL</url>
- <tag>HEAD</tag>
- </scm>
+ <connection>scm:git:ssh://git.opendaylight.org:29418/controller.git</connection>
+ <developerConnection>scm:git:ssh://git.opendaylight.org:29418/controller.git</developerConnection>
+ <url>https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL</url>
+ <tag>HEAD</tag>
+ </scm>
<dependencies>
<dependency>
<groupId>org.opendaylight.yangtools</groupId>
<artifactId>concepts</artifactId>
</dependency>
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ </dependency>
</dependencies>
- <packaging>bundle</packaging>
</project>
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import org.opendaylight.yangtools.concepts.ListenerRegistration;
+import org.opendaylight.yangtools.concepts.Path;
+
+public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChangeListener<P, D>> extends //
+ AsyncDataTransactionFactory<P, D> {
+
+ /**
+ *
+ * Scope of Data Change
+ *
+ * Represents scope of data change (addition, replacement, deletion).
+ *
+ * The terminology for types is reused from LDAP
+ *
+ * @see http://www.idevelopment.info/data/LDAP/LDAP_Resources/SEARCH_Setting_the_SCOPE_Parameter.shtml
+ */
+ public enum DataChangeScope {
+
+ /**
+ * Represents only a direct change of the node, such as replacement of node,
+ * addition or deletion.
+ *
+ */
+ BASE,
+ /**
+ * Represent a change (addition,replacement,deletion)
+ * of the node or one of it's direct childs.
+ *
+ */
+ ONE,
+ /**
+ * Represents a change of the node or any of it's child nodes.
+ *
+ */
+ SUBTREE
+ }
+
+ @Override
+ public AsyncReadTransaction<P, D> newReadOnlyTransaction();
+
+ @Override
+ public AsyncReadWriteTransaction<P,D> newReadWriteTransaction();
+
+ @Override
+ public AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
+
+ /**
+ * Registers {@link DataChangeListener} for Data Change callbacks
+ * which will be triggered on which will be triggered on the store
+ *
+ * @param store Logical store in which listener is registered.
+ * @param path Path (subtree identifier) on which client listener will be invoked.
+ * @param listener Instance of listener which should be invoked on
+ * @param triggeringScope Scope of change which triggers callback.
+ * @return Listener registration of the listener, call {@link ListenerRegistration#close()}
+ * to stop delivery of change events.
+ */
+ ListenerRegistration<L> registerDataChangeListener(LogicalDatastoreType store, P path, L listener, DataChangeScope triggeringScope);
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import java.util.Map;
+import java.util.Set;
+
+import org.opendaylight.yangtools.concepts.Immutable;
+import org.opendaylight.yangtools.concepts.Path;
+
+public interface AsyncDataChangeEvent<P extends Path<P>,D> extends Immutable {
+ /**
+ * Returns a immutable map of paths and newly created objects
+ *
+ * @return map of paths and newly created objects
+ */
+ Map<P, D> getCreatedData();
+
+ /**
+ * Returns a immutable map of paths and respective updated objects after update.
+ *
+ * Original state of the object is in
+ * {@link #getOriginalData()}
+ *
+ * @return map of paths and newly created objects
+ */
+ Map<P, D> getUpdatedData();
+
+ /**
+ * Returns a immutable set of removed paths.
+ *
+ * Original state of the object is in
+ * {@link #getOriginalData()}
+ *
+ * @return set of removed paths
+ */
+ Set<P> getRemovedPaths();
+
+ /**
+ * Return a immutable map of paths and original state of updated and removed objects.
+ *
+ * This map is populated if at changed path was previous object, and captures
+ * state of previous object.
+ *
+ * @return map of paths and original state of updated and removed objects.
+ */
+ Map<P, ? extends D> getOriginalData();
+
+ /**
+ * Returns a immutable stable view of data state, which
+ * captures state of data store before the reported change.
+ *
+ *
+ * The view is rooted at the point where the listener, to which the event is being delivered, was registered.
+ *
+ * @return Stable view of data before the change happened, rooted at the listener registration path.
+ *
+ */
+ D getOriginalSubtree();
+
+ /**
+ * Returns a immutable stable view of data, which captures state of data store
+ * after the reported change.
+ *
+ * The view is rooted at the point where the listener, to which the event is being delivered, was registered.
+ *
+ * @return Stable view of data after the change happened, rooted at the listener registration path.
+ */
+ D getUpdatedSubtree();
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import java.util.EventListener;
+
+import org.opendaylight.yangtools.concepts.Path;
+
+public interface AsyncDataChangeListener<P extends Path<P>, D> extends EventListener {
+ /**
+ * Note that this method may be invoked from a shared thread pool, so
+ * implementations SHOULD NOT perform CPU-intensive operations and they
+ * definitely MUST NOT invoke any potentially blocking operations.
+ *
+ * @param change Data Change Event being delivered.
+ */
+ void onDataChanged(AsyncDataChangeEvent<P, D> change);
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import org.opendaylight.yangtools.concepts.Path;
+
+public interface AsyncDataTransactionFactory<P extends Path<P>, D> {
+
+ AsyncReadTransaction<P, D> newReadOnlyTransaction();
+
+ AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
+
+ AsyncWriteTransaction<P,D> newWriteOnlyTransaction();
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import java.util.concurrent.Future;
+
+import org.opendaylight.yangtools.concepts.Path;
+
+import com.google.common.base.Optional;
+import com.google.common.util.concurrent.ListenableFuture;
+
+public interface AsyncReadTransaction<P extends Path<P>, D> extends AsyncTransaction<P, D> {
+
+ /**
+ *
+ * Reads data from provided logical data store located at provided path
+ *
+ *
+ * @param store
+ * Logical data store from which read should occur.
+ * @param path
+ * Path which uniquely identifies subtree which client want to
+ * read
+ * @return Listenable Future which contains read result
+ * <ul>
+ * <li>If data at supplied path exists the {@link Future#get()}
+ * returns Optional object containing data
+ * <li>If data at supplied path does not exists the
+ * {@link Future#get()} returns {@link Optional#absent()}.
+ * </ul>
+ */
+ ListenableFuture<Optional<D>> read(LogicalDatastoreType store, P path);
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import org.opendaylight.yangtools.concepts.Path;
+
+/**
+ * Transaction enabling client to have combined transaction,
+ * which provides read and write capabilities.
+ *
+ *
+ * @param <P> Path Type
+ * @param <D> Data Type
+ */
+public interface AsyncReadWriteTransaction<P extends Path<P>, D> extends AsyncReadTransaction<P, D>,
+ AsyncWriteTransaction<P, D> {
+
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import org.opendaylight.yangtools.concepts.Identifiable;
+import org.opendaylight.yangtools.concepts.Path;
+
+
+/**
+ *
+ * @author
+ *
+ * @param <P> Type of path (subtree identifier), which represents location in tree
+ * @param <D> Type of data (payload), which represents data payload
+ */
+public interface AsyncTransaction<P extends Path<P>,D> extends //
+ Identifiable<Object>,
+ AutoCloseable {
+
+ @Override
+ public Object getIdentifier();
+
+ /**
+ * Closes transaction and releases all resources associated with it.
+ */
+ @Override
+ public void close();
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+import java.util.concurrent.Future;
+
+import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
+import org.opendaylight.yangtools.concepts.Path;
+import org.opendaylight.yangtools.yang.common.RpcResult;
+
+public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransaction<P, D> {
+ /**
+ * Cancels transaction.
+ *
+ * Transaction could be only cancelled if it's status
+ * is {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
+ *
+ * Invoking cancel() on {@link TransactionStatus#FAILED} or {@link TransactionStatus#CANCELED}
+ * will have no effect.
+ *
+ * @throws IllegalStateException If transaction status is {@link TransactionStatus#COMMITED}
+ *
+ */
+ public void cancel();
+
+ /**
+ * Store a piece of data at specified path. This acts as a add / replace operation,
+ * which is to say that whole subtree will be replaced by specified path.
+ *
+ * If you need add or merge of current object with specified use {@link #merge(LogicalDatastoreType, Path, Object)}
+ *
+ * @param store Logical data store which should be modified
+ * @param path Data object path
+ * @param data Data object to be written to specified path
+ * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
+ */
+ public void put(LogicalDatastoreType store, P path, D data);
+
+ /**
+ * Store a piece of data at specified path. This acts as a merge operation,
+ * which is to say that any pre-existing data which is not explicitly
+ * overwritten will be preserved. This means that if you store a container,
+ * its child lists will be merged. Performing the following put operations:
+ *
+ * 1) container { list [ a ] }
+ * 2) container { list [ b ] }
+ *
+ * will result in the following data being present:
+ *
+ * container { list [ a, b ] }
+ *
+ * This also means that storing the container will preserve any augmentations
+ * which have been attached to it.
+ *
+ * If you require an explicit replace operation, use {@link #put(LogicalDatastoreType, Path, Object)} instead.
+ *
+ * @param store Logical data store which should be modified
+ * @param path Data object path
+ * @param data Data object to be written to specified path
+ * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
+ */
+ public void merge(LogicalDatastoreType store, P path, D data);
+
+ /**
+ * Remove a piece of data from specified path. This operation does not fail
+ * if the specified path does not exist.
+ *
+ * @param store Logical data store which should be modified
+ * @param path Data object path
+ * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
+ */
+ public void delete(LogicalDatastoreType store, P path);
+
+ /**
+ *
+ * Closes transaction and resources allocated to the transaction.
+ *
+ * This call does not change Transaction status. Client SHOULD
+ * explicitly {@link #commit()} or {@link #cancel()} transaction.
+ *
+ * @throws IllegalStateException if the transaction has not been
+ * updated by invoking {@link #commit()} or {@link #cancel()}.
+ */
+ @Override
+ public void close();
+
+ /**
+ * Initiates a commit of modification. This call logically seals the
+ * transaction, preventing any the client from interacting with the
+ * data stores. The transaction is marked as {@link TransactionStatus#SUBMITED}
+ * and enqueued into the data store backed for processing.
+ *
+ * <p>
+ * The successful commit changes the state of the system and may affect
+ * several components.
+ *
+ * <p>
+ * The effects of successful commit of data are described in the
+ * specifications and YANG models describing the Provider components of
+ * controller. It is assumed that Consumer has an understanding of this
+ * changes.
+ *
+ * @see DataCommitHandler for further information how two-phase commit is
+ * processed.
+ * @param store Identifier of the store, where commit should occur.
+ * @return Result of the Commit, containing success information or list of
+ * encountered errors, if commit was not successful. The Future
+ * blocks until {@link TransactionStatus#COMMITED} or
+ * {@link TransactionStatus#FAILED} is reached.
+ * @throws IllegalStateException if the transaction is not {@link TransactionStatus#NEW}
+ */
+ public Future<RpcResult<TransactionStatus>> commit();
+
+}
import org.opendaylight.yangtools.concepts.Path;
public interface DataChangeListener<P extends Path<P>, D> extends EventListener {
-
+ /**
+ * Note that this method may be invoked from a shared thread pool, so
+ * implementations SHOULD NOT perform CPU-intensive operations and they
+ * definitely MUST NOT invoke any potentially blocking operations.
+ *
+ * @param change Data Change Event being delivered.
+ **/
void onDataChanged(DataChangeEvent<P, D> change);
}
--- /dev/null
+/*
+ * Copyright (c) 2014 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.controller.md.sal.common.api.data;
+
+public enum LogicalDatastoreType {
+
+ /**
+ * Logical atastore representing operational state of the system
+ * and it's components
+ *
+ * This datastore is used to describe operational state of
+ * the system and it's operation related data.
+ *
+ */
+ OPERATIONAL,
+ /**
+ * Logical Datastore representing configuration state of the system
+ * and it's components.
+ *
+ * This datastore is used to describe intended state of
+ * the system and intended operation mode.
+ *
+ */
+ CONFIGURATION
+
+}
* A chain of transactions. Transactions in a chain need to be committed in sequence and each
* transaction should see the effects of previous transactions as if they happened. A chain
* makes no guarantees of atomicity, in fact transactions are committed as soon as possible.
+ *
*/
-public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable {
+public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable, AsyncDataTransactionFactory<P, D> {
+
/**
- * Create a new transaction which will continue the chain. The previous transaction
- * has to be either COMMITTED or CANCELLED.
+ * Create a new read only transaction which will continue the chain.
+ * The previous read-write transaction has to be either COMMITED or CANCELLED.
*
* @return New transaction in the chain.
- * @throws IllegalStateException if the previous transaction was not COMMITTED or CANCELLED.
+ * @throws IllegalStateException if the previous transaction was not COMMITED
+ * or CANCELLED.
* @throws TransactionChainClosedException if the chain has been closed.
*/
- DataModification<P, D> newTransaction();
+ @Override
+ public AsyncReadTransaction<P, D> newReadOnlyTransaction();
+
+
+ /**
+ * Create a new read write transaction which will continue the chain.
+ * The previous read-write transaction has to be either COMMITED or CANCELLED.
+ *
+ * @return New transaction in the chain.
+ * @throws IllegalStateException if the previous transaction was not COMMITTED
+ * or CANCELLED.
+ * @throws TransactionChainClosedException if the chain has been closed.
+ */
+ @Override
+ public AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
@Override
void close();
* @param transaction Transaction which caused the chain to fail
* @param cause The cause of transaction failure
*/
- void onTransactionChainFailed(TransactionChain<?, ?> chain, DataModification<?, ?> transaction, Throwable cause);
+ void onTransactionChainFailed(TransactionChain<?, ?> chain, AsyncTransaction<?, ?> transaction, Throwable cause);
/**
* Invoked when a transaction chain is completed. A transaction chain is considered completed when it has been