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