HHH-11186 - Add examples for all Hibernate annotations

Document @SqlFragmentAlias annotation

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

@@ -1237,7 +1237,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
 
 The alias (e.g. `myAlias`) can then be used in the `@Filter` `condition` clause using the `{alias}` (e.g. `{myAlias}`) placeholder.
 
-//TODO: Add example
+See the <<chapters/domain/basic_types.adoc#mapping-column-filter-sql-fragment-alias,`@SqlFragmentAlias` mapping>> section for more info.
 
 [[annotations-hibernate-sqlinsert]]
 ==== `@SQLInsert`

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

@@ -1851,6 +1851,40 @@ include::{extrasdir}/basic/mapping-filter-join-table-collection-query-example.sq
 ----
 ====
 
+[[mapping-column-filter-sql-fragment-alias]]
+==== `@Filter` with `@SqlFragmentAlias`
+
+When using the `@Filter` annotation and working with entities that are mapped onto multiple database tables,
+you will need to use the
+https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/SqlFragmentAlias.html[`@SqlFragmentAlias`] annotation
+if the `@Filter` defines a condition that uses predicates across multiple tables.
+
+[[mapping-filter-sql-fragment-alias-example]]
+.`@SqlFragmentAlias` mapping usage
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterSqlFragementAliasTest.java[tags=mapping-filter-sql-fragment-alias-example]
+----
+====
+
+Now, when fetching the `Account` entities and activating the filter,
+Hibernate is going to apply the right table aliases to the filter predicates:
+
+[[mapping-filter-sql-fragment-alias-query-example]]
+.Fetching a collection filtered with `@SqlFragmentAlias`
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterSqlFragementAliasTest.java[tags=mapping-filter-sql-fragment-alias-query-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-filter-sql-fragment-alias-query-example.sql[]
+----
+====
+
 [[mapping-column-any]]
 ==== `@Any` mapping
 

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-filter-sql-fragment-alias-query-example.sql

@@ -0,0 +1,16 @@
+select
+    filtersqlf0_.id as id1_0_,
+    filtersqlf0_.active as active2_0_,
+    filtersqlf0_.amount as amount3_0_,
+    filtersqlf0_.rate as rate4_0_,
+    filtersqlf0_1_.deleted as deleted1_1_
+from
+    account filtersqlf0_
+left outer join
+    account_details filtersqlf0_1_
+        on filtersqlf0_.id=filtersqlf0_1_.id
+where
+    filtersqlf0_.active = ?
+    and filtersqlf0_1_.deleted = false
+
+-- binding parameter [1] as [BOOLEAN] - [true]

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

@@ -0,0 +1,176 @@
+/*
+ * 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.Timestamp;
+import java.util.ArrayList;
+import java.util.List;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.EnumType;
+import javax.persistence.Enumerated;
+import javax.persistence.Id;
+import javax.persistence.ManyToOne;
+import javax.persistence.NoResultException;
+import javax.persistence.OneToMany;
+import javax.persistence.SecondaryTable;
+import javax.persistence.Table;
+
+import org.hibernate.Session;
+import org.hibernate.annotations.Filter;
+import org.hibernate.annotations.FilterDef;
+import org.hibernate.annotations.ParamDef;
+import org.hibernate.annotations.SQLDelete;
+import org.hibernate.annotations.SqlFragmentAlias;
+import org.hibernate.dialect.H2Dialect;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.hibernate.testing.RequiresDialect;
+import org.junit.Test;
+
+import org.jboss.logging.Logger;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+
+/**
+ * @author Vlad Mihalcea
+ */
+@RequiresDialect(H2Dialect.class)
+public class FilterSqlFragementAliasTest extends BaseEntityManagerFunctionalTestCase {
+
+	private static final Logger log = Logger.getLogger( FilterSqlFragementAliasTest.class );
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Account.class
+		};
+	}
+
+	@Test
+	public void testLifecycle() {
+		doInJPA( this::entityManagerFactory, entityManager -> {
+
+			Account account1 = new Account( );
+			account1.setId( 1L );
+			account1.setAmount( 5000d );
+			account1.setRate( 1.25 / 100 );
+			account1.setActive( true );
+			entityManager.persist( account1 );
+
+			Account account2 = new Account( );
+			account2.setId( 2L );
+			account2.setAmount( 0d );
+			account2.setRate( 1.05 / 100 );
+			account2.setActive( false );
+			entityManager.persist( account2 );
+
+			Account account3 = new Account( );
+			account3.setId( 3L );
+			account3.setAmount( 250d );
+			account3.setRate( 1.05 / 100 );
+			account3.setActive( true );
+			entityManager.persist( account3 );
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			log.infof( "Activate filter [%s]", "activeAccount");
+
+			//tag::mapping-filter-sql-fragment-alias-query-example[]
+			entityManager
+				.unwrap( Session.class )
+				.enableFilter( "activeAccount" )
+				.setParameter( "active", true);
+
+			List<Account> accounts = entityManager.createQuery(
+				"select a from Account a", Account.class)
+			.getResultList();
+			//end::mapping-filter-sql-fragment-alias-query-example[]
+			assertEquals( 2, accounts.size());
+		} );
+	}
+
+	//tag::mapping-filter-sql-fragment-alias-example[]
+	@Entity(name = "Account")
+	@Table(name = "account")
+	@SecondaryTable(
+		name = "account_details"
+	)
+	@SQLDelete(
+		sql = "UPDATE account_details SET deleted = true WHERE id = ? "
+	)
+	@FilterDef(
+		name="activeAccount",
+		parameters = @ParamDef(
+			name="active",
+			type="boolean"
+		)
+	)
+	@Filter(
+		name="activeAccount",
+		condition="{a}.active = :active and {ad}.deleted = false",
+		aliases = {
+			@SqlFragmentAlias( alias = "a", table= "account"),
+			@SqlFragmentAlias( alias = "ad", table= "account_details"),
+		}
+	)
+	public static class Account {
+
+		@Id
+		private Long id;
+
+		private Double amount;
+
+		private Double rate;
+
+		private boolean active;
+
+		@Column(table = "account_details")
+		private boolean deleted;
+
+		//Getters and setters omitted for brevity
+
+	//end::mapping-filter-sql-fragment-alias-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public Double getAmount() {
+			return amount;
+		}
+
+		public void setAmount(Double amount) {
+			this.amount = amount;
+		}
+
+		public Double getRate() {
+			return rate;
+		}
+
+		public void setRate(Double rate) {
+			this.rate = rate;
+		}
+
+		public boolean isActive() {
+			return active;
+		}
+
+		public void setActive(boolean active) {
+			this.active = active;
+		}
+
+		//tag::mapping-filter-sql-fragment-alias-example[]
+	}
+	//end::mapping-filter-sql-fragment-alias-example[]
+}