Merge "Update documentation regarding retry/timeout configuration in dmaap-client."

1 files changed, 88 insertions, 1 deletions

diff --git a/docs/sections/sdk/apis.rst b/docs/sections/sdk/apis.rst
index a4937f73..ebd9a6d2 100644
--- a/docs/sections/sdk/apis.rst
+++ b/docs/sections/sdk/apis.rst
@@ -168,6 +168,93 @@ Writing message subscriber
                     logger.warn("An unexpected error while receiving messages from DMaaP", ex);
                 });
 
+******************************************
+Configure timeout when talking to DMaaP-MR
+******************************************
+
+* publisher:
+
+.. code-block:: java
+
+   final MessageRouterPublishRequest request = ImmutableMessageRouterPublishRequest.builder()
+                .timeoutConfig(ImmutableDmaapTimeoutConfig.builder()
+                        .timeout(Duration.ofSeconds(2))
+                        .build())
+                .
+                .
+                .
+                .build();
+
+* subscriber:
+
+.. code-block:: java
+
+  final MessageRouterSubscribeRequest request = ImmutableMessageRouterSubscribeRequest.builder()
+                .timeoutConfig(ImmutableDmaapTimeoutConfig.builder()
+                        .timeout(Duration.ofSeconds(2))
+                        .build())
+                .
+                .
+                .
+                .build();
+
+The default timeout value (4 seconds) can be used:
+
+.. code-block:: java
+
+   ImmutableDmaapTimeoutConfig.builder().build()
+
+For timeout exception following message is return as failReason in DmaapResponse:
+
+.. code-block:: RST
+
+   408 Request Timeout
+   {"requestError":{"serviceException":{"messageId":"SVC0001","text":"Client timeout exception occurred, Error code is %1","variables":["408"]}}}
+
+*************************
+Configure retry mechanism
+*************************
+
+* publisher:
+
+.. code-block:: java
+
+       final MessageRouterPublisherConfig config = ImmutableMessageRouterPublisherConfig.builder()
+                .retryConfig(ImmutableDmaapRetryConfig.builder()
+                        .retryIntervalInSeconds(2)
+                        .retryCount(2)
+                        .build())
+                .
+                .
+                .
+                .build();
+       final MessageRouterPublisher publisher = DmaapClientFactory.createMessageRouterPublisher(config);
+
+* subscriber:
+
+.. code-block:: java
+
+    final MessageRouterSubscriberConfig config = ImmutableMessageRouterSubscriberConfig.builder()
+                .retryConfig(ImmutableDmaapRetryConfig.builder()
+                        .retryIntervalInSeconds(2)
+                        .retryCount(2)
+                        .build())
+                .
+                .
+                .
+                .build();
+    final MessageRouterSubscriber subscriber = DmaapClientFactory.createMessageRouterSubscriber(config);
+
+The default retry config (retryCount=3, retryIntervalInSeconds=1) can be used:
+
+.. code-block:: java
+
+    ImmutableDmaapRetryConfig.builder().build()
+
+Retry functionality works for:
+ - DMaaP MR HTTP response status codes: 404, 408, 413, 429, 500, 502, 503, 504
+ - Java Exception classes: ReadTimeoutException, ConnectException
+
 hvvesclient-producer - a reference Java implementation of High Volume VES Collector client
 ------------------------------------------------------------------------------------------
 This library is used in xNF simulator which helps us test HV VES Collector in CSIT tests. You may use it as a reference when implementing your code in non-JVM language or directly when using Java/Kotlin/etc.
@@ -287,4 +374,4 @@ Errors in one of the mappings in schema-map - this mapping is not cached, a warn
 Errors in schemaRefPath returns errors:
 
 - If in the schemaRef path in the event we provide an url that refers to an existing schema, but the part after # refers to a non-existent part of it, then an error is thrown: IncorrectInternalFileReferenceException ("Schema reference refer to existing file, but internal reference (after #) is incorrect.") "
-- When in the schemaRef path in the event, we provide a url that refers to a non-existent mapping from public to localURL, a NoLocalReferenceException is thrown, which logs to the console: "Couldn't find mapping for public url. PublicURL: {}"
\ No newline at end of file
+- When in the schemaRef path in the event, we provide a url that refers to a non-existent mapping from public to localURL, a NoLocalReferenceException is thrown, which logs to the console: "Couldn't find mapping for public url. PublicURL: {}"