Add documentation about persistence layer

Benjamin Rühl
1 parent aff23f2f
Showing 3 changed files with 179 additions and 2 deletions
README.md
docu/img/persistence/domain-model.png
docu/persistence.md
@@ -195,7 +195,7 @@ NOTE: Localtunnel tends to crash every now and then, displaying an error message
 ## Debugging
-At the moment, the Spring Boot server is always started in debug mode. To attach the process using IntelliJ, a remote debug configuration has to be created. To do so, perform the following steps:
+At the moment, the JBoss server is always started with open debugging ports. To attach to the process using IntelliJ, a remote debug configuration has to be created. To do so, perform the following steps:
 - Go to `Run` -> `Edit Configurations...`
 - Add a new configuration using the button in the top left corner of the dialog
@@ -217,7 +217,7 @@ The following issues are currently known in the application:
 ### Wildfly
-- During the boot process of the Wildfly server, the error `Mount point not found` occurs
+- During the boot process of the Wildfly server, the error `Mount point not found` occurs, wich does not seem to have any impact on the running system
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+# BeuthBot persistence FAQ
+
+## Which technologies are used in the persistence layer?
+
+- a **PostgreSQL** database is running as a seperate docker container
+- **Adminer** is used as a web client for inspection and manipulation of the database; it is running in its own docker container
+- to enable the communication between java and the database, a database driver is required which is the **postgres jdbc driver** in our case
+- **JPA** is the specification which is used as interface for every interaction with the database using java
+- **Hibernate** implements JPA and is used as the persistence provider which does the actual object-relational mapping
+
+## Where can the configuration files be found?
+
+- the jdbc driver can be found in `/docker/postgres/volumes`
+- the connection between the JBoss server and the database is configured as a subsystem in `/docker/wildfly/standalone.xml`
+- the configuration of Hibernate is located in `common/resources/META-INF/persistence.xml`
+
+## How to interact with persisted entities?
+
+- Data Access Objects (DAOs) are designed as an encapsulation of JPA / Hibernate
+    - DAO interfaces provide CRUD functionality
+    - DAO implementations use JPA to perform operations on the database
+- The following snippet shows tha base interface for all DAOs:
+
+```java
+public interface GenericDAO<T extends Entity, ID extends Serializable> {
+
+    T findById(ID id);
+
+    List<T> findAll();
+
+    T saveOrUpdate(T entity);
+
+    void delete(T entity);
+}
+```
+
+- The following snippet shows a DAO interface for a specific entity having the basic CRUD functionality and optional extensions to that
+
+```java
+public interface AppUserDAO extends GenericDAO<AppUser, Long> {
+    AppUser createUser();
+}
+```
+
+# How can a DAO instance be used?
+
+- using dependency injection in a class that is managed by JBoss
+
+```java
+@Resource(lookup = "java:global/global/AppUserDAO")
+private AppUserDAO userDAO;
+```
+
+# How to create an entity?
+
+- currently a DAO is responsible for creating instances of its context entity, e.g. `AppUser newUser = userDAO.createUser()`
+- direct creation of an entity like `AppUser newUser = new AppUser()` were not possible at first, but could be used now, too
+- When the persistence layer was designed, direct references to the entity classes were impossible to use, because those classes were placed in the `global` module. This location changed to `common` because this solved some issues that could no be fixed otherwise, although this solution is less clean.
+
+```java
+public interface AppUserDAO extends GenericDAO<AppUser, Long> {
+    
+    AppUser createUser();
+}
+```
+
+- the entity can then be modified and updated in the database using the DAO instance
+
+# AppUsers have generic attributes. How can they be used?
+
+- the **Entity-Attribute-Value model (EAV)** is a common pattern in relational database design which aims at structuring a database schema in rows instead of columns; please do some research to really understand it
+- the pattern is implemented and used in the `AppUser` entity to give developers the ability to define attributes at runtime
+- the advantage here is that attributes can be created and retrieved in `Drools` without changing the actual entity class
+- the disadvantage is that a developer cannot rely on an attribute being present and having the expected data type
+- the following snippet is a usage expample of the implemented pattern
+
+```java
+AppUser u = userDAO.createUser();
+
+u.setProperty("test_property_string", "test_value");
+u.setProperty("test_property_bool", true);
+u.setProperty("test_property_double", 3.65);
+
+userDAO.saveOrUpdate(u);
+```
+
+- the shown syntax is achieved using custom json serialization as a convenience method
+- instead of this, the EAV structure can be build manually, too
+- please note that complex data types and lists are not supported using this syntax at the moment; to add support, the custom serializers and deserializers found in `common/persistence` must be extended
+
+# How does the implementation of the EAV pattern work internally for the AppUser entity?
+
+![Domain model as UML class diagram](img/persistence/domain-model.png)
+
+# How to retrieve the generic attributes of an AppUser?
+
+- the following snippet shows the retrieval using the convenience method
+- instead of this, the EAV structure can be queried an walked manually, too
+
+```java
+AppUser u = userDAO.findById(1);
+
+String testValueString = u.getProperty("test_property_string", String.class);
+boolean testValueBool = u.getProperty("test_property_bool", Boolean.class);
+Double testValueDouble = u.getProperty("test_property_double", Double.class);
+```
+
+# How does the convenience method for accessing the `GenericEntity` hierarchy actually work?
+
+A trivial implementation providing access to the structure with getters and setters is provided, but it gives the responsibility of traversing this structure to the using component. To simplify this for developers, a mechanic using custom JSON serializers and deserializers has been implemented.
+When setting a generic attribute, the given value is serialized to JSON using a common serializer. The value as JSON is then given to the custom deserializers which can create a GenericEntity structure from this JSON. 
+When retrieving the value later, the GenericAttribute hierarchy behind the given attribute key is serialized to JSON using the custom serializers as if it would be an unvariable implemented structure instead of the dynamic EAV model. This JSON is then given to a common deserializer which creates an instance of the desired type from it.
+<br>
+
+To understand the flow better, see the following example.
+A common serialization of a `GenericEntity` hierarchy could look like the following:
+
+```json
+{
+    "name": "user",
+    "attributes": [
+        {
+            "name": "test_property_string",
+            "values": [
+                {
+                    "valueAsLong": null,
+                    "valueAsBool": null,
+                    "valueAsDouble": null,
+                    "valueAsString": "test_value",
+                    "valueAsEntity": null,
+                }
+            ]
+        },
+        {
+            "name": "test_property_bool",
+            "values": [
+                {
+                    "valueAsLong": null,
+                    "valueAsBool": true,
+                    "valueAsDouble": null,
+                    "valueAsString": null,
+                    "valueAsEntity": null,
+                }
+            ]
+        }
+        {
+            "name": "test_property_object",
+            "values": [
+                {
+                    "valueAsLong": null,
+                    "valueAsBool": true,
+                    "valueAsDouble": null,
+                    "valueAsString": null,
+                    "valueAsEntity": {
+                        "name": "FavoriteFood",
+                        "attributes": [...]
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+The custom serializers instead have something like the following output:
+
+```json
+{
+    "test_property_string": "test_value",
+    "test_property_bool": true,
+    "test_property_object": {
+        ...
+    }
+}
+```
+
+This result can be used as input for a common JSON deserializer which can create an instance of a desired type from it as long as the type has exactly the same attributes as the structure has in JSON.
 \ No newline at end of file