host=gerrit.onap.org
port=29418
project=dmaap/messagerouter/messageservice
+defaultbranch=master
# Required
version: 2
-formats:
- - htmlzip
-
build:
image: latest
install:
- requirements: docs/requirements-docs.txt
+submodules:
+ include: all
+
sphinx:
- configuration: docs/conf.py
+ configuration: docs/conf.py
\ No newline at end of file
\r
Environment\r
-----------\r
-Message Router is developed using Kafka, Zookeeper and Java. AJSC framework is used to create the REST service and Docker was used to package the service.\r
+\r
+Message Router is developed using Kafka, Zookeeper and Java. AJSC framework is\r
+used to create the REST service and Docker was used to package the service.\r
\r
Steps\r
-----\r
+\r
Message Router has 3 docker containers. Dmaap\_container,\r
kafka\_container and zookeeper\_container. Zookeeper runs on 172.18.0.2,\r
kafka runs on 172.18.0.3 and dmaap on 172.18.0.4.\r
\r
1) Clone message service repo\r
\r
- git clone http://gerrit.onap.org/r/dmaap/messagerouter/messageservice\r
+ .. code-block::\r
+\r
+ git clone http://gerrit.onap.org/r/dmaap/messagerouter/messageservice\r
\r
-2) copy\r
- messageservice/bundleconfig-local/etc/appprops/MsgRtrApi.properties\r
+2) copy messageservice/bundleconfig-local/etc/appprops/MsgRtrApi.properties\r
to /var/tmp directory\r
\r
3) In /var/tmp/MsgRtrApi.properties, change value of below variables as\r
shown below:\r
\r
- config.zk.servers=172.18.0.2(Change as per where ZooKeepeer is deployed)\r
+ .. code-block::\r
\r
- kafka.metadata.broker.list=172.18.0.3:9092(Change as per where Kafka is deployed)\r
+ config.zk.servers=172.18.0.2 (Change as per where ZooKeepeer is deployed)\r
+ kafka.metadata.broker.list=172.18.0.3:9092 (Change as per where Kafka is deployed)\r
\r
4) Install docker and docker-compose\r
\r
5) Go to messageservice/src/main/resources/docker-compose and run:\r
- \r
- .. code:: bash\r
- \r
- docker-compose up # add -d argument to start process as a daemon (background process)\r
+\r
+ .. code-block::\r
+ \r
+ docker-compose up # add -d argument to start process as a daemon (background process)\r
+ \r
\r
This should start 3 containers.\r
\r
6) Run docker ps. It should show 3 containers.\r
\r
|image0|\r
- \r
+\r
.. |image0| image:: docker.png\r
- \r
+ \r
Testing\r
-------\r
\r
- For publishing, create a sample.txt file with some content in the\r
directory where you will run below rest api. Run below rest api:\r
\r
- curl -H "Content-Type:text/plain" -X POST -d @sample.txt\r
- http://172.18.0.4:3904/events/TestTopic1\r
+ .. code-block::\r
+\r
+ curl -H "Content-Type:text/plain" -X POST -d @sample.txt http://172.18.0.4:3904/events/TestTopic1\r
\r
- For subscribing, run below rest api:\r
\r
- curl -H "Content-Type:text/plain" -XGET\r
- http://172.18.0.4:3904/events/TestTopic1/CG1/C1?timeout=1000\r
+ .. code-block::\r
+\r
+ curl -H "Content-Type:text/plain" -XGET http://172.18.0.4:3904/events/TestTopic1/CG1/C1?timeout=1000\r
+\r
\r
Note: You will only receive messages which have been published after\r
you have subscribed to a topic.\r
\r
\r
Steps for local development and test\r
-------------------------\r
+------------------------------------\r
+\r
On Intel dev machine, in terminal (> indicates prompt) :\r
+\r
1) Build kafka11aaf\r
- > git clone https://gerrit.onap.org/r/dmaap/kafka\r
- > cd kafka11aaf\r
- > mvn clean install -Pdocker\r
+\r
+ .. code-block::\r
+\r
+ > git clone https://gerrit.onap.org/r/dmaap/kafka\r
+ > cd kafka11aaf\r
+ > mvn clean install -Pdocker\r
+\r
+\r
2) Build messageservice \r
- > git clone https://gerrit.onap.org/r/dmaap/messagerouter/messageservice\r
- - anonymous http, can't push changes\r
- > cd messageservice\r
- > mvn clean install -Pdocker\r
+\r
+ .. code-block::\r
+\r
+ > git clone https://gerrit.onap.org/r/dmaap/messagerouter/messageservice\r
+ (Note: anonymous http, can't push changes)\r
+ > cd messageservice\r
+ > mvn clean install -Pdocker\r
+\r
+\r
3) Run tests \r
- > cp bundleconfig-local/etc/appprops/MsgRtrApi.properties /var/tmp/\r
+\r
+ .. code-block::\r
+\r
+ > cp bundleconfig-local/etc/appprops/MsgRtrApi.properties /var/tmp/\r
+\r
+\r
- edit /var/tmp/MsgRtrApi.properties\r
config.zk.servers=zookeeper\r
kafka.metadata.broker.list=kafka:9092\r
+\r
- docker-compose network maps service name(zookeeper, kafka) to IP\r
+\r
- set docker preferences/file sharing to access /var/tmp\r
+ \r
> cd src/main/resources/docker-compose\r
+\r
- edit docker-compose.yml\r
- remove "nexus3.onap.org:10001/" from kafka and dmaap image names to \r
use local images\r
+ \r
> docker-compose up -d\r
- create sample.txt file (as above)(content of file not important)\r
+ \r
> curl -H "Content-Type:text/plain" -X POST -d @sample.txt http://localhost:3904/events/TestTopic1\r
\r
On Arm:\r
+\r
1) Build kafka11aaf\r
- > git clone https://gerrit.onap.org/r/dmaap/kafka\r
+\r
+ .. code-block::\r
+\r
+ > git clone https://gerrit.onap.org/r/dmaap/kafka\r
+ \r
> cd kafka11aaf\r
+ \r
> mvn clean install -Pdocker -Ddocker.pull.registry=docker.io\r
- ensure we pull Arm version of base image\r
+\r
+\r
2) Build messageservice \r
+\r
+ .. code-block::\r
+\r
> git clone https://gerrit.onap.org/r/dmaap/messagerouter/messageservice\r
- anonymous http, can't push changes\r
+ \r
> cd messageservice\r
+ \r
> mvn clean install -Pdocker -Ddocker.pull.registry=docker.io\r
- ensure we pull Arm version of base image\r
+\r
+\r
3) Run tests \r
+\r
+ .. code-block::\r
+\r
> cp bundleconfig-local/etc/appprops/MsgRtrApi.properties /var/tmp/\r
+\r
- edit /var/tmp/MsgRtrApi.properties\r
config.zk.servers=zookeeper\r
kafka.metadata.broker.list=kafka:9092\r
+\r
- docker-compose network maps service name(zookeeper, kafka) to IP\r
+\r
- set docker preferences/file sharing to access /var/tmp\r
+ \r
> cd src/main/resources/docker-compose\r
- edit docker-compose.yml\r
+\r
- remove "nexus3.onap.org:10001/" from from kafka and dmaap image names to \r
use local images\r
+\r
- replace 'nexus3.onap.org:10001/onap/dmaap/zookeeper:1.0.0' with\r
multi-platform 'zookeeper'\r
+ \r
> docker-compose up -d\r
+\r
- create sample.txt file (as above)(content of file not important)\r
+ \r
> curl -H "Content-Type:text/plain" -X POST -d @sample.txt http://localhost:3904/events/TestTopic1\r
-\r
- \r
/* fix width of the screen */
.wy-nav-content {
- max-width: none;
-}
+ max-width: 800px;
+}
\ No newline at end of file
-from docs_conf.conf import *
+project = "onap"
+release = "master"
+version = "master"
-master_doc = 'index'
+author = "Open Network Automation Platform"
+# yamllint disable-line rule:line-length
+copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License"
-intersphinx_mapping = {}
+pygments_style = "sphinx"
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+ "style_nav_header_background": "white",
+ "sticky_navigation": "False" }
+html_logo = "_static/logo_onap_2017.png"
+html_favicon = "_static/favicon.ico"
+html_static_path = ["_static"]
+html_show_sphinx = False
-linkcheck_ignore = [
- 'http://localhost',
- 'https://example.com',
- 'about:config',
- # this URL is not directly reachable and must be configured in the system hosts file.
- 'https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm',
- # anchor issues
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases_release.html#.*',
- 'https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#.*',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_robot.html#docs-robot',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases_release.html#docs-usecases-release',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases.html#docs-usecases',
- 'https://docs.onap.org/projects/onap-integration/en/latest/usecases/release_non_functional_requirements.html#release-non-functional-requirements',
+extensions = [
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.graphviz',
+ 'sphinxcontrib.blockdiag',
+ 'sphinxcontrib.seqdiag',
+ 'sphinxcontrib.swaggerdoc',
+ 'sphinxcontrib.plantuml'
]
+#
+# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch.
+# Change to {releasename} after you have created the new 'doc' branch.
+#
-html_last_updated_fmt = '%d-%b-%y %H:%M'
+branch = 'latest'
+
+intersphinx_mapping = {}
+doc_url = 'https://docs.onap.org/projects'
+master_doc = 'index'
+exclude_patterns = ['.tox']
+
+spelling_word_list_filename='spelling_wordlist.txt'
+spelling_lang = "en_GB"
+
+#
+# Example:
+# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None)
+#
+
+html_last_updated_fmt = '%d-%b-%y %H:%M'
def setup(app):
app.add_css_file("css/ribbon.css")
+
+linkcheck_ignore = [
+ r'http://localhost:\d+/',
+ r'http://<hostname>:3904/events/org.onap.dmaap.mr.sprint/mygroup/mycus'
+]
+++ /dev/null
----
-project_cfg: onap
-project: onap
-
-# Change this to ReleaseBranchName to modify the header
-default-version: latest
-#
.. http://creativecommons.org/licenses/by/4.0
.. _master_index:
-dmaap/message router(MR)
-====================
-
-
+dmaap/message router (MR)
+=========================
.. toctree::
:maxdepth: 1
administration/administration.rst
humaninterfaces/humaninterfaces.rst
release-notes/release-notes.rst
-
-
of the specific transactions described in this section.
HTTP URL
--------
+--------
http[s]://serverBaseURL{/routing}{resourcePath}
| partitionKey | | QueryParam | String | | N | String value | ?Partitionkey=123 |
+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
+
**NOTE**: To publish data to the authenticated topic, Publisher must
- have the AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|pub.
+have the AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|pub.
Publishers may use DMaaP BusController for provisoning the AAF permissions
+
Response Parameters
===================
Sample Request:
===============
-+----------------------------------------------------------------------------------------------------+
-| GET http://<hostname>:3904/events/org.onap.dmaap.mr.sprint/mygroup/mycus |
-| |
-| Content-Type: application/json |
-| |
-| Example: |
-| |
-|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' |
-| |
-|http://10.12.7.22:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 |
-| |
-|[I am r sending first msg,I am R sending first msg] |
-+----------------------------------------------------------------------------------------------------+
++-----------------------------------------------------------------------------+
+| GET http ://{hostname}:3904/events/org.onap.dmaap.mr.sprint/mygroup/mycus |
+| |
+| Content-Type: application/json |
+| |
+| Example: |
+| |
+|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' |
+| |
+|http ://10.12.7.22:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 |
+| |
+|[I am r sending first msg,I am R sending first msg] |
++-----------------------------------------------------------------------------+
Provisioning
------------
+
**Description**: To create, modify or delete the MessageRouter topics. These APIs can also be used by other applications to provision topics in MessageRouter.
DMaaP BusController is recommended for topic and AAF permissions provisioning
+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
| Name | Description | Param Type | datatype | MaxLen | Required | Format | Valid/Example Values |
+===================+=================================+==================+============+==============+=============+=============+===================================+
-| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics |
+| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics |
+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
| topicDescription | description for topic | Body | String | 15 | Y | | |
+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
Sample Request:
===============
- .. code:: bash
-
- POST http://<hostname>:3904/topics/create
- Request Body
- {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ",
- "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"}
- Content-Type: application/json
- Example:
- curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d
- @topicname.txt http://message-router:3904/topics/create
- {
- "writerAcl": {
- "enabled": false,
- "users": []
- },
- "description": "This is a TestTopic",
- "name": "org.onap.dmaap.mr.testtopic",
- "readerAcl": {
- "enabled": false,
- "users": []
+ .. code:: bash
+
+ POST http: //<hostname>:3904/topics/create
+ Request Body
+ {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ",
+ "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"}
+ Content-Type: application/json
+ Example:
+ curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d
+ @topicname.txt http: //message-router:3904/topics/create
+ {
+ "writerAcl": {
+ "enabled": false,
+ "users": []
+ },
+ "description": "This is a TestTopic",
+ "name": "org.onap.dmaap.mr.testtopic",
+ "readerAcl": {
+ "enabled": false,
+ "users": []
GetTopic Details
===============
+-----------------------------------------------------------------------------------------------------------------------------------+
-| GET http://<hostname>:3904/topic/org.onap.dmaap.mr.testtopic |
+| GET http ://<hostname>:3904/topic/org.onap.dmaap.mr.testtopic |
| curl -u XXX@csp.abc.com:x$ -X |
-| GET http://10.12.7.22:3904/topics |
+| GET http ://10.12.7.22:3904/topics |
| {"topics": [ |
| {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "org.onap.dmaap.mr.Load9" |
| {"txenabled": false,"description": "", "owner": "", "topicName": "org.onap.dmaap.mr.Load1" |
Sample Request:
===============
-ex: http://<hostname>:3904/topics/org.onap.dmaap.mr.testopic
+ex: http ://<hostname>:3904/topics/org.onap.dmaap.mr.testopic
+---------------------------+------------------------------------+
| Response statusCode | Response statusMessage |
| | from write | String consumerId) | {consumerId} | | |
| | ACL on a Topic | | | | |
+-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
-
-
-
-lfdocs-conf
sphinx>=4.2.0 # BSD
sphinx-rtd-theme>=1.0.0 # MIT
+sphinxcontrib-blockdiag # BSD
+sphinxcontrib-seqdiag # BSD
+sphinxcontrib-swaggerdoc
+sphinxcontrib-spelling
+sphinxcontrib-plantuml
\ No newline at end of file
[tox]
minversion = 1.6
-envlist = docs,
+envlist = docs,docs-linkcheck,docs-spellcheck
skipsdist = true
[testenv:docs]
deps =
-r{toxinidir}/requirements-docs.txt
-chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
- -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt
-whitelist_externals =
- echo
+ -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
commands =
- sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
- echo "Generated docs available in {toxinidir}/_build/html"
+ sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
[testenv:docs-linkcheck]
basepython = python3.8
-# deps =
-# -r{toxinidir}/requirements-docs.txt
-# -chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt
-# -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt
-commands = echo "Link Checking not enforced"
-# commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
-whitelist_externals = echo
+deps =
+ -r{toxinidir}/requirements-docs.txt
+ -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
+ -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
+commands =
+ sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck
+
+[testenv:docs-spellcheck]
+basepython = python3.8
+deps =
+ -r{toxinidir}/requirements-docs.txt
+ -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
+ -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
+commands =
+ sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck