HHH-11186 - Add examples for all Hibernate annotations

Document @Index annotation

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

@@ -79,7 +79,7 @@ See the <<chapters/query/native/Native.adoc#sql-composite-key-entity-association
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/ConstructorResult.html[`@ConstructorResult`] annotation is used in conjunction with the <<annotations-jpa-sqlresultsetmapping>> annotations to map columns of a given SELECT query to a certain object constructor.
 
-//TODO: Add example
+See the <<chapters/query/native/Native.adoc#sql-multiple-scalar-values-dto-NamedNativeQuery-example, Multiple scalar values `NamedNativeQuery` with `ConstructorResult`>> section for more info.
 
 [[annotations-jpa-convert]]
 ==== `@Convert`
@@ -235,7 +235,7 @@ See the <<chapters/domain/identifiers.adoc#identifiers-composite-nonaggregated,C
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/Index.html[`@Index`] annotation is used by the automated schema generation tool to create a database index.
 
-//TODO: Add example
+See the <<chapters/schema/Schema.adoc#schema-generation-columns-index, Columns index>> chapter for more info.
 
 [[annotations-jpa-inheritance]]
 ==== `@Inheritance`
@@ -256,8 +256,6 @@ See the <<chapters/domain/associations.adoc#associations-many-to-one-example,`@M
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/JoinColumns.html[`@JoinColumns`] annotation is used to group multiple <<annotations-jpa-joincolumn>> annotations, which are used when mapping entity association or an embeddable collection using a composite identifier
 
-//TODO: Add example
-
 [[annotations-jpa-jointable]]
 ==== `@JoinTable`
 
@@ -327,8 +325,6 @@ See the <<chapters/domain/collections.adoc#collections-map-value-type-entity-key
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/MapKeyJoinColumns.html[`@MapKeyJoinColumns`] annotation is used to group several <<annotations-jpa-mapkeyjoincolumn>> mappings when the `java.util.Map` association key uses a composite identifier.
 
-//TODO: Add example
-
 [[annotations-jpa-mapkeytemporal]]
 ==== `@MapKeyTemporal`
 

documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc

@@ -198,4 +198,25 @@ include::{extrasdir}/schema-generation-columns-unique-constraint-persist-example
 ----
 ====
 
-The second INSERT statement fails because of the unique coonstraint violation.
+The second INSERT statement fails because of the unique constraint violation.
+
+[[schema-generation-columns-index]]
+=== Columns index
+
+The http://docs.oracle.com/javaee/7/api/javax/persistence/Index.html[`@Index`] annotation is used by the automated schema generation tool to create a database index.
+
+Considering the following entity mapping, Hibernate generates the index when creating the database schema:
+
+[[schema-generation-columns-index-mapping-example]]
+.`@Index` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/IndexTest.java[tag=schema-generation-columns-index-mapping-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/schema-generation-columns-index-mapping-example.sql[]
+----
+====

documentation/src/main/asciidoc/userguide/chapters/schema/extras/schema-generation-columns-index-mapping-example.sql

@@ -0,0 +1,9 @@
+create table author (
+    id bigint not null,
+    first_name varchar(255),
+    last_name varchar(255),
+    primary key (id)
+)
+
+create index idx_author_first_last_name
+    on author (first_name, last_name)

documentation/src/main/asciidoc/userguide/chapters/schema/extras/schema-generation-columns-unique-constraint-mapping-example.sql

@@ -1,7 +1,7 @@
 create table author (
     id bigint not null,
-    firstName varchar(255),
-    lastName varchar(255),
+    first_name varchar(255),
+    last_name varchar(255),
     primary key (id)
 )
 

documentation/src/main/asciidoc/userguide/chapters/schema/extras/schema-generation-columns-unique-constraint-persist-example.sql

@@ -1,7 +1,7 @@
 insert
 into
     author
-    (firstName, lastName, id)
+    (first_name, last_name, id)
 values
     (?, ?, ?)
 

documentation/src/test/java/org/hibernate/userguide/schema/IndexTest.java

@@ -0,0 +1,105 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.userguide.schema;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.FetchType;
+import javax.persistence.ForeignKey;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+import javax.persistence.Index;
+import javax.persistence.JoinColumn;
+import javax.persistence.ManyToOne;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+
+import org.hibernate.exception.ConstraintViolationException;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.hibernate.testing.util.ExceptionUtil;
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+import static org.junit.Assert.assertNotNull;
+
+/**
+ * @author Vlad Mihalcea
+ */
+
+public class IndexTest extends BaseEntityManagerFunctionalTestCase {
+
+    @Override
+    protected Class<?>[] getAnnotatedClasses() {
+        return new Class<?>[] {
+            Author.class,
+        };
+    }
+
+    @Test
+    public void test() {
+        doInJPA( this::entityManagerFactory, entityManager -> {
+            Author author = new Author();
+            author.setFirstName( "Vlad" );
+            author.setLastName( "Mihalcea" );
+            entityManager.persist( author );
+        } );
+    }
+
+    //tag::schema-generation-columns-index-mapping-example[]
+    @Entity
+    @Table(
+        name = "author",
+        indexes =  @Index(
+            name = "idx_author_first_last_name",
+            columnList = "first_name, last_name",
+            unique = false
+        )
+    )
+    public static class Author {
+
+        @Id
+        @GeneratedValue
+        private Long id;
+
+        @Column(name = "first_name")
+        private String firstName;
+
+        @Column(name = "last_name")
+        private String lastName;
+
+        //Getter and setters omitted for brevity
+    //end::schema-generation-columns-index-mapping-example[]
+
+        public Long getId() {
+            return id;
+        }
+
+        public void setId(Long id) {
+            this.id = id;
+        }
+
+        public String getFirstName() {
+            return firstName;
+        }
+
+        public void setFirstName(String firstName) {
+            this.firstName = firstName;
+        }
+
+        public String getLastName() {
+            return lastName;
+        }
+
+        public void setLastName(String lastName) {
+            this.lastName = lastName;
+        }
+
+    //tag::schema-generation-columns-index-mapping-example[]
+    }
+    //end::schema-generation-columns-index-mapping-example[]
+}

documentation/src/test/java/org/hibernate/userguide/schema/UniqueConstraintTest.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate.userguide.schema;
 
+import javax.persistence.Column;
 import javax.persistence.Entity;
 import javax.persistence.FetchType;
 import javax.persistence.ForeignKey;
@@ -138,8 +139,10 @@ public class UniqueConstraintTest extends BaseEntityManagerFunctionalTestCase {
         @GeneratedValue
         private Long id;
 
+        @Column(name = "first_name")
         private String firstName;
 
+        @Column(name = "last_name")
         private String lastName;
 
         //Getter and setters omitted for brevity