From 0556bc61f7cb201974cbcb66fa9d82b8d27c50bc Mon Sep 17 00:00:00 2001 From: "Lee, Tian (tl5884)" Date: Mon, 5 Feb 2018 10:17:48 +0000 Subject: Initial draft of Event Client documentation In RST format Change-Id: I52ecc7523aa0af3735d8417cb5edca1460252f2f Issue-ID: AAI-700 Signed-off-by: Lee, Tian (tl5884) --- .../EventClientAPI_Beijing.rst | 128 +++++++++++++++++++++ docs/index.rst | 17 +++ docs/release-notes.rst | 33 ++++++ 3 files changed, 178 insertions(+) create mode 100644 docs/Event Client API Documentation/EventClientAPI_Beijing.rst create mode 100644 docs/index.rst create mode 100644 docs/release-notes.rst (limited to 'docs') diff --git a/docs/Event Client API Documentation/EventClientAPI_Beijing.rst b/docs/Event Client API Documentation/EventClientAPI_Beijing.rst new file mode 100644 index 0000000..3d5e2c7 --- /dev/null +++ b/docs/Event Client API Documentation/EventClientAPI_Beijing.rst @@ -0,0 +1,128 @@ +DMaaP Client based API +====================== + +ONAP Gerrit repo: \ https://gerrit.onap.org/r/#/admin/projects/aai/event-client + +This is a thin API library based on the DMaaP Client, and exposes +methods that can be used to publish and consume JSON messages to/from a +DMaaP topic. + +Importing the library +===================== + +To add the Event Bus Client Library to your project simply include the +following dependencies in your project's pom.xml. Note that +the httpclient dependency may be required in your project pom if you are +also depending on AJSC artifacts, as they use an earlier version of +the httpclient which may overwrite the later version required by the +library. + + + +org.onap.aai.event-client + +event-client-dmaap + +1.2.0-SNAPSHOT + + + + + + + +org.apache.httpcomponents + +httpclient + +4.5.2 + + + + + +**Note** - In order to retrieve all of the client's transitive +dependencies you may need to configure your maven settings.xml with the +ONAP repositories. + +Publishing +========== + +Here is an example of how to use the client to publish a message to the +DMaaP topic. + +DMaaPEventPublisher eventPublisher = new DMaaPEventPublisher(host, +topic, username, password); + +try { + +int result = eventPublisher.sendSync(partition, messages); + +// result should equal number of messages supplied to sendSync + +} catch (...) { + +} finally { + +List unsentMessages = eventPublisher.closeWithUnsent() + +// Handle unsent messages + +} + +**host** - The host URL to use to connect to the DMaaP topic, in the +form of . + +**topic** - The topic name to publish to. This must be an existing DMaaP +topic. + +**username** - The MechID of the calling application. + +**password** - The password for the MechID. + +**partition** - The partition to publish the message to. + +**message** - A List of JSON String messages to publish as a batch. + +Consuming +--------- + +Here is an example of how to use the client to consume messages from the +UEB. + +try { + +DMaaPEventConsumer consumer = new DMaaPEventConsumer(host, topic, +username, password, consumerGroup, consumerId) + +Iterable messages = consumer.consume(); + +for(String message : messages) { + +// process message + +} + +} catch(...) {} + +**host** - The host URL to use to connect to the DMaaP topic, in the +form of . + +**topic** - The topic name to consume from. This must be an existing +topic. + +**username** - The MechID of the calling application. + +**password** - The password for the MechID. + +**consumerGroup** - The name of the consumer group this consumer is part +of. + +**consumerId** - The unique id of this consumer in its group. + +Creating Topics and Authentication +================================== + +For information about creating and managing DMaaP topics, refer to the +`DMaaP DBCAPI `__ +project documentation. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b16d6b3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Event Client Documentation Repository +---------------------------- +The Event Client project is a common API library that can be used by various microservices to publish/consume events to/from supported event messaging platforms. + +Supported event messaging platforms: + +- DMaaP: This is the bespoke messaging platform released with ONAP. It is based ontop of Kafka. +- Kafka: This is the vanilla Apache Kafka messaging platform. It exposes additional API functionality such as replay and committing offsets. + +.. toctree:: + :maxdepth: 2 + + release-notes.rst + Event Client API Documentation/EventClientAPI_Beijing.rst + diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..c84287d --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,33 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + + +AAI Release Notes +================== + +.. note:: + * This Release Notes must be updated each time the team decides to Release new artifacts. + * The scope of this Release Notes is for this particular component. In other words, each ONAP component has its Release Notes. + * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of this Release Notes. + * Except the date and the version number, all the other sections are optional but there must be at least one section describing the purpose of this new release. + * This note must be removed after content has been added. + + +Version: 1.2.0-BEIJING +-------------- + + +:Release Date: 2018-06-01 + + +**New Features** +Initial release of Event Client + +Source code of Event Client is released under the following repositories on gerrit.onap.org + +- aai/event-client + +=========== + +End of Release Notes -- cgit 1.2.3-korg