HHH-11002 - Add documentation section about Filter and FilterDef

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

@@ -1238,7 +1238,7 @@ include::{extrasdir}/basic/mapping-where-persistence-example.sql[]
 ----
 ====
 
-When loading an `Account` entity, Hibernate is going to filter out all records that are not active.
+When executing an `Account` entity query, Hibernate is going to filter out all records that are not active.
 
 [[mapping-where-entity-query-example]]
 .Query entities mapped with `@Where`
@@ -1270,6 +1270,77 @@ include::{extrasdir}/basic/mapping-where-collection-query-example.sql[]
 ----
 ====
 
+[[mapping-column-filter]]
+==== @Filter
+
+The `@Filter` annotation is another way to filter out entities or collections using a custom SQL criteria, for both entities and collections.
+Unlike the `@Where` annotation, `@Filter` allows you to parameterize the filter clause at runtime.
+
+[[mapping-filter-example]]
+.`@Filter` mapping usage
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-example]
+----
+====
+
+If the database contains the following entities:
+
+[[mapping-filter-persistence-example]]
+.Persisting an fetching entities with a `@Filter` mapping
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-persistence-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-filter-persistence-example.sql[]
+----
+====
+
+By default, without explicitly enabling the filter, Hibernate is going to fetch all `Account` entities.
+If the filter is enabled and the filter parameter value is provided,
+then Hibernate is going to apply the filtering criteria to the associated `Account` entities.
+
+[[mapping-filter-entity-query-example]]
+.Query entities mapped with `@Filter`
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-entity-query-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-filter-entity-query-example.sql[]
+----
+====
+
+Jut like with entities, collections can be filtered as well, but only if the filter is explicilty enabled on the currently running Hibernate `Session`.
+This way, when fetching the `accounts` collections, Hibernate is going to apply the `@Filter` clause filtering criteria to the associated collection entries.
+
+[[mapping-filter-collection-query-example]]
+.Traversing collections mapped with `@Filter`
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-collection-query-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-filter-collection-query-example.sql[]
+----
+====
+
+[NOTE]
+====
+The main advantage of `@Filter` over teh `@Where` clause is that the filtering criteria can be customized at runtime.
+====
+
 [[mapping-column-any]]
 ==== @Any mapping
 

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

@@ -0,0 +1,42 @@
+SELECT
+    c.id as id1_1_0_,
+    c.name as name2_1_0_ 
+FROM
+    Client c 
+WHERE
+    c.id = 1
+
+SELECT
+    a.id as id1_0_,
+    a.active as active2_0_,
+    a.amount as amount3_0_,
+    a.client_id as client_i6_0_,
+    a.rate as rate4_0_,
+    a.account_type as account_5_0_
+FROM
+    Account a
+WHERE
+    a.client_id = 1
+
+-- Activate filter [activeAccount]
+
+SELECT
+    c.id as id1_1_0_,
+    c.name as name2_1_0_
+FROM
+    Client c
+WHERE
+    c.id = 1
+
+SELECT
+    a.id as id1_0_,
+    a.active as active2_0_,
+    a.amount as amount3_0_,
+    a.client_id as client_i6_0_,
+    a.rate as rate4_0_,
+    a.account_type as account_5_0_
+FROM
+    Account a
+WHERE
+    accounts0_.active = true
+    and a.client_id = 1

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

@@ -0,0 +1,23 @@
+SELECT
+    a.id as id1_0_,
+    a.active as active2_0_,
+    a.amount as amount3_0_,
+    a.client_id as client_i6_0_,
+    a.rate as rate4_0_,
+    a.account_type as account_5_0_
+FROM
+    Account a
+
+-- Activate filter [activeAccount]
+
+SELECT
+    a.id as id1_0_,
+    a.active as active2_0_,
+    a.amount as amount3_0_,
+    a.client_id as client_i6_0_,
+    a.rate as rate4_0_,
+    a.account_type as account_5_0_
+FROM
+    Account a
+WHERE
+    a.active = true

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

@@ -0,0 +1,11 @@
+INSERT INTO Client (name, id)
+VALUES ('John Doe', 1)
+
+INSERT INTO Account (active, amount, client_id, rate, account_type, id)
+VALUES (true, 5000.0, 1, 0.0125, 'CREDIT', 1)
+
+INSERT INTO Account (active, amount, client_id, rate, account_type, id)
+VALUES (false, 0.0, 1, 0.0105, 'DEBIT', 2)
+
+INSERT INTO Account (active, amount, client_id, rate, account_type, id)
+VALUES (true, 250.0, 1, 0.0105, 'DEBIT', 3)

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

@@ -9,7 +9,7 @@ SELECT
     c.account_type as account_5_0_1_
 FROM
     Account c
-WHERE ( c.active = 1 and c.account_type = 'CREDIT' ) AND c.client_id = 1
+WHERE ( c.active = true and c.account_type = 'CREDIT' ) AND c.client_id = 1
 
 SELECT
     d.client_id as client_i6_0_0_,
@@ -22,4 +22,4 @@ SELECT
     d.account_type as account_5_0_1_
 FROM
     Account d
-WHERE ( d.active = 1 and d.account_type = 'DEBIT' ) AND d.client_id = 1
+WHERE ( d.active = true and d.account_type = 'DEBIT' ) AND d.client_id = 1

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

@@ -7,4 +7,4 @@ SELECT
     a.account_type as account_5_0_
 FROM
     Account a
-WHERE ( a.active = 1 )
+WHERE ( a.active = true )

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

@@ -0,0 +1,252 @@
+/*
+ * 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.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.OneToMany;
+
+import org.hibernate.Session;
+import org.hibernate.annotations.Filter;
+import org.hibernate.annotations.FilterDef;
+import org.hibernate.annotations.ParamDef;
+import org.hibernate.annotations.Where;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import org.jboss.logging.Logger;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+import static org.junit.Assert.assertEquals;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class FilterTest extends BaseEntityManagerFunctionalTestCase {
+
+	private static final Logger log = Logger.getLogger( FilterTest.class );
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Client.class,
+			Account.class
+		};
+	}
+
+	@Test
+	public void testLifecycle() {
+		//tag::mapping-filter-persistence-example[]
+		doInJPA( this::entityManagerFactory, entityManager -> {
+
+			Client client = new Client();
+			client.setId( 1L );
+			client.setName( "John Doe" );
+			entityManager.persist( client );
+
+			Account account1 = new Account( );
+			account1.setId( 1L );
+			account1.setType( AccountType.CREDIT );
+			account1.setAmount( 5000d );
+			account1.setRate( 1.25 / 100 );
+			account1.setActive( true );
+			account1.setClient( client );
+			client.getAccounts().add( account1 );
+			entityManager.persist( account1 );
+
+			Account account2 = new Account( );
+			account2.setId( 2L );
+			account2.setType( AccountType.DEBIT );
+			account2.setAmount( 0d );
+			account2.setRate( 1.05 / 100 );
+			account2.setActive( false );
+			account2.setClient( client );
+			client.getAccounts().add( account2 );
+			entityManager.persist( account2 );
+
+			Account account3 = new Account( );
+			account3.setType( AccountType.DEBIT );
+			account3.setId( 3L );
+			account3.setAmount( 250d );
+			account3.setRate( 1.05 / 100 );
+			account3.setActive( true );
+			account3.setClient( client );
+			client.getAccounts().add( account3 );
+			entityManager.persist( account3 );
+		} );
+		//end::mapping-filter-persistence-example[]
+
+
+		//tag::mapping-filter-entity-query-example[]
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			List<Account> accounts = entityManager.createQuery(
+				"select a from Account a", Account.class)
+			.getResultList();
+			assertEquals( 3, accounts.size());
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			log.infof( "Activate filter [%s]", "activeAccount");
+
+			entityManager
+				.unwrap( Session.class )
+				.enableFilter( "activeAccount" )
+				.setParameter( "active", true);
+
+			List<Account> accounts = entityManager.createQuery(
+				"select a from Account a", Account.class)
+			.getResultList();
+			assertEquals( 2, accounts.size());
+		} );
+		//end::mapping-filter-entity-query-example[]
+
+		//tag::mapping-filter-collection-query-example[]
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Client client = entityManager.find( Client.class, 1L );
+			assertEquals( 3, client.getAccounts().size() );
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			log.infof( "Activate filter [%s]", "activeAccount");
+
+			entityManager
+				.unwrap( Session.class )
+				.enableFilter( "activeAccount" )
+				.setParameter( "active", true);
+
+			Client client = entityManager.find( Client.class, 1L );
+			assertEquals( 2, client.getAccounts().size() );
+		} );
+		//end::mapping-filter-collection-query-example[]
+	}
+
+	//tag::mapping-filter-example[]
+	public enum AccountType {
+		DEBIT,
+		CREDIT
+	}
+
+	@Entity(name = "Client")
+	public static class Client {
+
+		@Id
+		private Long id;
+
+		private String name;
+
+		@OneToMany(mappedBy = "client")
+		@Filter(name="activeAccount", condition="active = :active")
+		private List<Account> accounts = new ArrayList<>( );
+
+		//Getters and setters omitted for brevity
+
+		//end::mapping-filter-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;
+		}
+
+		public List<Account> getAccounts() {
+			return accounts;
+		}
+		//tag::mapping-filter-example[]
+	}
+
+	@Entity(name = "Account")
+	@FilterDef(name="activeAccount", parameters=@ParamDef( name="active", type="boolean" ) )
+	@Filter(name="activeAccount", condition="active = :active")
+	public static class Account {
+
+		@Id
+		private Long id;
+
+		@ManyToOne
+		private Client client;
+
+		@Column(name = "account_type")
+		@Enumerated(EnumType.STRING)
+		private AccountType type;
+
+		private Double amount;
+
+		private Double rate;
+
+		private boolean active;
+
+		//Getters and setters omitted for brevity
+
+	//end::mapping-filter-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public Client getClient() {
+			return client;
+		}
+
+		public void setClient(Client client) {
+			this.client = client;
+		}
+
+		public AccountType getType() {
+			return type;
+		}
+
+		public void setType(AccountType type) {
+			this.type = type;
+		}
+
+		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-example[]
+	}
+	//end::mapping-filter-example[]
+}