Rework persistence docs

Benjamin Rühl
1 parent 5a37cec9
Showing 1 changed file with 18 additions and 26 deletions
docu/persistence.md
@@ -2,24 +2,23 @@
 ## Which technologies are used in the persistence layer?
-- a **PostgreSQL** database is running as a seperate docker container
+- 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
+- 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`
+- The JDBC driver can be found in [/docker/wildfly/volumes/modules/org/postgres/main](../docker/wildfly/volumes/modules/org/postgres/main/)
+- The connection between the JBoss server and the database is configured as a subsystem in the [standalone.xml](../docker/wildfly/standalone.xml) file
+- The configuration of Hibernate is located in the [persistence.xml](services/Common/src/main/resources/META-INF/persistence.xml) file
 ## 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:
+Data Access Objects (DAOs) are designed as an encapsulation of JPA and Hibernate and should be used to create,retrieve, modify and delete entities. DAO interfaces provide at least CRUD functionality and DAO  implementations use JPA to perform the necessary operations on the database.
+
+The following snippet shows the base interface for all DAOs:
 ```java
 public interface GenericDAO<T extends Entity, ID extends Serializable> {
@@ -34,7 +33,7 @@ public interface GenericDAO&lt;T extends Entity, ID extends Serializable&gt; {
 }
 ```
-- The following snippet shows a DAO interface for a specific entity having the basic CRUD functionality and optional extensions to that
+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> {
@@ -44,7 +43,7 @@ public interface AppUserDAO extends GenericDAO&lt;AppUser, Long&gt; {
 ## How can a DAO instance be used?
-- using dependency injection in a class that is managed by JBoss
+DAO implementations are stateless EJBs which can be used using dependency injection in a class that is managed by JBoss.
 ```java
 @Resource(lookup = "java:global/global/AppUserDAO")
@@ -53,9 +52,7 @@ 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.
+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()` was 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 (see [Why is the persistence layer located in `common` instead of `global`?](#Why-is-the-persistence-layer-located-in-`common`-instead-of-`global`?)).
 ```java
 public interface AppUserDAO extends GenericDAO<AppUser, Long> {
@@ -64,15 +61,11 @@ public interface AppUserDAO extends GenericDAO&lt;AppUser, Long&gt; {
 }
 ```
-- the entity can then be modified and updated in the database using the DAO instance
+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
+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 if you want 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();
@@ -84,18 +77,17 @@ u.setProperty(&quot;test_property_double&quot;, 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
+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 [services/Common/.../persistence](services/Common/src/main/java/de/bht/beuthbot/persistence) must be extended.
-## How does the implementation of the EAV pattern work internally for the AppUser entity?
+## How does the implementation of the EAV pattern look like?
 ![Domain model as UML class diagram](img/persistence/domain-model.png)
+The important part here is that the `GenericEntity` can contain a recursive structure similar to the `composite` design pattern. This way primitive types are supported as well as lists and complex data types.
+
 ## 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
+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);