Skip to content

clarifications in section on collection mapping #9244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 12, 2024
Merged

clarifications in section on collection mapping #9244

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions documentation/src/main/asciidoc/introduction/Advanced.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -728,20 +733,27 @@ 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
@OrderColumn // order of list is persistent
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
Expand All @@ -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"]
Expand All @@ -763,13 +777,17 @@ 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)
@MapKey(name = Book_.TITLE) // the key of the map is the title of the book
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
Expand Down
Loading