[SDC-DIST-CLIENT] Add new RTD entry

Update README etc

Signed-off-by: efiacor <fiachra.corcoran@est.tech>
Change-Id: I4f92684e82d3fc2df978af12100be0871b94178d
Issue-ID: DMAAP-1792

6 files changed, 412 insertions, 0 deletions

diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 0000000..a04626d
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,97 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+Architecture
+============
+
+..
+   * This section is used to describe a software component from a high level
+     view of capability, common usage scenarios, and interactions with other
+     components required in the usage scenarios.
+
+   * The architecture section is typically: provided in a platform-component
+     and sdk collections; and referenced from developer and user guides.
+
+   * This note must be removed after content has been added.
+
+
+Capabilities
+------------
+
+The SDC Distribution client is a library that applications can use to simplify the handling of
+distribution related notifications from/to SDC and to download artifacts from SDC based on those notification.
+
+.. note::
+
+    As of version 2.0.0, the client uses kafka as it's message bus to publish/subscribe to/from the
+    relevant SDC distribution topics.
+
+    All previous releases of the client use DMaaP Message Router as it's message bus.
+
+Usage Scenarios
+---------------
+- **Get Distribution Notification event**
+
+    The client polls the relevant NOTIFICATION topic for distribution events sent from SDC.
+
+- **Get Deployment Artifact from SDC**
+
+    Once a new notification event is received, the client will download the relevant artifacts that it
+    has defined as part of it configuration.
+
+- **Send Distribution Status event**
+
+    As part of the processing of the downloaded artifacts, the client will publish it's progress to SDC
+    via the relevant STATUS topic.
+    Once the download has ben successfully completed, the client must publish it's final response
+    COMPONENT_DONE_OK to the STATUS topic.
+
+
+Interactions
+------------
+
+Kafka
+^^^^^
+The client uses kafka as it's messaging bus to publish and subscribe to the relevant SDC topics.
+
+.. _SDCE-6 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/4eca2a3848d70e58566570a5ef889efb/swagger-sdce-6.json
+.. _SDCE-7 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/542e76906472dae2e00adfad5fc7d879/swagger-sdce-7.json
+
+SDC
+^^^
+**The client interacts with the following SDC apis on initialization:**
+
+- ``/sdc/v1/artifactTypes``
+
+    Get the current artifact types from SDC to validate against the clients configured list.
+
+    See `SDCE-6 Swagger api`_ for more details
+
+- ``/sdc/v1/distributionKafkaData``
+
+    Get the kafka distribution config from SDC to be used during publish and subscribe
+
+    See `SDCE-6 Swagger api`_ for more details
+
+.. image:: ../images/sdc_client_init.png
+
+
+
+
+**The client interacts with the following SDC apis during distribution:**
+
+- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/resourceInstances/{resourceInstanceName}/artifacts/{artifactName}``
+
+    Get the artifact for a particular resource instance defined in the artifactUrl of the notification event
+
+    See `SDCE-7 Swagger api`_ for more details
+
+- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/artifacts/{artifactName}``
+
+    Get the artifact defined in the artifactUrl of the notification event
+
+    See `SDCE-7 Swagger api`_ for more details
+
+
+.. image:: ../images/sdc_distrib_flow.png
diff --git a/docs/sections/build.rst b/docs/sections/build.rst
new file mode 100644
index 0000000..4ef3e71
--- /dev/null
+++ b/docs/sections/build.rst
@@ -0,0 +1,43 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _build:
+
+Build
+=====
+
+..
+  * This section is used to describe how a software component is built from
+    source into something ready for use either in a run-time environment or to
+    build other components.
+
+  * This section is typically provided for a platform-component, application,
+    and sdk; and referenced in developer guides.
+
+
+Environment
+-----------
+
+- JDK 11
+
+- Maven 3.6.*
+
+  - local .m2 settings.xml set to https://git.onap.org/oparent/plain/settings.xml
+
+For more information regarding Env set up see `Setting Up Your Development Environment`_.
+
+.. _Setting Up Your Development Environment: https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment
+
+
+.. _Build steps:
+
+Steps
+-----
+
+Run the following from project root:
+
+``mvn clean install``
+
+The result is JAR file under the ``sdc-distribution-client/target`` folder
+
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 0000000..964d771
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,126 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _config:
+
+Configuration
+=============
+
+The sdc-distribution-client configuration in ONAP is generally done via a config file
+loaded to the container.
+
+Pre-requisites
+--------------
+The parent project must provide a mechanism to load the configuration at runtime.
+
+This configuration is then passed as input to the parent projects implementation of the
+sdc-distribution-client's IConfiguration interface.
+
+For more detailed information regarding the abstract methods of the interface that must be
+overridden byt the parent project, please refer to the javadocs.
+
+Client configuration
+--------------------
+The table below shows a brief outline of the client config.
+
+.. note::
+    Attention should be given to any methods which provide default values.
+
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| Name                      | Description                                                   | Type    | Required | Default |
++===========================+===============================================================+=========+==========+=========+
+| sdcAddress                | SDC Distribution Engine address                               | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| user                      | User Name for SDC distribution consumer authentication        | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| password                  | User Password for SDC distribution consumer authentication    | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| environmentName           | The environment name. Must match what is set in SDC           | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| useHttpsWithSdc           | Whether to use https towards SDC                              | boolean | N        | true    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| keyStorePath              | Y If useHttpsWithSdc is true                                  | String  | See desc | NA      |
+|                           | N if activateServerTLSAuth set to false                       |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| keyStorePassword          | Y If useHttpsWithSdc is true                                  | String  | See desc | NA      |
+|                           | N if activateServerTLSAuth set to false                       |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| activateServerTLSAuth     | mTLS setting.                                                 | boolean | Y        | NA      |
+|                           | If false, KeyStore path and password must be set              |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumeProduceStatusTopic | Whether to consume from both SDC distribution topics          | boolean | N        | false   |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumerGroup             | Group Id to use when consuming from the NOTIFICATION topic    | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumerId                | Consumer Id to use when consuming from the NOTIFICATION topic | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| pollingInterval           | Interval between polls on the NOTIFICATION topic in sec       | int     | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| pollingTimeout            | NOTIFICATION topic polling timeout in sec                     | int     | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| relevantArtifactTypes     | List of artifact types the client should consume              | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| filterEmptyResource       | See IConfiguration interface javadoc for more detail          | boolean | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| useSystemProxy            | Whether to use system or config proxies towards SDC           | boolean | N        | false   |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpsProxyHost            | The https proxy host to use towards SDC                       | String  | N        | null    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpsProxyPort            | The https proxy port to use towards SDC                       | int     | N        | 0       |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpProxyHost             | The http proxy host to use towards SDC                        | String  | N        | null    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpProxyPort             | The http proxy port to use towards SDC                        | int     | N        | 0       |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+
+
+Client Kafka config
+^^^^^^^^^^^^^^^^^^^
+
+The client will use kafka as a messaging bus to publish and subscribe to the relevant SDC topics.
+
+The client's kafka configuration in ONAP should be handled via Strimzi kafka's
+KafkaUser custom resource definition which provides access control to the relevant kafka topics.
+
+This is done at helm chart level for each component that requires access to kafka topics.
+
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| Name                  | Description                                                   | Type   | Required | Default                                      |
++=======================+===============================================================+========+==========+==============================================+
+| kafkaSecurityProtocol | The kafka security.protocol to use towards the kafka endpoint | String | N        | SASL_PLAINTEXT                               |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| kafkaSaslMechanism    | The kafka sasl.mechanism to use towards the kafka endpoint    | String | N        | SCRAM-SHA-512                                |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| KafkaSaslJaasConfig   | The kafka sasl.jaas.config to use towards the kafka endpoint  | String | Y        | Environment variable set to SASL_JAAS_CONFIG |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+
+.. note::
+    The sasl.jaas.config for the client to use will default to an environment variable set as SASL_JAAS_CONFIG.
+
+    This is expected to be in the form of org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="password";
+
+
+Initializing the client
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Once the client config is loaded, it can then be passed to the IDistributionClient to initialize.
+
+..  code-block:: java
+
+    // CustomClientConfig implementing IConfiguration
+    CustomClientConfig config = loadClientConfig();
+
+    IDistributionClient client = DistributionClientFactory.createDistributionClient();
+
+    // MyNotificationCallback implementing INotificationCallback
+    MyNotificationCallback callback;
+
+    IDistributionClientResult result = client.init(config, callback);
+    //Verify the result is SUCCESS, otherwise there’s a problem setting up vs either SDC or Kafka clients
+    System.out.println(result.getDistributionMessageResult());
+
+    System.out.println("Starting client...");
+    IDistributionClientResult startResult = client.start();
+    // Verify the result is SUCCESS, otherwise there’s a problem in receiving/sending notifications to/from kafka topics
+    System.out.println(startResult.getDistributionMessageResult());
diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst
new file mode 100644
index 0000000..135dcd3
--- /dev/null
+++ b/docs/sections/delivery.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+Delivery
+========
+
+..
+   * This section is used to describe the delivery of a software component.
+     For a run-time component, this might be executable images, containers, etc.
+     For an SDK, this might be libraries.
+
+   * This section is typically provided for a platform-component and sdk;
+     and referenced in developer and user guides.
+
+Deliverables
+------------
+
+SDC distribution client is delivered as a jar library and hosted on https://nexus.onap.org/
+
+To include it as a dependency in your project, see `SDC Distribution Client mvn`_.
+
+.. _SDC Distribution Client mvn: https://mvnrepository.com/artifact/org.onap.sdc.sdc-distribution-client/sdc-distribution-client
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644
index 0000000..7e59f76
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _api_docs:
+
+Offered APIs
+============
+
+The api javadocs for interfaces provided by the sdc distribution client can be compiled by building the project.
+
+See :ref:`build steps<Build Steps>` for more information.
+
+The javadocs can be then found under the ``sdc-distribution-client/target/apidocs`` folder.
+
+The main interface that must be implemented by clients is the IConfiguration interface.
+
+See the :ref:`configuration section<config>` configuration section for more details.
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 0000000..cf7b0cf
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,105 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+   International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _release_notes:
+
+
+..      ===========================
+..      * * *      LONDON     * * *
+..      ===========================
+
+
+*************
+Release Notes
+*************
+
+..
+   * The release note needs to be updated for each ONAP release
+   * Except the section "Release data" all other sections are optional and should be
+     applied where applicable
+   * Only the current release is to be documented in this document
+   * This note needs to be removed before publishing the final result
+
+
+London
+========
+
+
+Abstract
+========
+
+This document provides the release notes for the London release.
+
+Summary
+=======
+Client migration to use kafka as it's main messaging bus to publish and subscribe to the
+SDC distribution topics.
+Removal of all interaction with DMaaP Message Router apis.
+
+Release Data
+============
+
++--------------------------------------+--------------------------------------+
+| **Project**                          | sdc/sdc-distribution-client          |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Jars**                             |  sdc-distribution-client 2.0.0       |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+New features
+------------
+Modify client to use kafka native to publish and subscribe to SDC topics
+https://jira.onap.org/browse/DMAAP-1745
+
+Deliverables
+------------
+
+Software Deliverables
+~~~~~~~~~~~~~~~~~~~~~
+
+..  code-block:: xml
+
+    <groupId>org.onap.sdc.sdc-distribution-client</groupId>
+    <artifactId>sdc-distribution-client</artifactId>
+    <version>2.0.0</version>
+
+Known Limitations, Issues and Workarounds
+=========================================
+
+System Limitations
+------------------
+NA
+
+Known Vulnerabilities
+---------------------
+NA
+
+Workarounds
+-----------
+NA
+
+Security Notes
+--------------
+NA
+
+References
+==========
+
+For more information on the ONAP London release, please see:
+
+#. `ONAP Home Page`_
+#. `ONAP Documentation`_
+#. `ONAP Release Downloads`_
+#. `ONAP Wiki Page`_
+#. `SDC ReadTheDocs`_
+#. `SDC Portal`_
+
+.. _`ONAP Home Page`: https://www.onap.org
+.. _`ONAP Wiki Page`: https://wiki.onap.org
+.. _`ONAP Documentation`: https://docs.onap.org
+.. _`ONAP Release Downloads`: https://git.onap.org
+.. _`SDC ReadTheDocs`: https://docs.onap.org/projects/onap-sdc/en/latest/
+.. _`SDC Portal`: https://wiki.onap.org/display/DW/Service+Design+and+Creation+%28SDC%29+Portal