.. 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).