Blaze Persistence - Entity View Module

As already described in the core module setup, every module depends on the core module. So if you haven’t setup the core module dependencies yet, get back here when you did.

To make use of the entity view module, you require all artifacts from the entity-view directory of the distribution. CDI and Spring users can find integrations in integration/entity-view that give a good foundation for configuring for these environments.

Spring Data users can find a special integration in integration/entity-view which is described in more detail in a later chapter. This integration depends on all artifacts of the jpa-criteria module.

The entity view module of Blaze Persistence is usable in Java EE, Spring as well as in Java SE environments.

The entity view module like all other modules generally follows what has already been stated in the core moduel documentation.

Automatic module names for modules.

Generally, we support the usage in Java EE 6+ or Spring 4+ applications.

The following table outlines the supported library versions for the integrations.

This section is supposed to give you a first feeling of how to use entity views. For more detailed information, please see the subsequent chapters.

An entity view can be thought of as the ORM world’s dual to a database table view. It enables the user to query just a subset of an entity’s fields. This enables developers to only query what they actually need for their current use case, thereby reducing network traffic and improving performance.

Let’s start with a very simple example. Assume that in our application we want to display a list of the names of all the cats in our database. Using entity views we would first define a new view for this purpose:

The usage of the CatNameView could look like this:

Of course, you can apply further restrictions to your query by CriteriaBuilder means. E.g. you could avoid duplicate names in the above example by calling groupBy() on the CriteriaBuilder at any point after its creation.

By default the abstract getter methods in the view definition map to same named entity fields. So the getName() getter in the above example actually triggers querying of the name field. If we want to use a different name for the getter method we would have to add an additional @Mapping annotation:

Of course, it is also possible to combine various views via inheritance.

Moreover you can see that it is possible to use whole expressions inside the @Mapping annotations. The allowed expression will be covered in more detail in subsequent chapters.

Another useful feature are subviews which is illustrated in following example.

The last feature we are going to cover here are filters and sorters in conjunction with EntityViewSetting which allows the dynamic configuration of filters and sorters on your entity view and are also usable together with pagination. This makes them ideal an ideal fit whenever you need to query data for display in a filterable and/or sortable data table. Following example illustrates how this looks like:

In this example we once again define a view on our Cat entity and select the cat’s name only. But in addition we applied a filter on the name attribute. In this case we chose the ContainsFilter, one of the predefined filters. We also defined a custom filter where we check whether the cat’s doctor’s name starts with the string Julia. The next code snippet shows how we dynamically set the actual filter value by which the query should filter and how we paginate the resulting query.

If you want to go into more detail, you are now ready to discover the other chapters of the documentation or the API yourself.

A quick overview that presents the interfaces that are essential for users and how they are related.

Since entity views are mostly annotation driven and are about mapping attributes to entity attributes, there are not that many interfaces. The two most important ones are the EntityViewManager and the EntityViewSetting.

A EntityViewManager is built once on startup during which it analyzes and validates the configured entity views. It is responsible for building implementations for the interfaces and abstract classes from the metamodel and caching object builder instances for entity views.

The EntityViewSetting is a configuration that can be applied on a query builder through an EntityViewManager and contains information about

The entity view module builds on top of the ObjectBuilder integration point offered by query builders of the core module. Every entity view is translated into a ObjectBuilder which is then applied on a query builder.

During startup the metamodel is built which is then used for building an object builder pipeline. For every entity view interface/class a ObjectBuilder template called ViewTypeObjectBuilderTemplate is created which is cached. From these templates a normal ObjectBuilder is built that can be applied on any query builder. Depending on the features a entity view uses, the resulting object builder might actually be a object builder pipeline i.e. it invokes multiple object builders in an ordered manner on tuples.

In general, a object builder for an entity view just takes in the tuple and passes it to the constructor of the entity view implementation. As soon as subviews or collections are involved, it becomes a pipeline. The pipeline has two different forms, the abstract form represented by TupleTransformatorFactory and the concrete form TupleTransformator. When a object builder is created from a template, the concrete form is created from the abstract one which might involve building object builders for subviews. Every collection introduces a new transformation level i.e. elements of a collection must be materialized before the collection can be materialized.

So the result is processed from the leafs(i.e. the elements) upwards(i.e. a collection) until objects of the target entity view type are materialized.

Updatable entity views are still in flux and are not yet fully thought through, but here comes the essential idea.

Similar to the object builder pipeline, a EntityViewUpdater is composed of several possibly nested attribute flushers. A EntityViewUpdater is built once and is responsible for flushing dirty attributes to the persistence context. After flushing, attributes are considered to be non-dirty but they can become dirty again either through a change or a transaction rollback.

Dirty tracking is done either by remembering the initial state and comparing with changed state or not at all. Collections are tracked by using custom collection implementations that do action recording which is then replayed onto a collection of an entity reference.

So far, you have mostly seen basic attribute mappings in entity views, but there is actually support for far many mapping types.

Apart from mapping attributes, it is also possible have a constructor and map parameters when using an abstract class. One of the biggest use cases for this is for doing further transformations on the data that can’t be pushed to the DBMS like e.g. money formatting.

As mentioned before, the entity view module implements a convention over configuration approach and thus has some smart defaults for mappings. Whenever an attribute(getter method) without a mapping annotation is encountered, a default mapping to the same named entity attribute will be created. If there is none, it will obviously report an error.

Id mappings declare that an attribute represents the identifier i.e. can be used to uniquely identify an entity view object. The id mapping is declared by annotating the desired attribute with @IdMapping and optionally specifying the mapping path. Having an id attribute allows an entity view to map collections, be mapped in collections and gives an entity view object a meaningful identity. If an entity view has no id mapping, it is considered to be a flat view which probably only makes sense for scalar results or embedded objects.

When an id mapping is present, the generated entity view implementation’s equals-hashCode implementation will be based on it. Otherwise it will consider all attributes in the equals-hashCode implementation.

A flat view id mapping is given when the type of the id attribute is a flat view type. This is the case when the view type has no id declared. It’s very similar to subview mappings and is mostly used when working with JPA embeddable types. Imagine the following model for illustration purposes.

This example already makes use of many concepts. It declares the CatIdView as flat view with a basic mapping and the CatView with a flat view id. The mapping for the flat view id in CatView uses to the this expression extension to allow the flat view to be based on the same entity that is backing the CatView.

A basic mapping is declared by annotating the desired attribute with @Mapping and specifying the mapping expression. An attribute that has no mapping annotations is only considered to have a basic mapping if it is of a basic type like e.g. Integer. Without a mapping annotation, the default mapping rules apply. In general, every non-collection and non-managed type is considered to be basic. Managed types are JPA managed types and entity view types.

Although most example only use path expressions for the mapping, it is actually allowed to use any scalar expression that JPQL or Blaze Persistence allows.

As you might expect, the expression UPPER(name) will upper-case the name, so getUpperName() will return the upper-cased name. Applying such an entity view on a simple query builder will show what happens behind the scenes.

The expression in the mapping ends up as select item in the query just as expected.

Subview and embeddable view mappings are similar to basic mappings in the sense that the same rules apply, except for the allowed mappings. Since these mappings get their data from objects of managed types, only path expressions are allowed for their mappings. Path expressions can have arbitrary depth i.e. multiple de-references like relation.subRelation.otherRelation and path elements can be of the following types:

A subview mapping is given when the type of the attribute is a entity view type. Since a entity view is always declared for a specific entity type, the target type of the subview mapping and the entity view’s entity type must be compatible. This means that you could apply a AnimalView to a Cat if it extends Animal but can’t apply a PersonView since it’s not compatible i.e. Cat is not a subtype of Person.

As you might imagine, the CatView will additionally select attributes of the father relation since they are requested by the AnimalView. In order to understand the following generated query, you should know what an implicit join does and how entity views make use of such implicit joins.

Behind the scenes, the entity views runtime will apply a select on the criteria builder for the expressions cat.id, father.id and father.name. The expression father.name accesses an entity attribute is only accessible when actually joining the relation. This is why an implicit/default join is generated for the father relation.

Since the father relation is optional or nullable, a (default) left join is created due to the rules of model awareness in implicit joins. This is a perfect fit for entity views as the subview object will be simply null if a cat has no father. If the implicit join worked like JPQL defines it, an inner join would have to be created. An inner join would mean that cats without a father would get filtered out which is an undesirable effect since we only want a projection on top of a base query.

Subquery mappings allow to map scalar subqueries into entity views and are declared by annotating the desired attribute with @MappingSubquery and specifying a SubqueryProvider. The following example should illustrate the usage:

This entity view already comes into contact with the core API for creating subqueries. It produces just what it defines, a subquery in the select clause.

In the subquery provider before you saw the usage of EMBEDDING_VIEW which is gone in the final query. This is because EMBEDDING_VIEW is a way to refer to attributes of the relation of the entity view into which the subquery is embedded without having to refer to the concrete the query alias. For more information on this check out the documentation of the EMBEDDING_VIEW function

A parameter mapping is a convenient way to inject the values of query parameters or optional parameters into instances of an entity view. Introducing a parameter mapping with @MappingParameter will introduce a fake select item. If a parameter is not used in a query, NULL will be injected into the entity view.

Parameter mappings are probably most useful in constructor mappings where they can be used for some transformation logic.

Apart from having custom projections for entity or embeddable types through subviews, you can also map the JPA managed types directly. You can use the @Mapping annotation if desired and map any path expression as singular or plural attribute(i.e. collection) with managed types.

Beware that when using managed types directly, you might run into lazy loading issues when accessing uninitialized/un-fetched properties of the entity.

You can however specify what properties should be fetched for such entity mappings by using the fetches configuration.

This will fetch the kittens of the father.

One of the most important features of the Blaze Persistence entity view module is the possibility to map collections. You can map collections defined in the entity model to collections in the entity view model in multiple ways.

There are cases when the entity model defines a collection that is actually a singular entity attribute. This can happen when you use custom type implementations or JPA 2.1 attribute converters that produce collections. A custom type or converter could map a DBMS array, json, xml or any other type to a collection. Since such an entity attribute is not a relation, it can only be a singular attribute. By default Blaze Persistence entity views assume that an entity view attribute with a collection type is a plural attribute and the mapping refers to a plural entity attribute. In order to be able to map such special singular attribute collections, you have to specifically use @MappingSingular.

Beware that you can’t re-map the collection type in this case although this might soon be possible.

The query will not generate a join but simply select the tags since it’s a singular attribute.

In some entity models, not every relation between entities might be explicitly mapped. There are multiple possible reasons for that like e.g. not wanting to have explicit dependencies, to keep it simple etc. Apart from unmapped relations, there is sometimes the need to correlate entities based on some criteria with other entities which are more of an ad-hoc nature than explicit relations.

For these cases Blaze Persistence entity views introduces the concept of correlated mappings. These mappings can be used to connect entities through a custom criteria instead of through mapped entity relations. Correlated mappings can be used for any attribute type(basic, entity, subview, collection) although singular basic attributes can also be implemented as normal subqueries.

A correlation mapping is declared by annotating the desired attribute with @MappingCorrelated or @MappingCorrelatedSimple.

There are some special methods that can be declared abstract in an entity view type which have special runtime support.

Blaze Persistence entity views generally supports the full set of expressions that JPQL and Blaze Persistence core module supports, but in addition to that, also offers some expression extensions.

So far, all mapping examples used interfaces for entity views, but as outlined in the beginning, Blaze Persistence entity views also has support for abstract classes. There are multiple use cases for using abstract classes for entity views, but in general we recommend to use an interface as often as possible. The biggest advantage of using abstract classes is that you can have a custom constructor which can further apply transformations on data.

Entity views can have an inheritance relationship to subtypes via an inheritance mapping. This relationship allows instances of an entity view subtype to be materialized when a selection predicate defined by an inheritance mapping is satisfied.

The inheritance feature for an entity view is activated by annotating @EntityViewInheritance on an entity view. By default, all subtypes of the entity view are considered as inheritance subtypes and thus require a so called inheritance mapping.

An inheritance mapping is defined by annotating the subtype with @EntityViewInheritanceMapping and defining a selection predicate that represents the condition on which decides the instantiation of that subtype. The predicate is a normal JPQL predicate expression and can refer to all attributes of the mapped entity type.

Consider the following example

When querying for entity views of the type BaseCatView, the selection predicates age < 18 and age > 18 are merged into a type discriminator expression that returns a type index. The type index refers to the entity view type into which a result should be materialized. The resulting JPQL query for such an entity view looks like the following

The type index 0 refers to the base type BaseCatView, hence instances of BaseCatView are materialized when the age of a result equals 18.

Since it might not be desirable to use all entity view subtypes for the inheritance relationship, it is possible to explicitly declare the subtypes in the @EntityViewInheritance annotation on the super type.

This has the effect, that only BaseCatView or YoungCatView instances are materialized for a result.

Similarly to specifying the entity view inheritance subtypes at the declaration site, i.e. BaseCatView, it is also possible to define subtypes at the use site, i.e. at the subview attribute. By annotating the subview attribute with @MappingInheritance, it is possible to delimit and override the entity view subtype mappings that are considered for materialization from the result. When using the @MappingInheritance annotation, it is required to list all desired subtypes via @MappingInheritanceSubtype annotations that can optionally override the inheritance mapping.

When querying for PersonView, YoungCatView instances will be materialized if the cat’s age is lower or equal to 18 and otherwise instances of BaseCatView will be created. By setting the annotation property onlySubtypes to true, instances of the base type BaseCatView aren’t materialized but a null is propagated. Apart from skipping the base type, it is also possible to define the base type via @MappingInheritanceSubtype which allows to specify the inheritance mapping for the base type.

A CTE can be used in an entity view by correlating the CTE entity type, but it is still necessary to define the CTE. This can be done on the underlying Blaze Persistence core CriteriaBuilder before applying an entity view. Doing that is not always ideal e.g. when considering repositories for Spring Data or DeltaSpike Data, there is usually no access to the CriteriaBuilder.

The @With annotation can be applied on an entity view class to register a CTEProvider to the entity view class. When applying an entity view, it’s corresponding registered CTEProvider instances are invoked that can define CTEs

For more information about CTEs refer to the CTE section in the core documentation.

If your JPA provider supports entity joins, the JOIN strategy usually makes sense most of the time. In case of correlated mappings it will result in a LEFT JOIN entity join of the correlated entity type. The correlation expression created by the CorrelationProvider will be used in the ON condition.

For an example query that is generated by this strategy take a look at the correlation mappings chapter.

In general, the SELECT strategy will create a separate query for every attribute that uses it. It will collect up to N distinct correlation basis values and then will execute that query to actually fetch the values for the attributes of the instances. The parameter N is the batch size that can be configured at multiple levels.

Let’s look at an example that shows what happens

When using this entity view, there are 2 queries that are generated.

The main query will fetch the correlationBasis and all the other attributes.

The correlation query on the other hand will select the correlation value and the Person instances with an age matching any of the correlationParams values. What you see here is the use of the VALUES clause for making multiple values available like a table for querying which is required when wanting to select the correlation value. Selecting the actual correlation value via correlationParams along with the Person is necessary to be able to correlate the instances to the instance of the main query.

Depending on how many different values for age there are(cardinality), the correlation query might get executed multiple times. In general, the runtime will collect up to batch size different values and then execute the correlation query for these values. Results for a correlation value are cached during the querying to avoid querying the same correlation values multiple times in different batches.

This strategy works best when the cardinality of the correlationBasis is low i.e. there are only a few distinct values. If the cardinality is high and the batch size is too low, this can lead to something similar as an N + 1 select known from lazy loading of collection elements. You could theoretically choose a very big batch size to be able to handle more correlation values per query, but beware that there are limits to the efficiency of this approach. Also beware that the amount of possible parameters might be limited by the DBMS. A value of 1000 for the batch size shouldn’t generally be a problem for a DBMS, but before you configure such a high value, look into the subselect strategy which might be more appropriate for higher cardinalities.

The SUBSELECT strategy will create one query for every attribute that uses it and is especially efficient for bigger collections. It creates a separate query based on the outer query and applies the CorrelationProvider to it.

Let’s look at an example that shows what happens

When using this entity view, there are 2 queries that are generated.

The main query will fetch the correlationBasis and all the other attributes.

The correlation query looks very similar since it’s based on the main query, but has a custom select clause. It selects the correlation key as well as the attributes for the target representation in the main entity view.

The filter API allows to enable and parameterize a filter for entity view attributes.

Entity view filters are defined by annotating respective entity view attributes with @AttributeFilter or @AttributeFilters for multiple named filters.

In the annotation you can supply an optional filter name and a filter provider class which needs to extend AttributeFilterProvider. An attribute filter’s name must be unique for the attribute it is annotated on. The attribute filter without a filter name is the default filter. Only a single default attribute filter per attribute is allowed.

Example:

Default attribute filters are enabled by calling addAttributeFilter(String attributeName, Object filterValue) whereas named filters require calling addAttributeFilter(String attributeName, String filterName, Object filterValue).

The supplied object values are used by the filter provider to append the appropriate restrictions to the query builder.

Blaze Persistence provides a number of built-in filter providers in the com.blazebit.persistence.view.filter package:

It is also possible to filter by subview attributes. The following example illustrates this:

The sorter API allows to sort entity views by their attributes. A sorter can be applied for an attribute by invoking addAttributeSorter(String attributeName, Sorter sorter)

For an example of how to use the sorter API refer to the introductory example.

Blaze Persistence provides default sorters via the static methods in the Sorters class. These methods allow to easily create any combination of ascending/descending and nulls-first/nulls-last sorter.

Code in the presentation layer is intended to create an EntityViewSetting via the create() API and pass the entity view setting to a data access method. The data access method then applies the setting onto a CriteriaBuilder instance which it created to build a query.

Apart from the already presented aspects, a EntityViewSetting also contains so called optional parameters and configuration properties.

Optional parameters are set on a query if no value is set and also injected into entity views if requested by a parameter mapping and are a very good integration point for dependency injection into entity views. They can be set with the addOptionalParameter(String parameterName, Object value) method.

Configuration properties denoted as being always applicable can be set via setProperty(String propertyName, Object value) and allow to override or fine tune configuration time behavior for a single query.

Up until now, an entity view setting has always been applied on the query root of a CriteriaBuilder which might not always be doable because of the way relations are mapped or how the query is done. Fortunately, Blaze Persistence entity views also allow to apply a setting on a relation of the query root via EntityViewManager.applySetting(EntityViewSetting setting, CriteriaBuilder criteriaBuilder, String entityViewRoot).

Let’s consider the following example.

Mapping this entity view on e.g. the father relation like

This will map all fathers of cats to the CatView and roughly produce a query like the following

Although an entity view already represents a significantly state-reduced version of an entity, it might still be desirable to reduce the state even further. Imagine an UI that allows to configure visible columns in a table where entity view data is presented. Wouldn’t it be great if data that isn’t shown is not fetched at all? On a EntityViewSetting you can specify entity view attributes that you would like to fetch via the fetch(String path) method.

As soon as you call it once, you will have to specify all attributes that you want to be fetched.

Here a simple example:

Normally, when you fetch this, you will get a query like the following

But when you use the following settings instead

You will instead only get the mentioned attributes and the identifiers by which the objects are reachable

Even the join was omitted because of this change. You still get the same CatView objects returned, but the getOwner().getCatIds() is simply empty.

To declare an entity view as being updatable, it is required to additionally annotate it with @UpdatableEntityView. By default an updatable entity view will do full updates i.e. always update all (owned) updatable attributes if at least one (owned) attribute is dirty. Owned attributes are the ones that belong to the backing entity type like e.g. basic typed attributes. Collections or inverse attributes aren’t owned in this sense and are thus independent. This behavior can be configured by setting the mode attribute on the @UpdatableEntityView:

The flushing, by default, is done by executing JPQL DML statements, but can be configured to use entities instead by setting the strategy attribute on the @UpdatableEntityView:

To declare an entity view as being creatable, it is required to additionally annotate it with @CreatableEntityView. Note that updatable entity views for embeddable types are implicitly also creatable, yet the @CreatableEntityView annotation can still be applied for further configuration. By default, a creatable entity view is validated against the backing model regarding it’s persistability i.e. it is checked if an instance could be successfully persisted regarding the non-null constraints of the entity model. This allows to catch errors early that occur when adding new attributes to the entity model but forgetting to do so in the entity view. The validation can be disabled by setting the validatePersistability attribute on the @CreatableEntityView to false but can also be controlled in a fine grained manner by excluding specific entity attributes from the validation via the excludedEntityAttributes attribute. The latter is useful for attributes that are known to be set on the entity model through inverse relationship, entity listeners or entity view listeners.

Creatable views are converted to their context specific declaration type after persisting. This mean that if a creatable entity view is used as value for an attribute of an updatable entity view, the instance is replaced by an equivalent instance of the type that is declared for the attribute. Consider the following example model for illustration.

When flushing an instance of the type CatUpdateView that contains an owner of the creatable entity view type OwnerCreateView the following happens

The same replacing happens for creatable entity views that are contained in a collection, thus developers don’t need to think about possible problems related to primary key based equals-hashCode implementations. Since the object is properly replaced, the assignment of a generated primary key, which would change the object regarding equals-hashCode, is not problematic. Still, the object can safely make use of the primary key based equals-hashCode implementation that is generated for all entity views by default.

An updatable as well as an creatable entity view is flushed by invoking EntityViewManager.save(EntityManager em, Object view) or one of its variants and will flush changes according to the flush strategy and mode. Changes to collections are flushed depending on the collection mapping, flush strategy and JPA provider support.

The query flush strategy requires support for collection DML queries which is currently only provided with Hibernate.

If the provider doesn’t support collection DML, or you choose to do entity flushing, the owning entity is loaded and changes are applied to that. For collections that are not owned by the containing entity i.e. use a mappedBy, changes will be applied by creating/updating/deleting the target entities.

INFO: Blaze Persistence will manage inverse relationships automatically and even update the parent object in the child object if mapped.

Creatable entity views are constructed via EntityViewManager.create(Class type) and always result in a persist when being flushed directly or through an updatable attribute having the CascadeType.PERSIST enabled.

Deletion of entities through view types works either by supplying an existing view object to EntityViewManager.remove(EntityManager em, Object view) or by entity id via EntityViewManager.remove(EntityManager em, Class viewType, Object id).

The big advantage of using the remove APIs is that Blaze Persistence will reduce the amount of queries significantly, especially if the a view object is passed that already provides information about the object graph.

An entity view, similar to a JPA entity, also has something like a lifecycle, though within entity views, the states correspond to different entity view java types, rather than a transaction state. There are essentially 3 different kinds of entity views:

For most of the operations it is possible to register a listener which is invoked before or after an operation. The listeners can react to specific events but in some cases also alter the state of the corresponding object.

A listener can be defined within an entity view class but within a class hierarchy there may only be one listener of a kind. If multiple listeners of a single kind from e.g. super interfaces are inherited, the entity view type must declare a listener to disambiguate the situation. The listener then can invoke other parent listener methods or skip them.

Most listeners can be defined for a specific update or remove operation to react to change events in a particular manner for a specific use case, but it is also possible to register listeners globally. The globally registered listeners can be used to implement cross cutting concerns like soft-deletion, auditing, etc. Global listeners are registered via one of the EntityViewConfiguration.registerListener methods or discovered in a CDI or Spring environment if the classes are annotated with @EntityViewListener or @EntityViewListeners.

When an entity view has @UpdatableEntityView annotated, every attribute for which a setter method exists, is considered to be updatable. For an attribute to be updatable means that changes done to the attribute of an entity view, can be flushed to the entity attribute they map to. There is also a notion of mutable attributes which means that an attribute is updatable and/or the type of the attribute’s value might be mutable.

An unknown type is mutable by default and needs to be configured by registering a basic user type. Entity view types are only considered being mutable if they are updatable(@UpdatableEntityView) or creatable(@CreatableEntityView). Entity types are always considered to be mutable.

The mappings for updatable attributes must follow some rules

The general understanding is that mappings should be bi-directional i.e. it should be possible to map a value back to a specific entity attribute.

To prevent an attribute being considered updatable, it can be annotated with @UpdatableMapping(updatable = false). Sometimes, it’s also useful to annotate plural attributes i.e. collection attributes with @UpdatableMapping(updatable = true) when a setter is inappropriate.

Note that updatable and creatable entity view types require an id mapping to work properly, which is validated during the building of the metamodel. The getters and setters of abstract entity view classes may use the protected or default visibility setting which allows to encapsulate the access to these attributes properly.

Blaze Persistence entity views by default automatically makes use of a version field mapped in the entity type for optimistic locking. This is controlled by the lockMode attribute on the @UpdatableEntityView annotation which by default is set to AUTO.

By default, all updatable attributes in an entity view are protected by optimistic locking. This means that if the value of an attribute was changed, the change will be flushed with the optimistic lock condition. Attribute changes that should be excluded from optimistic locking can be annotated with @OptimisticLock(exclude = true) to prevent the optimistic lock condition when only such attributes are changed.

The entity type for which the optimistic lock condition is asserted is called the lock owner. If the entity type of an entity view does not have a version field and the LockMode.AUTO is used, the parent entity view type is considered being the lock owner. If the parent has no version field, it’s parent is considered and so forth. If no lock owner can be found, no optimistic locking is done.

When specifying a lock mode other than LockMode.AUTO, the entity object for an entity view becomes the lock owner. By annotating @LockOwner on an updatable entity view type, a custom lock owner can be defined.

The cascade types defined in Blaze Persistence entity views have different semantics than what JPA offers and should not be mixed up. JPA defines cascade types for logical operations whereas Blaze Persistence entity views defines cascade types for state changes. In a JPA entity, one can define for which operations the changes done to an attribute should be flushed. For example the JPA CascadeType.PERSIST will cause a flush of an attribute’s affected values only if the owning entity is about to be persisted.

Blaze Persistence entity views cascade types define whether a value of an attribute may do a specific state transition. If an attribute defines CascadeType.PERSIST, it means that new objects i.e. the ones created via EntityViewManager.create(), are allowed to be used as values and that these object should be persisted during flushing. Updates done to mutable values of an attribute are only flushed if the CascadeType.UPDATE is enabled.

Normally, the update or persist cascading is enabled for all subtypes of the declared attribute type, but can be restricted by specifying specific subtypes for which to allow updates or persists. This can be done via the subtypes attribute of the @UpdatableMapping or the updateSubtypes or persistSubtypes attributes for the corresponding cascade types.

Delete cascading and orphan removal have the same semantics as in JPA. If you delete an entity A that refers to entity B through an attribute that defines delete cascading, entity B is going to be deleted as well. When removing a reference from entity A to entity B through an attribute that defines orphan removal, entity B is going to be deleted. Orphan removal also implies delete cascading, so entity B is also deleted when deleting entity A.

Most JPA implementations only support cascading deletes and orphan removal for managed entities whereas DML statements for the entity types do not consider this configuration. Blaze Persistence respects the settings all the way and strives to avoid data loading even for the removal by id action done via EntityViewManager.remove(EntityManager, Class, Object). When an entity graph for an entity view type has an arbitrary depth relationship, Blaze Persistence still has to do some entity data loading, but it tries to reduce the executed statements as much as possible.

To enable delete cascading for an attribute, the CascadeType.DELETE has to be added to the cascade attribute of a @UpdatableMapping

When deleting a Cat like the following

the owner is going to be deleted along with the Cat. The delete cascading even works for attributes that are only defined to do delete cascading in the entity. Assuming Cat does not have the arbitrary depth relationship kittens, the removal might trigger the following logical JPQL statements.

First, the cascading delete enabled collections like e.g. the nickNames collection is deleted. Then the Cat is deleted and while doing that, the ids of the *ToOne relations with enabled cascading deletes like e.g. the owner’s id are returned. For DBMS not supporting the RETURNING clause for DML statements, a SELECT statement is issued before the DELETE to extract the ids of the *ToOne relations. Finally, the cascading deletes for the *ToOne relations are done e.g. the Person is deleted.

If the entity type for an updatable entity view uses delete cascading or orphan removal for an attribute, an updatable mapping for that attribute must use these configurations as well. So if the entity type uses delete cascading for the owner of Cat, it would be an error to omit the delete cascading configuration.

The same goes for orphan removal and the idea behind this is, that it makes delete cascading and orphan removal configurations visible in every updatable view, thus making it less surprising. It would make no sense to allow disabling delete cascading or orphan removal configurations because then the entity flush strategy would produce different results than the query flush strategy. Obviously the other way around i.e. enabling delete cascading or orphan removal if the entity attribute does not use these configurations, is very valid. Sometimes there are cases where delete cascading or orphan removal shouldn’t be done which means the cascading can’t be configured on the entity type attributes. This where Blaze Persistence entity views show their strength as they allow to control these configurations on a per-use case basis.

As explained in the beginning, the vision for updatable entity views is to support the modelling of use case specific write models. Although most of the data that is generally updatable is mostly loaded already when starting a use case it is rarely necessary to make it updatable right away. Some use cases might require only a subset of the data to be updatable, while others require a different subset. To support modelling this appropriately it is possible to convert between entity views types.

Imagine the following model for illustration purposes.

When navigating to e.g. a detail UI for a Cat the CatBaseView would be loaded. If the UI had a special action to initiate a transfer to a different owner, doing that action would lead to the conversion of the CatBaseView to the CatOwnerUpdateView.

After setting the new owner and flushing the changes via EntityViewManager.save(EntityManager, Object) the view is converted back to the base view by invoking EntityViewManager.convert(Class, Object, ConvertOption…​) again.

When initiating the kitten update action the conversion would be done to CatKittenUpdateView.

Keep in mind that most UIs do not necessarily work this way and that the added complexity might not be beneficial in all cases. Although this mechanism enables a clear separation for use cases, it might just as well be the case, that use cases are so small that it is better to have just a single write model. In some special cases like e.g. when simply changing a status of an object, it might not even be necessary to have an explicit write model. For such cases it is often more appropriate to have a specialized service method or event publishing of some sorts.

Note that internally, the conversion feature is used for converting successfully persisted creatable entity views to their context specific declaration type.

There are of course other possible use cases for this feature like e.g. conversion from a more detailed view to a view containing only a subset of the information.

A very interesting use case is duplicating data. Such a use case requires to partially copy existing data such that it can be saved with a new identity. This is where the control over sub-attributes through EntityViewManager.convertWith(Class, Object, ConvertOption…​) comes in handy. It allows to exclude attributes through ConvertOperationBuilder.excludeAttributes(String... attributes) and also convert specific attributes to a specific subtype with custom convert options through ConvertOperationBuilder.convertAttribute(String attributePath, Class<?> attributeViewClass, ConvertOption... convertOptions).

Imagine the following model for illustration purposes.

A clone of a cat and kittens could be done by using

The resulting object could then be persisted via EntityViewManager.save() which represents a duplicate of the original.

There are several well known types registered out of the box.

If found on the classpath, types for the following classes are registered

If you miss a type you can register it via EntityViewConfiguration.registerBasicUserType(Class type, BasicUserType userType).

When a basic type is used in a write model, it is very important that an appropriate BasicUserType is registered. If no basic user type is registered for a type, by default the com.blazebit.persistence.view.spi.type.MutableBasicUserType is used. This basic user type assume the type is mutable which will cause values of that type to always be assumed being dirty. Updatable entity views containing values of such a type are thus always considered being dirty which has the effect, that every call to EntityViewManager.save(EntityManager em, Object view) will cause a flush of attributes containing that value. The updatable-entity-view-change-model-api is also affected of this by always reporting such attributes as being dirty.

Immutable types, like e.g. java.lang.String already does, can use the basic user type implementation com.blazebit.persistence.view.spi.type.ImmutableBasicUserType which assumes objects of the type are immutable.

A proper basic user type implementation for mutable types, when based on the provided type com.blazebit.persistence.view.spi.type.AbstractMutableBasicUserType only needs an implementation for cloning a value. The cloned value is used to e.g. keep the initial state so that later changes can be detected by checking equality.

JPA managed types are also considered mutable by default, and since no dirty tracking information is available by default, objects of that such types are always considered dirty thus also always flushed. An integration with the native dirty tracking mechanism of the JPA provider might improve performance and will be considered in future versions. Entity types that handle change tracking manually, can implement a custom basic user type to improve the performance for usages of that entity type within updatable entity views, but are generally recommended to switch to subviews instead.

For further information on the possible SPI methods consult the JavaDoc of the BasicUserType interface

To allow an attribute to be used as version for optimistic locking, the registered basic type also needs to implement the com.blazebit.persistence.view.spi.type.VersionBasicUserType interface. This type additionally requires to provide an implementation for returning the next version based on a given current version.

There are several TypeConverters registered out of the box.

If found on the classpath, TypeConverters for the following types are registered

If you miss a TypeConverter you can register it via EntityViewConfiguration.registerTypeConverter(Class entityModelType, Class viewModelType, TypeConverter typeConverter).

To detect if a model or one of it’s child models is dirty, one can use the ChangeModel.isDirty() method. The actual change models of dirty elements within a SingularChangeModel can be retrieved via SingularChangeModel.getDirtyChanges(). Only attributes of the queried object are reported as change models i.e. only a single level.

The singular change models allow access to the attributes change models either via attribute path or via the metamodel attribute objects by using one of the overloaded SingularChangeModel.get(String attributePath) methods. The term path implicates a nested attribute access is possible, which is the case, but beware that accessing attributes of collection elements will result in an exception unless the SingularChangeModel.getAll(String attributePath) variant is used which returns a list of change models instead of a single one.

Another notable feature the singular change model provides is the checking for dirtyness of a specific attribute path. Instead of materializing every change model along the path, the SingularChangeModel.isDirty(String attributePath) method only reports the dirtyness of the object accessible through the given attribute path. A variant of this method SingularChangeModel.isChanged(String attributePath) will return early if one of the parent attributes was updated i.e. the identity was changed.

The plural change model is similar in the respect that it provides analogous methods that simply return a list of change models instead of a single one. It also allows to access the change models of the added, removed or mutated elements separately. To access all dirty changes similar to what is possible with SingularChangeModel#getDirtyChanges(), plural change models provide the method PluralChangeModel.getElementChanges() for doing the same.

The map change model additionally allows to differentiate between changes to key objects and element objects. It offers methods to access the key changes as well as the overall object changes with analogously named methods getAddedObjects(), getAddedKeys() etc.

The change model implementation gains it’s insights by inspecting the dirty tracking information of the actual objects. Since a transaction commit will flush dirty changes i.e. the dirtyness is resetted, change model objects won’t report any dirty changes after a commit. If information about the change models should be retained after a transaction commit, it must be serialized with a custom mechanism. When a rollback occurs, the dirtyness is restored to be able to commit again after doing further changes which also means that change models will work as expected.

The Change Model API builds on top of the BasicUserType foundation and it is thus essential to have a correct implementation for the type.

To setup the project for Spring Data you have to add dependencies as described in the Setup section and make beans available for CriteriaBuilderFactory and EntityViewManager instances as laid out in the Spring environment section.

In short, the following Maven dependencies are required

If you still work with Spring Data 2.1 you will have to use a different integration as Spring Data 2.2 changed quite a bit.

If you still work with Spring Data 2.0 you will have to use a different integration as Spring Data 2.1 changed quite a bit.

If you still work with Spring Data version 1 you will have to use a different integration.

The dependencies for other JPA providers or other versions can be found in the core module setup section.

A possible bean configuration for the required beans CriteriaBuilderFactory and EntityViewManager in short might look like this.

When enabling JPA repositories, make sure you configure BlazePersistenceRepositoryFactoryBean as repositoryFactoryBeanClass. Optionally specify a custom basePackage for repository class scanning and a custom entityManagerFactoryRef.

The integration comes with a convenience base interface com.blazebit.persistence.spring.data.repository.EntityViewRepository that you can use for your repository definitions.

Assume we have the following entity view:

A very simple repository might look like this:

Since we use EntityViewRepository as a base interface we inherit the most commonly used repository methods. You can now use this repository as any other Spring Data repository:

Spring Data Specifications can be used without restrictions. There is also the convenience base interface com.blazebit.persistence.spring.data.repository.EntityViewSpecificationExecutor that can be extended from.

Because Spring Data Specifications work on a JPA criteria builder we provide BlazeSpecification as an alternative that accepts a Blaze Persistence criteria builder but works analogously apart from that.

The integration handles ad-hoc uses of @EntityGraph by adapting the query generation through call of CriteriaBuilder.fetch() rather than passing the entity graphs as hints.

Another notable feature the integration provides is the support for the return type KeysetAwarePage as a replacement for Page. By using KeysetAwarePage the keyset pagination feature is enabled for the repository method.

Note that the Pageable should be an instance of KeysetPageable if keyset pagination should be used. A KeysetPageable can be retrieved through the KeysetAwarePage or manually by constructing a KeysetPageRequest. Note that constructing a KeysetPageRequest or actually the contained KeysetPage manually is not recommended. When working with Spring WebMvc, the Spring Data WebMvc or WebFlux integrations might come in handy. For stateful server side frameworks, it’s best to put the KeysetAwarePage into a session like storage to be able to use the previousOrFirst() and next() methods for retrieving KeysetPageable objects.

When using parameters in an entity view, these parameters are usually passed in as optional parameters to an EntityViewSetting rather than normal query parameters. You can customize the EntityViewSetting object that is used by providing a EntityViewSettingProcessor like so.

To just pass optional parameters, one can also annotate a parameter with @OptionalParam to designate it as being an optional parameter and to be included in the generated EntityViewSetting.

All other Spring Data repository features like restrictions, pagination, slices and ordering are supported as usual. Please consult the Spring Data documentation for further information.

The Spring Data WebMvc integration offers similar pagination features for keyset pagination to what Spring Data WebMvc integration already offers for normal offset pagination.

The Spring Data WebFlux integration provides the same features as the Spring Data WebMvc integration. In addition it also supports using Mono and Flux types.

To setup the project for DeltaSpike Data you have to add the entity view and CDI integration dependencies as described in the getting started section along with the integration dependencies for your JPA provider as described in the core module setup section.

In addition, the following Maven dependencies are required:

This will also work for DeltaSpike Data 1.9.

If you still work with DeltaSpike Data 1.7 you will have to use a different integration as DeltaSpike Data 1.9 and 1.8 changed quite a bit.

You also need to make beans available for CriteriaBuilderFactory and EntityViewManager as laid out in the CDI environment section.

To mark a class or an interface as repository, use the DeltaSpike org.apache.deltaspike.data.api.Repository annotation.

The integration provides the following base interfaces that you may optionally extend to define entity view repositories:

Similar to what Spring Data offers, it is also possible to make use of a Specification which essentially is a callback that allows to refine a query.

The integration handles ad-hoc uses of @EntityGraph by adapting the query generation through call of CriteriaBuilder.fetch() rather than passing the entity graphs as hints.

Another notable feature the integration provides is the support for a Pageable object with Page return type similar to what Spring Data offers. The integration also supports the return type KeysetAwarePage. By using KeysetAwarePage the keyset pagination feature is enabled for the repository method.

Note that the Pageable should be an instance of KeysetPageable if keyset pagination should be used. A KeysetPageable can be retrieved through the KeysetAwarePage or manually by constructing a KeysetPageRequest. Note that constructing a KeysetPageRequest or actually the contained KeysetPage manually is not recommended. When working with JAX-RS, the [DeltaSpike Data Rest] integration might come in handy. For stateful server side frameworks, it’s best to put the KeysetAwarePage into a session like storage to be able to use the previousOrFirst() and next() methods for retrieving KeysetPageable objects.

All other DeltaSpike Data repository features like restrictions, explicit offset pagination, returning QueryResult and others are supported as usual. Please consult the DeltaSpike Data documentation for further information.

The DeltaSpike Data Rest integration offers similar pagination features for normal and keyset pagination to what Spring Data offers for normal offset based pagination.

To use the Jackson integration directly you need the following Maven dependencies:

The main feature is the possibility to use entity views just like normal POJOs that can be deserialized automatically.

The JAX-RS integration can automatically deserialize entity views of request bodies by simply using the entity view type as parameter like this:

To use the GraphQL integration you need the following Maven dependencies:

Note that the integration works with the de facto standard runtime for GraphQL which is graphql-java.

The integration works by contributing entity view type as GraphQL types to a GraphQL TypeDefinitionRegistry. In general, the idea is that you define a custom GraphQL schema for your queries in which you use entity view types.

Let’s consider the following sample schema

With the following entity views

The integration happens through the class GraphQLEntityViewSupportFactory like so:

This will generate the following GraphQL types

The created GraphQLEntityViewSupport object is a singleton that should only be created during boot and can be used for creating EntityViewSetting objects in GraphQL DataFetcher implementations.

Next, one needs to define a DataFetcher for the defined query catById like so

The GraphQLEntityViewSupport.createSetting() method inspects the data fetching environment and knows which entity view type is needed. In addition, it will fill the fetches according to the DataFetchingEnvironment.getSelectionList(). This will lead to the optimal query to be generated for the fields that are requested. This is not only about skipping select items, but also avoids unnecessary joins!

Finally, the RuntimeWiring and TypeDefinitionRegistry are joined together to a GraphQL schema which is required for the GraphQL runtime.

The repository could look like this:

A sample GraphQL query

will cause a JPQL query similar to the following

It does not select or join the owner information although it is specified in the entity view! This optimization works through applying the selection list of the DataFetchingEnvironment via EntityViewSetting.fetch().

GraphQL itself does not really define a standard pagination mechanism, so the integration implements part of the Relay pagination specification in order to provide support for keyset pagination in a more or less common format.

To generate the types that are necessary for using a Relay compatible client, the GraphQLEntityViewSupportFactory can be further configured.

With the entity views defined before, this will generate the following GraphQL types

To use these type, the static GraphQL Schema needs to be extended

The Relay specification defines the first and last arguments to represent the amount of element to fetch. Using first will fetch the next X elements after the given reference point or the start, according to a specific ordering. Using last will fetch the last X elements before the given reference point or the end, according to a specific ordering.

If you can’t use keyset pagination, the GraphQL integration also allows to use an offset argument, but it is not recommended as offset based pagination has scalability problems.

In order to use this, a RuntimeWiring that executes a query is required.

The GraphQLEntityViewSupport.createPaginatedSetting() method is capable of reading all necessary information from the DataFetchingEnvironment and the schema. It knows how to process first, last, offset, before and after arguments as well as integrates with the selection list feature to

If the query does not specify first or last, the EntityViewSetting.getMaxResults() will be 0 which will cause an exception if used for querying.

Finally, the DataFetcher must return a GraphQLRelayConnection object that wraps a List or PagedList such that the correct result structure is produced.

A sample GraphQL query

will cause a JPQL query similar to the following

and provide a result object like the following

You can the use the endCursor on the client side as value for the after argument to get the next page:

which will cause a JPQL query similar to the following

and provide a result object like the following

For a full example see the following example project.

The com.blazebit.persistence.view.OptimisticLockException is very similar to the javax.persistence.OptimisticLockException and when thrown, it signals that an update isn’t possible because of a change of an object that happened in the meantime. This can also happen when you do not use optimistic locking explicitly.

Entity views are type checked for most parts, but there are some dynamic non-declarative parts that can’t be type checked that might cause this runtime exception when using a wrong result. Usually, this happens when a SubqueryProvider or CorrelationProvider is in use. The implementations of these classes define the result type in a manner that is not type checkable.

If a SubqueryProvider returns an integer via e.g. select("1") or select("someIntAttribute"), but the entity view attribute using the subquery provider uses a different type like e.g. boolean, constructing an instance of that entity view might fail when trying to interpret the integer as boolean with an IllegalArgumentException saying that types are incompatible. The obvious fix is to correct either the select item to return the correct type or the entity view attribute to declare the appropriate attribute type. In case of a subquery provider it is also possible to wrap the subquery into a more complex expression by using e.g. @MappingSubquery(value = MyProvider.class, subqueryAlias = "subquery", expression = "CASE WHEN EXISTS subquery THEN true ELSE false END").

A CorrelationProvider can fail in a similar manner as it defines the entity type it correlates via correlate(SomeEntity.class). If the entity view attribute expects a different type that is not compatible, it will fail at runtime with an IllegalArgumentException saying that types are incompatible. If a correlation result is defined via @MappingCorrelated(correlationResult = "someAttributeOfCorrelatedEntity") the type of that expression must be compatible which can be another cause for an error. This problem can be fixed by adapting the correlation result expression, by changing the correlated entity in the correlation provider or by changing the declared attribute type.