Persistence

The persistence layer has different extension points which can be used to adjust the default persistence logic. Developers usually need to create extensions if the business model has been modified or extended in a non standard way. Before contributing extensions in the persistence layer, please consider other possibilities like the command framework. Keep in mind that persistence layer extensions should only used to adjust persistence logic but not to implement business logic!

Most of the persistence layer implementation logic uses meta information to perform data manipulation operations (deletion, search, update, hql queries generations etc). This meta information is composed from persistence fields defined in the repository (called mappings) and JPA persistence entities called persistence meta model. JPA entities itself are called persistence model.

Detail persistence

If you need to adjust the detail model persistence logic, the property mediators extension point is a good place to start. If you need to contribute custom data modification audit logic, please use the AuditLog extension point. Using deleters, finders and interceptors you can adjust deeper aspects of the persistence process. In rare cases you can implement custom mediators. If you create new entity types you will also need to create new persistence model entities.

images/download/attachments/29819136/DetailModelPersistence.png

List persistence

If you need to adjust list access please have a look at the Fragments extension point. If you create new EntityTypes you need to set column data in the repository and contribute respective fragment (in most cases generic HQL fragment implementation will do the work). To define new reports you will need to create PL/SQL or T-SQL stored procedures, or you can simply use search expressions.

images/download/attachments/29819136/ListModelPersistence.png

Business and persistence models

HPM has a well defined separation between the persistence and business aspects of the domain model. Basically both models contain the same data but in the different forms and with different access methods. Business model provides generic access methods (for example using xPath-like queries), has meta information which is used for presentation, validation, business rules definition and a lot more. Business model also provides DTO capabilities like transferring disconnected data model sub-graphs over network and change logging. On the other hand persistence model is simple a set of JavaBeans enriched with JPA annotations. Persistence model is simple used to store/load data from DB using Hibernate and JPA. This approach provides a flexible and extendable model on business side and easy to implement and debug persistence technology on the other side. Data transfer between models is the task of the mediator framework. Mediators use mappings between business and persistence models which are defined in the repository.

Since the persistence model is also normalized, one could think it is exactly the same as the business model - in fact, it's not.
For example

  • the business model stores instances of EntityProxy, where the persistence model only stores the numeric id of the entity proxy.

  • customizing can introduce a 1:n field (a list) where as the persistence model just has a big string field (values will be stored by some sort of string separation).

  • parts of the business model might just be calculated from other fields or 3rd party systems

  • in business model every entity has version property, where in persistence model entity and entity revision are different objects

The central approach of the Heiler Product Manager - being easily customizable - is bound to the fact that we have a separate business model.

Mapping

As mentioned, the persistence model is quite similar to the business model. Because of this we're able to provide a lot of generic functionality which mediate between the business and the persistence model automatically - always being able to intercept and customize this of course.
For this we established a mapping model which holds the mapping information between business model and persistence model. You can obtain this model from the PersistenceComponent (PersistenceComponent.getMappingModelRegistry())

Persistence mapping in repository

The repository defines several attributes which map the business model to the persistence model
Please see the Persister Framework documentation for details on the used mapping algorithms, the following list gives only a short summary of the repository attributes.

Entity Type attributes

Persistence Class Name

All entity types

Fully qualified path to the persistence model's class which directly
corresponds to the business entity type on which the attribute is defined

Persistence xPath

All entity types

Path to the persistence object starting from the root.
Path segments are separated by a slash '/' and must also start with a slash and are build
using the object names of the corresponding members. E.G /articleRevision/articleLangs
(defines the articleRevision set in the Article object (root), followed by the articleLangs set.

Identifying Field Type

All entity types

The field type which uniquely identifies the record in the business as well as in the persistence model

Deletion Mode

All entity types

Defines what deletion modes the entity supports.

  • HARD = only hard (aka physical) deletion possible

  • SOFT = only soft (aka mark as deleted) deletion possible
    Note, in this case the persistence class must inherit from the Deletable class!

  • BOTH = both supported.

Deletion Date Field Type

All entity types

Field type which reflects the deletion date property of the entity type.
Empty in case the entity type doesn't support soft delete at all.
Used for the generic deletion algorithms.

Revision Persistence Class

Only root entity types

Fully qualified class name of the persistence class
which holds the revision information for this entity type. This attribute is empty in case the root entity type doesn't support revisions

Revision Property

Only root entity types

Name of the property which gives access to the set of revision objects (which based on the Revision Persistence Class)

Audit Log Entity Type

Only root entity types

The entity type which implements the audit log functionality,
empty in case the root entity type doesn't support the audit log feature

Field Type attributes

Fragment Column Access

Only used for SP based fragment access.
Defines the table name and the column name of the corresponding database column,
separated by a dot '.'. Both names are case sensitive!

Persistence class name

The java data type of the physical column in the database.
Values will automatically be converted to and from the class name (which reflects the
java data type in the business model). In case you have your own classes here, you need
to provide a converter through the ConverterUtils in the com.heiler.ppm.commons bundle.

Persistence model class

Fully qualified path to the persistence model's class which directly
corresponds to the business attribute. If empty, this defaults to the persistence class
name of the field type's entity type.

Persistence xPath

Path to the persistence property starting from the root persistence object
(In case of Collections in the persistence model, only the first value will be used!)

Physical Column Is Big

true in case the database column is some LOB object or similar
(like text, ntext, nvarchar(max), clob, nclob, etc.)

Persistence meta model

The meta model of the JPA provider was not able to satisfy all reqiurements which we had in order to provide the generic mapping algorithms. Therefore we created an own meta model which combines information from the JPA provider as well as the persistence classes and the annotations them self. Using this persistence model we could create generic JPQL generators for deletion of items as well as selecting data for list model access. The persistence meta model can be obtained through the DataSourceRegistry which itself is
available through the PersistenceComponent.