Development

The following guide is intended to help developers who maintain or want to make changes to the Kugelblitz.

Preparing for Local Development

This section discusses the one-time setup in order to develop FastWS.

Installing Java & Maven (on Mac)

brew update
brew install openjdk@17

At the end of the last command prompt, something like the below will show up:

For the system Java wrappers to find this JDK, symlink it with
  sudo ln -sfn ...openjdk@17/libexec/openjdk.jdk .../JavaVirtualMachines/openjdk-17.jdk

openjdk@17 is keg-only, which means it was not symlinked into /usr/local,
because this is an alternate version of another formula.

If you need to have openjdk@17 first in your PATH, run:
  echo 'export PATH=".../openjdk@17/bin:$PATH"' >> .../.bash_profile

For compilers to find openjdk@17 you may need to set:
  export CPPFLAGS="-I.../openjdk@17/include"

Make sure to execute the sudo ln -sfn, echo 'export PATH=..., and the export CPPFLAGS= commands above

tip

Kugelblitz is built using maven, which uses a separate JDK version. This can be seen via mvn -v. If it's not JDK 17, we should have Maven point to our JDK 17 using JAVA_HOME:

$ /usr/libexec/java_home
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

$ export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

If we see something similar after typing the command with the version flag below we're good to go

$ java --version
openjdk 17.0.10 2021-01-19
OpenJDK Runtime Environment (build 17.0.10+9)
OpenJDK 64-Bit Server VM (build 17.0.10+9, mixed mode)

Installing Docker Engine

Kugelblitz has Docker-based integration tests; it also supports running template webserivce in Docker. Docker can be installed by following this instruction

Getting Source Code

git clone git@github.com:QubitPi/Kugelblitz.git
cd Kugelblitz

Syncing up with Kugelblitz's Code Styles with IntelliJ

For the moment, we have distilled the most important code style conventions with respect to Kugelblitz's code as IntelliJ settings. If IntelliJ is used for IDE, we may import these code style settings by importing the Kugelblitz-Project-intellij-code-style.xml file in the root of the repo. The setting for the project will appear as a new Scheme named "Kugelblitz-Project" under IDE's Editor -> Code Style section.

Please also enable "remove unused imports" by Editor -> General -> Auto Import -> Optimize Imports on the Fly, which will automatically remove unused imports.

Running Tests

The following commands runs both unit and integration tests:

mvn clean verify

ArangoDB

Spin up an Arango database

docker run -d -p 8529:8529 \
       -e ARANGO_ROOT_PASSWORD=root \
       -v arango-data:/var/lib/arangodb3 \
       -v arango-app:/var/lib/arangodb3-apps \
       --name arangodb --platform linux/arm64/v8 arangodb

The ArangoDB Web console should be accessible at http://localhost:8529 with the username and password being root and root, respectively.

tip

For more documentation on navigating the Arango Web UI, please refer to ArangoDB documentation

git clone git@github.com:QubitPi/Kugelblitz.git
cd Kugelblitz
mvn clean package

export KUGELBLITZ_ARANGO_HOSTS=http://localhost:8529
export KUGELBLITZ_ARANGO_USERNAME=root
export KUGELBLITZ_ARANGO_PASSWORD=root

java -jar target/kugelblitz-0.0.1-SNAPSHOT.jar

Note that the KUGELBLITZ_ARANGO_USERNAME and the KUGELBLITZ_ARANGO_PASSWORD is in accordance with the ArandoDB Docker configuration above. In addition, KUGELBLITZ_ARANGO_HOSTS must start with either "http://" or "https://"

The default port is 8080.

• Healthcheck: http://localhost:8080/actuator/health

• Swagger UI: http://localhost:8080/swagger-ui/index.html

• Creating an entity:

  curl --location 'localhost:8080/arango/createDocument/mydatabase/mycollection' --header 'Content-Type: application/json' --data '{
      "myfield": "myvalue"
  }' -v

Troubleshooting

IntelliJ

IntelliJ Cannot READ Resource File

We sometimes see errors when we run unit tests in IntelliJ, saying "some resource file" cannot be found. We know the path is absolutely right. If this is the case, it's simply a IntelliJ issue which is solved by simply loading those resources explicitly by telling IntelliJ where those resources are:

Tab Width

We use 4-space as tab. This can be configured at Code Style -> Java -> Tabs and Indents with the following settings:

• Tab size: 4
• Indent: 4
• Continuation indent: 8

If tabs still come out at 2 spaces when hitting TAB or Enter, not 4 spaces, try:

1. "Settings | Editor | Code Style" -- try disabling "Detect and use existing file indents for editing" in case if you have it enabled (it is by default). NOTE: re-opening file in editor may be required.
2. Do you have any .editorconfig files anywhere in the path of that file? Settings from .editorconfig ("Settings | Editor | Code Style") have priority (will overwrite) over your IDE settings.