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

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

@@ -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]]
+If we persist an `IntegerProperty` as well as a `StringProperty` entity, and associate
-.`@Any` mapping usage
+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]]
+[[mapping-column-many-to-any-persist-example]]
-.`@Any` mapping usage
+.`@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[]
 ----
 ====
 

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-persist-example.sql

@@ -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 )

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-persistence-example.sql

@@ -1,25 +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_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_
-FROM   property_holder ph
-WHERE  ph.id = 1
-
-
-SELECT sp.id AS id1_2_0_,
-       sp."name" AS name2_2_0_,
-       sp."value" AS value3_2_0_
-FROM   string_property sp
-WHERE  sp.id = 1

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-column-any-query-example.sql

@@ -0,0 +1,12 @@
+SELECT ph.id AS id1_1_0_,
+       ph.property_type AS property2_1_0_,
+       ph.property_id AS property3_1_0_
+FROM   property_holder ph
+WHERE  ph.id = 1
+
+
+SELECT sp.id AS id1_2_0_,
+       sp."name" AS name2_2_0_,
+       sp."value" AS value3_2_0_
+FROM   string_property sp
+WHERE  sp.id = 1

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

@@ -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 )

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

@@ -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

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

@@ -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

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

@@ -36,33 +36,38 @@ protected String[] getAnnotatedPackages() {
     @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[]
     }
 
 

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

@@ -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 void setId(Long id) {
         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[]
 

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

@@ -37,36 +37,43 @@ protected String[] getAnnotatedPackages() {
     @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[]
     }
 
 

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

@@ -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() {

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

@@ -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() {

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

@@ -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 void setId(Long id) {
         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[]