HHH-11186 - Add examples for all Hibernate annotations

Document @WhereJoinTable annotation

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

@@ -1356,4 +1356,4 @@ See the <<chapters/domain/basic_types.adoc#mapping-where-example,`@Where` mappin
 
 The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/WhereJoinTable.html[`@WhereJoinTable`] annotation is used to specify a custom SQL `WHERE` clause used when fetching a join collection table.
 
-//TODO: Add example
+See the <<chapters/domain/basic_types.adoc#mapping-where-join-table, `@WhereJoinTable` mapping>> section for more info.

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

@@ -1655,6 +1655,50 @@ include::{extrasdir}/basic/mapping-where-collection-query-example.sql[]
 ----
 ====
 
+[[mapping-where-join-table]]
+==== `@WhereJoinTable`
+
+Just like `@Where` annotation, `@WhereJoinTable` is used to filter out collections using a joined table (e.g. @ManyToMany association).
+
+[[mapping-where-join-table-example]]
+.`@WhereJoinTable` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/WhereJoinTableTest.java[tags=mapping-where-join-table-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-where-join-table-example.sql[]
+----
+====
+
+In the example above, the current week `Reader` entities are included in the `currentWeekReaders` collection
+which uses the `@WhereJoinTable` annotation to filter the joined table rows according to the provided SQL clause.
+
+Considering that the following two `Book_Reader` entries are added into our system:
+
+[[mapping-where-join-table-persist-example]]
+.`@WhereJoinTable` test data
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/WhereJoinTableTest.java[tags=mapping-where-join-table-persist-example]
+----
+====
+
+When fetching the `currentWeekReaders` collection, Hibernate is going to find one one entry:
+
+[[mapping-where-join-table-fetch-example]]
+.`@WhereJoinTable` fetch example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/WhereJoinTableTest.java[tags=mapping-where-join-table-fetch-example]
+----
+====
+
 [[mapping-column-filter]]
 ==== `@Filter`
 

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-where-join-table-example.sql

@@ -0,0 +1,31 @@
+create table Book (
+    id bigint not null,
+    author varchar(255),
+    title varchar(255),
+    primary key (id)
+)
+
+create table Book_Reader (
+    book_id bigint not null,
+    reader_id bigint not null
+)
+
+create table Reader (
+    id bigint not null,
+    name varchar(255),
+    primary key (id)
+)
+
+alter table Book_Reader
+    add constraint FKsscixgaa5f8lphs9bjdtpf9g
+    foreign key (reader_id)
+    references Reader
+
+alter table Book_Reader
+    add constraint FKoyrwu9tnwlukd1616qhck21ra
+    foreign key (book_id)
+    references Book
+
+alter table Book_Reader
+    add created_on timestamp
+    default current_timestamp

documentation/src/test/java/org/hibernate/userguide/mapping/basic/WhereJoinTableTest.java

@@ -0,0 +1,187 @@
+/*
+ * 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.mapping.basic;
+
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.List;
+import javax.persistence.Entity;
+import javax.persistence.Id;
+import javax.persistence.JoinColumn;
+import javax.persistence.JoinTable;
+import javax.persistence.ManyToMany;
+
+import org.hibernate.Session;
+import org.hibernate.annotations.WhereJoinTable;
+import org.hibernate.dialect.H2Dialect;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.hibernate.testing.RequiresDialect;
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+import static org.junit.Assert.assertEquals;
+
+/**
+ * @author Vlad Mihalcea
+ */
+@RequiresDialect(H2Dialect.class)
+public class WhereJoinTableTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Book.class,
+			Reader.class
+		};
+	}
+
+	@Test
+	public void testLifecycle() {
+		//tag::mapping-where-persistence-example[]
+		doInJPA( this::entityManagerFactory, entityManager -> {
+
+			entityManager.unwrap( Session.class ).doWork( connection -> {
+				try(Statement statement = connection.createStatement()) {
+					statement.executeUpdate(
+						"ALTER TABLE Book_Reader ADD created_on TIMESTAMP DEFAULT CURRENT_TIMESTAMP"
+					);
+				}
+			} );
+
+			//tag::mapping-where-join-table-persist-example[]
+			Book book = new Book();
+			book.setId( 1L );
+			book.setTitle( "High-Performance Java Persistence" );
+			book.setAuthor( "Vad Mihalcea" );
+			entityManager.persist( book );
+
+			Reader reader1 = new Reader();
+			reader1.setId( 1L );
+			reader1.setName( "John Doe" );
+			entityManager.persist( reader1 );
+
+			Reader reader2 = new Reader();
+			reader2.setId( 2L );
+			reader2.setName( "John Doe Jr." );
+			entityManager.persist( reader2 );
+			//end::mapping-where-join-table-persist-example[]
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			entityManager.unwrap( Session.class ).doWork( connection -> {
+				try(Statement statement = connection.createStatement()) {
+			//tag::mapping-where-join-table-persist-example[]
+
+			statement.executeUpdate(
+				"INSERT INTO Book_Reader " +
+				"	(book_id, reader_id) " +
+				"VALUES " +
+				"	(1, 1) "
+			);
+			statement.executeUpdate(
+				"INSERT INTO Book_Reader " +
+				"	(book_id, reader_id, created_on) " +
+				"VALUES " +
+				"	(1, 2, DATEADD( 'DAY', -10, CURRENT_TIMESTAMP() )) "
+			);
+				//end::mapping-where-join-table-persist-example[]
+				}}
+			);
+
+			//tag::mapping-where-join-table-fetch-example[]
+			Book book = entityManager.find( Book.class, 1L );
+			assertEquals( 1, book.getCurrentWeekReaders().size() );
+			//end::mapping-where-join-table-fetch-example[]
+		} );
+	}
+
+	//tag::mapping-where-join-table-example[]
+	@Entity(name = "Book")
+	public static class Book {
+
+		@Id
+		private Long id;
+
+		private String title;
+
+		private String author;
+
+		@ManyToMany
+		@JoinTable(
+			name = "Book_Reader",
+			joinColumns = @JoinColumn(name = "book_id"),
+			inverseJoinColumns = @JoinColumn(name = "reader_id")
+		)
+		@WhereJoinTable( clause = "created_on > DATEADD( 'DAY', -7, CURRENT_TIMESTAMP() )")
+		private List<Reader> currentWeekReaders = new ArrayList<>( );
+
+		//Getters and setters omitted for brevity
+
+		//end::mapping-where-join-table-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public String getTitle() {
+			return title;
+		}
+
+		public void setTitle(String title) {
+			this.title = title;
+		}
+
+		public String getAuthor() {
+			return author;
+		}
+
+		public void setAuthor(String author) {
+			this.author = author;
+		}
+
+		public List<Reader> getCurrentWeekReaders() {
+			return currentWeekReaders;
+		}
+
+		//tag::mapping-where-join-table-example[]
+	}
+
+	@Entity(name = "Reader")
+	public static class Reader {
+
+		@Id
+		private Long id;
+
+		private String name;
+
+		//Getters and setters omitted for brevity
+
+		//end::mapping-where-join-table-example[]
+
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public String getName() {
+			return name;
+		}
+
+		public void setName(String name) {
+			this.name = name;
+		}
+		//tag::mapping-where-join-table-example[]
+	}
+		//end::mapping-where-join-table-example[]
+}