Skip to content

Commit 8631bb2

Browse files
committed
HHH-19965 remove misleading examples from the User Guide
@OrderColumn is like @MapKeyColumn. It's not supposed to be used on the unowned side of an association.
1 parent d100907 commit 8631bb2

File tree

2 files changed

+14
-49
lines changed

2 files changed

+14
-49
lines changed

documentation/src/main/asciidoc/introduction/Advanced.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -886,6 +886,17 @@ On the other hand, the following annotations specify how a collection should be
886886

887887
Under the covers, Hibernate uses a `TreeSet` or `TreeMap` to maintain the collection in sorted order.
888888

889+
[CAUTION]
890+
====
891+
The unowned (`mappedBy`) side of a bidirectional association is not responsible for specifying column mappings.
892+
So it's wrong in principle to use `@OrderColumn` or `@MapKeyColumn` on the unowned side of an association mapping.
893+
But for unowned collections, we may use `@OrderBy` or `@MapKey` instead.
894+
That is:
895+
896+
- You can use `@OrderColumn` or `@MapKeyColumn` with an `@ElementCollection`, owned `@ManyToMany`, or owned `@OneToMany`.
897+
- But use `@OrderBy` or `@MapKey` when it's an _unowned_ `@ManyToMany` or `@OneToMany`.
898+
====
899+
889900
[[any]]
890901
=== Any mappings
891902

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

Lines changed: 3 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -683,7 +683,9 @@ include::{extrasdir}/collections-unidirectional-ordered-list-order-column-select
683683
----
684684
====
685685

686-
With the `order_id` column in place, Hibernate can order the list in-memory after it's being fetched from the database.
686+
With the `order_id` column in place, Hibernate can order the list in-memory after it's fetched from the database.
687+
688+
The <<collection-list-indexbase-ex,`@ListIndexBase` annotation>> may be used to choose between 0-based and 1-based indexing on the database side.
687689

688690
[[collections-bidirectional-ordered-list]]
689691
===== Bidirectional ordered lists
@@ -701,54 +703,6 @@ include::{example-dir-collection}/BidirectionalOrderByListTest.java[tags=collect
701703

702704
Just like with the unidirectional `@OrderBy` list, the `number` column is used to order the statement on the SQL level.
703705

704-
When using the `@OrderColumn` annotation, the `order_id` column is going to be embedded in the child table:
705-
706-
[[collections-bidirectional-ordered-list-order-column-example]]
707-
.Bidirectional `@OrderColumn` list
708-
====
709-
[source,java]
710-
----
711-
include::{example-dir-collection}/BidirectionalOrderColumnListTest.java[tags=collections-bidirectional-ordered-list-order-column-example,indent=0]
712-
----
713-
714-
[source,sql]
715-
----
716-
include::{extrasdir}/collections-bidirectional-ordered-list-order-column-example.sql[]
717-
----
718-
====
719-
720-
When fetching the collection, Hibernate will use the fetched ordered columns to sort the elements according to the `@OrderColumn` mapping.
721-
722-
[[collections-customizing-ordered-list-ordinal]]
723-
===== Customizing ordered list ordinal
724-
725-
You can customize the ordinal of the underlying ordered list by using the https://docs.hibernate.org/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/ListIndexBase.html[`@ListIndexBase`] annotation.
726-
727-
[[collections-customizing-ordered-list-ordinal-mapping-example]]
728-
.`@ListIndexBase` mapping example
729-
====
730-
[source,java]
731-
----
732-
include::{example-dir-collection}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-mapping-example,indent=0]
733-
----
734-
====
735-
736-
When inserting two `Phone` records, Hibernate is going to start the List index from 100 this time.
737-
738-
[[collections-customizing-ordered-list-ordinal-persist-example]]
739-
.`@ListIndexBase` persist example
740-
====
741-
[source,java]
742-
----
743-
include::{example-dir-collection}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-persist-example,indent=0]
744-
----
745-
746-
[source,sql]
747-
----
748-
include::{extrasdir}/collections-customizing-ordered-list-ordinal-persist-example.sql[]
749-
----
750-
====
751-
752706
[[collections-customizing-ordered-by-sql-clause]]
753707
===== Customizing ORDER BY SQL clause
754708

0 commit comments

Comments
 (0)