diff --git a/.travis.yml b/.travis.yml index abc379c7e5..fd51a9e95e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,7 @@ language: java sudo: false +notifications: + slack: $SLACK_API_TOKEN cache: directories: - '$HOME/.m2/repository' diff --git a/README.md b/README.md index 45ca0bbcb1..4d1647e58c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ [![Build Status](https://travis-ci.org/Blazebit/blaze-persistence.svg?branch=master)](https://travis-ci.org/Blazebit/blaze-persistence) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.blazebit/blaze-persistence-core-impl/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.blazebit/blaze-persistence-core-impl) +[![Slack Status](https://blazebit.herokuapp.com/badge.svg)](https://blazebit.herokuapp.com) + +[![Javadoc - Core](https://javadoc-emblem.rhcloud.com/doc/com.blazebit/blaze-persistence-core-api/badge.svg?subject=javadoc%20-%20core-api)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-core-api) +[![Javadoc - Entity-View](https://javadoc-emblem.rhcloud.com/doc/com.blazebit/blaze-persistence-entity-view-api/badge.svg?subject=javadoc%20-%20entity-view-api)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-entity-view-api) +[![Javadoc - JPA-Criteria](https://javadoc-emblem.rhcloud.com/doc/com.blazebit/blaze-persistence-jpa-criteria-api/badge.svg?subject=javadoc%20-%20jpa-criteria-api)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-jpa-criteria-api) + Blaze-Persistence ========== Blaze-Persistence is a rich Criteria API for JPA providers. @@ -19,145 +26,320 @@ You can roughly imagine an entity view is to an entity, what a RDBMS view is to The JPA-Criteria module implements the Criteria API of JPA but is backed by the Blaze-Persistence Core API so you can get a query builder out of your CriteriaQuery objects. +Features +============== + +Blaze-Persistence is not only a Criteria API that allows to build queries easier, +but it also comes with a lot of features that are normally not supported by JPA providers. + +Here is a rough overview of new features that are introduced by Blaze-Persistence + +* Use CTEs and recursive CTEs +* Use modification CTEs aka DML in CTEs +* Make use of the RETURNING clause from DML statements +* Use the VALUES clause for reporting queries and soon make use of table generating functions +* Create queries that use SET operations like UNION, EXCEPT and INTERSECT +* Define functions similar to Hibernates SQLFunction in a JPA provider agnostic way +* Use many built-in functions like GROUP_CONCAT, date extraction, date arithmetic and many more +* Easy pagination and simple API to make use of keyset pagination + +In addition to that, Blaze-Persistence also works around some JPA provider issues in a transparent way. + How to use it? ============== Blaze-Persistence is split up into different modules. We recommend that you define a version property in your parent pom that you can use for all artifacts. Modules are all released in one batch so you can safely increment just that property. - - 1.2.0.Alpha1 - +```xml + + 1.2.0.Alpha1 + +``` For compiling you will only need API artifacts and for the runtime you need impl and integration artifacts. Choose the integration artifacts based on your JPA provider. Blaze-Persistence Core module dependencies - - com.blazebit - blaze-persistence-core-api - ${blaze-persistence.version} - compile - - - com.blazebit - blaze-persistence-core-impl - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-core-api + ${blaze-persistence.version} + compile + + + com.blazebit + blaze-persistence-core-impl + ${blaze-persistence.version} + runtime + +``` Blaze-Persistence Entity-View module dependencies - - com.blazebit - blaze-persistence-entity-view-api - ${blaze-persistence.version} - compile - - - com.blazebit - blaze-persistence-entity-view-impl - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-entity-view-api + ${blaze-persistence.version} + compile + + + com.blazebit + blaze-persistence-entity-view-impl + ${blaze-persistence.version} + runtime + +``` Blaze-Persistence Entity-View CDI integration dependencies - - com.blazebit - blaze-persistence-entity-view-impl - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-entity-view-impl + ${blaze-persistence.version} + runtime + +``` Blaze-Persistence JPA provider integration module dependencies Hibernate 5.2 - - com.blazebit - blaze-persistence-integration-hibernate-5.2 - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-integration-hibernate-5.2 + ${blaze-persistence.version} + runtime + +``` Hibernate 5+ - - - com.blazebit - blaze-persistence-integration-hibernate-5 - ${blaze-persistence.version} - runtime - + +```xml + + com.blazebit + blaze-persistence-integration-hibernate-5 + ${blaze-persistence.version} + runtime + +``` Hibernate 4.3 - - com.blazebit - blaze-persistence-integration-hibernate-4.3 - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-integration-hibernate-4.3 + ${blaze-persistence.version} + runtime + +``` Hibernate 4.2 - - - com.blazebit - blaze-persistence-integration-hibernate-4.2 - ${blaze-persistence.version} - runtime - + +```xml + + com.blazebit + blaze-persistence-integration-hibernate-4.2 + ${blaze-persistence.version} + runtime + +``` Datanucleus - - - com.blazebit - blaze-persistence-integration-datanucleus - ${blaze-persistence.version} - runtime - + +```xml + + com.blazebit + blaze-persistence-integration-datanucleus + ${blaze-persistence.version} + runtime + +``` EclipseLink - - - com.blazebit - blaze-persistence-integration-eclipselink - ${blaze-persistence.version} - runtime - + +```xml + + com.blazebit + blaze-persistence-integration-eclipselink + ${blaze-persistence.version} + runtime + +``` OpenJPA - - - com.blazebit - blaze-persistence-integration-openjpa - ${blaze-persistence.version} - runtime - + +```xml + + com.blazebit + blaze-persistence-integration-openjpa + ${blaze-persistence.version} + runtime + +``` Blaze-Persistence JPA-Criteria module dependencies - - com.blazebit - blaze-persistence-jpa-criteria-api - ${blaze-persistence.version} - compile - - - com.blazebit - blaze-persistence-jpa-criteria-impl - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-jpa-criteria-api + ${blaze-persistence.version} + compile + + + com.blazebit + blaze-persistence-jpa-criteria-impl + ${blaze-persistence.version} + runtime + +``` Blaze-Persistence JPA-Criteria JPA 2.0 provider support dependencies - - com.blazebit - blaze-persistence-jpa-criteria-jpa-2-compatibility - ${blaze-persistence.version} - runtime - +```xml + + com.blazebit + blaze-persistence-jpa-criteria-jpa-2-compatibility + ${blaze-persistence.version} + runtime + +``` + +Documentation +========= + +The current documentation is still pretty raw and we are happy about every contribution! +The documentation is split into a reference for the [core module](https://github.com/Blazebit/blaze-persistence/blob/master/documentation/src/main/asciidoc/core/manual/en_US/index.adoc) and for the [entity-view module](https://github.com/Blazebit/blaze-persistence/blob/master/documentation/src/main/asciidoc/entity-view/manual/en_US/entity-view-index.adoc). +Core quick-start +================= + +First you need to create a `CriteriaBuilderFactory` which is the entry point to the core api. + +```java +CriteriaBuilderConfiguration config = Criteria.getDefault(); +// optionally, perform dynamic configuration +CriteriaBuilderFactory cbf = config.createCriteriaBuilderFactory(entityManagerFactory); +``` + +NOTE: The `CriteriaBuilderFactory` should have the same scope as your `EntityManagerFactory` as it is bound to it. + +For demonstration purposes, we will use the following simple entity model. + +```java +@Entity +public class Cat { + @Id + private Integer id; + private String name; + @ManyToOne(fetch = FetchType.LAZY) + private Cat father; + @ManyToOne(fetch = FetchType.LAZY) + private Cat mother; + @OneToMany + private Set kittens; + // Getter and setters omitted for brevity +} +``` + +If you want select all cats and fetch their kittens as well as their father you do the following. + +```java +cbf.create(em, Cat.class).fetch("kittens.father").getResultList(); +``` + +This will create quite a query behind the scenes: + +```sql +SELECT cat FROM Cat cat LEFT JOIN FETCH cat.kittens kittens_1 LEFT JOIN FETCH kittens_1.father father_1 +``` + +An additional bonus is that the paths and generally every expression you write will get checked against the metamodel so you can spot typos very early. + +Entity-view usage +================= + +Every project has some kind of DTOs and implementing these properly isn't easy. Based on the super quick-start model we will show how entity views come to the rescue! + +To make use of entity views, you will need a `EntityViewManager` with entity view classes registered. In a CDI environment you can inject a `EntityViewConfiguration` that has all discoverable entity view classes registered, but in a normal Java application you will have to register the classes yourself like this: + +```java +EntityViewConfiguration config = EntityViews.createDefaultConfiguration(); +config.addEntityView(CatView.class); +EntityViewManager evm = config.createEntityViewManager(criteriaBuilderFactory, entityManagerFactory); +``` + +NOTE: The `EntityViewManager` should have the same scope as your `EntityManagerFactory` and `CriteriaBuilderFactory` as it is bound to it. + +The entity view itself is a simple interface describing the structure of the projection that you want. It is very similar to defining an entity class with the difference that it is based on the entity model instead of the DBMS model. + +```java +@EntityView(Cat.class) +public interface CatView { + @IdMapping + public Integer getId(); + + @Mapping("CONCAT(mother.name, 's kitty ', name)") + public String getCuteName(); + + public SimpleCatView getFather(); + +} +``` + +```java +@EntityView(Cat.class) +public interface SimpleCatView { + @IdMapping + public Integer getId(); + + public String getName(); + +} +``` + +The `CatView` has a property `cuteName` which will be computed by the JPQL expression `CONCAT(mother.name, 's kitty ', name)` and a subview for `father`. Note that every entity view needs an id mapping except for `EmbeddableEntityView` classes. +The `SimpleCatView` is the projection which is used for the `father` relation and only consists of the `id` and the `name` of the `Cat`. + +You just created two DTO interfaces that contain projection information. Now the interesting part is that entity views can be applied on any query, so you can define a base query and then create the projection like this: + +```java +CriteriaBuilder cb = criteriaBuilderFactory.create(entityManager, Cat.class); +cb.whereOr() + .where("father").isNull() + .where("father.name").like().value("Darth%").noEscape() +.endOr(); +CriteriaBuilder catViewBuilder = evm.applySetting(EntityViewSetting.create(CatView.class), cb); +List catViews = catViewBuilder.getResultList(); +``` + +This will behind the scenes execute the following optimized query and transparently build your entity view objects based on the results. + +```sql +SELECT + cat.id, + CONCAT(mother_1.name, 's kitty ', cat.name), + father_1.id, + father_1.name +FROM Cat cat +LEFT JOIN cat.father father_1 +LEFT JOIN cat.mother mother_1 +WHERE father_1 IS NULL + OR father_1.name LIKE :param_0 +``` + +See the left joins created for relations used in the projection? These are implicit joins which are by default what we call "model-aware". If you specified that a relation is `optional = false`, we would generate an inner join instead. This is different from how JPQL path expressions are normally interpreted, but in case of projections like in entity views, this is just what you would expect! You can always override the join type of implicit joins with `joinDefault` if you like. + +Questions or issues +=================== + +Drop by on [![Slack Status](https://blazebit.herokuapp.com/badge.svg)](https://blazebit.herokuapp.com) and ask questions any time or just create an issue on [GitHub](https://github.com/Blazebit/blaze-persistence/issues/new). + Licensing ========= diff --git a/documentation/src/main/asciidoc/core/manual/en_US/03_configuration.adoc b/documentation/src/main/asciidoc/core/manual/en_US/03_configuration.adoc index cb1c956d02..ba4635a0ac 100644 --- a/documentation/src/main/asciidoc/core/manual/en_US/03_configuration.adoc +++ b/documentation/src/main/asciidoc/core/manual/en_US/03_configuration.adoc @@ -81,6 +81,28 @@ This feature can make writing queries a lot easier since it will implicitly copy | Default | true |==================== +==== EXPRESSION_OPTIMIZATION + +Defines whether expressions should be optimized. + +[width="100%",options="header,footer"] +|==================== +| Key | com.blazebit.persistence.expression_optimization +| Type | boolean +| Default | true +|==================== + +==== EXPRESSION_CACHE_CLASS + +The full qualified expression cache implementation class name. + +[width="100%",options="header,footer"] +|==================== +| Key | com.blazebit.persistence.expression.cache_class +| Type | String +| Default | com.blazebit.persistence.impl.expression.ConcurrentHashMapExpressionCache +|==================== + === Query transformers Query tranformers are used to apply object builders to typed queries. This is normally provided by an integration module for persistence providers. @@ -107,4 +129,4 @@ By registering a custom implementation for a specific dbms via `registerDialect( === Entity manager integrators -A little integration layer to extract the dbms of an entity manager and register `JpqlFunctionGroup`s with the entity manager. This is normally provided by an integration module for persistence providers. \ No newline at end of file +A little integration layer to extract the dbms of an entity manager and register `JpqlFunctionGroup` instances with the entity manager. This is normally provided by an integration module for persistence providers. \ No newline at end of file diff --git a/documentation/src/main/asciidoc/entity-view/manual/en_US/01_getting_started.adoc b/documentation/src/main/asciidoc/entity-view/manual/en_US/01_getting_started.adoc index 0a27b5057a..426768fd9c 100644 --- a/documentation/src/main/asciidoc/entity-view/manual/en_US/01_getting_started.adoc +++ b/documentation/src/main/asciidoc/entity-view/manual/en_US/01_getting_started.adoc @@ -23,7 +23,7 @@ EntityViewConfiguration cfg = EntityViews.createDefaultConfiguration(); cfg.addEntityView(EntityView1.class); // Add some more cfg.addEntityView(EntityViewn.class); -EntityViewManager evm = cfg.createEntityViewManager(); +EntityViewManager evm = cfg.createEntityViewManager(criteriaBuilderFactory, entityManagerFactory); ---- As you can see, the `EntityViewConfiguration` is used to register all the entity view classes that you want to make accessible within the an `EntityViewManager`. @@ -215,7 +215,7 @@ query should filter and how we paginate the resulting query. ---- // Base setting EntityViewSetting> setting = - EntityViewSetting.create(FilteredCatView.class, 0, 10); + EntityViewSetting.create(FilteredCatView.class, 0, 10); // Query CriteriaBuilder cb = cbf.create(em, Cat.class); diff --git a/documentation/src/main/asciidoc/entity-view/manual/en_US/03_configuration.adoc b/documentation/src/main/asciidoc/entity-view/manual/en_US/03_configuration.adoc index 6a832f60c3..87b52a0a54 100644 --- a/documentation/src/main/asciidoc/entity-view/manual/en_US/03_configuration.adoc +++ b/documentation/src/main/asciidoc/entity-view/manual/en_US/03_configuration.adoc @@ -16,6 +16,18 @@ To improve startup performance this is deactivated by default. When using entity | Default | false |==================== +==== TEMPLATE_EAGER_LOADING + +Defines whether entity view template objects should be created eagerly when creating the `EntityViewManager` or on demand. +To improve startup performance this is deactivated by default. In a production environment you might want to enable this so that templates don't have to be built on-demand but are retrieved from a cache. + +[width="100%",options="header,footer"] +|==================== +| Key | com.blazebit.persistence.view.eager_loading +| Type | boolean +| Default | false +|==================== + ==== PROXY_UNSAFE_ALLOWED Defines whether proxy classes that support using the getter methods in a constructor should be allowed. @@ -38,4 +50,15 @@ Defines whether the expressions of entity view mappings should be validated. | Key | com.blazebit.persistence.view.expression_validation_disabled | Type | boolean | Default | true +|==================== + +==== DEFAULT_BATCH_SIZE + +Defines the default batch size to be used for attributes that are fetched via the `SELECT` fetch strategy. + +[width="100%",options="header,footer"] +|==================== +| Key | com.blazebit.persistence.view.batch_size +| Type | int +| Default | 1 |==================== \ No newline at end of file diff --git a/documentation/src/main/asciidoc/entity-view/manual/en_US/entity-view-index.adoc b/documentation/src/main/asciidoc/entity-view/manual/en_US/entity-view-index.adoc index 127645ce94..ff95d6741a 100644 --- a/documentation/src/main/asciidoc/entity-view/manual/en_US/entity-view-index.adoc +++ b/documentation/src/main/asciidoc/entity-view/manual/en_US/entity-view-index.adoc @@ -10,8 +10,8 @@ Copyright (C) 2014 Blazebit toc::[] -include::01_ev_getting_started.ad[] +include::01_getting_started.adoc[] -include::02_architecture.ad[] +include::02_architecture.adoc[] -include::03_configuration.ad[] +include::03_configuration.adoc[] diff --git a/entity-view/impl/src/main/java/com/blazebit/persistence/view/impl/ConfigurationProperties.java b/entity-view/impl/src/main/java/com/blazebit/persistence/view/impl/ConfigurationProperties.java index c85a632bcd..006b51816f 100644 --- a/entity-view/impl/src/main/java/com/blazebit/persistence/view/impl/ConfigurationProperties.java +++ b/entity-view/impl/src/main/java/com/blazebit/persistence/view/impl/ConfigurationProperties.java @@ -66,8 +66,6 @@ public final class ConfigurationProperties { * To specify the batch size of a specific property, append the property name after the "batch_size" like * e.g. com.blazebit.persistence.view.batch_size.subProperty * - * Valid values for this property are true or false. - * * @since 1.2.0 */ public static final String DEFAULT_BATCH_SIZE = "com.blazebit.persistence.view.batch_size";