Skip to content

Commit 664a9d5

Browse files
vladmihalceavladmihalcea
committed
HHH-11837 - MapsId and PrimaryKeyJoinColumn examples in the documentation should use OneToOne rather than ManyToOne
1 parent 3d2baa8 commit 664a9d5

File tree

6 files changed

+277
-138
lines changed

6 files changed

+277
-138
lines changed

‎documentation/src/main/asciidoc/userguide/chapters/domain/extras/id/CompositeIdAssociationPrimaryKeyJoinColumn.java

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎documentation/src/main/asciidoc/userguide/chapters/domain/extras/id/DerivedIdentifier.java

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎documentation/src/main/asciidoc/userguide/chapters/domain/identifiers.adoc

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[[identifiers]]
22
=== Identifiers
33
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/identifier
4+
:sourcedir-associations: ../../../../../test/java/org/hibernate/userguide/associations
45
:extrasdir: extras
56

67
Identifiers model the primary key of an entity. They are used to uniquely identify each specific entity.
@@ -482,12 +483,22 @@ JPA 2.0 added support for derived identifiers which allow an entity to borrow th
482483
====
483484
[source,java]
484485
----
485-
include::{extrasdir}/id/DerivedIdentifier.java[]
486+
include::{sourcedir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid, indent=0]
486487
----
487488
====
488489

489490
In the example above, the `PersonDetails` entity uses the `id` column for both the entity identifier and for the many-to-one association to the `Person` entity.
490491
The value of the `PersonDetails` entity identifier is "derived" from the identifier of its parent `Person` entity.
492+
493+
[[identifiers-derived-mapsid-persist-example]]
494+
.Derived identifier with `@MapsId` persist example
495+
====
496+
[source,java]
497+
----
498+
include::{sourcedir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid-persist-example, indent=0]
499+
----
500+
====
501+
491502
The `@MapsId` annotation can also reference columns from an `@EmbeddedId` identifier as well.
492503

493504
The previous example can also be mapped using `@PrimaryKeyJoinColumn`.
@@ -497,13 +508,14 @@ The previous example can also be mapped using `@PrimaryKeyJoinColumn`.
497508
====
498509
[source,java]
499510
----
500-
include::{extrasdir}/id/CompositeIdAssociationPrimaryKeyJoinColumn.java[]
511+
include::{sourcedir-associations}/OneToOnePrimaryKeyJoinColumnTest.java[tag=identifiers-derived-primarykeyjoincolumn, indent=0]
501512
----
502513
====
503514

504515
[NOTE]
505516
====
506-
Unlike `@MapsId`, the application developer is responsible for ensuring that the identifier and the many-to-one (or one-to-one) association are in sync.
517+
Unlike `@MapsId`, the application developer is responsible for ensuring that the identifier and the many-to-one (or one-to-one) association are in sync
518+
as you can see in the `PersonDetails#setPerson` method.
507519
====
508520

509521
[[identifiers-rowid]]

‎documentation/src/test/java/org/hibernate/userguide/associations/OneToOneMapsIdTest.java

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
/*
2+
* Hibernate, Relational Persistence for Idiomatic Java
3+
*
4+
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
5+
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
6+
*/
7+
package org.hibernate.userguide.associations;
8+
9+
import javax.persistence.Entity;
10+
import javax.persistence.Id;
11+
import javax.persistence.ManyToOne;
12+
import javax.persistence.MapsId;
13+
import javax.persistence.OneToOne;
14+
15+
import org.hibernate.annotations.NaturalId;
16+
import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
17+
18+
import org.junit.Test;
19+
20+
import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
21+
import static org.junit.Assert.assertEquals;
22+
23+
/**
24+
* @author Vlad Mihalcea
25+
*/
26+
public class OneToOneMapsIdTest extends BaseEntityManagerFunctionalTestCase {
27+
28+
@Override
29+
protected Class<?>[] getAnnotatedClasses() {
30+
return new Class<?>[] {
31+
Person.class,
32+
PersonDetails.class
33+
};
34+
}
35+
36+
@Test
37+
public void testLifecycle() {
38+
//tag::identifiers-derived-mapsid-persist-example[]
39+
doInJPA( this::entityManagerFactory, entityManager -> {
40+
Person person = new Person( "ABC-123" );
41+
person.setId( 1L );
42+
entityManager.persist( person );
43+
44+
PersonDetails personDetails = new PersonDetails();
45+
personDetails.setNickName( "John Doe" );
46+
personDetails.setPerson( person );
47+
48+
entityManager.persist( personDetails );
49+
} );
50+
51+
doInJPA( this::entityManagerFactory, entityManager -> {
52+
PersonDetails personDetails = entityManager.find( PersonDetails.class, 1L );
53+
54+
assertEquals("John Doe", personDetails.getNickName());
55+
} );
56+
//end::identifiers-derived-mapsid-persist-example[]
57+
}
58+
59+
//tag::identifiers-derived-mapsid[]
60+
@Entity(name = "Person")
61+
public static class Person {
62+
63+
@Id
64+
private Long id;
65+
66+
@NaturalId
67+
private String registrationNumber;
68+
69+
public Person() {}
70+
71+
public Person(String registrationNumber) {
72+
this.registrationNumber = registrationNumber;
73+
}
74+
75+
//Getters and setters are omitted for brevity
76+
//end::identifiers-derived-mapsid[]
77+
78+
public Long getId() {
79+
return id;
80+
}
81+
82+
public void setId(Long id) {
83+
this.id = id;
84+
}
85+
86+
public String getRegistrationNumber() {
87+
return registrationNumber;
88+
}
89+
//tag::identifiers-derived-mapsid[]
90+
}
91+
92+
@Entity(name = "PersonDetails")
93+
public static class PersonDetails {
94+
95+
@Id
96+
private Long id;
97+
98+
private String nickName;
99+
100+
@OneToOne
101+
@MapsId
102+
private Person person;
103+
104+
//Getters and setters are omitted for brevity
105+
//end::identifiers-derived-mapsid[]
106+
107+
public String getNickName() {
108+
return nickName;
109+
}
110+
111+
public void setNickName(String nickName) {
112+
this.nickName = nickName;
113+
}
114+
115+
public Person getPerson() {
116+
return person;
117+
}
118+
119+
public void setPerson(Person person) {
120+
this.person = person;
121+
}
122+
//tag::identifiers-derived-mapsid[]
123+
}
124+
//end::identifiers-derived-mapsid[]
125+
126+
}

‎documentation/src/test/java/org/hibernate/userguide/associations/OneToOnePrimaryKeyJoinColumnTest.java

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
/*
2+
* Hibernate, Relational Persistence for Idiomatic Java
3+
*
4+
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
5+
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
6+
*/
7+
package org.hibernate.userguide.associations;
8+
9+
import javax.persistence.Entity;
10+
import javax.persistence.Id;
11+
import javax.persistence.MapsId;
12+
import javax.persistence.OneToOne;
13+
import javax.persistence.PrimaryKeyJoinColumn;
14+
15+
import org.hibernate.annotations.NaturalId;
16+
import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
17+
18+
import org.junit.Test;
19+
20+
import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
21+
import static org.junit.Assert.assertEquals;
22+
23+
/**
24+
* @author Vlad Mihalcea
25+
*/
26+
public class OneToOnePrimaryKeyJoinColumnTest extends BaseEntityManagerFunctionalTestCase {
27+
28+
@Override
29+
protected Class<?>[] getAnnotatedClasses() {
30+
return new Class<?>[] {
31+
Person.class,
32+
PersonDetails.class
33+
};
34+
}
35+
36+
@Test
37+
public void testLifecycle() {
38+
//tag::identifiers-derived-primarykeyjoincolumn-persist-example[]
39+
doInJPA( this::entityManagerFactory, entityManager -> {
40+
Person person = new Person( "ABC-123" );
41+
person.setId( 1L );
42+
entityManager.persist( person );
43+
44+
PersonDetails personDetails = new PersonDetails();
45+
personDetails.setNickName( "John Doe" );
46+
personDetails.setPerson( person );
47+
48+
entityManager.persist( personDetails );
49+
} );
50+
51+
doInJPA( this::entityManagerFactory, entityManager -> {
52+
PersonDetails personDetails = entityManager.find( PersonDetails.class, 1L );
53+
54+
assertEquals("John Doe", personDetails.getNickName());
55+
} );
56+
//end::identifiers-derived-primarykeyjoincolumn-persist-example[]
57+
}
58+
59+
//tag::identifiers-derived-primarykeyjoincolumn[]
60+
@Entity(name = "Person")
61+
public static class Person {
62+
63+
@Id
64+
private Long id;
65+
66+
@NaturalId
67+
private String registrationNumber;
68+
69+
public Person() {}
70+
71+
public Person(String registrationNumber) {
72+
this.registrationNumber = registrationNumber;
73+
}
74+
75+
//Getters and setters are omitted for brevity
76+
//end::identifiers-derived-primarykeyjoincolumn[]
77+
78+
public Long getId() {
79+
return id;
80+
}
81+
82+
public void setId(Long id) {
83+
this.id = id;
84+
}
85+
86+
public String getRegistrationNumber() {
87+
return registrationNumber;
88+
}
89+
//tag::identifiers-derived-primarykeyjoincolumn[]
90+
}
91+
92+
@Entity(name = "PersonDetails")
93+
public static class PersonDetails {
94+
95+
@Id
96+
private Long id;
97+
98+
private String nickName;
99+
100+
@OneToOne
101+
@PrimaryKeyJoinColumn
102+
private Person person;
103+
104+
public void setPerson(Person person) {
105+
this.person = person;
106+
this.id = person.getId();
107+
}
108+
109+
//Other getters and setters are omitted for brevity
110+
//end::identifiers-derived-primarykeyjoincolumn[]
111+
112+
public Long getId() {
113+
return id;
114+
}
115+
116+
public void setId(Long id) {
117+
this.id = id;
118+
}
119+
120+
public String getNickName() {
121+
return nickName;
122+
}
123+
124+
public void setNickName(String nickName) {
125+
this.nickName = nickName;
126+
}
127+
128+
public Person getPerson() {
129+
return person;
130+
}
131+
132+
//tag::identifiers-derived-primarykeyjoincolumn[]
133+
}
134+
//end::identifiers-derived-primarykeyjoincolumn[]
135+
136+
}

0 commit comments

Comments
 (0)