docs/offeredapis/offeredapis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Offered APIs
   5 ~~~~~~~~~~~~
   6
   7 .. toctree::
   8     :maxdepth: 3
   9
  10 DMaaP Message Router utilizes an HTTP REST API to service all Publish
  11 and Consume transactions. HTTP and REST standards are followed so
  12 clients as varied as CURL, Java applications and even Web Browsers will
  13 work to interact with Message Router.Message Router uses AAF for user's
  14 authentication and authorization.
  15
  16 General HTTP Requirements
  17 -------------------------
  18
  19 A DMaaP Message Router transactions consists of 4 distinct segments,
  20 HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general
  21 considerations for each segment are as follows and are required for each
  22 of the specific transactions described in this section.
  23
  24 HTTP URL
  25 -------
  26
  27 http[s]://serverBaseURL{/routing}{resourcePath}
  28
  29 - The serverBaseURL points to DMaaP Message Router host/port that will service the request.
  30
  31 - The resourcePath specifies the specific service, or Topic, that the client is attempting to reach
  32
  33 HTTP Header
  34 -----------
  35
  36 Specifies HTTP Headers, such as Content-Type, that define the parameters
  37 of the HTTP Transaction
  38
  39 HTTP Body
  40 ---------
  41
  42 The HTTP Body contains the topic content when Publishing or Consuming.
  43 The Body may contain topic messages in several formats (like below) but
  44 it must be noted, that, except in very specific circumstances, messages
  45 are not inspected for content.
  46
  47
  48 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
  49 | Content-Type            |  Description                                                                                                    |
  50 +=========================+=================================================================================================================+
  51 | text/plain              | Each line in the POST body is treated as a separate message. No partition key is specified, and therefore no    |
  52 |                         | order is guaranteed. This format is mainly for test, as messages are highly likely to be re-ordered when        |
  53 |                         | delivered through the Kafka cluster.                                                                            |
  54 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
  55 | application/json        | The payload maybe a single JSON object or a JSON array of JSON objects. Each object is handled as an individual |
  56 |                         | message..Note that use of this format may result in equivalent but altered JSON objects sent to consumers.      |
  57 |                         | That's because MR uses a standard JSON parser to read each object into memory before pushing the object to the  |
  58 |                         | Kafka system. At that point, the JSON object is re-written from the in-memory object. This can result in        |
  59 |                         | re-ordered fields or changes in whitespace. If you want to preserve JSON objects exactly,                       |
  60 |                         | use application/cambria. Recommended to follow the JSON format.                                                 |
  61 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
  62
  63 Publishers
  64 -----------
  65
  66 **Description**:Publishes data to Kafka server on the topic mentioned in the URL.
  67 Messages will be in the request body
  68
  69 The MessageRouter service has no requirements on what publishers can put
  70 onto a topic. The messages are opaque to the service and are treated as
  71 raw bytes. In general, passing JSON messages is preferred, but this is
  72 due to higher-level features and related systems, not the MessageRouter
  73 broker itself. The only constraint placed on messages is their on their
  74 size � messages must be under the maximum size, which is currently
  75 configured at 1 MB.
  76
  77 Request URL
  78 ===========
  79
  80 POST http(s)://{HOST:PORT}/events/{topicname}
  81
  82 Request Parameters
  83 ==================
  84
  85 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  86 | Name               | Description                  | Param Type       | Data type  | Max Len   | Required    | Format                         | Valid/EXample values        |
  87 +====================+==============================+==================+============+===========+=============+================================+=============================+
  88 | Topicname          | topic name to be posted      | Path             | String     | 40        | Y           |  <app namespace>.<topicname>   | org.onap.crm.empdetails     |
  89 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  90 | content-type       | To specify type of message   | Header           | String     | 20        | N           |                                | application/json            |
  91 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  92 | Username           | userid                       | Header           | String     |           | N           | Basic Authentication Header    |                             |
  93 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  94 | Password           |                              | Header           | String     |           | N           | Basic Authentication Header    |                             |
  95 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  96 | partitionKey       |                              | QueryParam       | String     |           | N           | String value                   | ?Partitionkey=123           |
  97 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
  98
  99 **NOTE**: Publishers/user should have access on the topics. The user (id) and
 100 permissions details needs to be in AAF.
 101
 102 Response Parameters
 103 ===================
 104
 105 +------------------+------------------------+------------+--------------+------------------------------+
 106 | Name             | Description            | Type       | Format       | Valid/Example Values         |
 107 +==================+========================+============+==============+==============================+
 108 | httpStatusCode   |                        |            |              | 200, 201 etc.                |
 109 +------------------+------------------------+------------+--------------+------------------------------+
 110 | mrErrorCode      | Numeric error code     |            |              | 200, 201 etc.                |
 111 +------------------+------------------------+------------+--------------+------------------------------+
 112 | errorMessage     |                        |            |              | SUCCESS, or error message.   |
 113 +------------------+------------------------+------------+--------------+------------------------------+
 114 | helpURL          | helpurl                |            |              |                              |
 115 +------------------+------------------------+------------+--------------+------------------------------+
 116 | transactionid    | transaction-id value   |            |              |                              |
 117 +------------------+------------------------+------------+--------------+------------------------------+
 118
 119
 120
 121 Response /Error Codes
 122 =====================
 123
 124 +---------------------------+------------------------------------+
 125 | Response statusCode       |  Response statusMessage            |
 126 +===========================+====================================+
 127 | 200-299                   | Success                            |
 128 +---------------------------+------------------------------------+
 129 | 400-499                   | the client request has a problem   |
 130 +---------------------------+------------------------------------+
 131 | 500-599                   | the DMaaP service has a problem    |
 132 +---------------------------+------------------------------------+
 133
 134 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 135 | Error code             |  HTTPCode     |  Description                    | Issue Reason                                                                                            |
 136 +========================+===============+=================================+=========================================================================================================+
 137 | DMaaP\_MR\_ERR\_3001   | 413           | Request Entity too large        | Message size exceeds the batch limit <limit>.Reduce the batch size and try again                        |
 138 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 139 | DMaaP\_MR\_ERR\_3002   | 500           | Internal Server Error           | Unable to publish messages. Please contact administrator                                                |
 140 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 141 | DMaaP\_MR\_ERR\_3003   | 400           | Bad Request                     | Incorrect Batching format. Please correct the batching format and try again                             |
 142 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 143 | DMaaP\_MR\_ERR\_3004   | 413           | Request Entity too large        | Message size exceeds the message size limit <limit>.Reduce the message size and try again               |
 144 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 145 | DMaaP\_MR\_ERR\_3005   | 400           | Bad Request                     | Incorrect JSON object. Please correct the JSON format and try again                                     |
 146 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 147 | DMaaP\_MR\_ERR\_3006   | 504           | Network Connect Timeout Error   | Connection to the DMaaP MR was timed out.Please try again                                               |
 148 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 149 | DMaaP\_MR\_ERR\_3007   | 500           | Internal Server Error           | Failed to publish  messages to topic <topicName>. Successfully published <count > number of messages.   |
 150 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 151
 152 Sample Request:
 153 ===============
 154
 155 +-----------------------------------------------------------------------------------+
 156 | POST                                                                              |
 157 |                                                                                   |
 158 | *Payload-* *{"message":"message description"}* *Content-Type: application/json*   |
 159 |                                                                                   |
 160 | Example:                                                                          |
 161 |                                                                                   |
 162 | curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt     |
 163 |                                                                                   |
 164 | {    "count": 1,                                                                  |
 165 |                                                                                   |
 166 |     "serverTimeMs": 19"                                                           |
 167 |                                                                                   |
 168 | }                                                                                 |
 169 +-----------------------------------------------------------------------------------+
 170
 171 Sample Response:
 172 ================
 173
 174 +---------------------------------------------------------------------+
 175 | HTTP/1.1 200 OK                                                     |
 176 |                                                                     |
 177 |     Server: Apache-Coyote/1.1                                       |
 178 |                                                                     |
 179 |     transactionId: 28-12-2015::08:18:50:682::<IP>::28122015552391   |
 180 |                                                                     |
 181 |     Content-Type: application/json                                  |
 182 |                                                                     |
 183 |     Content-Length: 42                                              |
 184 |                                                                     |
 185 |     Date: Mon, 28 Dec 2015 13:18:50 GMT                             |
 186 +---------------------------------------------------------------------+
 187
 188
 189
 190 Subscribers
 191 -----------
 192 **Description**:To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.
 193
 194 Request URL:
 195 ============
 196
 197 GET http(s)://{HOST:PORT}}/events/{topicname}/{consumegroup}/{consumerid}/{timeout=x}
 198
 199 Request Parameters:
 200 ===================
 201
 202 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 203 | Name         | Description                     |  Param Type      |  data type |   MaxLen     |  Required   |  Format             |  Valid/Example Values  |
 204 +==============+=================================+==================+============+==============+=============+=====================+========================+
 205 | Topicname    | topic name to be posted         |     Path         |   String   |    40        |     Y       | namespace.String    |                        |
 206 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 207 | Consumer     | A name that uniquely identifies |     Path         |   String   |              |     Y       |                     | CG1                    |
 208 | group        | your subscribers                |                  |            |              |             |                     |                        |
 209 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 210 | consumerId   | Within your subscribers group,  |     Path         |   String   |              |     Y       |                     | C1                     |
 211 |              | a name that uniquely identifies |                  |            |              |             |                     |                        |
 212 |              | your subscribers  process       |                  |            |              |             |                     |                        |
 213 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 214 | content-type | To specify type of message      |     Header       |   String   |     20       |     N       |                     | aplication/json        |
 215 |              | content(json,text or cambria)   |                  |            |              |             |                     |                        |
 216 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 217 | Username     | userid                          |     Header       |   String   |     1        |     N       |                     |                        |
 218 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 219 | Password     |                                 |     Header       |   String   |     1        |     N       |                     |                        |
 220 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 221
 222 **NOTE1**:Subscribers /user should have access on the topics. The user () and
 223 permissions details needs to be in AAF.
 224
 225 Response Parameters:
 226 ====================
 227
 228 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 229 | Name             | Description                    |  Type      | Format       | Valid/Example Values                                      |
 230 +==================+================================+============+==============+===========================================================+
 231 | httpStatusCode   |                                |            |              | 200, 201 etc.                                             |
 232 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 233 | mrErrorCode      | Numeric error code             |            |              | 200, 201 etc.                                             |
 234 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 235 | errorMessage     |                                |            |              | SUCCESS, or error message.                                |
 236 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 237 | helpURL          | helpurl                        |            |              |                                                           |
 238 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 239 | tranactionid     | transaction-id value           |            |              | 28-12-2015::08:18:50:682::135.25.227.66::28122015552391   |
 240 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 241 | ResponseBody     | Messages consumed from topic   | Json       | Json         |                                                           |
 242 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 243
 244
 245 Response /Error Codes
 246 =====================
 247
 248
 249 +---------------------------+------------------------------------+
 250 | Response statusCode       | Response statusMessage             |
 251 +===========================+====================================+
 252 | 200-299                   | Success                            |
 253 +---------------------------+------------------------------------+
 254 | 400-499                   | the client request has a problem   |
 255 +---------------------------+------------------------------------+
 256 | 500-599                   | the DMaaP service has a problem    |
 257 +---------------------------+------------------------------------+
 258
 259 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 260 | Error code              |  HTTPCode       |  Description               | Issue Reason                                                                                |
 261 +=========================+=================+============================+=============================================================================================+
 262 | DMaaP\_MR\_ERR\_3008    | 413             | Request Entity too large   | Message size exceeds the batch limit <limit>.Reduce the batch size and try again            |
 263 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 264 | DMaaP\_MR\_ERR\_3009    | 500             | Internal Server Error      | Unable to publish messages. Please contact administrator                                    |
 265 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 266 | DMaaP\_MR\_ERR\_3010    | 400             | Bad Request                | Incorrect Batching format. Please correct the batching format and try again                 |
 267 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 268 | DMaaP\_MR\_ERR\_3011    | 413             | Request Entity too large   | Message size exceeds the message size limit <limit>.Reduce the message size and try again   |
 269 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 270 | DMaaP\_MR\_ERR\_5012    | 429             | Too many requests          | This client is making too many requests. Please use a long poll setting to decrease the     |
 271 |                         |                 |                            | number of requests that result in empty responses.                                          |
 272 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 273 |                         | 503             | Service Unavailable        | Service Unavailable.                                                                        |
 274 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 275
 276 Sample Request:
 277 ===============
 278
 279 +----------------------------------------------------------------------------------------------------+
 280 | GET  http://<hostname>:3904/events/com.att.dmaap.mr.sprint/mygroup/mycus                           |
 281 |                                                                                                    |
 282 | Content-Type: application/json                                                                     |
 283 |                                                                                                    |
 284 | Example:                                                                                           |
 285 |                                                                                                    |
 286 |curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage'                                      |
 287 |                                                                                                    |
 288 |http://mrlocal00.dcae.proto.research.att.com:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1       |
 289 |                                                                                                    |
 290 |[I am r sending first msg,I am R sending first msg]                                                 |
 291 +----------------------------------------------------------------------------------------------------+
 292
 293 Provisioning
 294 ------------
 295 **Description**: To create , modify or delete the MessageRouter topics. Generally Invenio application will use these  below apis to create , assign topics to the users. These APIs can also be used by other applications to provision topics in MessageRouter
 296
 297 Create Topic
 298 ============
 299 Request URL:
 300 ============
 301
 302 POST http(s)://{HOST:PORT}/topics/create
 303
 304 Request Parameters:
 305 ===================
 306
 307 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 308 | Name              | Description                     |  Param Type      |  datatype  |   MaxLen     |  Required   |  Format     |  Valid/Example Values             |
 309 +===================+=================================+==================+============+==============+=============+=============+===================================+
 310 | Topicname         | topicname to be created in MR   |     Body         |   String   |     20       |     Y       | Json        | com.att.dmaap.mr.metrics          |
 311 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 312 | topicDescription  | description for topic           |     Body         |   String   |     15       |     Y       |             |                                   |
 313 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 314 | partitionCount    | Kafka topic partition           |     Body         |   String   |     1        |    Y        |             |                                   |
 315 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 316 | replicationCount  | Kafka topic replication         |     Body         |   String   |     1        |    Y        |             | 3 (Default -for 3 node Kafka )    |
 317 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 318 | transaction       | to create transaction id for    |     Body         |  Boolean   |     1        |    N        |             | true                              |
 319 | Enabled           | each message transaction        |                  |            |              |             |             |                                   |
 320 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 321 | Content-Type      | application/json                |     Header       |   String   |              |             |             | application/json                  |
 322 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 323
 324 +---------------------------+------------------------------------+
 325 | Response statusCode       | Response statusMessage             |
 326 +===========================+====================================+
 327 | 200-299                   | Success                            |
 328 +---------------------------+------------------------------------+
 329 | 400-499                   | the client request has a problem   |
 330 +---------------------------+------------------------------------+
 331 | 500-599                   | the DMaaP service has a problem    |
 332 +---------------------------+------------------------------------+
 333
 334
 335 +-------------------------+-----------------+--------------------------------------------------+
 336 | Error code              |  HTTP Code      |  Description                                     |
 337 +=========================+=================+==================================================+
 338 | DMaaP\_MR\_ERR\_5001    | 500             | Failed to retrieve list of all topics            |
 339 +-------------------------+-----------------+--------------------------------------------------+
 340 | DMaaP\_MR\_ERR\_5002    | 500             | Failed to retrieve details of topic:<topicName>  |
 341 +-------------------------+-----------------+--------------------------------------------------+
 342 | DMaaP\_MR\_ERR\_5003    | 500             | Failed to create topic:<topicName>               |
 343 +-------------------------+-----------------+--------------------------------------------------+
 344 | DMaaP\_MR\_ERR\_5004    | 500             | Failed to delete topic:<topicName>               |
 345 +-------------------------+-----------------+--------------------------------------------------+
 346
 347
 348 Response Parameters
 349 ====================
 350
 351 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 352 | Name             | Description                    |  Type      | Format       | Valid/Example Values                                      |
 353 +==================+================================+============+==============+===========================================================+
 354 | httpStatusCode   |                                |            |              | 200, 201 etc.                                             |
 355 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 356 | mrErrorCode      | Numeric error code             |            |              | 5005                                                      |
 357 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 358 | errorMessage     |                                |            |              | SUCCESS, or error message.                                |
 359 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 360 | helpURL          | helpurl                        |            |              |                                                           |
 361 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 362 | ResponseBody     | Topic details (owner,          |  Json      |  Json        |                                                           |
 363 |                  | trxEnabled=true)               |            |              |                                                           |
 364 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 365
 366
 367 Sample Request:
 368 ===============
 369
 370     .. code:: bash
 371
 372       POST   http://<hostname>:3904/topic/create
 373   Request Body
 374   {"topicName":"com.abc.dmaap.mr.topicname","description":"This is a SAPTopic ",
 375   "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"}
 376   Content-Type: application/json
 377   Example:
 378   curl -u XXXc@csp.abc.com:xxxxx$  -H 'Content-Type:application/json' -X POST -d
 379   @topicname.txt  http://mrlocal00.dcae.proto.research.abc.com:3904/topics/create
 380   {
 381   "writerAcl": {
 382   "enabled": false,
 383   "users": []
 384   },
 385   "description": "This is a TestTopic",
 386   "name": "com.abc.ecomp_test.crm.Load9",
 387   "readerAcl": {
 388   "enabled": false,
 389   "users": []
 390
 391
 392 GetTopic Details
 393 ----------------
 394
 395 Request URL
 396 ===========
 397
 398 GET http(s)://{HOST:PORT}/topics    : To list the details of all the topics in Message Router.
 399
 400 GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of specified topic .
 401
 402 Request Parameters
 403 ==================
 404
 405 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
 406 | Name                     | Description             | Param Type       | Data type  | Max Len   | Required    | Format          | Valid/EXample values        |
 407 +==========================+=========================+==================+============+===========+=============+=================+=============================+
 408 | Topicname                | topic name details      | Body             | String     | 20        | Y           |  Json           | com.abc.dmaap.mr.metrics    |
 409 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
 410
 411
 412 Response Parameters
 413 ====================
 414
 415 +------------------+------------------------+------------+----------+---------+--------------------------+
 416 | Name             | Description            | ParamType  | datatype |Format   | Valid/Example Values     |
 417 +==================+========================+============+==========+=========+==========================+
 418 | topicname        |  topic name details    |      Body  |   String |   Json  | com.abc.dmaap.mr.metrics |
 419 +------------------+------------------------+------------+----------+---------+--------------------------+
 420 | description      |                        |            |   String |         |                          |
 421 +------------------+------------------------+------------+----------+---------+--------------------------+
 422 | owner            |user id who created the |            |          |         |                          |
 423 |                  |         topic          |            |          |         |                          |
 424 +------------------+------------------------+------------+----------+---------+--------------------------+
 425 | txenabled        |     true or false      |            |  boolean |         |                          |
 426 +------------------+------------------------+------------+----------+---------+--------------------------+
 427
 428 +---------------------------+------------------------------------+
 429 | Response statusCode       | Response statusMessage             |
 430 +===========================+====================================+
 431 | 200-299                   | Success                            |
 432 +---------------------------+------------------------------------+
 433 | 400-499                   | the client request has a problem   |
 434 +---------------------------+------------------------------------+
 435 | 500-599                   | the DMaaP service has a problem    |
 436 +---------------------------+------------------------------------+
 437
 438
 439 Sample Request:
 440 ===============
 441
 442 +-----------------------------------------------------------------------------------------------------------------------------------+
 443 | GET   http://<hostname>:3904/topic/com.att.dmaap.mr.testtopic                                                                     |
 444 |       curl -u XXX@csp.abc.com:x$  -X                                                                                              |
 445 | GET  http://mrlocal00.dcae.proto.research.att.com:3904/topics                                                                     |
 446 |    {"topics": [                                                                                                                   |
 447 |    {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "com.abc.ecomp_test.crm.Load9"|
 448 |    {"txenabled": false,"description": "", "owner": "", "topicName": "com.abc.ecomp_test.crm.Load1"                                |
 449 |    ]},                                                                                                                            |
 450 +-----------------------------------------------------------------------------------------------------------------------------------+
 451
 452
 453 Delete Topics
 454 -------------
 455
 456 Request URL:
 457 ============
 458
 459 DELETE http(s)://{HOST:PORT}/topic/{topicname}
 460
 461 Sample Request:
 462 ===============
 463 ex: http://<hostname>:3904/dmaap/v1/topics/com.att.dmaap.mr.testopic
 464
 465 +---------------------------+------------------------------------+
 466 | Response statusCode       | Response statusMessage             |
 467 +===========================+====================================+
 468 | 200-299                   | Success                            |
 469 +---------------------------+------------------------------------+
 470 | 400-499                   | the client request has a problem   |
 471 +---------------------------+------------------------------------+
 472 | 500-599                   | the DMaaP service has a problem    |
 473 +---------------------------+------------------------------------+
 474
 475 +-------------------------+---------------------------------------------+----------------------+
 476 | Error code              |    Description                              |HTTP code             |
 477 +=========================+=============================================+======================+
 478 |  DMaaP\_MR\_ERR\_5004   |  Failed to delete topic:<topicName>         |   500                |
 479 +-------------------------+---------------------------------------------+----------------------+
 480
 481 API Inventory
 482 -------------
 483
 484 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 485 |           |   API Name         |   API Method                            |   REST API Path                       |                | Comments                         |
 486 +===========+====================+=========================================+=======================================+================+==================================+
 487 | Topics    | GetAll Topics      | getTopics()                             | /topics                               | GET            |                                  |
 488 |           | List               |                                         |                                       |                |                                  |
 489 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 490 |           | Get All Topics     |                                         |                                       |                |                                  |
 491 |           | List with details  | getAllTopics()                          | /topics/listAll                       | GET            |                                  |
 492 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 493 |           | Get individual     |                                         |                                       |                |                                  |
 494 |           | Topic Details      | getTopic(String topicName)              | /topics/{topicName}                   | GET            |                                  |
 495 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 496 |           | Create Topic       | createTopic(TopicBean topicBean)        | /topics/create                        | POST           |                                  |
 497 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 498 |           | Delete Topic       | deleteTopicString topicName)            | /topics/{topicName}                   | DELETE         |  Not used in current MR version  |
 499 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 500 |           | Get Publishers     | getPublishersByTopicName                |                                       |                |                                  |
 501 |           | for a Topic        | String topicName)                       | /topics/{topicName}/producers         | GET            |  UEB Backward Compatibility      |
 502 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 503 |           | Add a Publisher    | permitPublisherForTopic                 | /topics/{topicName}/producers/        | PUT            |                                  |
 504 |           | to write ACLon     | (String topicName, String producerId)   | {producerId}                          |                |                                  |
 505 |           | a Topic            |                                         |                                       |                |                                  |
 506 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 507 |           | Remove a Publisher | denyPublisherForTopic(String topicName, | /topics/{topicName}/producers/        | DELETE         |                                  |
 508 |           | from write ACL on  | String producerId)                      | {producerId}                          |                |                                  |
 509 |           | a Topic            |                                         |                                       |                |                                  |
 510 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 511 |           | Get Consumers for  | getConsumersByTopicName                 | /topics/{topicName}/consumers         |  GET           |                                  |
 512 |           | a Topic            | (String topicName)                      |                                       |                |                                  |
 513 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 514 |           | Add a Consumer     | permitConsumerForTopic(String           | /topics/{topicName}/consumers/        |  PUT           |                                  |
 515 |           | to read ACL        | topicName,String consumerId)            | {consumerId}                          |                |                                  |
 516 |           | on a Topic         |                                         |                                       |                |                                  |
 517 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 518 |           | Remove a consumer  | denyPublisherForTopic(String topicName, | /topics/{topicName}/consumers/        | DELETE         |                                  |
 519 |           | from write         | String consumerId)                      | {consumerId}                          |                |                                  |
 520 |           | ACL on a Topic     |                                         |                                       |                |                                  |
 521 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 522
 523
 524
 525 Filters
 526 -------
 527
 528 A filter examine an event and decides if it matches or doesn't.  Filters
 529 are mainly used in rules to decide if the processing entries should be
 530 executed on the given event. They're also used for settings, and systems
 531 like the Graph Correlator re-use Highland Park's filter mechanism to
 532 specify which alarms fit in a correlation.  Some publishers may produce
 533 topics with a lot of volume and a subscriber may want only a portion of
 534 those messages. The subscriber can certainly filter messages after
 535 receiving them, but it may be substantially more efficient to ask the
 536 API server to filter the messages before sending them to the
 537 subscriber.The standard library includes a number of simple filters. The
 538 Equals filter, for example, compares a field's value with some other
 539 value and returns true if the values match.  The standard library also
 540 includes filter classes called And, Or, and Not, so you can compose more
 541 complex filters. For example, written in the standard JSON config
 542 format:
 543
 544 +-----------------------------------------+
 545 | "filter":{                              |
 546 | "class":"And",                          |
 547 | "filters":                              |
 548 | [                                       |
 549 | { "class":"Equals", "foo":"abc" },      |
 550 | { "class":"Assigned", "field":"bar" }   |
 551 | ]                                       |
 552 | }                                       |
 553 +-----------------------------------------+
 554
 555 - This filter matches events in which the field "foo" has value "abc"
 556   and the field "bar" is assigned to some value (as opposed to not being
 557   present on the event). Filters are used by the consumers to filter out
 558   data and consume only specific set of data which matches the
 559   conditions mentioned in filter. Filters can be passed as a query
 560   parameter by the consumer in consume request as mentioned below:
 561   **http://localhost:8080/DMaaP/dmaaprest/events/DMaaP/consumergroup/mHOeNFY4XiWx4CBa?filter=\\{"class":"Equals",
 562   "field":"email", "value":"test@abc.com" }**
 563 - Filters can be applied only on data in JSON format i.e. if applied,
 564   filters will automatically ignore any non-json data.  While consuming,
 565   request CONTENT\_TYPE is not relevant to filter.
 566
 567 All the supported filter can be found below.
 568
 569 Types of Filters
 570 ================
 571
 572 - DMaaP Message Router supports all the filters which were supported by
 573   DMaaP Message Router and are mentioned below:-
 574 - **All Alarms:**
 575   - Match all alarms.
 576 - **And:**
 577   - Create a set of filters. This filter matches when all of them matches.
 578
 579 +-------------+--------------------+------------+---------------------+
 580 | **Field**   | **Description**    | **Type**   | **Notes**           |
 581 +=============+====================+============+=====================+
 582 | filters     | Combined Filters   | LIST       | A list of filters   |
 583 +-------------+--------------------+------------+---------------------+
 584 |             |                    |            |                     |
 585 +-------------+--------------------+------------+---------------------+
 586
 587 - **Assigned:**
 588   - Choose a field from the event to check for assignment. This filter
 589   matches when the field is assigned.
 590
 591 +-------------------+--------------------------------------------------------+------------+-----------------+
 592 | **Field**         | **Description**                                        | **Type**   | **Notes**       |
 593 +===================+========================================================+============+=================+
 594 | field             | The field to check for on the event.                   | STRING     | A field name    |
 595 +-------------------+--------------------------------------------------------+------------+-----------------+
 596 | emptyIsAssigned   | If true, an empty value is considered an assignment.   | BOOLEAN    | True or False   |
 597 +-------------------+--------------------------------------------------------+------------+-----------------+
 598
 599 - **Contains:**
 600    - Check if a search string contains another string.
 601
 602 +-------------+---------------------------------------------------+------------+--------------+
 603 | **Field**   | **Description**                                   | **Type**   | **Notes**    |
 604 +=============+===================================================+============+==============+
 605 | String      | The value to search. Supports ${} notation.       | STRING     | Any string   |
 606 +-------------+---------------------------------------------------+------------+--------------+
 607 | Value       | The value to search for. Supports ${} notation.   | STRING     | Any string   |
 608 +-------------+---------------------------------------------------+------------+--------------+
 609 |             |                                                   |            |              |
 610 +-------------+---------------------------------------------------+------------+--------------+
 611
 612 -  **EndsWith**:
 613    -  Check if a search string ends with another string.
 614
 615 +-------------+---------------------------------------------------+------------+--------------+
 616 | **Field**   | **Description**                                   | **Type**   | **Notes**    |
 617 +=============+===================================================+============+==============+
 618 | string      | The value to search. Supports ${} notation.       | STRING     | Any string   |
 619 +-------------+---------------------------------------------------+------------+--------------+
 620 | value       | The value to search for. Supports ${} notation.   | STRING     | Any string   |
 621 +-------------+---------------------------------------------------+------------+--------------+
 622
 623 -  **Equals:**
 624
 625   - Choose a field from the event and a value to check for equality.
 626
 627 +-------------+----------------------------------------------+------------+--------------+
 628 | **Field**   | **Description**                              | **Type**   | **Notes**    |
 629 +=============+==============================================+============+==============+
 630 | field       | The field to check. Supports ${} notation.   | STRING     | Any string   |
 631 +-------------+----------------------------------------------+------------+--------------+
 632 | value       | The value to match. Supports ${} notation.   | STRING     | Any string   |
 633 +-------------+----------------------------------------------+------------+--------------+
 634
 635 -  **FlatironObjectExists**
 636
 637   -  Matches when the given object exists in the given Flatiron instance.
 638
 639 +-------------+---------------------------------------------+------------+--------------+
 640 | **Field**   | **Description**                             | **Type**   | **Notes**    |
 641 +=============+=============================================+============+==============+
 642 | oid         | The OID of the object to look for.          | STRING     | Any string   |
 643 +-------------+---------------------------------------------+------------+--------------+
 644 | flatiron    | The name of the Flatiron client instance.   | STRING     | Any string   |
 645 +-------------+---------------------------------------------+------------+--------------+
 646
 647 - **IsAging**
 648   -  Choose a field to test. This filter matches if the expression is
 649   numeric.
 650
 651 +-------------+---------------------------------------------+------------+--------------+
 652 | **Field**   | **Description**                             | **Type**   | **Notes**    |
 653 +=============+=============================================+============+==============+
 654 | field       | The field to test. Supports ${} notation.   | STRING     | Any string   |
 655 +-------------+---------------------------------------------+------------+--------------+
 656
 657 - **IsNumeric**
 658   - Choose a field to test. This filter matches if the expression is
 659   numeric.
 660
 661 +-------------+---------------------------------------------+------------+--------------+
 662 | **Field**   | **Description**                             | **Type**   | **Notes**    |
 663 +=============+=============================================+============+==============+
 664 | field       | The field to test. Supports ${} notation.   | STRING     | Any string   |
 665 +-------------+---------------------------------------------+------------+--------------+
 666
 667 - **MathCondition**
 668   - Choose a field from the event and a value for logical math conditions.
 669
 670 +-------------+-------------------------------------------------+------------+-----------------------------------+
 671 | **Field**   | **Description**                                 | **Type**   | **Notes**                         |
 672 +=============+=================================================+============+===================================+
 673 | Field       | The field to check. Supports ${} notation.      | STRING     | Any string                        |
 674 +-------------+-------------------------------------------------+------------+-----------------------------------+
 675 | Value       | The value to consider. Supports ${} notation.   | STRING     | Any string                        |
 676 +-------------+-------------------------------------------------+------------+-----------------------------------+
 677 | operator    | The operation.                                  | STRING     | One of { "<=", ">=", ">", "<" }   |
 678 +-------------+-------------------------------------------------+------------+-----------------------------------+
 679 |             |                                                 |            |                                   |
 680 +-------------+-------------------------------------------------+------------+-----------------------------------+
 681
 682 - **NoAlarms**
 683   -  Don't match any alarms.
 684 - **Not**
 685   -  Negate the configured filter.
 686
 687 +-------------+-------------------------+------------+-------------+
 688 | **Field**   | **Description**         | **Type**   | **Notes**   |
 689 +=============+=========================+============+=============+
 690 | filter      | The filter to negate.   | FILTER     | A filter    |
 691 +-------------+-------------------------+------------+-------------+
 692
 693 - **NotEqual**
 694   -  Choose a field from the event and a value to check for inequality.
 695
 696 +-------------+----------------------------------------------+------------+--------------+
 697 | **Field**   | **Description**                              | **Type**   | **Notes**    |
 698 +=============+==============================================+============+==============+
 699 | field       | The field to check. Supports ${} notation.   | STRING     | Any string   |
 700 +-------------+----------------------------------------------+------------+--------------+
 701 | value       | The value to match. Supports ${} notation.   | STRING     | Any string   |
 702 +-------------+----------------------------------------------+------------+--------------+
 703
 704 - **NotOneOf**
 705   -  Match when the specified field does not have a value from the given list.
 706
 707 +-------------+---------------------------------------------+------------+---------------------+
 708 | **Field**   | **Description**                             | **Type**   | **Notes**           |
 709 +=============+=============================================+============+=====================+
 710 | field       | The field to test. Supports ${} notation.   | STRING     | Any string          |
 711 +-------------+---------------------------------------------+------------+---------------------+
 712 | values      | The matching values.                        | LIST       | A list of strings   |
 713 +-------------+---------------------------------------------+------------+---------------------+
 714
 715 - **OneOf**
 716   -  Match when the specified field has a value from the given list.
 717
 718 +-------------+---------------------------------------------+------------+---------------------+
 719 | **Field**   | **Description**                             | **Type**   | **Notes**           |
 720 +=============+=============================================+============+=====================+
 721 | field       | The field to test. Supports ${} notation.   | STRING     | Any string          |
 722 +-------------+---------------------------------------------+------------+---------------------+
 723 | values      | The matching values.                        | LIST       | A list of strings   |
 724 +-------------+---------------------------------------------+------------+---------------------+
 725
 726 - **Or**
 727    - Create a set of filters. This filter matches when any one of them
 728      matches.
 729
 730 +-------------+--------------------+------------+---------------------+
 731 | **Field**   | **Description**    | **Type**   | **Notes**           |
 732 +=============+====================+============+=====================+
 733 | filters     | Combined Filters   | LIST       | A list of filters   |
 734 +-------------+--------------------+------------+---------------------+
 735
 736 - **RegEx**
 737    - Choose a field from the event to match against the regular expression
 738      you provide.
 739
 740 +-------------+---------------------------------------------------------+------------+--------------+
 741 | **Field**   | **Description**                                         | **Type**   | **Notes**    |
 742 +=============+=========================================================+============+==============+
 743 | field       | The text to check for a match. Supports ${} notation.   | STRING     | Any string   |
 744 +-------------+---------------------------------------------------------+------------+--------------+
 745 | value       | The regular expression (pattern) to match.              | STRING     | Any string   |
 746 +-------------+---------------------------------------------------------+------------+--------------+
 747
 748 - **StartsWith**
 749   - Check if a search string starts with another string.
 750
 751 +-------------+---------------------------------------------------+------------+--------------+
 752 | **Field**   | **Description**                                   | **Type**   | **Notes**    |
 753 +=============+===================================================+============+==============+
 754 | string      | The value to search. Supports ${} notation.       | STRING     | Any string   |
 755 +-------------+---------------------------------------------------+------------+--------------+
 756 | Value       | The value to search for. Supports ${} notation.   | STRING     | Any string   |
 757 +-------------+---------------------------------------------------+------------+--------------+
 758
 759 - **Unassigned**
 760    - Choose a field from the event to check for assignment. This filter
 761      matches when the field is not assigned.
 762
 763 +-------------------+--------------------------------------------------------+------------+-----------------+
 764 | **Field**         | **Description**                                        | **Type**   | **Notes**       |
 765 +===================+========================================================+============+=================+
 766 | field             | The field to check for on the event.                   | STRING     | A field name    |
 767 +-------------------+--------------------------------------------------------+------------+-----------------+
 768 | emptyIsAssigned   | If true, an empty value is considered an assignment.   | BOOLEAN    | True or False   |
 769 +-------------------+--------------------------------------------------------+------------+-----------------+
 770
 771 - **WithinSecondsFrom**
 772   - This filter matches when the specified epoch time value is within the
 773   given number of seconds from the baseline time value. Both time values
 774   are assumed to be in seconds. If a value is in milliseconds, set
 775   baselineTimeInMillis and/or eventTimeInMillis to true.
 776
 777 +------------------------+------------------------------------------------------------+------------+-----------------+
 778 | **Field**              | **Description**                                            | **Type**   | **Notes**       |
 779 +========================+============================================================+============+=================+
 780 | field                  | The time value to test. Supports ${}                       | STRING     | A field name    |
 781 +------------------------+------------------------------------------------------------+------------+-----------------+
 782 | eventTimeInMillis      | Whether to convert the event value from milliseconds.      | BOOLEAN    | True or False   |
 783 +------------------------+------------------------------------------------------------+------------+-----------------+
 784 | seconds                | The number of seconds.                                     | NUMBER     | A number        |
 785 +------------------------+------------------------------------------------------------+------------+-----------------+
 786 | baselineTimeInMillis   | Whether to convert the baseline value from milliseconds.   | BOOLEAN    | True or False   |
 787 +------------------------+------------------------------------------------------------+------------+-----------------+
 788 | baseline               | The baseline time value. Supports ${}.                     | STRING     | Any string      |
 789 +------------------------+------------------------------------------------------------+------------+-----------------+
 790
 791 - **WithinTimeFromNow**
 792   - This filter matches when the named field has an epoch time value
 793   within the given number of seconds from the current time. The event's
 794   time value is assumed to be in seconds. If it's in milliseconds, set
 795   eventTimeInMillis to true.
 796
 797 +---------------------+---------------------------------------------------------+------------+-----------------+
 798 | **Field**           | **Description**                                         | **Type**   | **Notes**       |
 799 +=====================+=========================================================+============+=================+
 800 | field               | The field to check on the event.                        | STRING     | A field name    |
 801 +---------------------+---------------------------------------------------------+------------+-----------------+
 802 | eventTimeInMillis   | Whether to convert the event value from milliseconds.   | BOOLEAN    | True or False   |
 803 +---------------------+---------------------------------------------------------+------------+-----------------+
 804 | seconds             | The number of seconds.                                  | NUMBER     | A number        |
 805 +---------------------+---------------------------------------------------------+------------+-----------------+
 806
 807 - **Limit:**
 808
 809   -  Limit is the integer value and DMaaP Message Router will consumes
 810      only that set of message which are specified in limit.
 811
 812   .. code:: bash
 813
 814         Suppose if we set limit=2, then only 2 sets of data will be consumed.
 815         *Get \ **<<topicName>>/group/2?limit=4***
 816         Let us suppose if
 817         **No of data available** = 4
 818         **Set limit** = 6
 819         i.e. limit>no of data
 820         In this scenario all 4 sets of data will be consumed.
 821
 822 -  If limit is not passed with the url then by default limit is set to
 823    4096.
 824
 825    .. code:: bash
 826
 827         i.e. 4096 sets of data will be consumed.
 828         **Timeout and Long Poll:**
 829
 830 -  Timeout is the integer value which will be treated by DMaaP Message
 831    Router as time in millisecond.
 832
 833
 834
 835 -  Get
 836
 837 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 838 | `***http://localhost/DMaaP/dmaaprest/events/<<topicName>>/group/2?timeout=20000*** <http://localhost/DMaaP/dmaaprest/events/%3c%3ctopicName%3e%3e/group/2?timeout=20000>`__   |
 839 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 840
 841 -  If there is no data available to be consumed, then DMaaP Message
 842    Router will poll for the particular period of time specified in
 843    timeout this mechanism is known as Long Poll.
 844
 845 -  If timeout is not passed with url then DMaaP Message Router will set
 846    the value of timeout =10000
 847
 848 -  i.e. if no set of data are available then DMaaP Message Router will
 849    poll for 10000 ms.
 850
 851 ***Meta:***
 852
 853 -  Meta is a Boolean value.
 854
 855 -  DMaaP Message Router reads the value of meta from
 856    MRConfiguration.properties file at the time of startup.
 857
 858 -  If the value of meta is not null and if value of meta is one of these
 859    values true, yes, on, 1, y, checked then DMaaP Message Router will
 860    take meta flag as true, else it will be false.
 861
 862 -  If meta is set to true then consumer will get the value of message
 863    offset along with message.
 864
 865    |image1|
 866
 867    .. |image1| image:: images/image1.png
 868
 869 - **Pretty**:
 870
 871 -  Pretty is a Boolean value.
 872
 873 -  DMaaP Message Router reads the value of pretty from
 874    MRConfiguration.properties file at the time of startup.
 875
 876 -  If the value of pretty is not null and if value of pretty is one of
 877    these values true, yes, on, 1, y, checked then DMaaP Message Router
 878    will take pretty flag as true, else it will be false.
 879
 880 -  If pretty is set to true then different sets of messages will be
 881    printed in next line separated by comma (,).
 882
 883    |image2|
 884
 885    .. |image2| image:: images/image2.png
 886
 887 - **Filter**
 888
 889    - A filter examine an event and decides if it matches or doesn't.
 890    - Filters are mainly used in rules to decide if the processing entries
 891      should be executed on the given event. They're also used for settings,
 892      and systems like the Graph Correlator re-use Highland Park's filter
 893      mechanism to specify which alarms fit in a correlation.
 894    - The standard library includes a number of simple filters. The Equals
 895      filter, for example, compares a field's value with some other value
 896      and returns true if the values match.
 897    - The standard library also includes filter classes called And, Or, and
 898      Not, so you can compose more complex filters. For example, written in
 899      the standard JSON config format:
 900
 901     +-----------------------------------------+
 902     | "filter":{                              |
 903     | "class":"And",                          |
 904     | "filters":                              |
 905     | [                                       |
 906     | { "class":"Equals", "foo":"abc" },      |
 907     | { "class":"Assigned", "field":"bar" }   |
 908     | ]                                       |
 909     | }                                       |
 910     +-----------------------------------------+
 911
 912    - This filter matches events in which the field "foo" has value "abc" and
 913      the field "bar" is assigned to some value (as opposed to not being
 914      present on the event).
 915    - Filters are used by the consumers to filter out data and consume only
 916      specific set of data which matches the conditions mentioned in filter.
 917    - Filters can be passed as a query parameter by the consumer in consume
 918      request as mentioned below:
 919      - **http://localhost:8080/DMaaP/dmaaprest/events/DMaaP/consumergroup/mHOeNFY4XiWx4CBa?filter=\\{"class":"Equals","field":"email", "value":"`test@abc.com <mailto:test@att.com>`__" }**
 920      - Filters can be applied only on data in JSON format i.e. if applied, filters will automatically ignore any non-json data.
 921      - While consuming, request CONTENT\_TYPE is not relevant to filter.
 922
 923    The MR API allows a subscriber pass a Highland Park filter as part of
 924    the GET request. This will filter the stream of messages sent back to
 925    the subscriber, but for this to work, there are some requirements:
 926
 927    -  The message payload must be JSON
 928
 929    -  Only a filter built from Highland Park's Standard Library  may be
 930       used. (The Cambria API server doesn't have access to plugged in
 931       filters.)
 932
 933    -  The filter must be encoded properly in the URL path.
 934
 935 Server-side filtering can also be setup in the Java client as illustrated below
 936
 937 **Filtering Consumer**
 938
 939 You can also provide a Highland Park filter to your consumer instance,
 940 and this filter is passed on to the server in the GET request. One way
 941 to create the filter is programmatically. In your code, instantiate a
 942 filter from the Highland Park Standard Library Then create a String
 943 representation of the filter using the FilterIo.write utility. This
 944 String can then be passed to the Cambria client instance for use on the
 945 server.
 946
 947 Remember, only Highland Park standard library filter components can be
 948 used -- no plug-ins are available in the Cambria server context.
 949
 950   .. code:: bash
 951
 952   package org.onap.sa.highlandPark.integration;
 953
 954   import java.io.IOException;
 955
 956   import java.util.UUID;
 957
 958   import org.onap.nsa.cambria.client.CambriaClientFactory;
 959
 960   import org.onap.nsa.cambria.client.CambriaConsumer;
 961
 962   import org.onap.sa.highlandPark.processor.HpEvent;
 963
 964   import org.onap.sa.highlandPark.stdlib.filters.FilterIo;
 965
 966   import org.onap.sa.highlandPark.stdlib.filters.OneOf;
 967
 968   public class ExampleFilteringConsumer
 969
 970   {
 971
 972   public static void main ( String[] args ) throws IOException,
 973   InterruptedException
 974
 975   {
 976
 977   // Cambria clients take a set of 1 or more servers to use in round-robin
 978   fashion.
 979
 980   // If a server becomes unreachable, another in the group is used.
 981
 982   final String
 983   serverGroup="ueb01hydc.it.att.com,ueb02hydc.it.att.com,ueb03hydc.it.att.com";
 984
 985   // choose a topic
 986
 987   final String topic = "TEST-TOPIC";
 988
 989   // Cambria clients can run in a cooperative group to handle high-volume
 990   topics.
 991
 992   // Here, we create a random group name, which means this client is not
 993   re-startable.
 994
 995   final String consumerGroup = UUID.randomUUID ().toString ();
 996
 997   final String consumerId = "0";
 998
 999   // Cambria clients can sit in a tight loop on the client side, using a
1000   long-poll
1001
1002   // to wait for messages, and a limit to tell the server the most to send
1003   at a time.
1004
1005   final int longPollMs = 30\*1000;
1006
1007   final int limit = -1;
1008
1009   // The Cambria server can filter the returned message stream using
1010   filters from the
1011
1012   // Highland Park system. Here, we create a simple filter to test for the
1013   AlarmID
1014
1015   // value being one of the Mobility power alarms.
1016
1017   final OneOf oneOf = new OneOf ( "AlarmId", kPowerAlarms );
1018
1019   // create the consumer
1020
1021   final CambriaConsumer cc = CambriaClientFactory.createConsumer (
1022   serverGroup, topic,
1023
1024   consumerGroup, consumerId, longPollMs, limit, FilterIo.write ( oneOf )
1025   );
1026
1027   // now loop reading messages. Note that cc.fetch() will wait in its HTTP
1028   receive
1029
1030   // method for up to 30 seconds (longPollMs) when nothing's available at
1031   the server.
1032
1033   long count = 0;
1034
1035   while ( true )
1036
1037   {
1038
1039   for ( String msg : cc.fetch () )
1040
1041   {
1042
1043   System.out.println ( "" + (++count) + ": " + msg );
1044
1045   }
1046
1047   }
1048
1049   }
1050
1051   private static final String[] kPowerAlarms =
1052
1053   {
1054
1055   "HUB COMMERCIAL POWER FAIL\_FWD",
1056
1057   "HUB COMMERCIAL POWER FAIL",
1058
1059   "RBS COMMERCIAL POWER FAIL - Fixed\_FWD",
1060
1061   "RBS COMMERCIAL POWER FAIL\_FWD",
1062
1063   "RBS COMMERCIAL POWER FAIL - No Generator\_FWD",
1064
1065   "RBS COMMERCIAL POWER FAIL - Portable\_FWD",
1066
1067   "RBS COMMERCIAL POWER FAIL - Shared\_FWD",
1068
1069   "RBS COMMERCIAL POWER FAIL - Yes\_FWD",
1070
1071   "RBS COMMERCIAL POWER FAIL - YES\_FWD",
1072
1073   "RBS COMMERCIAL POWER FAIL - Fixed",
1074
1075   "RBS COMMERCIAL POWER FAIL - No Generator",
1076
1077   "RBS COMMERCIAL POWER FAIL - Portable",
1078
1079   "RBS COMMERCIAL POWER FAIL - Shared",
1080
1081   "RBS COMMERCIAL POWER FAIL - YES",
1082
1083   "RBS COMMERCIAL POWER FAIL - Yes",
1084
1085   "RBS COMMERCIAL POWER FAIL",
1086
1087   "HUB COMMERCIAL POWER FAIL - Fixed",
1088
1089   "HUB COMMERCIAL POWER FAIL - No Generator",
1090
1091   "HUB COMMERCIAL POWER FAIL - Portable",
1092
1093   "HUB COMMERCIAL POWER FAIL - Shared",
1094
1095   "HUB COMMERCIAL POWER FAIL - Fixed\_FWD",
1096
1097   "HUB COMMERCIAL POWER FAIL - No Generator\_FWD",
1098
1099   "HUB COMMERCIAL POWER FAIL - Portable\_FWD",
1100
1101   "HUB COMMERCIAL POWER FAIL - Shared\_FWD",
1102
1103   };
1104
1105   }
1106
1107
1108
1109 **Filter Builder**
1110
1111  MR server-side filtering allows a consumer to filter the stream of
1112  messages returned from the GET call.  The following link provide details
1113  of building some of the filter to illustrate Filter Builder.  It is not
1114  meant to cover and provide examples of every filter
1115