Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clarifications in section on collection mapping 

(to agree with blog)
This commit is contained in:
Gavin King 2024-11-12 15:06:42 +01:00
parent 2a9f4c41a8
commit f3482078c1
1 changed files with 22 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
documentation/src/main/asciidoc/introduction/Advanced.adoc
View File

@ -713,7 +713,12 @@ But if you feel like you _really_ need a collection with a fancier structure tha
TIP: For more detail about the use of these annotations, please refer to https://in.relation.to/2024/11/12/-what-collection/[this post on the Hibernate blog].
The first three options let us map the index of a `List` or key of a `Map` to a column, and are usually used with `@ElementCollection`, or on the owning side of an association:
The following options let us map the index of a `List` or key of a `Map` to a column, and are used with:
- `@ElementCollection`, or
- on the owning side of an association.
They should not be used on the unowned (that is, `mappedBy`) side of an association.
.Annotations for mapping lists and maps
[%breakable,cols="22,~,^13"]
@ -728,6 +733,8 @@ The first three options let us map the index of a `List` or key of a `Map` to a
(used when the key is an entity) | ✔
|===
The name of the `@OrderColumn` or `@MapKeyColumn` may be defaulted, for example:
[source,java]
----
@ManyToMany
@ -735,13 +742,18 @@ The first three options let us map the index of a `List` or key of a `Map` to a
List<Author> authors = new ArrayList<>();
----
But it's usually better to specify the column name explicitly:
[source,java]
----
@ElementCollection
@OrderColumn(name="tag_order") @ListIndexBase(1) // order column and base value
@OrderColumn(name="tag_order")
@ListIndexBase(1) // order column and base value
List<String> tags;
----
Such mappings can get pretty complicated:
[source,java]
----
@ElementCollection
@ -752,8 +764,10 @@ List<String> tags;
Map<Author,String> biographies;
----
For a `Map` representing an unowned `@OneToMany` association, the column must also be mapped on the owning side, usually by an attribute of the target entity.
In this case we usually use a different annotation:
As you can imagine, we think you should use such mappings very sparingly, if at all.
For a `Map` representing an unowned `@OneToMany` association, the column holding the key of the map must also be mapped on the owning side, usually by an attribute of the target entity.
In this case we use a different annotation:
.Annotation for mapping an entity attribute to a map key
[%breakable,cols="22,~,^13"]
@ -763,6 +777,8 @@ In this case we usually use a different annotation:
| `@MapKey` | Specifies an attribute of the target entity which acts as the key of the map | &#10004;
|===
Note that `@MapKey` specifies a field or property name, not a column name.
[source,java]
----
@OneToMany(mappedBy = Book_.PUBLISHER)
@ -770,6 +786,8 @@ In this case we usually use a different annotation:
Map<String,Book> booksByTitle = new HashMap<>();
----
In fact, `@MapKey` may also be used for owned collections.
Now, let's introduce a little distinction:
- an _ordered collection_ is one with an ordering maintained in the database, and