HHH-11186 - Add examples for all Hibernate annotations

Document @Persister annotation

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

@@ -1146,7 +1146,7 @@ For entities, the custom persister must implement the https://docs.jboss.org/hib
 
 For collections, the custom persister must implement the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/persister/collection/CollectionPersister.html[`CollectionPersister`] interface.
 
-//TODO: Add example
+See the <<chapters/domain/entity.adoc#entity-persister, `@Persister` mapping>> section for more info.
 
 [[annotations-hibernate-polymorphism]]
 ==== `@Polymorphism`

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

@@ -3,6 +3,7 @@
 :sourcedir-locking: ../../../../../test/java/org/hibernate/userguide/locking
 :sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping/basic
 :sourcedir-proxy: ../../../../../test/java/org/hibernate/userguide/proxy
+:sourcedir-persister: ../../../../../test/java/org/hibernate/userguide/persister
 :extrasdir: extras
 
 .Usage of the word _entity_
@@ -426,4 +427,28 @@ include::{sourcedir-proxy}/tuplizer/TuplizerTest.java[tag=entity-tuplizer-dynami
 ----
 ====
 
+[[entity-persister]]
+==== Define a custom entity persister
 
+The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Persister.html[`@Persister`] annotation is used to specify a custom entity or collection persister.
+
+For entities, the custom persister must implement the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/persister/entity/EntityPersister.html[`EntityPersister`] interface.
+
+For collections, the custom persister must implement the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/persister/collection/CollectionPersister.html[`CollectionPersister`] interface.
+
+[[entity-persister-mapping]]
+.Entity persister mapping
+====
+[source,java]
+----
+include::{sourcedir-persister}/Author.java[tag=entity-persister-mapping,indent=0]
+----
+
+[source,java]
+----
+include::{sourcedir-persister}/Book.java[tag=entity-persister-mapping,indent=0]
+----
+====
+
+By providing you own `EntityPersister` and `CollectionPersister` implementations,
+you can control how entities and collections are persisted in to the database.

documentation/src/test/java/org/hibernate/userguide/persister/Author.java

@@ -0,0 +1,54 @@
+/*
+ * 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.persister;
+
+import java.util.HashSet;
+import java.util.Set;
+import javax.persistence.Entity;
+import javax.persistence.Id;
+import javax.persistence.OneToMany;
+
+import org.hibernate.annotations.Persister;
+
+
+/**
+ * @author Shawn Clowater
+ */
+//tag::entity-persister-mapping[]
+@Entity
+@Persister( impl = EntityPersister.class )
+public class Author {
+
+    @Id
+    public Integer id;
+
+    @OneToMany( mappedBy = "author" )
+    @Persister( impl = CollectionPersister.class )
+    public Set<Book> books = new HashSet<>();
+
+    //Getters and setters omitted for brevity
+    //end::entity-persister-mapping[]
+
+    public Integer getId() {
+        return id;
+    }
+
+    public void setId(Integer id) {
+        this.id = id;
+    }
+
+    public Set<Book> getBooks() {
+        return books;
+    }
+
+    //tag::entity-persister-mapping[]
+    public void addBook(Book book) {
+        this.books.add( book );
+        book.setAuthor( this );
+    }
+}
+//end::entity-persister-mapping[]

documentation/src/test/java/org/hibernate/userguide/persister/Book.java

@@ -0,0 +1,61 @@
+/*
+ * 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.persister;
+
+import javax.persistence.Entity;
+import javax.persistence.FetchType;
+import javax.persistence.Id;
+import javax.persistence.ManyToOne;
+
+import org.hibernate.annotations.Persister;
+
+/**
+ * @author Shawn Clowater
+ */
+//tag::entity-persister-mapping[]
+
+@Entity
+@Persister( impl = EntityPersister.class )
+public class Book {
+
+    @Id
+    public Integer id;
+
+    private String title;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    public Author author;
+
+    //Getters and setters omitted for brevity
+    //end::entity-persister-mapping[]
+
+    public Integer getId() {
+        return id;
+    }
+
+    public void setId(Integer id) {
+        this.id = id;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    public Author getAuthor() {
+        return author;
+    }
+
+    public void setAuthor(Author author) {
+        this.author = author;
+    }
+//tag::entity-persister-mapping[]
+}
+//end::entity-persister-mapping[]

documentation/src/test/java/org/hibernate/userguide/persister/CollectionPersister.java

@@ -0,0 +1,32 @@
+/*
+ * 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.persister;
+
+import org.hibernate.MappingException;
+import org.hibernate.cache.CacheException;
+import org.hibernate.cache.spi.access.CollectionRegionAccessStrategy;
+import org.hibernate.mapping.Collection;
+import org.hibernate.persister.collection.OneToManyPersister;
+import org.hibernate.persister.spi.PersisterCreationContext;
+
+/**
+ * @author Shawn Clowater
+ */
+//tag::entity-persister-mapping[]
+
+public class CollectionPersister
+        extends OneToManyPersister {
+
+    public CollectionPersister(
+            Collection collectionBinding,
+            CollectionRegionAccessStrategy cacheAccessStrategy,
+            PersisterCreationContext creationContext)
+            throws MappingException, CacheException {
+        super( collectionBinding, cacheAccessStrategy, creationContext );
+    }
+}
+//end::entity-persister-mapping[]

documentation/src/test/java/org/hibernate/userguide/persister/EntityPersister.java

@@ -0,0 +1,34 @@
+/*
+ * 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.persister;
+
+import org.hibernate.HibernateException;
+import org.hibernate.cache.spi.access.EntityRegionAccessStrategy;
+import org.hibernate.cache.spi.access.NaturalIdRegionAccessStrategy;
+import org.hibernate.mapping.PersistentClass;
+import org.hibernate.persister.entity.SingleTableEntityPersister;
+import org.hibernate.persister.spi.PersisterCreationContext;
+
+/**
+ * @author Shawn Clowater
+ */
+//tag::entity-persister-mapping[]
+
+public class EntityPersister
+    extends SingleTableEntityPersister {
+
+    public EntityPersister(
+            PersistentClass persistentClass,
+            EntityRegionAccessStrategy cache,
+            NaturalIdRegionAccessStrategy naturalIdRegionAccessStrategy,
+            PersisterCreationContext creationContext)
+            throws HibernateException {
+        super( persistentClass, cache, naturalIdRegionAccessStrategy, creationContext );
+    }
+}
+//end::entity-persister-mapping[]
+

documentation/src/test/java/org/hibernate/userguide/persister/PersisterTest.java

@@ -0,0 +1,53 @@
+/*
+ * 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.persister;
+
+import org.hibernate.mapping.Collection;
+import org.hibernate.mapping.PersistentClass;
+import org.hibernate.persister.entity.SingleTableEntityPersister;
+
+import org.hibernate.testing.junit4.BaseNonConfigCoreFunctionalTestCase;
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+
+/**
+ * @author Shawn Clowater
+ */
+public class PersisterTest extends BaseNonConfigCoreFunctionalTestCase {
+    @Test
+    public void testEntityEntityPersisterAndPersisterSpecified() throws Exception {
+        //checks to see that the persister specified with the @Persister annotation takes precedence if a @Entity.persister() is also specified     
+        PersistentClass persistentClass = metadata().getEntityBinding( Author.class.getName() );
+        assertEquals( "Incorrect Persister class for " + persistentClass.getMappedClass(), EntityPersister.class,
+                persistentClass.getEntityPersisterClass() );
+    }
+
+    @Test
+    public void testEntityEntityPersisterSpecified() throws Exception {
+        //tests the persister specified with an @Entity.persister()
+        PersistentClass persistentClass = metadata().getEntityBinding( Book.class.getName() );
+        assertEquals( "Incorrect Persister class for " + persistentClass.getMappedClass(),
+                SingleTableEntityPersister.class, persistentClass.getEntityPersisterClass() );
+    }
+
+    @Test
+    public void testCollectionPersisterSpecified() throws Exception {
+        //tests the persister specified by the @Persister annotation on a collection
+        Collection collection = metadata().getCollectionBinding( Author.class.getName() + ".cards" );
+        assertEquals( "Incorrect Persister class for collection " + collection.getRole(), CollectionPersister.class,
+                collection.getCollectionPersisterClass() );
+    }
+
+    @Override
+    protected Class[] getAnnotatedClasses() {
+        return new Class[]{
+                Book.class,
+                Author.class
+        };
+    }
+}