{"id":16284128,"url":"https://github.com/blazebit/blaze-persistence","last_synced_at":"2026-01-11T13:04:59.150Z","repository":{"id":18563113,"uuid":"21765334","full_name":"Blazebit/blaze-persistence","owner":"Blazebit","description":"Rich Criteria API for JPA providers","archived":false,"fork":false,"pushed_at":"2024-10-29T08:47:31.000Z","size":38016,"stargazers_count":730,"open_issues_count":324,"forks_count":86,"subscribers_count":25,"default_branch":"main","last_synced_at":"2024-10-29T09:58:44.497Z","etag":null,"topics":["criteria-api","cte","java","jpa","sql"],"latest_commit_sha":null,"homepage":"https://persistence.blazebit.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Blazebit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.asciidoc","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-12T11:08:47.000Z","updated_at":"2024-10-29T08:47:36.000Z","dependencies_parsed_at":"2023-09-24T12:00:55.898Z","dependency_job_id":"3c63def5-3583-4dfe-ac71-6514eeb6b3ad","html_url":"https://github.com/Blazebit/blaze-persistence","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazebit%2Fblaze-persistence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazebit%2Fblaze-persistence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazebit%2Fblaze-persistence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazebit%2Fblaze-persistence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blazebit","download_url":"https://codeload.github.com/Blazebit/blaze-persistence/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248261916,"owners_count":21074225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["criteria-api","cte","java","jpa","sql"],"created_at":"2024-10-10T19:18:31.257Z","updated_at":"2026-01-11T13:04:59.142Z","avatar_url":"https://github.com/Blazebit.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://persistence.blazebit.com/images/blaze_persistence_logo_colors_render.png\" width=\"200\" /\u003e\n\n[![Build Status](https://github.com/Blazebit/blaze-persistence/workflows/Blaze-Persistence%20CI/badge.svg)](https://github.com/Blazebit/blaze-persistence/actions)\n\n[![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)\n[![Zulip Chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://blazebit.zulipchat.com)\n\n[![Javadoc - Core](https://www.javadoc.io/badge2/com.blazebit/blaze-persistence-core-api/Core%20API%20Javadoc.svg?color=green)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-core-api)\n[![Javadoc - Entity-View](https://www.javadoc.io/badge2/com.blazebit/blaze-persistence-entity-view-api/EntityView%20API%20Javadoc.svg?color=green)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-entity-view-api)\n[![Javadoc - JPA-Criteria](https://www.javadoc.io/badge2/com.blazebit/blaze-persistence-jpa-criteria-api/JPA%20Criteria%20API%20Javadoc.svg?color=green)](http://www.javadoc.io/doc/com.blazebit/blaze-persistence-jpa-criteria-api)\n\nBlaze-Persistence\n==========\nBlaze-Persistence is a rich Criteria API for JPA providers.\n\nWhat is it?\n===========\n\nBlaze-Persistence is a rich Criteria API for JPA providers that aims to be better\nthan all the other Criteria APIs available.\nIt provides a fluent API for building queries and removes common restrictions\nencountered when working with JPA directly.\nIt offers rich pagination support and also supports keyset pagination.\n\nThe Entity-View module can be used to create views for JPA entites.\nYou can roughly imagine an entity view is to an entity, what a RDBMS view is to a table.\n\nThe JPA-Criteria module implements the Criteria API of JPA but is backed by the Blaze-Persistence Core API\nso you can get a query builder out of your CriteriaQuery objects.\n\nWith Spring Data or DeltaSpike Data integrations you can make use of Blaze-Persistence easily in your existing repositories.\n\nFeatures\n==============\n\nBlaze-Persistence is not only a Criteria API that allows to build queries easier,\nbut it also comes with a lot of features that are normally not supported by JPA providers.\n\nHere is a rough overview of new features that are introduced by Blaze-Persistence on top of the JPA model\n\n* Use CTEs and recursive CTEs\n* Use modification CTEs aka DML in CTEs\n* Make use of the RETURNING clause from DML statements\n* Use the VALUES clause for reporting queries and soon make use of table generating functions\n* Create queries that use SET operations like UNION, EXCEPT and INTERSECT\n* Manage entity collections via DML statements to avoid reading them in memory\n* Define functions similar to Hibernates SQLFunction in a JPA provider agnostic way\n* Use many built-in functions like GROUP_CONCAT, date extraction, date arithmetic and many more\n* Easy pagination and simple API to make use of keyset pagination\n\nIn addition to that, Blaze-Persistence also works around some JPA provider issues in a transparent way.\n\nHow to use it?\n==============\n\nBlaze-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. \n\n```xml\n\u003cproperties\u003e\n    \u003cblaze-persistence.version\u003e1.6.17\u003c/blaze-persistence.version\u003e\n\u003c/properties\u003e\n```\n\nAlternatively you can also use our BOM in the `dependencyManagement` section.\n\n```xml\n\u003cdependencyManagement\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ecom.blazebit\u003c/groupId\u003e\n            \u003cartifactId\u003eblaze-persistence-bom\u003c/artifactId\u003e\n            \u003cversion\u003e${blaze-persistence.version}\u003c/version\u003e\n            \u003ctype\u003epom\u003c/type\u003e\n            \u003cscope\u003eimport\u003c/scope\u003e\n        \u003c/dependency\u003e    \n    \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\n## Quickstart\n\nIf you want a sample application with everything setup where you can poke around and try out things, just go with our archetypes!\n\nCore-only archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-core-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nEntity view archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nSpring-Data archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-spring-data-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nSpring-Boot archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-spring-boot-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nDeltaSpike Data archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-deltaspike-data-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nJava EE archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-java-ee-sample\" \"-DarchetypeVersion=1.6.17\"\n```\n\nCore-only Jakarta archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-core-sample-jakarta\" \"-DarchetypeVersion=1.6.17\"\n```\n\nEntity view Jakarta archetype:\n\n```bash\nmvn archetype:generate \"-DarchetypeGroupId=com.blazebit\" \"-DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample-jakarta\" \"-DarchetypeVersion=1.6.17\"\n```\n\n## Supported Java runtimes\n\nAll projects are built for Java 7 except for the ones where dependencies already use Java 8 like e.g. Hibernate 5.2, Spring Data 2.0 etc.\nSo you are going to need a JDK 8 for building the project. The latest Java version we test and support is Java 21.\n\nWe also support building the project with JDK 9 and try to keep up with newer versions.\nIf you want to run your application on a Java 9 JVM you need to handle the fact that JDK 9+ doesn't export the JAXB and JTA APIs anymore.\nIn fact, JDK 11 removed the modules, so the command line flags to add modules to the classpath won't work.\n\nSince libraries like Hibernate and others require these APIs you need to make them available. The easiest way to get these APIs back on the classpath is to package them along with your application.\nThis will also work when running on Java 8. We suggest you add the following dependencies.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ejakarta.xml.bind\u003c/groupId\u003e\n    \u003cartifactId\u003ejakarta.xml.bind-api\u003c/artifactId\u003e\n    \u003c!-- Use version 3.0.1 if you want to use Jakarta EE 9 --\u003e\n    \u003cversion\u003e2.3.3\u003c/version\u003e\n    \u003c!-- In a managed environment like Java/Jakarta EE, use 'provided'. Otherwise use 'compile' --\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.sun.xml.bind\u003c/groupId\u003e\n    \u003cartifactId\u003ejaxb-impl\u003c/artifactId\u003e\n    \u003c!-- Use version 3.0.2 if you want to use Jakarta EE 9 --\u003e\n    \u003cversion\u003e2.3.3\u003c/version\u003e\n    \u003c!-- In a managed environment like Java/Jakarta EE, use 'provided'. Otherwise use 'compile' --\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ejakarta.transaction\u003c/groupId\u003e\n    \u003cartifactId\u003ejakarta.transaction-api\u003c/artifactId\u003e\n    \u003c!-- Use version 2.0.0 if you want to use Jakarta EE 9 --\u003e\n    \u003cversion\u003e1.3.3\u003c/version\u003e\n    \u003c!-- In a managed environment like Java/Jakarta EE, use 'provided'. Otherwise use 'compile' --\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ejakarta.activation\u003c/groupId\u003e\n    \u003cartifactId\u003ejakarta.activation-api\u003c/artifactId\u003e\n    \u003c!-- Use version 2.0.1 if you want to use Jakarta EE 9 --\u003e\n    \u003cversion\u003e1.2.2\u003c/version\u003e\n    \u003c!-- In a managed environment like Java/Jakarta EE, use 'provided'. Otherwise use 'compile' --\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ejakarta.annotation\u003c/groupId\u003e\n    \u003cartifactId\u003ejakarta.annotation-api\u003c/artifactId\u003e\n    \u003c!-- Use version 2.0.0 if you want to use Jakarta EE 9 --\u003e\n    \u003cversion\u003e1.3.5\u003c/version\u003e\n    \u003c!-- In a managed environment like Java/Jakarta EE, use 'provided'. Otherwise use 'compile' --\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nThe `jakarta.transaction` and `jakarta.activation` dependencies are especially relevant for the JPA metamodel generation.\n\n## Supported environments/libraries\n\nThe bare minimum is JPA 2.0. If you want to use the JPA Criteria API module, you will also have to add the JPA 2 compatibility module.\nGenerally, we support the usage in Java EE 6+ or Spring 4+ applications.\n\nSee the following table for an overview of supported versions.\n\nModule                           | Minimum version                     | Supported versions\n---------------------------------|-------------------------------------|--------------------\nHibernate integration            | Hibernate 4.2                       | 4.2, 4.3, 5.0+, 6.2+, 7.1 (not all features are available in older versions)\nEclipseLink integration          | EclipseLink 2.6                     | 2.6 (Probably 2.4 and 2.5 work as well, but only tested against 2.6)\nDataNucleus integration          | DataNucleus 4.1                     | 4.1, 5.0\nOpenJPA integration              | N/A                                 | (Currently not usable. OpenJPA doesn't seem to be actively developed anymore and no users asked for support yet)\nEntity View CDI integration      | CDI 1.0                             | 1.0, 1.1, 1.2, 2.0, 3.0\nEntity View Spring integration   | Spring 4.3                          | 4.3, 5.0, 5.1, 5.2, 5.3, 6.0\nDeltaSpike Data integration      | DeltaSpike 1.7                      | 1.7, 1.8, 1.9\nSpring Data integration          | Spring Data 1.11                    | 1.11 - 2.7, 3.1 - 3.5\nSpring Data WebMvc integration   | Spring Data 1.11, Spring WebMvc 4.3 | Spring Data 1.11 - 3.5, Spring WebMvc 4.3 - 6.2\nSpring Data WebFlux integration  | Spring Data 2.0, Spring WebFlux 5.0 | Spring Data 2.0 - 3.5, Spring WebFlux 5.0 - 6.2\nSpring HATEOAS WebMvc integration| Spring Data 2.2, Spring WebMvc 5.2  | Spring Data 2.3+, Spring WebMvc 5.2+, Spring HATEOAS 1.0+\nJackson integration              | 2.8.11                              | 2.8.11+\nGraphQL integration              | 17.3                                | 17.3+\nJAX-RS integration               | Any JAX-RS version                  | Any JAX-RS version\nQuarkus integration              | 1.4.2                               | 1.4+, 2.0+, 3.1+\n\n## Manual setup\n\nFor compiling you will only need API artifacts and for the runtime you need impl and integration artifacts.\n\nSee the [core documentation](https://persistence.blazebit.com/documentation/core/manual/en_US/index.html#maven-setup) for the necessary dependencies needed to setup\nBlaze-Persistence. If you want to use entity views, the [entity view documentation](https://persistence.blazebit.com/documentation/entity-view/manual/en_US/index.html#maven-setup) \ncontains a similar setup section describing the necessary dependencies.\n\nDocumentation\n=========\n\nThe current documentation is a reference manual and is split into a reference for the [core module](https://persistence.blazebit.com/documentation/core/manual/en_US/index.html) and for the [entity-view module](https://persistence.blazebit.com/documentation/entity-view/manual/en_US/index.html).\nAt some point we might introduce topical documentation, but for now you can find articles on the [Blazebit Blog](https://blazebit.com/blog.html)\n\nCore quick-start\n=================\n\nFirst you need to create a `CriteriaBuilderFactory` which is the entry point to the core api. \n\n```java\nCriteriaBuilderConfiguration config = Criteria.getDefault();\n// optionally, perform dynamic configuration\nCriteriaBuilderFactory cbf = config.createCriteriaBuilderFactory(entityManagerFactory);\n```\n\nNOTE: The `CriteriaBuilderFactory` should have the same scope as your `EntityManagerFactory` as it is bound to it.\n\nFor demonstration purposes, we will use the following simple entity model.\n\n```java\n@Entity\npublic class Cat {\n    @Id\n    private Integer id;\n    private String name;\n    @ManyToOne(fetch = FetchType.LAZY)\n    private Cat father;\n    @ManyToOne(fetch = FetchType.LAZY)\n    private Cat mother;\n    @OneToMany\n    private Set\u003cCat\u003e kittens;\n    // Getter and setters omitted for brevity\n}\n```\n\nIf you want to select all cats and fetch their kittens as well as their father you do the following.\n\n```java\ncbf.create(em, Cat.class).fetch(\"kittens.father\").getResultList();\n```\n\nThis will create quite a query behind the scenes:\n\n```sql\nSELECT cat FROM Cat cat LEFT JOIN FETCH cat.kittens kittens_1 LEFT JOIN FETCH kittens_1.father father_1\n```\n\nAn 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.\n\nJPA Criteria API quick-start\n=================\n\nBlaze-Persistence provides an implementation of the JPA Criteria API what allows you to mostly code against the standard JPA Criteria API,\nbut still be able to use the advanced features Blaze-Persistence provides.\n\nAll you need is a `CriteriaBuilderFactory` and when constructing the actual query, an `EntityManager`.\n\n```java\n// This is a subclass of the JPA CriteriaBuilder interface\nBlazeCriteriaBuilder cb = BlazeCriteria.get(criteriaBuilderFactory);\n// A subclass of the JPA CriteriaQuery interface\nBlazeCriteriaQuery\u003cCat\u003e query = cb.createQuery(Cat.class);\n\n// Do your JPA Criteria query logic with cb and query\nRoot\u003cCat\u003e root = query.from(Cat.class);\nquery.where(cb.equal(root.get(Cat_.name), \"Felix\"));\n\n// Finally, transform the BlazeCriteriaQuery to the Blaze-Persistence Core CriteriaBuilder\nCriteriaBuilder\u003cCat\u003e builder = query.createCriteriaBuilder(entityManager);\n// From here on, you can use all the power of the Blaze-Persistence Core API\n\n// And finally fetch the result\nList\u003cCat\u003e resultList = builder.getResultList();\n```\n\nThis will create a query that looks just about what you would expect:\n\n```sql\nSELECT cat FROM Cat cat WHERE cat.name = :param_0\n```\n\nThis alone is not very spectacular. The interesting part is that you can use the Blaze-Persistence `CriteriaBuilder` then to do your advanced SQL things\nor consume your result as entity views as explained in the next part.  \n\nEntity-view usage\n=================\n\nEvery 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!\n\nTo 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:\n\n```java\nEntityViewConfiguration config = EntityViews.createDefaultConfiguration();\nconfig.addEntityView(CatView.class);\nEntityViewManager evm = config.createEntityViewManager(criteriaBuilderFactory);\n```\n\nNOTE: The `EntityViewManager` should have the same scope as your `EntityManagerFactory` and `CriteriaBuilderFactory` as it is bound to it.\n\nAn entity view itself is a simple interface or abstract class 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.\n\n```java\n@EntityView(Cat.class)\npublic interface CatView {\n    @IdMapping\n    public Integer getId();\n\n    @Mapping(\"CONCAT(mother.name, 's kitty ', name)\")\n    public String getCuteName();\n\n    public SimpleCatView getFather();\n\n}\n```\n\n```java\n@EntityView(Cat.class)\npublic interface SimpleCatView {\n    @IdMapping\n    public Integer getId();\n\n    public String getName();\n\n}\n```\n\nThe `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 although not required in this particular case,\nevery entity view for an entity type should have an id mapping if possible. Entity views without an id mapping will by default have equals and hashCode implementations that consider all attributes, whereas with an id mapping, only the id is considered.\nThe `SimpleCatView` is the projection which is used for the `father` relation and only consists of the `id` and the `name` of the `Cat`.\n\nYou 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:\n\n```java\nCriteriaBuilder\u003cCat\u003e cb = criteriaBuilderFactory.create(entityManager, Cat.class);\ncb.whereOr()\n    .where(\"father\").isNull()\n    .where(\"father.name\").like().value(\"Darth%\").noEscape()\n.endOr();\nCriteriaBuilder\u003cCatView\u003e catViewBuilder = evm.applySetting(EntityViewSetting.create(CatView.class), cb);\nList\u003cCatView\u003e catViews = catViewBuilder.getResultList();\n```\n\nThis will behind the scenes execute the following optimized query and transparently build your entity view objects based on the results.\n\n```sql\nSELECT\n    cat.id,\n    CONCAT(mother_1.name, 's kitty ', cat.name),\n    father_1.id,\n    father_1.name\nFROM Cat cat\nLEFT JOIN cat.father father_1\nLEFT JOIN cat.mother mother_1\nWHERE father_1 IS NULL\n   OR father_1.name LIKE :param_0\n```\n\nSee 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.\nThis 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!\nYou can always override the join type of implicit joins with `joinDefault` if you like.\n\nQuestions or issues\n===================\n\nDrop by on [![Zulip Chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://blazebit.zulipchat.com) and ask questions any time or just create an issue on [GitHub](https://github.com/Blazebit/blaze-persistence/issues/new) or ask on [Stackoverflow](https://stackoverflow.com/questions/ask?tags=java+blaze-persistence).\n\nCommercial support\n==================\n\nYou can find commercial support offerings by Blazebit in the [support section](https://persistence.blazebit.com/support.html#_blaze_persistence_support).\n\nIf you are a commercial customer and want to use commercial releases, you need to define the following repository in a profile of your project or the `settings.xml` located in `~/.m2`.\n\n```xml\n\u003crepository\u003e\n  \u003cid\u003eblazebit\u003c/id\u003e\n  \u003cname\u003eBlazebit\u003c/name\u003e\n  \u003curl\u003ehttps://nexus.blazebit.com/repository/maven-releases/\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nYou also need to add the following server in the `settings.xml` with the appropriate credentials:\n\n```xml\n\u003cserver\u003e\n  \u003cid\u003eblazebit\u003c/id\u003e\n  \u003cusername\u003eUSERNAME\u003c/username\u003e\n  \u003cpassword\u003ePASSWORD\u003c/password\u003e\n\u003c/server\u003e\n```\n\nCommercial customers also get access to the [commercial repository](https://github.com/Blazebit-Commercial/blaze-persistence) where they access the source code of commercial releases,\ncreate issues that are treated with higher priority and browse commercial releases.\n\nUsing snapshots\n==================\n\nTo use the current snapshots which are published to the Sonatype OSS snapshot repository,\nyou need to define the following repository in a profile of your project or the `settings.xml` located in `~/.m2`.\n\n```xml\n\u003crepository\u003e\n  \u003cid\u003esonatype-snapshots\u003c/id\u003e\n  \u003cname\u003eSonatype Snapshots\u003c/name\u003e\n  \u003curl\u003ehttps://central.sonatype.com/repository/maven-snapshots/\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nAlso see the [Maven documentation](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) for further details.\n\nSetup local development\n=======================\n\nHere some notes about setting up a local environment for testing.\n\n## Setup general build environment\n\nAlthough Blaze-Persistence still supports running on Java 7, the build must be run with at least JDK 8.\nWhen doing a release at least a JDK 9 is required as we need to build some Multi-Release or MR JARs.\nSince we try to support the latest JDK versions as well, we require developers that want to build the project with JDK 11+ to define a system property for a release build.\n\nThe system property `jdk8.home` should be set to the path to a Java 7 or 8 installation that contains either `jre/lib/rt.jar` or `jre/lib/classes.jar`.\nThis property is necessary when using JDK 11+ because `sun.misc.Unsafe.defineClass` was removed.\n\n## Building the website and documentation\n\nYou have to install [GraphViz](http://www.graphviz.org/Download.php) and make it available in your PATH.\n\nAfter that, it's easiest to just invoke `./serve-website.sh` which builds the documentation, website and starts an embedded server to serve at port 8820.\n\n## Checkstyle in IntelliJ\n\n1. Build the whole thing with `mvn clean install` once to have the checkstyle-rules jar in your M2 repository\n2. Install the CheckStyle-IDEA Plugin\n3. After a restart, go to Settings \u003e Other Settings \u003e Checkstyle and configure version `9.3.0`\n4. Add a _Third party check_ that points to the _checkstyle-rules.jar_ of your M2 repository\n5. Add a configuration file named *Blaze-Persistence Checkstyle rules* pointing to `checkstyle-rules/src/main/resources/blaze-persistence/checkstyle-config.xml`\n\nNow you should be able to select *Blaze-Persistence Checkstyle rules* in the dropdown of the CheckStyle window. +\nClick on *Check project* and checkstyle will run once for the whole project, then it should do some work incrementally.\n\n## Testing a JPA provider and DBMS combination\n\nBy default, a Maven build `mvn clean install` will test against H2 and Hibernate 5.2 but you can activate different profiles to test other combinations.\nTo test a specific combination, you need to activate at least 4 profiles\n\n* One of the JPA provider profiles\n  * `hibernate-7.1` + the `jakarta` profile\n  * `hibernate-6.6` + the `jakarta` profile\n  * `hibernate-6.5` + the `jakarta` profile\n  * `hibernate-6.4` + the `jakarta` profile\n  * `hibernate-6.3` + the `jakarta` profile\n  * `hibernate-6.2` + the `jakarta` profile\n  * `hibernate-5.6`\n  * `hibernate-5.5`\n  * `hibernate-5.4`\n  * `hibernate-5.3`\n  * `hibernate-5.2`\n  * `hibernate-5.1`\n  * `hibernate-5.0`\n  * `hibernate-4.3`\n  * `hibernate`\n  * `eclipselink`\n  * `datanucleus-5.1`\n  * `datanucleus-5`\n  * `datanucleus-4`\n  * `openjpa`\n* A DBMS profile\n  * `h2`\n  * `postgresql`\n  * `mysql`\n  * `mysql8`\n  * `oracle`\n  * `db2`\n  * `mssql`\n  * `firebird`\n  * `sqllite`\n* A Spring data profile\n  * `spring-data-4.0.x`\n  * `spring-data-3.5.x`\n  * `spring-data-3.4.x`\n  * `spring-data-3.3.x`\n  * `spring-data-3.2.x`\n  * `spring-data-3.1.x`\n  * `spring-data-2.7.x`\n  * `spring-data-2.6.x`\n  * `spring-data-2.5.x`\n  * `spring-data-2.4.x`\n  * `spring-data-2.3.x`\n  * `spring-data-2.2.x`\n  * `spring-data-2.1.x`\n  * `spring-data-2.0.x`\n  * `spring-data-1.11.x`\n* A DeltaSpike profile\n  * `deltaspike-1.9`\n  * `deltaspike-1.8`\n  * `deltaspike-1.7`\n\nThe default DBMS connection infos are defined via Maven properties, so you can override them in a build by passing the properties as system properties.\n\n* `jdbc.url`\n* `jdbc.user`\n* `jdbc.password`\n* `jdbc.driver`\n\nThe values are defined in e.g. `core/testsuite/pom.xml` in the respective DBMS profiles.\n\nFor executing tests against a database on a dedicated host you might want to specify the following system property `-DdbHost=192.168.99.100`.\n\n## Testing with Jakarta Persistence provider\n\nTo build everything use `mvn -pl core/testsuite-jakarta-runner clean install -am -P \"hibernate-6.2,jakarta,h2,spring-data-2.6.x,deltaspike-1.9\" -DskipTests`\nand to run tests use `mvn -pl core/testsuite-jakarta-runner clean install -P \"hibernate-6.2,jakarta,h2,spring-data-2.6.x,deltaspike-1.9\" \"-Dtest=com.blazebit.persistence.testsuite.SetOperationTest#testUnionAllOrderBySubqueryLimit\"`.\n\n## Switching JPA provider profiles in IntelliJ\n\nWhen switching between Hibernate and other JPA provider profiles, IntelliJ does not unmark the `basic` or `hibernate` source directories in *core/testsuite*.\nIf you encounter errors like _duplicate class file found_ or something alike, make sure that\n\n* With a Hibernate profile you unmark the *core/testsuite/src/main/basic* directory as source root\n* With a non-Hibernate profile you unmark the *core/testsuite/src/main/hibernate* and *core/testsuite/src/test/hibernate* directory as source root\n\nUnmarking as source root can be done by right clicking on the source directory, going to the submenu _Mark directory as_ and finally clicking _Unmark as Sources Root_.\n\n## Using DataNucleus profiles in IntelliJ\n\nDataNucleus requires bytecode enhancement to work properly which requires an extra step to be able to do testing within IntelliJ.\nUsually when switching the JPA provider profile, it is recommended to trigger a _Rebuild Project_ action in IntelliJ to avoid strange errors causes by previous bytecode enhancement runs.\nAfter that, the entities in the project *core/testsuite* have to be enhanced. This is done through a Maven command.\n\n* DataNucleus 4: `mvn -P \"datanucleus-4,h2,deltaspike-1.8,spring-data-2.0.x\" -pl core/testsuite,entity-view/testsuite,integration/spring-data/testsuite/webmvc,integration/spring-data/testsuite/webflux datanucleus:enhance`\n* DataNucleus 5: `mvn -P \"datanucleus-5,h2,deltaspike-1.8,spring-data-2.0.x\" -pl core/testsuite,entity-view/testsuite,integration/spring-data/testsuite/webmvc,integration/spring-data/testsuite/webflux datanucleus:enhance`\n* DataNucleus 5.1: `mvn -P \"datanucleus-5.1,h2,deltaspike-1.8,spring-data-2.0.x\" -pl core/testsuite,entity-view/testsuite,integration/spring-data/testsuite/webmvc,integration/spring-data/testsuite/webflux datanucleus:enhance`\n\nAfter doing that, you should be able to execute any test in IntelliJ.\n\nNote that if you make changes to an entity class or add a new entity class you might need to redo the rebuild and enhancement. \n\n## Firebird\n\nWhen installing the 3.x version, you also need a 3.x JDBC driver.\nAdditionally you should add the following to the firebird.conf\n\n```\nWireCrypt = Enabled\n```\n\nAfter creating the DB with `create database 'localhost:test' user 'sysdba' password 'sysdba';`, you can connect with JDBC with `jdbc:firebirdsql:localhost:test?charSet=utf-8`\n\n## Oracle\n\nWhen setting up Oracle locally, keep in mind that when you connect to it, you have to set the NLS_SORT to BINARY.\nSince the JDBC driver derives values from the locale settings of the JVM, you should set the default locale settings to en_US.\nIn IntelliJ when defining the Oracle database, go to the Advanced tab an specify the JVM options `-Duser.country=us -Duser.language=en`.\n\n## GraalVM for native images with Quarkus\n\nThe general setup required for building native images with GraalVM is described in https://quarkus.io/guides/building-native-image.\n\n* Install GraalVM 20.2.0 (Java 11) and make sure you install the native-image tool and set `GRAALVM_HOME` environment variable\n* Install required packages for a C development environment\n  *  Under Windows, install [Visual Studio 2017 Visual C++ Build Tools](https://aka.ms/vs/15/release/vs_buildtools.exe)\n\nFor example, run the following maven build to execute native image tests for H2:\n\n```\nmvn -pl examples/quarkus/testsuite/native/h2 -am integration-test -Pnative,h2,spring-data-2.7.x,deltaspike-1.9\n```\n\nUnder Windows, make sure you run maven builds that use native image from the VS2017 native tools command line.\n\n## Website deployment\n\nYou can use `build-deploy-website.sh` to deploy to the target environment but need to configure in ~/.m2/settings.xml the following servers.\n\nId: staging-persistence.blazebit.com\nUser/Password: user/****\n\nId: persistence.blazebit.com\nUser/Password: user/****\n\nLicensing\n=========\n\nThis distribution, as a whole, is licensed under the terms of the Apache\nLicense, Version 2.0 (see LICENSE.txt).\n\nReferences\n==========\n\nProject Site:              https://persistence.blazebit.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblazebit%2Fblaze-persistence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblazebit%2Fblaze-persistence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblazebit%2Fblaze-persistence/lists"}