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

HHH-12350 - User Guide documentation for @Any is too verbose

This commit is contained in:
Vlad Mihalcea 2018-07-03 15:41:20 +03:00
parent 5b40dfca26
commit 58613cba73
12 changed files with 141 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
View File

@ -2087,19 +2087,40 @@ include::{sourcedir}/basic/any/package-info.java[tags=mapping-column-any-meta-de
It is recommended to place the `@AnyMetaDef` mapping as a package metadata.
====
To see how the `@Any` annotation in action, consider the following example:
To see the `@Any` annotation in action, consider the next examples.
[[mapping-column-any-persistence-example]]
.`@Any` mapping usage
If we persist an `IntegerProperty` as well as a `StringProperty` entity, and associate
the `StringProperty` entity with a `PropertyHolder`,
Hibernate will generate the following SQL queries:
[[mapping-column-any-persist-example]]
.`@Any` mapping persist example
====
[source, JAVA, indent=0]
----
include::{sourcedir}/basic/any/AnyTest.java[tags=mapping-column-any-persistence-example]
include::{sourcedir}/basic/any/AnyTest.java[tags=mapping-column-any-persist-example]
----
[source, SQL, indent=0]
----
include::{extrasdir}/basic/mapping-column-any-persistence-example.sql[]
include::{extrasdir}/basic/mapping-column-any-persist-example.sql[]
----
====
When fetching the `PropertyHolder` entity and navigating its `property` association,
Hibernate will fetch the associated `StringProperty` entity like this:
[[mapping-column-any-query-example]]
.`@Any` mapping query example
====
[source, JAVA, indent=0]
----
include::{sourcedir}/basic/any/AnyTest.java[tags=mapping-column-any-query-example]
----
[source, SQL, indent=0]
----
include::{extrasdir}/basic/mapping-column-any-query-example.sql[]
----
====
@ -2110,6 +2131,7 @@ The `@Any` mapping is useful to emulate a `@ManyToOne` association when there ca
To emulate a `@OneToMany` association, the `@ManyToAny` annotation must be used.
In the following example, the `PropertyRepository` entity has a collection of `Property` entities.
The `repository_properties` link table holds the associations between `PropertyRepository` and `Property` entities.
[[mapping-column-many-to-any-example]]
@ -2126,20 +2148,40 @@ include::{extrasdir}/basic/mapping-column-many-to-any-example.sql[]
----
====
To see the `@ManyToAny` annotation in action, consider the next examples.
To see how the `@ManyToAny` annotation works, consider the following example:
If we persist an `IntegerProperty` as well as a `StringProperty` entity,
and associate both of them with a `PropertyRepository` parent entity,
Hibernate will generate the following SQL queries:
[[mapping-column-many-to-any-persistence-example]]
.`@Any` mapping usage
[[mapping-column-many-to-any-persist-example]]
.`@ManyToAny` mapping persist example
====
[source, JAVA, indent=0]
----
include::{sourcedir}/basic/any/ManyToAnyTest.java[tags=mapping-column-many-to-any-persistence-example]
include::{sourcedir}/basic/any/ManyToAnyTest.java[tags=mapping-column-many-to-any-persist-example]
----
[source, SQL, indent=0]
----
include::{extrasdir}/basic/mapping-column-many-to-any-persistence-example.sql[]
include::{extrasdir}/basic/mapping-column-many-to-any-persist-example.sql[]
----
====
When fetching the `PropertyRepository` entity and navigating its `properties` association,
Hibernate will fetch the associated `IntegerProperty` and `StringProperty` entities like this:
[[mapping-column-many-to-any-query-example]]
.`@ManyToAny` mapping query example
====
[source, JAVA, indent=0]
----
include::{sourcedir}/basic/any/ManyToAnyTest.java[tags=mapping-column-many-to-any-query-example]
----
[source, SQL, indent=0]
----
include::{extrasdir}/basic/mapping-column-many-to-any-query-example.sql[]
----
====

11
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-persist-example.sql Normal file
View File

@ -0,0 +1,11 @@
INSERT INTO integer_property
( "name", "value", id )
VALUES ( 'age', 23, 1 )
INSERT INTO string_property
( "name", "value", id )
VALUES ( 'name', 'John Doe', 1 )
INSERT INTO property_holder
( property_type, property_id, id )
VALUES ( 'S', 1, 1 )

13
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-persistence-example.sql → documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-query-example.sql
View File

@ -1,16 +1,3 @@
INSERT INTO integer_property
( "name", "value", id )
VALUES ( 'age', 23, 1 )
INSERT INTO string_property
( "name", "value", id )
VALUES ( 'name', 'John Doe', 1 )
INSERT INTO property_holder
( property_type, property_id, id )
VALUES ( 'S', 1, 1 )
SELECT ph.id AS id1_1_0_,
ph.property_type AS property2_1_0_,
ph.property_id AS property3_1_0_

15
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-many-to-any-persist-example.sql Normal file
View File

@ -0,0 +1,15 @@
INSERT INTO integer_property
( "name", "value", id )
VALUES ( 'age', 23, 1 )
INSERT INTO string_property
( "name", "value", id )
VALUES ( 'name', 'John Doe', 1 )
INSERT INTO property_repository ( id )
VALUES ( 1 )
INSERT INTO repository_properties
( repository_id , property_type , property_id )
VALUES
( 1 , 'I' , 1 )

36
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-many-to-any-persistence-example.sql
View File

@ -1,36 +0,0 @@
INSERT INTO integer_property
( "name", "value", id )
VALUES ( 'age', 23, 1 )
INSERT INTO string_property
( "name", "value", id )
VALUES ( 'name', 'John Doe', 1 )
INSERT INTO property_repository ( id )
VALUES ( 1 )
INSERT INTO repository_properties
( repository_id , property_type , property_id )
VALUES
( 1 , 'I' , 1 )
INSERT INTO repository_properties
( repository_id , property_type , property_id )
VALUES
( 1 , 'S' , 1 )
SELECT pr.id AS id1_1_0_
FROM property_repository pr
WHERE pr.id = 1
SELECT ip.id AS id1_0_0_ ,
integerpro0_."name" AS name2_0_0_ ,
integerpro0_."value" AS value3_0_0_
FROM integer_property integerpro0_
WHERE integerpro0_.id = 1
SELECT sp.id AS id1_3_0_ ,
sp."name" AS name2_3_0_ ,
sp."value" AS value3_3_0_
FROM string_property sp
WHERE sp.id = 1

15
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-many-to-any-query-example.sql Normal file
View File

@ -0,0 +1,15 @@
SELECT pr.id AS id1_1_0_
FROM property_repository pr
WHERE pr.id = 1
SELECT ip.id AS id1_0_0_ ,
ip."name" AS name2_0_0_ ,
ip."value" AS value3_0_0_
FROM integer_property ip
WHERE ip.id = 1
SELECT sp.id AS id1_3_0_ ,
sp."name" AS name2_3_0_ ,
sp."value" AS value3_3_0_
FROM string_property sp
WHERE sp.id = 1

11
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/AnyTest.java
View File

@ -36,33 +36,38 @@ public class AnyTest extends BaseCoreFunctionalTestCase {
@Test
public void test() {
//tag::mapping-column-any-persistence-example[]
doInHibernate( this::sessionFactory, session -> {
//tag::mapping-column-any-persist-example[]
IntegerProperty ageProperty = new IntegerProperty();
ageProperty.setId( 1L );
ageProperty.setName( "age" );
ageProperty.setValue( 23 );
session.persist( ageProperty );
StringProperty nameProperty = new StringProperty();
nameProperty.setId( 1L );
nameProperty.setName( "name" );
nameProperty.setValue( "John Doe" );
session.persist( ageProperty );
session.persist( nameProperty );
PropertyHolder namePropertyHolder = new PropertyHolder();
namePropertyHolder.setId( 1L );
namePropertyHolder.setProperty( nameProperty );
session.persist( namePropertyHolder );
//end::mapping-column-any-persist-example[]
} );
doInHibernate( this::sessionFactory, session -> {
//tag::mapping-column-any-query-example[]
PropertyHolder propertyHolder = session.get( PropertyHolder.class, 1L );
assertEquals("name", propertyHolder.getProperty().getName());
assertEquals("John Doe", propertyHolder.getProperty().getValue());
//end::mapping-column-any-query-example[]
} );
//end::mapping-column-any-persistence-example[]
}

23
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/IntegerProperty.java
View File

@ -26,6 +26,19 @@ public class IntegerProperty implements Property<Integer> {
@Column(name = "`value`")
private Integer value;
@Override
public String getName() {
return name;
}
@Override
public Integer getValue() {
return value;
}
//Getters and setters omitted for brevity
//end::mapping-column-any-property-example[]
public Long getId() {
return id;
}
@ -34,22 +47,14 @@ public class IntegerProperty implements Property<Integer> {
this.id = id;
}
@Override
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getValue() {
return value;
}
public void setValue(Integer value) {
this.value = value;
}
//tag::mapping-column-any-property-example[]
}
//end::mapping-column-any-property-example[]

13
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/ManyToAnyTest.java
View File

@ -37,36 +37,43 @@ public class ManyToAnyTest extends BaseCoreFunctionalTestCase {
@Test
public void test() {
//tag::mapping-column-many-to-any-persistence-example[]
doInHibernate( this::sessionFactory, session -> {
//tag::mapping-column-many-to-any-persist-example[]
IntegerProperty ageProperty = new IntegerProperty();
ageProperty.setId( 1L );
ageProperty.setName( "age" );
ageProperty.setValue( 23 );
session.persist( ageProperty );
StringProperty nameProperty = new StringProperty();
nameProperty.setId( 1L );
nameProperty.setName( "name" );
nameProperty.setValue( "John Doe" );
session.persist( ageProperty );
session.persist( nameProperty );
PropertyRepository propertyRepository = new PropertyRepository();
propertyRepository.setId( 1L );
propertyRepository.getProperties().add( ageProperty );
propertyRepository.getProperties().add( nameProperty );
session.persist( propertyRepository );
//end::mapping-column-many-to-any-persist-example[]
} );
doInHibernate( this::sessionFactory, session -> {
//tag::mapping-column-many-to-any-query-example[]
PropertyRepository propertyRepository = session.get( PropertyRepository.class, 1L );
assertEquals(2, propertyRepository.getProperties().size());
for(Property property : propertyRepository.getProperties()) {
assertNotNull( property.getValue() );
}
//end::mapping-column-many-to-any-query-example[]
} );
//end::mapping-column-many-to-any-persistence-example[]
}

2
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/PropertyHolder.java
View File

@ -29,7 +29,7 @@ public class PropertyHolder {
@JoinColumn( name = "property_id" )
private Property property;
//Getters and setters are omitted for brevity
//Getters and setters are omitted for brevity
//end::mapping-column-any-example[]
public Long getId() {

2
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/PropertyRepository.java
View File

@ -37,7 +37,7 @@ public class PropertyRepository {
)
private List<Property<?>> properties = new ArrayList<>( );
//Getters and setters are omitted for brevity
//Getters and setters are omitted for brevity
//end::mapping-column-many-to-any-example[]
public Long getId() {

23
documentation/src/test/java/org/hibernate/userguide/mapping/basic/any/StringProperty.java
View File

@ -26,6 +26,19 @@ public class StringProperty implements Property<String> {
@Column(name = "`value`")
private String value;
@Override
public String getName() {
return name;
}
@Override
public String getValue() {
return value;
}
//Getters and setters omitted for brevity
//end::mapping-column-any-property-example[]
public Long getId() {
return id;
}
@ -34,21 +47,13 @@ public class StringProperty implements Property<String> {
this.id = id;
}
@Override
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getValue() {
return value;
}
public void setValue(String value) {
this.value = value;
}
//tag::mapping-column-any-property-example[]
}
//end::mapping-column-any-property-example[]