docs/architecture/NBI_Developer_Guide.rst

   1 .. This work is licensed under
   2 .. a Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2018 ORANGE
   5
   6
   7 =====================
   8 NBI - Developer Guide
   9 =====================
  10 ************
  11 Introduction
  12 ************
  13
  14 NBI is a Java 11 web application built over Spring Framework.
  15 Using Spring Boot 2.2.2 dependencies, it runs as a standalone
  16 application with an embedded Tomcat server.
  17
  18 ************
  19 Dependencies
  20 ************
  21 This project use various framework which are managed with Maven
  22 dependency management tool (see *pom.xml* file at root level) :
  23
  24 - Swagger annotations
  25 - `Spring Framework <https://github.com/spring-projects/spring-boot>`_
  26 - `JOLT <https://github.com/bazaarvoice/jolt>`_ to perform JsonToJson transformation
  27 - `FasterXML/Jackson <https://github.com/FasterXML/jackson>`_ to perform JSON parsing
  28 - `Wiremock <https://github.com/tomakehurst/wiremock>`_ to perform testing over HTTP mocked response
  29
  30
  31 *************
  32 Configuration
  33 *************
  34 A configuration file, *src/main/resources/application-localhost.properties*
  35 list all the component interface that can be configured depending on
  36 the environment were the application is deployed.
  37 By default, the application runs with an embedded both MongoDB and MariaDB
  38 local instance.
  39 This file also list configurations of all the REST interface maid from NBI
  40 to other ONAP component such as SDC, AA&I and SO.
  41
  42 ***********
  43 Source tree
  44 ***********
  45 This application provides ServiceOrder, ServiceCatalag and ServiceInventory
  46 as main functional resources and HealthCheck. Each resource is implemented
  47 independently in a package corresponding to its name.
  48
  49 *commons , configuration, and exceptions* are shared technical classes that
  50 provided for all the application.
  51
  52
  53 ***********************************
  54 Running and testing the application
  55 ***********************************
  56
  57 **Locally**
  58
  59 Ensure that you have a MongoDB and MariaDB instance running and properly
  60 configured in *application.properties* file.
  61 Run *Application.java* class in your favorite IDE
  62
  63 Or through a terminal, ensure that your maven installation is works and
  64 run *mvn spring-boot:run* command to start the application.
  65
  66
  67 **Docker**
  68
  69 Requirements: `Docker engine <https://docs.docker.com/engine/>`_ and
  70 `docker-compose <https://docs.docker.com/compose/>`_.
  71
  72 To start the application:
  73
  74     1. Generate the application .jar file: `$ mvn clean package`
  75     2. Configure the **.env** file
  76     3. Start the *MariaDB* and *MongoDB* services:
  77        `$ docker-compose up -d mongo mariadb`
  78     4. Build and start the *NBI* service: `$ docker-compose up --build -d nbi`
  79
  80 You can view the log output of the application with the following command:
  81
  82 `$ docker-compose logs -f nbi`
  83
  84 **Testing**
  85 When the application is running, you can access the API at
  86 :samp:`http://yourhostname:8080/nbi/api/v4` and fill the URL with the name
  87 of the resources you asking for (/serviceSpecification, /service,
  88 /serviceOrder or /status)
  89 You can run a test by using `VisualStudio RestClient plugin <https://github.com/Huachao/vscode-restclient>`_
  90 See the *restclient* package at root level to find *.vscode/settings.json*
  91 configuration file and */json/* package with samples requests that can be run.
  92 You can also trigger these endpoints with any RESTful client or automation
  93 framework.