From 4380fa85b751a0d74a28c7856f12b202f3186991 Mon Sep 17 00:00:00 2001 From: "nathan.xu" Date: Sat, 23 Nov 2024 11:52:43 -0500 Subject: [PATCH 1/3] fix some defects in repositories doc --- .../asciidoc/repositories/Configuration.adoc | 4 ++-- .../asciidoc/repositories/Repositories.adoc | 17 +++++++++-------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/documentation/src/main/asciidoc/repositories/Configuration.adoc b/documentation/src/main/asciidoc/repositories/Configuration.adoc index 89f0f0242b39..9cefe9b16767 100644 --- a/documentation/src/main/asciidoc/repositories/Configuration.adoc +++ b/documentation/src/main/asciidoc/repositories/Configuration.adoc @@ -60,7 +60,7 @@ annotationProcessor 'org.hibernate.orm:hibernate-processor:7.0.0' === Excluding classes from processing -There's three ways to limit the annotation processor to certain classes: +There are three ways to limit the annotation processor to certain classes: 1. A given repository may be excluded from processing simply by specifying `@Repository(provider="acme")` where `"acme"` is any string other than the empty string or a string equal, ignoring case, to `"Hibernate"`. This is the preferred solution when there are multiple Jakarta Data Providers available. 2. A package or type may be excluded by annotating it with the link:{doc-javadoc-url}org/hibernate/annotations/processing/Exclude.html[`@Exclude`] annotation from `org.hibernate.annotations.processing`. @@ -126,7 +126,7 @@ It's always possible to instantiate a repository implementation directly. [source,java] ---- -Library library = new Library_(statelessSession); +Library library = new Library(statelessSession); ---- This is useful for testing, or for executing in an environment with no support for `jakarta.inject`. diff --git a/documentation/src/main/asciidoc/repositories/Repositories.adoc b/documentation/src/main/asciidoc/repositories/Repositories.adoc index 8c8f71bd39a8..7f5427eb4361 100644 --- a/documentation/src/main/asciidoc/repositories/Repositories.adoc +++ b/documentation/src/main/asciidoc/repositories/Repositories.adoc @@ -16,6 +16,7 @@ public class Book { @Basic(optional = false) String title; + @Basic(optional = false) LocalDate publicationDate; @Basic(optional = false) @@ -113,7 +114,7 @@ This really isn't as bad as it sounds; overuse of lazy fetching is associated wi A future release of Jakarta Data will feature repositories backed by Jakarta Persistence stateful persistence contexts, but this functionality did not make the cut for Jakarta Data 1.0. ==== -The second big difference is that instead of providing a generic interface like `EntityManager` that's capable of performing persistence operations for any entity class, Jakarta Data requires that each interaction with the database go via a user-written method specific to just one entity type. The method is marked with annotations allowing Hibernate to fill in the method implementation. +The second big difference is that instead of providing a generic interface like `EntityManager` that's capable of performing persistence operations for any entity class, Jakarta Data requires that each interaction with the database goes via a user-written method specific to just one entity type. The method is marked with annotations allowing Hibernate to fill in the method implementation. For example, whereas Jakarta Persistence defines the methods `find()` and `persist()` of `EntityManager`, in Jakarta Data the application programmer is required to write an interface like the following: @@ -168,7 +169,7 @@ The--perhaps surprising--answer is: it's completely up to you. === Organizing persistence operations Jakarta Data lets you freely assign persistence operations to repositories according to your own preference. -In particular, Jakarta Data does not require that a repository interface inherit a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity. +In particular, Jakarta Data does not require that a repository interface inherits a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity. You're permitted, for example, to have a single `Library` interface instead of `BookRepository`, `AuthorRepository`, and `PublisherRepository`. Thus, the whole programming model is much more flexible than older approaches such as Spring Data, which require a repository interface per entity class, or, at least, per so-called "aggregate". @@ -325,7 +326,7 @@ void add(Book... books); [NOTE] ==== A future release of Jakarta Data might expand the list of built-in lifecycle annotations. -In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove`, mapping to the fundamental operations of `EntityManager`. +In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove` mapping to the fundamental operations of `EntityManager`. ==== Repositories wouldn't be useful at all if this was all they could do. @@ -352,7 +353,7 @@ This is our first glimpse of the advantages of using Jakarta Data repositories w ==== If there is no `Book` with the given `isbn` in the database, the method throws `EmptyResultException`. -There's two ways around this if that's not what we want: +There are two ways around this if that's not what we want: - declare the method to return `Optional`, or - annotate the method `@jakarta.annotation.Nullable`. @@ -399,7 +400,7 @@ Furthermore, if the parameter type is a list or array of the entity field type, List books(String[] ibsn); ---- -Or course, an automatic query method might have multiple parameters. +Of course, an automatic query method might have multiple parameters. [source,java] ---- @@ -462,7 +463,7 @@ List booksByTitle(String pattern); You might notice that: - The `from` clause is not required in JDQL, and is inferred from the return type of the repository method. -- Since Jakarta Persistence 3.2, neither the `select` cause nor entity aliases (identification variables) are required in JPQL, finally standardizing a very old feature of HQL. +- Since Jakarta Persistence 3.2, neither the `select` clause nor entity aliases (identification variables) are required in JPQL, finally standardizing a very old feature of HQL. This allows simple queries to be written in a very compact form. @@ -493,7 +494,7 @@ The JPQL specification provides the `select new` construct for this. [source,java] ---- -@Query("select new AuthorBookRecord(b.isbn, a.ssn, a.name, b.title " + +@Query("select new AuthorBookRecord(b.isbn, a.ssn, a.name, b.title) " + "from Author a join books b " + "where title like :pattern") List summariesForTitle(@Pattern String pattern); @@ -509,7 +510,7 @@ Since this is quite verbose, Hibernate doesn't require the use of `select new`, @Query("select isbn, ssn, name, title " + "from Author join books " + "where title like :pattern") -List summariesForTitle(@Pattern String pattern); +List summariesForTitle(String pattern); ---- ==== From ba0fd59382e54dccfc46d93bbdc2a92d092ab6d2 Mon Sep 17 00:00:00 2001 From: "nathan.xu" Date: Sat, 23 Nov 2024 14:48:46 -0500 Subject: [PATCH 2/3] revert back a change --- documentation/src/main/asciidoc/repositories/Configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/main/asciidoc/repositories/Configuration.adoc b/documentation/src/main/asciidoc/repositories/Configuration.adoc index 9cefe9b16767..dcd68bd9ce70 100644 --- a/documentation/src/main/asciidoc/repositories/Configuration.adoc +++ b/documentation/src/main/asciidoc/repositories/Configuration.adoc @@ -126,7 +126,7 @@ It's always possible to instantiate a repository implementation directly. [source,java] ---- -Library library = new Library(statelessSession); +Library library = new Library_(statelessSession); ---- This is useful for testing, or for executing in an environment with no support for `jakarta.inject`. From 341d7433eb7fcc75e11b778788b310d3f9a24621 Mon Sep 17 00:00:00 2001 From: "nathan.xu" Date: Sun, 24 Nov 2024 08:58:36 -0500 Subject: [PATCH 3/3] revert back more changes --- .../src/main/asciidoc/repositories/Repositories.adoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/documentation/src/main/asciidoc/repositories/Repositories.adoc b/documentation/src/main/asciidoc/repositories/Repositories.adoc index 7f5427eb4361..c2920b15e579 100644 --- a/documentation/src/main/asciidoc/repositories/Repositories.adoc +++ b/documentation/src/main/asciidoc/repositories/Repositories.adoc @@ -16,7 +16,6 @@ public class Book { @Basic(optional = false) String title; - @Basic(optional = false) LocalDate publicationDate; @Basic(optional = false) @@ -169,7 +168,7 @@ The--perhaps surprising--answer is: it's completely up to you. === Organizing persistence operations Jakarta Data lets you freely assign persistence operations to repositories according to your own preference. -In particular, Jakarta Data does not require that a repository interface inherits a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity. +In particular, Jakarta Data does not require that a repository interface inherit a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity. You're permitted, for example, to have a single `Library` interface instead of `BookRepository`, `AuthorRepository`, and `PublisherRepository`. Thus, the whole programming model is much more flexible than older approaches such as Spring Data, which require a repository interface per entity class, or, at least, per so-called "aggregate". @@ -326,7 +325,7 @@ void add(Book... books); [NOTE] ==== A future release of Jakarta Data might expand the list of built-in lifecycle annotations. -In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove` mapping to the fundamental operations of `EntityManager`. +In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove`, mapping to the fundamental operations of `EntityManager`. ==== Repositories wouldn't be useful at all if this was all they could do.