quit using abbreviations
don't know quite what came over me...
This commit is contained in:
Gavin
parent
6078e4792d
commit
e4539d9b44
|
|
@ -173,7 +173,7 @@ We may obtain an `EntityManagerFactory` by calling `Persistence.createEntityMana
|
|||
|
||||
[source,java]
|
||||
----
|
||||
EntityManagerFactory emf =
|
||||
EntityManagerFactory entityManagerFactory =
|
||||
Persistence.createEntityManagerFactory("org.hibernate.example");
|
||||
----
|
||||
|
||||
|
|
@ -181,7 +181,7 @@ If necessary, we may override configuration properties specified in `persistence
|
|||
|
||||
[source,java]
|
||||
----
|
||||
EntityManagerFactory emf =
|
||||
EntityManagerFactory entityManagerFactory =
|
||||
Persistence.createEntityManagerFactory("org.hibernate.example",
|
||||
Map.of(AvailableSettings.JAKARTA_JDBC_PASSWORD, password));
|
||||
----
|
||||
|
|
@ -193,7 +193,7 @@ Alternatively, the venerable class `org.hibernate.cfg.Configuration` allows an i
|
|||
|
||||
[source,java]
|
||||
----
|
||||
SessionFactory sf = new Configuration()
|
||||
SessionFactory sessionFactory = new Configuration()
|
||||
.addAnnotatedClass(Book.class)
|
||||
.addAnnotatedClass(Author.class)
|
||||
.setProperty(AvailableSettings.JAKARTA_JDBC_URL, "jdbc:postgresql://localhost/example")
|
||||
|
|
@ -228,7 +228,6 @@ Of course, we're not going to cover every useful configuration setting in this c
|
|||
Instead, we'll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning.
|
||||
|
||||
[TIP]
|
||||
// .Ya ain't gunna need 'em
|
||||
====
|
||||
Hibernate has many—too many—switches and toggles.
|
||||
Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate.
|
||||
|
|
|
|||
|
|
@ -91,28 +91,28 @@ It's quite unsurprising that we may use this object to create an `EntityManager`
|
|||
|
||||
[source,java]
|
||||
----
|
||||
EntityManager em = emf.createEntityManager();
|
||||
EntityManager entityManager = entityManagerFactory.createEntityManager();
|
||||
----
|
||||
|
||||
When we're finished with the `EntityManager`, we should explicitly clean it up:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
em.close();
|
||||
entityManager.close();
|
||||
----
|
||||
|
||||
On the other hand, if we're starting from a `SessionFactory`, as described in <<configuration-api>>, we may use:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
Session s = sf.openSession();
|
||||
Session session = sessionFactory.openSession();
|
||||
----
|
||||
|
||||
But we still need to clean up:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
em.close();
|
||||
entityManager.close();
|
||||
----
|
||||
|
||||
.Injecting the `EntityManager`
|
||||
|
|
@ -122,14 +122,14 @@ For example, in Java (or Jakarta) EE you would write:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
@PersistenceContext EntityManager em;
|
||||
@PersistenceContext EntityManager entityManager;
|
||||
----
|
||||
|
||||
In Quarkus, injection is handled by CDI:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Inject EntityManager em;
|
||||
@Inject EntityManager entityManager;
|
||||
----
|
||||
****
|
||||
|
||||
|
|
@ -143,8 +143,8 @@ The idiom we recommend is the following:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
EntityManager em = emf.createEntityManager();
|
||||
EntityTransaction tx = em.getTransaction();
|
||||
EntityManager entityManager = entityManagerFactory.createEntityManager();
|
||||
EntityTransaction tx = entityManager.getTransaction();
|
||||
try {
|
||||
tx.begin();
|
||||
//do some work
|
||||
|
|
@ -156,17 +156,17 @@ catch (Exception e) {
|
|||
throw e;
|
||||
}
|
||||
finally {
|
||||
em.close();
|
||||
entityManager.close();
|
||||
}
|
||||
----
|
||||
|
||||
Using Hibernate's native APIs we might write something really similar,
|
||||
// [source,java]
|
||||
// ----
|
||||
// Session s = sf.openSession();
|
||||
// Session session = sessionFactory.openSession();
|
||||
// Transaction tx = null;
|
||||
// try {
|
||||
// tx = s.beginTransaction();
|
||||
// tx = session.beginTransaction();
|
||||
// //do some work
|
||||
// ...
|
||||
// tx.commit();
|
||||
|
|
@ -176,14 +176,14 @@ Using Hibernate's native APIs we might write something really similar,
|
|||
// throw e;
|
||||
// }
|
||||
// finally {
|
||||
// s.close();
|
||||
// session.close();
|
||||
// }
|
||||
// ----
|
||||
but since this sort of code is extremely tedious, we have a much nicer option:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
sf.inTransaction(s -> {
|
||||
sessionFactory.inTransaction(session -> {
|
||||
//do the work
|
||||
...
|
||||
});
|
||||
|
|
@ -347,14 +347,14 @@ For example, to disable flushes that occur before query execution, call:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
em.setFlushMode(FlushModeType.COMMIT);
|
||||
entityManager.setFlushMode(FlushModeType.COMMIT);
|
||||
----
|
||||
|
||||
Hibernate allows greater control over the flush mode than JPA:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
s.setHibernateFlushMode(FlushMode.MANUAL);
|
||||
session.setHibernateFlushMode(FlushMode.MANUAL);
|
||||
----
|
||||
|
||||
Since flushing is a somewhat expensive operation (the session must dirty-check every entity in the persistence context), setting the flush mode to `COMMIT` can occasionally be a useful optimization.
|
||||
|
|
@ -420,9 +420,9 @@ So for the `Session` API we would write:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> matchingBooks =
|
||||
s.createSelectionQuery("from Book where title like :titleSearchPattern", Book.class)
|
||||
.setParameter("titleSearchPattern", titleSearchPattern)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Book where title like :titleSearchPattern", Book.class)
|
||||
.setParameter("titleSearchPattern", titleSearchPattern)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
Or, if we're sticking to the JPA-standard APIs:
|
||||
|
|
@ -430,9 +430,9 @@ Or, if we're sticking to the JPA-standard APIs:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> matchingBooks =
|
||||
s.createQuery("from Book where title like :titleSearchPattern", Book.class)
|
||||
.setParameter("titleSearchPattern", titleSearchPattern)
|
||||
.getResultList();
|
||||
session.createQuery("from Book where title like :titleSearchPattern", Book.class)
|
||||
.setParameter("titleSearchPattern", titleSearchPattern)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
The only difference between `createSelectionQuery()` and `createQuery()` is that `createSelectionQuery()` throw an exception if passed a Mutation.
|
||||
|
|
@ -444,9 +444,9 @@ These are called _ordinal parameters_.
|
|||
[source,java]
|
||||
----
|
||||
List<Book> matchingBooks =
|
||||
s.createSelectionQuery("from Book where title like ?1", Book.class)
|
||||
.setParameter(1, titleSearchPattern)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Book where title like ?1", Book.class)
|
||||
.setParameter(1, titleSearchPattern)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
When a query has multiple parameters, named parameters tend to be easier to read, even if slightly more verbose.
|
||||
|
|
@ -463,9 +463,9 @@ If we're expecting a query to return a single result, we can use `getSingleResul
|
|||
[source,java]
|
||||
----
|
||||
Book book =
|
||||
s.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.getSingleResult();
|
||||
session.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.getSingleResult();
|
||||
----
|
||||
|
||||
Or, if we're expecting it to return at most one result, we can use `getSingleResultOrNull()`.
|
||||
|
|
@ -473,9 +473,9 @@ Or, if we're expecting it to return at most one result, we can use `getSingleRes
|
|||
[source,java]
|
||||
----
|
||||
Book bookOrNull =
|
||||
s.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.getSingleResultOrNull();
|
||||
session.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.getSingleResultOrNull();
|
||||
----
|
||||
|
||||
The difference, of course, is that `getSingleResult()` throws an exception if there is no matching row in the database, whereas `getSingleResultOrNull()` just returns `null`.
|
||||
|
|
@ -488,10 +488,10 @@ To disable this behavior, set the flush mode to `COMMIT` or `MANUAL`:
|
|||
[source,java]
|
||||
----
|
||||
Book bookOrNull =
|
||||
s.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.setHibernateFlushMode(MANUAL)
|
||||
.getSingleResult();
|
||||
session.createSelectionQuery("from Book where isbn = ?1", Book.class)
|
||||
.setParameter(1, isbn)
|
||||
.setHibernateFlushMode(MANUAL)
|
||||
.getSingleResult();
|
||||
----
|
||||
|
||||
[CAUTION]
|
||||
|
|
@ -520,14 +520,14 @@ Using the JPA-standard APIs, this would be a `CriteriaBuilder`, and we get it fr
|
|||
|
||||
[source,java]
|
||||
----
|
||||
CriteriaBuilder cb = emf.getCriteriaBuilder();
|
||||
CriteriaBuilder cb = entityManagerFactory.getCriteriaBuilder();
|
||||
----
|
||||
|
||||
But if we have a `SessionFactory`, we get something much better, a `HibernateCriteriaBuilder`:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
HibernateCriteriaBuilder cb = sf.getCriteriaBuilder();
|
||||
HibernateCriteriaBuilder cb = sessionFactory.getCriteriaBuilder();
|
||||
----
|
||||
|
||||
The `HibernateCriteriaBuilder` extends `CriteriaBuilder` and adds many operations that JPQL doesn't have.
|
||||
|
|
@ -540,14 +540,14 @@ Either:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
HibernateCriteriaBuilder cb = emf.unwrap(SessionFactory.class).getCriteriaBuilder();
|
||||
HibernateCriteriaBuilder cb = entityManagerFactory.unwrap(SessionFactory.class).getCriteriaBuilder();
|
||||
----
|
||||
|
||||
Or simply:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
HibernateCriteriaBuilder cb = (HibernateCriteriaBuilder) emf.getCriteriaBuilder();
|
||||
HibernateCriteriaBuilder cb = (HibernateCriteriaBuilder) entityManagerFactory.getCriteriaBuilder();
|
||||
----
|
||||
====
|
||||
|
||||
|
|
@ -600,8 +600,8 @@ For example:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> matchingBooks =
|
||||
s.createSelectionQuery(query)
|
||||
.getResultList();
|
||||
session.createSelectionQuery(query)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
When all else fails, and sometimes even before that, we're left with the option of writing a query in SQL.
|
||||
|
|
@ -627,9 +627,9 @@ For the most simple cases, Hibernate can infer the shape of the result set:
|
|||
|
||||
[source, java]
|
||||
----
|
||||
Book book = s.createNativeQuery("select * from Books where isbn = ?1", Book.class).getSingleResult();
|
||||
Book book = session.createNativeQuery("select * from Books where isbn = ?1", Book.class).getSingleResult();
|
||||
|
||||
String title = s.createNativeQuery("select title from Books where isbn = ?1", String.class).getSingleResult();
|
||||
String title = session.createNativeQuery("select title from Books where isbn = ?1", String.class).getSingleResult();
|
||||
----
|
||||
|
||||
However, in general, there isn't enough information in the JDBC `ResultSetMetaData` to infer the mapping of columns to entity objects.
|
||||
|
|
@ -643,8 +643,8 @@ So if there are any unflushed changes to ``Book``s, this query might return stal
|
|||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
s.createNativeQuery("select * from Books")
|
||||
.getResultList()
|
||||
session.createNativeQuery("select * from Books")
|
||||
.getResultList()
|
||||
----
|
||||
|
||||
There's two ways to ensure the persistence context is flushed before this query is executed.
|
||||
|
|
@ -654,9 +654,9 @@ Either, we could simply force a flush by set the flush mode to `ALWAYS`:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
s.createNativeQuery("select * from Books")
|
||||
.setHibernateFlushMode(ALWAYS)
|
||||
.getResultList()
|
||||
session.createNativeQuery("select * from Books")
|
||||
.setHibernateFlushMode(ALWAYS)
|
||||
.getResultList()
|
||||
----
|
||||
|
||||
Or, alternative, we could tell Hibernate which modified state affects the results of the query:
|
||||
|
|
@ -664,9 +664,9 @@ Or, alternative, we could tell Hibernate which modified state affects the result
|
|||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
s.createNativeQuery("select * from Books")
|
||||
.addSynchronizedEntityClass(Book.class)
|
||||
.getResultList()
|
||||
session.createNativeQuery("select * from Books")
|
||||
.addSynchronizedEntityClass(Book.class)
|
||||
.getResultList()
|
||||
----
|
||||
|
||||
|
||||
|
|
@ -694,10 +694,10 @@ For example, this:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
s.createSelectionQuery("from Book where title like ?1")
|
||||
.setParameter(1, titlePatterm)
|
||||
.setMaxResults(10)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Book where title like ?1")
|
||||
.setParameter(1, titlePatterm)
|
||||
.setMaxResults(10)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
is simpler than:
|
||||
|
|
@ -705,10 +705,10 @@ is simpler than:
|
|||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
s.createSelectionQuery("from Book where title like ?1 fetch first ?2 rows only")
|
||||
.setParameter(1, titlePatterm)
|
||||
.setParameter(2, 10)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Book where title like ?1 fetch first ?2 rows only")
|
||||
.setParameter(1, titlePatterm)
|
||||
.setParameter(2, 10)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
[[named-queries]]
|
||||
|
|
@ -744,9 +744,10 @@ We execute our named query as follows:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
em.createNamedQuery("10BooksByTitle")
|
||||
.setParameter("titlePattern", titlePattern)
|
||||
.getResultList()
|
||||
List<Book> books =
|
||||
entityManager.createNamedQuery("10BooksByTitle")
|
||||
.setParameter("titlePattern", titlePattern)
|
||||
.getResultList()
|
||||
----
|
||||
|
||||
Note that the code which executes the named query is not aware of whether the query was written in HQL or in native SQL, making it slightly easier to change and optimize the query later.
|
||||
|
|
|
|||
|
|
@ -637,7 +637,7 @@ We can get one from the `Session`:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
LobHelper helper = s.getLobHelper();
|
||||
LobHelper helper = session.getLobHelper();
|
||||
book.text = helper.createClob(text);
|
||||
book.coverArt = helper.createBlob(image);
|
||||
----
|
||||
|
|
@ -646,7 +646,7 @@ In principle, the `Blob` and `Clob` objects provide efficient ways to read or st
|
|||
|
||||
[source,java]
|
||||
----
|
||||
Book book = s.find(Book.class, bookId);
|
||||
Book book = session.find(Book.class, bookId);
|
||||
String text = book.text.getSubString(1, textLength);
|
||||
InputStream bytes = book.images.getBinaryStream();
|
||||
----
|
||||
|
|
|
|||
|
|
@ -308,7 +308,7 @@ This cache is utilized when the entity is retrieved using one of the operations
|
|||
|
||||
[source,java]
|
||||
----
|
||||
Book book = s.byNaturalId().using("isbn", isbn, "printing", printing).load();
|
||||
Book book = session.byNaturalId().using("isbn", isbn, "printing", printing).load();
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
|
|
@ -403,9 +403,9 @@ To cache the results of a query, call `SelectionQuery.setCacheable(true)`:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
s.createQuery("from Product where discontinued = false")
|
||||
.setCacheable(true)
|
||||
.getResultList();
|
||||
session.createQuery("from Product where discontinued = false")
|
||||
.setCacheable(true)
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
By default, the query result set is stored in a cache region named `default-query-results-region`.
|
||||
|
|
@ -413,10 +413,10 @@ Since different queries should have different caching policies, it's common to e
|
|||
|
||||
[source,java]
|
||||
----
|
||||
s.createQuery("from Product where discontinued = false")
|
||||
.setCacheable(true)
|
||||
.setCacheRegion("ProductCatalog")
|
||||
.getResultList();
|
||||
session.createQuery("from Product where discontinued = false")
|
||||
.setCacheable(true)
|
||||
.setCacheRegion("ProductCatalog")
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
A result set is cached together with a _logical timestamp_.
|
||||
|
|
@ -447,15 +447,15 @@ At worst, interaction with the cache may be controlled by specifying of an expli
|
|||
|
||||
[source,java]
|
||||
----
|
||||
s.setCacheMode(CacheMode.IGNORE);
|
||||
session.setCacheMode(CacheMode.IGNORE);
|
||||
----
|
||||
|
||||
Or, using JPA-standard APIs:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
em.setCacheRetrieveMode(CacheRetrieveMode.BYPASS);
|
||||
em.setCacheStoreMode(CacheStoreMode.BYPASS);
|
||||
entityManager.setCacheRetrieveMode(CacheRetrieveMode.BYPASS);
|
||||
entityManager.setCacheStoreMode(CacheStoreMode.BYPASS);
|
||||
----
|
||||
|
||||
The JPA-defined cache modes are:
|
||||
|
|
@ -500,11 +500,11 @@ In JPA we would use this idiom:
|
|||
|
||||
[source,java]
|
||||
----
|
||||
em.setCacheStoreMode(CacheStoreMode.BYPASS);
|
||||
entityManager.setCacheStoreMode(CacheStoreMode.BYPASS);
|
||||
List<Publisher> allpubs =
|
||||
em.createQuery("from Publisher", Publisher.class)
|
||||
.getResultList();
|
||||
em.setCacheStoreMode(CacheStoreMode.USE);
|
||||
entityManager.createQuery("from Publisher", Publisher.class)
|
||||
.getResultList();
|
||||
entityManager.setCacheStoreMode(CacheStoreMode.USE);
|
||||
----
|
||||
|
||||
But Hibernate has a better way:
|
||||
|
|
@ -512,9 +512,9 @@ But Hibernate has a better way:
|
|||
[source,java]
|
||||
----
|
||||
List<Publisher> allpubs =
|
||||
s.createSelectionQuery("from Publisher", Publisher.class)
|
||||
.setCacheStoreMode(CacheStoreMode.BYPASS)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Publisher", Publisher.class)
|
||||
.setCacheStoreMode(CacheStoreMode.BYPASS)
|
||||
.getResultList();
|
||||
----
|
||||
====
|
||||
|
||||
|
|
@ -526,15 +526,15 @@ There's a really easy way to do this: just execute a query immediately after obt
|
|||
|
||||
[source,java]
|
||||
----
|
||||
SessionFactory sf = setupHibernate(new Configuration()).buildSessionFactory();
|
||||
SessionFactory sessionFactory = setupHibernate(new Configuration()).buildSessionFactory();
|
||||
// prime the second-level cache
|
||||
sf.inSession(s -> {
|
||||
s.createSelectionQuery("from Countries"))
|
||||
.setReadOnly(true)
|
||||
.getResultList();
|
||||
s.createSelectionQuery("from Product where discontinued = false"))
|
||||
.setReadOnly(true)
|
||||
.getResultList();
|
||||
sessionFactory.inSession(session -> {
|
||||
session.createSelectionQuery("from Countries"))
|
||||
.setReadOnly(true)
|
||||
.getResultList();
|
||||
session.createSelectionQuery("from Product where discontinued = false"))
|
||||
.setReadOnly(true)
|
||||
.getResultList();
|
||||
});
|
||||
|
||||
----
|
||||
|
|
@ -545,7 +545,7 @@ The `Cache` interface allows programmatic eviction of cached items.
|
|||
|
||||
[source,java]
|
||||
----
|
||||
sf.getCache().evictEntityData(Book.class, bookId);
|
||||
sessionFactory.getCache().evictEntityData(Book.class, bookId);
|
||||
----
|
||||
|
||||
[CAUTION]
|
||||
|
|
|
|||
Loading…
Reference in New Issue