dmaap-adaptor-java/README.md

   1 # O-RAN-SC Non-RealTime RIC DMaaP Information Producer
   2 This product is a generic information producer (as defined by the Information Coordinator Service (ICS)). It can produce any information that can be retrieved from DMaaP or Kafka. Its main tasks is to register information types and itself as a producer using the ICS Data Producer API.
   3
   4 A data consumer may create information jobs through the ICS Data Producer API.
   5
   6 This service will retrieve data from the DMaaP Message Router (MR) or from the Kafka streaming platform and will distribute it further to the data consumers (information job owners).
   7
   8 The component is a springboot service and is configured as any springboot service through the file `config/application.yaml`. The component log can be retrieved and logging can be controled by means of REST call. See the API documentation (api/api.yaml).
   9
  10 The file `config/application_configuration.json` contains the configuration of job types that the producer will support. Here follows an example with one type:
  11
  12 ```sh
  13     {
  14        "types":
  15         [
  16           {
  17              "id":  "ExampleInformationType1_1.0.0",
  18              "dmaapTopicUrl":  "events/unauthenticated.SEC_FAULT_OUTPUT/dmaapmediatorproducer/STD-Fault-Messages_1.0.0",
  19              "useHttpProxy": true
  20           },
  21           {
  22              "id": "ExampleInformationType2_2.0.0",
  23              "kafkaInputTopic": "KafkaInputTopic",
  24              "useHttpProxy": false
  25           }
  26         ]
  27     }
  28 ```
  29
  30 Each information type has the following properties:
  31  - id the information type identity as exposed in the Information Coordination Service data consumer API
  32  - dmaapTopicUrl the URL to for fetching information from  DMaaP
  33  - kafkaInputTopic a Kafka topic to get input from
  34  - useHttpProxy if true, the received information will be delivered using a HTTP proxy (provided that one is setup in the application.yaml file). This might for instance be needed if the data consumer is in the RAN or outside the cluster.
  35
  36 The service producer will poll MR and/or listen to Kafka topics for all configured job types. When receiving messages for a type, it will distribute these messages to all jobs registered for the type. If a consumer is unavailable for distribution, the messages will be discarded for that consumer.
  37
  38 When an Information Job is created in the Information Coordinator Service Consumer API, it is possible to define a number of job specific properties. For an Information type that has a Kafka topic defined, the following Json schema defines the properties that can be used:
  39
  40
  41 ```sh
  42 {
  43   "$schema": "http://json-schema.org/draft-04/schema#",
  44   "type": "object",
  45   "properties": {
  46     "filter": {
  47       "type": "string"
  48     },
  49     "maxConcurrency": {
  50       "type": "integer"
  51     },
  52     "bufferTimeout": {
  53       "type": "object",
  54       "properties": {
  55         "maxSize": {
  56           "type": "integer"
  57         },
  58         "maxTimeMiliseconds": {
  59           "type": "integer"
  60         }
  61       },
  62       "additionalProperties": false,
  63       "required": [
  64         "maxSize",
  65         "maxTimeMiliseconds"
  66       ]
  67     }
  68   },
  69   "additionalProperties": false
  70 }
  71 ```
  72 -filter is a regular expression. Only strings that matches the expression will be pushed further to the consumer.
  73 -maxConcurrency the maximum number of concurrent REST session for the data delivery to the consumer.
  74  The default is 1 and that is the number that must be used to guarantee that the object sequence is maintained.
  75  A higher number will give higher throughtput.
  76 -bufferTimeout, can be used to reduce the number of REST calls to the consumer. If defined, a number of objects will be
  77  buffered and sent in one REST call to the consumer.
  78  The buffered objects will be put in a Json array and quoted. Example;
  79    Object1 and Object2 may be posted in one call -->  ["Object1", "Object2"]
  80  The bufferTimeout is a Json object and the parameters in the object are:
  81    - maxSize the maximum number of buffered objects before posting
  82    - maxTimeMiliseconds the maximum delay time to buffer before posting
  83  If no bufferTimeout is specified, each object will be posted as received in separate calls (not quoted and put in a Json array).
  84
  85
  86 For an information type that only has a DMaaP topic, the following Json schema defines the possible parameters to use when creating an information job:
  87
  88 ```sh
  89 {
  90   "$schema": "http://json-schema.org/draft-04/schema#",
  91   "type": "object",
  92   "properties": {
  93     "filter": {
  94        "type": "string"
  95      }
  96   },
  97   "additionalProperties": false
  98 }
  99 ```
 100 -filter is a regular expression. Only strings that matches the expression will be pushed furter to the consumer. This
 101  has a similar meaning as in jobs that receives data from Kafka.
 102
 103 ## License
 104
 105 Copyright (C) 2021 Nordix Foundation. Licensed under the Apache License, Version 2.0 (the "License") you may not use this file except in compliance with the License. You may obtain a copy of the License at
 106
 107 http://www.apache.org/licenses/LICENSE-2.0
 108
 109 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 110 For more information about license please see the [LICENSE](LICENSE.txt) file for details.