Add documentation for SalFlatBatchService in OFP

Change-Id: I33a8a0d03f58988a976a76d503a9ace52c1c1948
Signed-off-by: Andrej Leitner <andrej.leitner@pantheon.tech>
(cherry picked from commit 3c99182fb21df059301e257da5ee30c5a703cd1e)

diff --git a/docs/developer-guide/openflow-plugin-project-developer-guide.rst b/docs/developer-guide/openflow-plugin-project-developer-guide.rst
index fd89f2e53f7a2ebe68bcd67927ff1042dc20909c..2e5f73e8424136c12aa0a5b6e901d31a35c06172 100644 (file)
--- a/docs/developer-guide/openflow-plugin-project-developer-guide.rst
+++ b/docs/developer-guide/openflow-plugin-project-developer-guide.rst
@@ -809,33 +809,122 @@ SalFlatBatchService
 FRS uses service with implemented barrier waiting logic between
 dependent objects
 
-SalFlatBatchService for FRS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Service: SalFlatBatchService
+----------------------------
+
+Basics
+~~~~~~
 
 SalFlatBatchService was created along forwardingrules-sync application
-as the service that should application used by default. This service
-uses only one input with bag of flow/group/meter objects and their
-common add/update/remove action. So you practically send only one input
-(of specific bags) to this service.
+as the service that should application used by default. This service uses
+only one input with bag of flow/group/meter objects and their common
+add/update/remove action. So you practically send only one input (of specific
+bags) to this service.
+
+-  interface: *org.opendaylight.yang.gen.v1.urn.opendaylight.flat.batch.service.rev160321.SalFlatBatchService*
+
+-  implementation: *org.opendaylight.openflowplugin.impl.services.SalFlatBatchServiceImpl*
+
+-  method: *processFlatBatch(input)*
+
+-  input: *org.opendaylight.yang.gen.v1.urn.opendaylight.flat.batch.service.rev160321.ProcessFlatBatchInput*
+
+Usage benefits
+^^^^^^^^^^^^^^
+
+-  possibility to use only one input bag with particular failure analysis preserved
+
+-  automatic barrier decision (chain+wait)
+
+-  less RPC routing in cluster environment (since one call encapsulates all others)
+
+ProcessFlatBatchInput
+~~~~~~~~~~~~~~~~~~~~~
+
+Input for SalFlatBatchService (ProcessFlatBatchInput object) consists of:
+
+-  node - NodeRef
+
+-  batch steps - List<Batch> - defined action + bag of objects + order for failures analysis
+
+   -  BatchChoice - yang-modeled action choice (e.g. FlatBatchAddFlowCase) containing batch bag of objects (e.g. flows to be added)
+
+   -  BatchOrder - (integer) order of batch step (should be incremented by single action)
+
+-  exitOnFirstError - boolean flag
 
 Workflow
-^^^^^^^^
+~~~~~~~~
+#. prepare **list of steps** based on input
 
--  prepare plan of actions
+#. **mark barriers** in steps where needed
 
-   -  mark actions where the barrier is needed before continue
+#. prepare particular **F/G/M-batch** service calls from **Flat-batch** steps
 
--  run appropriate service calls
+   -  F/G/M-batch services encapsulate bulk of single service calls
+
+   -  they actually chain barrier after processing all single calls if actual step is marked as barrier-needed
+
+#. **chain** futures and **start** executing
+
+   - start all actions that can be run simultaneously (chain all on one starting point)
+
+   -  in case there is a step marked as barrier-needed
+
+      -  wait for all fired jobs up to one with barrier
+
+      - merge rpc results (status, errors, batch failures) into single one
+
+      - the latest job with barrier is new starting point for chaining
+
+Services encapsulation
+^^^^^^^^^^^^^^^^^^^^^^
+
+-  SalFlatBatchService
+
+   -  SalFlowBatchService
+
+      -  SalFlowService
+
+   -  SalGroupBatchService
+
+      -  SalGroupService
+
+   -  SalMeterBatchService
+
+      -  SalMeterService
+
+Barrier decision
+^^^^^^^^^^^^^^^^
+
+-  decide on actual step and all previous steps since the latest barrier
+
+-  if condition in table below is satisfied the latest step before actual is marked as barrier-needed
+
++---------------------------+------------------------------------------------------------------+
+| actual step               | previous steps contain                                           |
++===========================+==================================================================+
+| FLOW_ADD *or* FLOW_UPDATE | GROUP_ADD *or* METER_ADD                                         |
++---------------------------+------------------------------------------------------------------+
+| GROUP_ADD                 | GROUP_ADD *or* GROUP_UPDATE                                      |
++---------------------------+------------------------------------------------------------------+
+| GROUP_REMOVE              | FLOW_UPDATE *or* FLOW_REMOVE *or* GROUP_UPDATE *or* GROUP_REMOVE |
++---------------------------+------------------------------------------------------------------+
+| METER_REMOVE              | FLOW_UPDATE *or* FLOW_REMOVE                                     |
++---------------------------+------------------------------------------------------------------+
+
+Error handling
+^^^^^^^^^^^^^^
 
-   -  start all actions that can be run simultaneously
+There is flag in ProcessFlatBatchInput to stop process on the first error.
 
-   -  if there is barrier-needed mark, wait for all fired jobs and only
-      then continue with the next action
+-  *true* - if partial step is not successful stop whole processing
 
-error handling:
+-  *false* (default) - try to process all steps regardless partial results
 
--  there is flag to stop process on the first error (default set to
-   false)
+If error occurs in any of partial steps upper FlatBatchService call will return as unsuccessful in both cases.
+However every partial error is attached to general flat batch result along with BatchFailure (contains BatchOrder
+and BatchItemIdChoice to identify failed step).
 
 Cluster singleton approach in plugin
 ------------------------------------