Merge "Add ocpplugin release notes"

[docs.git] / docs / developer-guide / controller.rst

diff --git a/docs/developer-guide/controller.rst b/docs/developer-guide/controller.rst
index 94b81a220d940de68031d605906a8874a05e2d22..ade88739f08716ef1e7efc96882808573a2b67f3 100644 (file)
--- a/docs/developer-guide/controller.rst
+++ b/docs/developer-guide/controller.rst
@@ -52,6 +52,8 @@ data using following model-driven protocols:
    manipulate YANG modeled data and invoke YANG modeled RPCs, using XML
    or JSON as payload format.
 
+.. _mdsal_dev_guide:
+
 MD-SAL Overview
 ---------------
 
@@ -311,12 +313,12 @@ Application may listen on commit state asynchronously using
 
 .. code:: java
 
-    Futures.addCallback( writeTx.submit(), new FutureCallback<Void>() { 
-            public void onSuccess( Void result ) { 
+    Futures.addCallback( writeTx.submit(), new FutureCallback<Void>() {
+            public void onSuccess( Void result ) {
                 LOG.debug("Transaction committed successfully.");
             }
 
-            public void onFailure( Throwable t ) { 
+            public void onFailure( Throwable t ) {
                 LOG.error("Commit failed.",e);
             }
         });
@@ -337,8 +339,8 @@ If application need to block till commit is finished it may use
 .. code:: java
 
     try {
-        writeTx.submit().checkedGet(); 
-    } catch (TransactionCommitFailedException e) { 
+        writeTx.submit().checkedGet();
+    } catch (TransactionCommitFailedException e) {
         LOG.error("Commit failed.",e);
     }
 
@@ -362,13 +364,13 @@ Let assume initial state of data tree for ``PATH`` is ``A``.
 
 .. code:: java
 
-    ReadWriteTransaction rwTx = broker.newReadWriteTransaction(); 
+    ReadWriteTransaction rwTx = broker.newReadWriteTransaction();
 
-    rwRx.read(OPERATIONAL,PATH).get(); 
-    rwRx.put(OPERATIONAL,PATH,B); 
-    rwRx.read(OPERATIONAL,PATH).get(); 
-    rwRx.put(OPERATIONAL,PATH,C); 
-    rwRx.read(OPERATIONAL,PATH).get(); 
+    rwRx.read(OPERATIONAL,PATH).get();
+    rwRx.put(OPERATIONAL,PATH,B);
+    rwRx.read(OPERATIONAL,PATH).get();
+    rwRx.put(OPERATIONAL,PATH,C);
+    rwRx.read(OPERATIONAL,PATH).get();
 
 -  Allocates new ``ReadWriteTransaction``.
 
@@ -395,16 +397,16 @@ Lets assume initial state of data tree for ``PATH`` is ``A``.
 
 .. code:: java
 
-    ReadOnlyTransaction txRead = broker.newReadOnlyTransaction(); 
-    ReadWriteTransaction txWrite = broker.newReadWriteTransaction(); 
+    ReadOnlyTransaction txRead = broker.newReadOnlyTransaction();
+    ReadWriteTransaction txWrite = broker.newReadWriteTransaction();
 
-    txRead.read(OPERATIONAL,PATH).get(); 
-    txWrite.put(OPERATIONAL,PATH,B); 
-    txWrite.read(OPERATIONAL,PATH).get(); 
-    txWrite.submit().get(); 
-    txRead.read(OPERATIONAL,PATH).get(); 
-    txAfterCommit = broker.newReadOnlyTransaction(); 
-    txAfterCommit.read(OPERATIONAL,PATH).get(); 
+    txRead.read(OPERATIONAL,PATH).get();
+    txWrite.put(OPERATIONAL,PATH,B);
+    txWrite.read(OPERATIONAL,PATH).get();
+    txWrite.submit().get();
+    txRead.read(OPERATIONAL,PATH).get();
+    txAfterCommit = broker.newReadOnlyTransaction();
+    txAfterCommit.read(OPERATIONAL,PATH).get();
 
 -  Allocates read only transaction, which is based on data tree which
    contains value ``A`` for ``PATH``.
@@ -486,11 +488,11 @@ same initial state of data tree and proposes conflicting modifications.
     WriteTransaction txA = broker.newWriteTransaction();
     WriteTransaction txB = broker.newWriteTransaction();
 
-    txA.put(CONFIGURATION, PATH, A);    
-    txB.put(CONFIGURATION, PATH, B);     
+    txA.put(CONFIGURATION, PATH, A);
+    txB.put(CONFIGURATION, PATH, B);
 
-    CheckedFuture<?,?> futureA = txA.submit(); 
-    CheckedFuture<?,?> futureB = txB.submit(); 
+    CheckedFuture<?,?> futureA = txA.submit();
+    CheckedFuture<?,?> futureB = txB.submit();
 
 -  Updates ``PATH`` to value ``A`` using ``txA``
 
@@ -1413,7 +1415,7 @@ The response should look something like this:
 
     {
         "output": {
-            "stream-name": "toaster:toaster/toaster:toasterStatus/datastore=CONFIGURATION/scope=SUBTREE"
+            "stream-name": "data-change-event-subscription/toaster:toaster/toaster:toasterStatus/datastore=CONFIGURATION/scope=SUBTREE"
         }
     }
 
@@ -1436,10 +1438,25 @@ response from *create-data-change-event-subscription* RPC from the
 previous step.
 
 -  URI:
-   http://{odlAddress}:{odlPort}/restconf/streams/stream/toaster:toaster/datastore=CONFIGURATION/scope=SUBTREE
+   http://{odlAddress}:{odlPort}/restconf/streams/stream/data-change-event-subscription/toaster:toaster/datastore=CONFIGURATION/scope=SUBTREE
 
 -  OPERATION: GET
 
+The subscription call may be modified with the following query parameters defined in the RESTCONF RFC:
+
+-  `filter <https://tools.ietf.org/html/draft-ietf-netconf-restconf-05#section-4.8.6>`__
+
+-  `start-time <https://tools.ietf.org/html/draft-ietf-netconf-restconf-05#section-4.8.7>`__
+
+-  `end-time <https://tools.ietf.org/html/draft-ietf-netconf-restconf-05#section-4.8.8>`__
+
+In addition, the following ODL extension query parameter is supported:
+
+:odl-leaf-nodes-only:
+  If this parameter is set to "true", create and update notifications will only
+  contain the leaf nodes modified instead of the entire subscription subtree.
+  This can help in reducing the size of the notifications.
+
 The expected response status is 200 OK and response body should be
 empty. You will get your WebSocket location from **Location** header of
 response. For example in our particular toaster example location header