summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorFiete Ostkamp <Fiete.Ostkamp@telekom.de>2024-02-07 09:31:17 +0100
committerFiete Ostkamp <Fiete.Ostkamp@telekom.de>2024-02-07 09:31:17 +0100
commitdc041e1c41c78dfc9f62cdb64280b69299c5ffd0 (patch)
tree4726c883708985bf0f6554c6aafd40eec0c5538c /README.md
parent1619a148ae617d1c80ea90468fe3d27c1510d1dd (diff)
Improve aai-common README
- add prerequisite section describing the need for Java 8 and the ONAP `settings.xml` - add sections for running tests and debug attaching Issue-ID: AAI-3775 Signed-off-by: Fiete Ostkamp <Fiete.Ostkamp@telekom.de> Change-Id: I1b4c8d37112ab29e7b1218f24f8e6970f991be1b
Diffstat (limited to 'README.md')
-rw-r--r--README.md68
1 files changed, 57 insertions, 11 deletions
diff --git a/README.md b/README.md
index ccb528c5..a8828884 100644
--- a/README.md
+++ b/README.md
@@ -3,19 +3,65 @@
## Introduction
`AAI-Common` is a collection of common utility modules used by the other AAI components (`AAI-Resources` and `AAI-Traversal`). These utilities include `aai-schema`, which contains the schema oxm and xsd files; `aai-annotations`, which enables the annotations on the schema files; and `aai-core`, which includes various java packages used by all AAI microservices. `AAI-Resources` and `AAI-Traversal` are already configured to pull these dependencies using maven. For more information on `AAI-Resources` and `AAI-Traversal`, please see the `README.md` files in their respective repositories. This readme only covers AAI-Common.
-## Compiling AAI-Common
-Each module of AAI-Common can be compiled using
-``` bash
-mvn clean install -DskipTests
-```
-To compile all of them at once, run this command at the top level of `aai-common`; to do so for a specific module, run it in that module's subdirectory. Integration tests are started by omitting the skipTests flag `mvn clean install`. Again, this can be done for all the submodules at once or for any one individually.
+## Getting started
+
+### Prerequisites
+
+The AAI services have some prerequisite requirements that must be met before being able to compile and test the services.
+As with any other ONAP service, you need the [ONAP `settings.xml` file](https://git.onap.org/oparent/plain/settings.xml) in your `~/.m2/` folder.
-## Logging
-EELF framework is used for **specific logs** (audit, metric and error logs). They are tracking inter component logs (request and response) and allow to follow a complete flow through the AAI subsystem
+In addition, the AAI services are still based on Java 8. As such, you can either
-Each microservice (AAI-Resources and AAI-Traversal) keeps its own logging directories. Please see their specific readmes for more information.
+- globally define java 8 to be the standard jdk for the system (i.e `echo -e '\nexport JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/' >> ~/.bashrc`)
+- define it locally for each command (i.e `JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/ mvn install -DskipTests`)
+- configure it in your IDE
+
+### Install
+A `mvn install` will build all modules make them locally available on your system:
+```sh
+mvn install -Dcheckstyle.skip
+```
-## Testing AAI-Common Functionalities
-There are JUnit tests for aai-core and aai-annotations. Changes to the schema must be tested in the context of the AAI-Resources microservice via the REST interface. Please see the AAI-Resources readme for details on how to test via the REST API.
+## Test
+Run all tests
+```sh
+mvn test -Dcheckstyle.skip
+```
+Run a test class
+```sh
+mvn test -Dcheckstyle.skip -DfailIfNoTests=false -Dtest=PserverTest
+```
+```sh
+cd aai-core/
+mvn test -Dcheckstyle.skip -Dtest=PserverTest
+```
+## Docker build
+```sh
+mvn clean install -P docker -Dcheckstyle.skip -DskipTests
+```
+## Debugging
+If your IDE supports it, then use the built-in way to debug run a single test. Should that not be possible, you can attach your IDE to the debug port opened by maven via:
+```sh
+mvn test -Dcheckstyle.skip -Dtest=PserverTest -Dmaven.surefire.debug
+```
+This will open up a debug connection on port `5005`.T
+The process of connecting to this port is IDE-specific.
+For VSCode for example you have to create a `.vscode/launch.json` in the project with the following content:
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "java",
+ "name": "Debug (attach)",
+ "request": "attach",
+ "hostName": "localhost",
+ "port": 5005,
+ "internalConsoleOptions": "neverOpen",
+ "projectName": "aai-core"
+ }
+ ]
+}
+``` \ No newline at end of file