From 49af3f957e0323eb910c5ec3cad0bd13ea4b0088 Mon Sep 17 00:00:00 2001 From: Gavin Date: Sun, 14 May 2023 12:36:17 +0200 Subject: [PATCH] add some additional material to doc --- .../asciidoc/introduction/Configuration.adoc | 12 ++++-- .../main/asciidoc/introduction/Entities.adoc | 20 ++++++++++ .../main/asciidoc/introduction/Mapping.adoc | 37 ++++++++++++++++++- .../main/asciidoc/introduction/Tuning.adoc | 22 +++++++++++ 4 files changed, 86 insertions(+), 5 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index b735dcff3d..6d1c4af4bc 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -351,13 +351,14 @@ logger.hibernate.name = org.hibernate.SQL 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"] |=== | 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.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 -_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 [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 ==== Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`. -==== \ No newline at end of file +==== + +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. + diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index 97c886270f..b2be697b6f 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/documentation/src/main/asciidoc/introduction/Entities.adoc @@ -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. ==== +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 <> to the associated entity (a list of ``CascadeType``s) | `{}` +| `fetch` | Whether the association is eagerly <> or may be <> +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. [[many-to-one]] diff --git a/documentation/src/main/asciidoc/introduction/Mapping.adoc b/documentation/src/main/asciidoc/introduction/Mapping.adoc index 9f0a753629..dda7e63899 100644 --- a/documentation/src/main/asciidoc/introduction/Mapping.adoc +++ b/documentation/src/main/asciidoc/introduction/Mapping.adoc @@ -651,4 +651,39 @@ String text = book.text.getSubString(1, textLength); 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. \ No newline at end of file +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 <>. +|=== + +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; + ... +} +---- \ No newline at end of file diff --git a/documentation/src/main/asciidoc/introduction/Tuning.adoc b/documentation/src/main/asciidoc/introduction/Tuning.adoc index b151f5c4f3..66b019e06c 100644 --- a/documentation/src/main/asciidoc/introduction/Tuning.adoc +++ b/documentation/src/main/asciidoc/introduction/Tuning.adoc @@ -394,6 +394,28 @@ List 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. The `Cache` interface allows programmatic eviction of cached items.