import org.opendaylight.yangtools.concepts.Path;
/**
- *
- * Provides access to a conceptual data tree store.
- *
- * <p>
- * Also provides the ability to subscribe for changes to data under a given
- * branch of the tree.
+ * Base interface that provides access to a conceptual data tree store and also provides the ability to
+ * subscribe for changes to data under a given branch of the tree.
*
* <p>
- * All operations on data tree are performed via one of the transactions:
+ * All operations on the data tree are performed via one of the transactions:
* <ul>
* <li>Read-Only - allocated using {@link #newReadOnlyTransaction()}
* <li>Write-Only - allocated using {@link #newWriteOnlyTransaction()}
* For a detailed explanation of how transaction are isolated and how transaction-local
* changes are committed to global data tree, see
* {@link AsyncReadTransaction}, {@link AsyncWriteTransaction},
- * {@link AsyncReadWriteTransaction} and {@link AsyncWriteTransaction#commit()}.
+ * {@link AsyncReadWriteTransaction} and {@link AsyncWriteTransaction#submit()}.
*
*
* <p>
AsyncDataTransactionFactory<P, D> {
/**
- *
* Scope of Data Change
*
* <p>
* Represents scope of data change (addition, replacement, deletion).
- *
* The terminology for scope types is reused from LDAP.
*
* <h2>Examples</h2>
*
+ * <p>
* Following is an example model with comments describing what notifications
* you would receive based on the scope you specify, when you are
* registering for changes on container a.
* id "b" // scope SUBTREE
* </pre>
*
+ * <p>
* Following is an example model with comments describing what notifications
* you would receive based on the scope you specify, when you are
* registering for changes on list list (without specifying concrete item in
* </pre>
*
*
- * @see http://www.idevelopment.info/data/LDAP/LDAP_Resources/
- * SEARCH_Setting_the_SCOPE_Parameter.shtml
+ * @see <a href="http://www.idevelopment.info/data/LDAP/LDAP_Resources/SEARCH_Setting_the_SCOPE_Parameter.shtml">LDAP</a>
*/
- public enum DataChangeScope {
+ enum DataChangeScope {
/**
- * Represents only a direct change of the node, such as replacement of a
- * node, addition or deletion.
+ * Represents only a direct change of the node, such as replacement of a node, addition or
+ * deletion. Note that, as described in {@link #ONE}, this may have counterintuitive
+ * interactions when viewed from a <i>binding aware</i> application, in particular when it
+ * pertains to lists.
*
*/
BASE,
/**
- * Represent a change (addition,replacement,deletion) of the node or one
- * of its direct children.
+ * Represent a change (addition,replacement,deletion) of the node or one of its direct
+ * children.
+ *
+ * <p>
+ * Note that this is done in the <i>binding independent</i> data tree and so the behavior
+ * might be counterintuitive when used with <i>binding aware</i> interfaces particularly
+ * when it comes to lists. The list itself is a node in the <i>binding independent</i> tree,
+ * which means that if you want to listen on new elements you must listen on the list itself
+ * with the scope of {@link #ONE}.
+ *
+ * <p>
+ * As an example, in the below YANG snippet, listening on <tt>node</tt> with scope
+ * {@link #ONE} would tell you if the <tt>node-connector</tt> list was created or deleted,
+ * but not when elements were added or removed from the list assuming the list itself
+ * already existed.
*
+ * <pre>
+ * container nodes {
+ * list node {
+ * key "id";
+ * leaf id {
+ * type string;
+ * }
+ * list node-connector {
+ * leaf id {
+ * type string;
+ * }
+ * }
+ * }
+ * }
+ * </pre>
+ *
+ * <p>
* This scope is superset of {@link #BASE}.
*
*/
* Represents a change of the node or any of or any of its child nodes,
* direct and nested.
*
+ * <p>
* This scope is superset of {@link #ONE} and {@link #BASE}.
*
*/
SUBTREE
}
- /**
- * {@inheritDoc}
- */
@Override
-
public AsyncReadTransaction<P, D> newReadOnlyTransaction();
+
AsyncReadOnlyTransaction<P, D> newReadOnlyTransaction();
- /**
- * {@inheritDoc}
- */
@Override
-
public AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
+ AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
- /**
- * {@inheritDoc}
- */
@Override
-
public AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
+ AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
/**
* Registers a {@link AsyncDataChangeListener} to receive
* notifications when data changes under a given path in the conceptual data
* tree.
+ *
* <p>
* You are able to register for notifications for any node or subtree
* which can be reached via the supplied path.
+ *
* <p>
* If path type <code>P</code> allows it, you may specify paths up to the leaf nodes
* then it is possible to listen on leaf nodes.
+ *
* <p>
* You are able to register for data change notifications for a subtree even
- * if it does not exist. You will receive notification once that node is
- * created.
+ * if it does not exist. You will receive notification once that node is created.
+ *
* <p>
* If there is any preexisting data in data tree on path for which you are
* registering, you will receive initial data change event, which will
* <p>
* You are also able to specify the scope of the changes you want to be
* notified.
+ *
* <p>
* Supported scopes are:
* <ul>
* or replaced.
* </ul>
* See {@link DataChangeScope} for examples.
+ *
* <p>
* This method returns a {@link ListenerRegistration} object. To
* "unregister" your listener for changes call the "close" method on this
* returned object.
+ *
* <p>
* You MUST call close when you no longer need to receive notifications
* (such as during shutdown or for example if your bundle is shutting down).
* your listener using {@link ListenerRegistration#close()} to stop
* delivery of change events.
*/
- ListenerRegistration<L> registerDataChangeListener(LogicalDatastoreType store, P path, L listener,
- DataChangeScope triggeringScope);
+ @Deprecated
+ default ListenerRegistration<L> registerDataChangeListener(LogicalDatastoreType store, P path, L listener,
+ DataChangeScope triggeringScope) {
+ throw new UnsupportedOperationException("Data change listeners are no longer supported.");
+ }
}
Code Review / controller.git / blobdiff