add Gradle Java toolchain and improve documentation

README.md

@@ -23,8 +23,10 @@ Everything is tested on _Ubuntu Linux 22.04_ and _MacOS Monterey (12.4)_.
 To be able to build and run the Java Spring Boot application, you need the following tools:
 
 - Docker 20.x (on MacOS you also need *Docker Desktop* or similar)
-- PostgreSQL Server 13.7-bullseye (see instructions below to install and run in Docker)
-- Java JDK 17.x
+- PostgreSQL Server 13.7-bullseye 
+  (see instructions below to install and run in Docker)
+- Java JDK at least recent enough to run Gradle
+  (JDK 17.x will be automatically installed by Gradle toolchain support)
 - Gradle in some not too outdated version (7.4 will be installed via wrapper)
 
 You also might need an IDE (e.g. *IntelliJ IDEA* or *Eclipse* or *VS Code* with *[STS](https://spring.io/tools)* and a GUI Frontend for *PostgreSQL* like *Postbird*.
@@ -207,6 +209,17 @@ pandoc --filter pandoc-plantuml rbac.md -o rbac.pdf
 
 If you have figured out how it works, please add instructions above this section.
 
+### IDE Specific Settings
+
+#### IntelliJ IDEA
+
+Go to [Gradle Settings}(jetbrains://idea/settings?name=Build%2C+Execution%2C+Deployment--Build+Tools--Gradle) and select "Build and run using" and "Run tests using" both to "gradle".
+Otherwise, settings from `build.gradle`, like compiler arguments, are not applied when compiling through *IntelliJ IDEA*.
+
+Go to [Annotations Processors](jetbrains://idea/settings?name=Build%2C+Execution%2C+Deployment--Compiler--Annotation+Processors) and activate annotation processing.
+Otherwise, *IntelliJ IDEA* can't see *Lombok* generated classes 
+and will show false errors (missing identifiers).
+
 ### Other Tools
 
 **jq**: a JSON formatter. 
@@ -238,7 +251,46 @@ You can explore the prototype as follows:
 
 ### Directory and Package Structure
 
-Generally, the standard Java directory structure is used, where productive and test code are sparated like this:
+#### General Directory Structure
+
+.aliases
+
+build/
+
+build.gradle
+
+doc/
+
+.editorconfig
+
+etc/
+
+.git/
+
+.gitattributes
+
+.gitignore
+
+.gradle/
+gradle/
+gradlew
+gradlew.bat
+.idea/
+LICENSE.md
+out/
+README.md
+.run/
+settings.gradle
+sql/
+src/
+TODO.md
+TODO-progress.png
+tools/
+
+
+#### Source Code Package Structure
+
+For the source code itself, the general standard Java directory structure is used, where productive and test code are separated like this:
 
 ```
 src

build.gradle

@@ -8,7 +8,6 @@ plugins {
 
 group = 'net.hostsharing'
 version = '0.0.1-SNAPSHOT'
-sourceCompatibility = '17'
 
 wrapper {
     distributionType = Wrapper.DistributionType.BIN
@@ -25,6 +24,12 @@ repositories {
     mavenCentral()
 }
 
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
+}
+
 ext {
     set('testcontainersVersion', "1.17.3")
 }
@@ -61,6 +66,10 @@ dependencyManagement {
     }
 }
 
+tasks.withType(JavaCompile) {
+    options.compilerArgs += ["-parameters"]
+}
+
 tasks.named('test') {
     useJUnitPlatform()
 }

doc/glossary.md

@@ -62,3 +62,13 @@ A whitebox-test knows and considers the internals of an implementation, e.g. it
 
 A "double" is a general term for something which replaces a real implementation of a dependency of the unit under test.
 This can be a "dummy", a "fake", a "mock", a "spy" or a "stub".
+
+
+#### Test-Fixture
+
+Generally a test-fixture refers to all code within a test 
+which is needed to setup the test environment and extract results, 
+but which is not part of the test-cases.
+
+In other words: The code which is needed to bind test-cases to the actual unit under test,
+is called test-fixture.

doc/test-concept.md

@@ -9,13 +9,16 @@
 - [System-Integration-Tests](#system-integration-tests)
 <!-- generated TOC end. -->
 
-### General Issues
+### General Concepts
 
 The following test concept uses terms like "double" and "mock" (maybe in inflected form like "mocking" or "mocked"), "whitebox-test" and "blackbox-tests" and "test-fixture".
 Please look up their definition in the [glossary](glossary.md)
 
 Where our APIs should be designed in a way that it's possible, using a mocking library like *Mockito* often leads to shorter test code.
 
+Most important for a test is, to clearly express what it actually is testing.
+For this, it might help to wrap test setup and assertions into test fixture 
+
 
 ### Kinds of Tests
 
@@ -26,7 +29,7 @@ Depending on the concrete aspects which we want to test, we are using different
 In this project a *Unit* for *UnitTests* can be a single method (function), a class or even a group of classes which express a common concept.
 
 The unit are technically whitebox-tests and count into test-code-coverage.
-But the whitebox-knowledge should only be used for the text-fixture.
+But the whitebox-knowledge should only be used for the [test-fixture](./glossary.md#test-fixture).
 
 Unit-Test in this project are implemented with *JUnit Jupiter*, *Mockito* and *AssertJ*.
 
@@ -65,10 +68,17 @@ Such tests are implemented with *JUnit Jupiter* through some sort of `@SpringBoo
 *Mockito* can also be used for this kind of tests, to separate multiple integrations.
 
 Integration-Tests are relatively slow and therefore should focus on the integration.
-Internal issues should be tested through Unit-Tests.
+Java-internal issues should be tested through Unit-Tests.
 
 These Tests are always named `...IntegrationTest` and can automatically run in the build-process.
 
+##### DataJpaTest / Database-Integration-Tests
+
+In this project, a major part of the program logic is coded in the database as stored procedures, functions and triggers.
+
+This program logic is tested through *integration tests* using `DataJpaTest`
+because pure unit tests in the database are not only cumbersome but also easily lead to large test gaps. 
+
 
 #### Acceptance-Tests