From 06ec85e8296b75049f2a5a8d2aea3ea4cc5c5183 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Mon, 4 Sep 2023 05:48:33 +0200 Subject: [PATCH] add four code examples of list index/map key to H6 doc --- .../main/asciidoc/introduction/Advanced.adoc | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index 988eba8164..cc5d2a0bf2 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -633,13 +633,38 @@ The first three options let us map the index of a `List` or key of a `Map` to a | Annotation | Purpose | JPA-standard | `@OrderColumn` | Specifies the column used to maintain the order of a list | ✔ +| `@ListIndexBase` | The column value for the first element of the list (zero by default) | ✖ | `@MapKeyColumn` | Specifies the column used to persist the keys of a map (used when the key is of basic type)| ✔ | `@MapKeyJoinColumn` | Specifies the column used to persist the keys of a map (used when the key is an entity) | ✔ |=== -For an unowned `@OneToMany` association, the column must also be mapped on the owning side, usually by an attribute of the target entity. +[source,java] +---- +@ManyToMany +@OrderColumn // order of list is persistent +List authors = new ArrayList<>(); +---- + +[source,java] +---- +@ElementCollection +@OrderColumn(name="tag_order") @ListIndexBase(1) // order column and base value +List tags; +---- + +[source,java] +---- +@ElementCollection +@CollectionTable(name = "author_bios", // table name + joinColumns = @JoinColumn(name = "book_ssn")) // column holding foreign key of owner +@Column(name="bio") // column holding map values +@MapKeyJoinColumn(name="author_ssn") // column holding map keys +Map 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: .Annotation for mapping an entity attribute to a map key @@ -650,6 +675,13 @@ 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 | ✔ |=== +[source,java] +---- +@OneToMany(mappedBy = Book_.PUBLISHER) +@MapKey(name = Book_.TITLE) // the key of the map is the title of the book +Map booksByTitle = new HashMap<>(); +---- + Now, let's introduce a little distinction: - an _ordered collection_ is one with an ordering maintained in the database, and