diff options
Diffstat (limited to 'docs/sections/components/component-specification/dmaap-connection-objects.rst')
| -rwxr-xr-x | docs/sections/components/component-specification/dmaap-connection-objects.rst | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/docs/sections/components/component-specification/dmaap-connection-objects.rst b/docs/sections/components/component-specification/dmaap-connection-objects.rst new file mode 100755 index 00000000..dfd4980f --- /dev/null +++ b/docs/sections/components/component-specification/dmaap-connection-objects.rst @@ -0,0 +1,276 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _dmaap-connection-objects:
+
+DMaaP connection objects
+========================
+
+DMaaP Connection Objects are JSON objects that:
+
+1. At Runtime - this is generated by the DCAE Platform and passed to the
+ component in its application_configuration to be used to connect to
+ the DMaaP feed or topic. Components will receive the entire object
+ with all properties populated (default will be \`null) unless
+ specified otherwise.
+2. During dcae_cli testing - this is provided through the command-line
+ argument ``--dmaap-file`` to test the component with manually
+ provisioned feeds and topics. Developers are not required to provide
+ the entire object. The required properties are labeled below with
+ “*Required as input*”.
+
+.. _dmaap-message-router:
+
+Message Router
+--------------
+
+Publishers and subscribers have the same generated
+``Dmaap Connection Object`` structure. Here’s an example for any given
+config-key: (This is what will be in application_configuration)
+
+.. code:: json
+
+ {
+ "type": "message_router",
+ "aaf_username": "some-user",
+ "aaf_password": "some-password",
+ "dmaap_info": {
+ "client_role": "com.dcae.member",
+ "client_id": "1500462518108",
+ "location": "mtc00",
+ "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``message_router`` for |
+| | | message router topics |
++--------------------------------+---------+---------------------------+
+| aaf_username | string | AAF username message |
+| | | router clients use to |
+| | | authenticate with secure |
+| | | topics |
++--------------------------------+---------+---------------------------+
+| aaf_password | string | AAF password message |
+| | | router clients use to |
+| | | authenticate with secure |
+| | | topics |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the topic |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| client_role | string | AAF client role that’s |
+| | | requesting publish or |
+| | | subscribe access to the |
+| | | topic |
++--------------------------------+---------+---------------------------+
+| client_id | string | Client id for given AAF |
+| | | client |
++--------------------------------+---------+---------------------------+
+| location | string | DCAE location for the |
+| | | publisher or subscriber, |
+| | | used to set up routing |
++--------------------------------+---------+---------------------------+
+| topic_url | string | *Required as input*. URL |
+| | | for accessing the topic |
+| | | to publish or receive |
+| | | events |
++--------------------------------+---------+---------------------------+
+
+The –dmaap-file argument (to the component ``run`` or ``dev`` command),
+must minimally contain:
+
+.. code:: json
+
+ {
+ "type": "message_router",
+ "dmaap_info": {
+ "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
+ }
+ }
+
+.. _dmaap-data-router:
+
+Data Router
+-----------
+
+Publisher
+~~~~~~~~~
+
+Here’s an example of what the generated ``Dmaap Connection Object`` for
+Data Router Publisher looks like: (This is what will be in
+application_configuration)
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ "location": "mtc00",
+ "publish_url": "https://we-are-data-router.us/feed/xyz",
+ "log_url": "https://we-are-data-router.us/feed/xyz/logs",
+ "username": "some-user",
+ "password": "some-password",
+ "publisher_id": "123456"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``data_router`` for |
+| | | data router feeds |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the feed |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| location | string | DCAE location for the |
+| | | publisher, used to set up |
+| | | routing |
++--------------------------------+---------+---------------------------+
+| publish_url | string | *Required as input*. URL |
+| | | to which the publisher |
+| | | makes Data Router publish |
+| | | requests |
++--------------------------------+---------+---------------------------+
+| log_url | string | URL from which log data |
+| | | for the feed can be |
+| | | obtained |
++--------------------------------+---------+---------------------------+
+| username | string | Username the publisher |
+| | | uses to authenticate to |
+| | | Data Router |
++--------------------------------+---------+---------------------------+
+| password | string | Password the publisher |
+| | | uses to authenticate to |
+| | | Data Router |
++--------------------------------+---------+---------------------------+
+| publisher_id | string | Publisher id in Data |
+| | | Router |
++--------------------------------+---------+---------------------------+
+
+The –dmaap-file argument (to the component ``run`` or ``dev`` command),
+must minimally contain:
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ "publish_url": "https://we-are-data-router.us/feed/xyz"
+ }
+ }
+
+Subscriber
+~~~~~~~~~~
+
+Here’s an example of what the generated ``Dmaap Connection Object`` for
+a Data Router Subscriber looks like: (This is what will be passed in
+application_configuration)
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ "location": "mtc00",
+ "delivery_url": "https://my-subscriber-app.dcae:8080/target-path",
+ "username": "some-user",
+ "password": "some-password",
+ "subscriber_id": "789012"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``data_router`` for |
+| | | data router feeds |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the feed |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| location | string | DCAE location for the |
+| | | subscriber, used to set |
+| | | up routing |
++--------------------------------+---------+---------------------------+
+| delivery_url | string | URL to which the Data |
+| | | Router should deliver |
+| | | files |
++--------------------------------+---------+---------------------------+
+| username | string | Username Data Router uses |
+| | | to authenticate to the |
+| | | subscriber when |
+| | | delivering files |
++--------------------------------+---------+---------------------------+
+| password | string | Password Data Router uses |
+| | | to authenticate to the |
+| | | subscriber when |
+| | | delivering files |
++--------------------------------+---------+---------------------------+
+| subscriber_id | string | Subscriber id in Data |
+| | | Router |
++--------------------------------+---------+---------------------------+
+
+The –dmaap-file argument (to the component ``run`` or ``dev`` command),
+must minimally contain:
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ }
+ }
+
+It is the recommended security practice that ``username`` and
+``password`` are specified. You cannot provide the ``delivery_url`` in
+your dmaap-file, because it’s not constructed until deployment time.
+Therefore, after the test deployment, go back to the Data Router Feed
+and provide the delivery_url (in order to start receiving the feeds).
+
+Data Router Example
+~~~~~~~~~~~~~~~~~~~
+
+(After the Data Router feed has been manually provisioned)
+
+::
+
+ $ dcae_cli component run --dmaap-file $dmaap_file $component-name
+ DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls:
+
+ some-sub-dr: http://135.205.226.128:32838/identity
+
+(Update the Data Router Feed to provide the delivery_url).
|