add some additional material to doc

This commit is contained in:
Gavin 2023-05-14 12:36:17 +02:00 committed by Christian Beikov
parent a3682e14e7
commit 49af3f957e
4 changed files with 86 additions and 5 deletions

View File

@ -351,13 +351,14 @@ logger.hibernate.name = org.hibernate.SQL
logger.hibernate.level = debug logger.hibernate.level = debug
---- ----
You can make the logged SQL more readable by enabling one or both of the following settings: You can make the SQL logged to the console more readable by enabling formatting or highlighting.
.Setting for SQL logging to the console .Settings for SQL logging to the console
[cols=",2"] [cols=",2"]
|=== |===
| Configuration property name | Purpose | Configuration property name | Purpose
| `hibernate.show_sql` | If `true`, log SQL directly to the console
| `hibernate.format_sql` | If `true`, log SQL in a multiline, indented format | `hibernate.format_sql` | If `true`, log SQL in a multiline, indented format
| `hibernate.highlight_sql` | If `true`, log SQL with syntax highlighting via ANSI escape codes | `hibernate.highlight_sql` | If `true`, log SQL with syntax highlighting via ANSI escape codes
|=== |===
@ -391,7 +392,7 @@ Please refer to the Javadoc for these interfaces for more information about the
=== Nationalized character data in SQL Server === Nationalized character data in SQL Server
_By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` types. _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. But a Java string may contain any Unicode character. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` column types.
.Setting the use of nationalized character data .Setting the use of nationalized character data
[cols=",2"] [cols=",2"]
@ -405,4 +406,7 @@ _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode
// .Configuring SQL Server to use UTF-8 by default // .Configuring SQL Server to use UTF-8 by default
==== ====
Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`. Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
==== ====
On the other hand, if only _some_ columns store nationalized data, use the `@Nationalized` annotation to indicate fields of your entities which map these columns.

View File

@ -897,6 +897,26 @@ This is quite normal.
A one-to-one association is the usual way we implement subtyping in a fully-normalized relational model. A one-to-one association is the usual way we implement subtyping in a fully-normalized relational model.
==== ====
There are three annotations for mapping associations: `@ManyToOne`, `@OneToMany`, and `@ManyToMany`.
They share some common annotation members:
.Association-defining annotation members
[cols=",4,3"]
|===
| Member | Interpretation | Default value
| `cascade` | Persistence operations which should <<cascade,cascade>> to the associated entity (a list of ``CascadeType``s) | `{}`
| `fetch` | Whether the association is eagerly <<association-fetching,fetched>> or may be <<proxies-and-lazy-fetching,proxied>>
a|
- `LAZY` for `@OneToMany` and `@ManyToMany`
- `EAGER` for `@ManyToOne` 💀💀💀
| `targetEntity` | The associated entity class | Determined from the attribute type declaration
| `optional` | For `@ManyToOne` or `@OneToOne` associations, whether the association can be `null` | `true`
| `mappedBy` | For a bidirectional association, an attribute of the associated entity which maps the association | By default, the association is assumed unidirectional
|===
We'll explain the effect of these members as we consider the various types of association mapping.
Let's begin with the most common association multiplicity. Let's begin with the most common association multiplicity.
[[many-to-one]] [[many-to-one]]

View File

@ -651,4 +651,39 @@ String text = book.text.getSubString(1, textLength);
InputStream bytes = book.images.getBinaryStream(); InputStream bytes = book.images.getBinaryStream();
---- ----
Of course, the behavior here depends very much on the JDBC driver, and so we really can't promise that this is a sensible thing to do on your database. Of course, the behavior here depends very much on the JDBC driver, and so we really can't promise that this is a sensible thing to do on your database.
[[mapping-formulas]]
=== Mapping to formulas
Hibernate lets us map an attribute of an entity to a SQL formula involving columns of the mapped table.
Thus, the attribute is a sort of "derived" value.
.Annotations for mapping formulas
[cols=",5"]
|===
| Annotation | Purpose
| `@Formula` | Map an attribute to a SQL formula
| `@JoinFormula` | Map an association to a SQL formula
| `@DiscriminatorFormula` | Use a SQL formula as the discriminator in <<mapping-inheritance,single table inheritance>>.
|===
For example:
[source,java]
----
@Entity
class Order {
...
@Column(name = "sub_total", scale=2, precision=8)
BigDecimal subTotal;
@Column(name = "tax", scale=4, precision=4)
BigDecimal taxRate;
@Formula("sub_total * (1.0 + tax)")
BigDecimal totalWithTax;
...
}
----

View File

@ -394,6 +394,28 @@ List<Publisher> allpubs =
---- ----
==== ====
[TIP]
====
For "reference" data, that is, for data which is expected to always be found in the second-level cache, it's a good idea to _prime_ the cache at startup.
There's a really easy way to do this: just execute a query immediately after obtaining the
`EntityManager` or `SessionFactory`.
[source,java]
----
SessionFactory sf = 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();
});
----
====
Very occasionally, it's necessary or advantageous to control the cache explicitly, for example, to evict some data that we know to be stale. Very occasionally, it's necessary or advantageous to control the cache explicitly, for example, to evict some data that we know to be stale.
The `Cache` interface allows programmatic eviction of cached items. The `Cache` interface allows programmatic eviction of cached items.