diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc index 9b4f306160..eb18e68931 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc @@ -1638,7 +1638,27 @@ include::{extrasdir}/basic/mapping-filter-entity-query-example.sql[] ---- ==== -Just like with entities, collections can be filtered as well, but only if the filter is explicitly enabled on the currently running Hibernate `Session`. +[IMPORTANT] +==== +Filters apply to entity queries, but not to direct fetching. +Therefore, in the following example, the filter is not taken into consideration when fetching an entity from the Persistence Context. + +[[mapping-filter-entity-example]] +.Fetching entities mapped with `@Filter` +[source, JAVA, indent=0] +---- +include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-entity-example] +---- + +[source, SQL, indent=0] +---- +include::{extrasdir}/basic/mapping-filter-entity-example.sql[] +---- + +As you can see from the example above, contrary to an entity query, the filter does not prevent the entity from being loaded. +==== + +Just like with entity queries, collections can be filtered as well, but only if the filter is explicitly 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]] diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-filter-entity-example.sql b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-filter-entity-example.sql new file mode 100644 index 0000000000..f3d4d61627 --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-filter-entity-example.sql @@ -0,0 +1,16 @@ +SELECT + a.id as id1_0_0_, + a.active as active2_0_0_, + a.amount as amount3_0_0_, + a.client_id as client_i6_0_0_, + a.rate as rate4_0_0_, + a.account_type as account_5_0_0_, + c.id as id1_1_1_, + c.name as name2_1_1_ +FROM + Account a +LEFT OUTER JOIN + Client c + ON a.client_id=c.id +WHERE + a.id = 2 \ No newline at end of file diff --git a/documentation/src/test/java/org/hibernate/userguide/mapping/basic/FilterTest.java b/documentation/src/test/java/org/hibernate/userguide/mapping/basic/FilterTest.java index decf06ee0b..c050a51f43 100644 --- a/documentation/src/test/java/org/hibernate/userguide/mapping/basic/FilterTest.java +++ b/documentation/src/test/java/org/hibernate/userguide/mapping/basic/FilterTest.java @@ -30,6 +30,7 @@ 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; import static org.junit.Assert.assertNull; @@ -129,7 +130,21 @@ public class FilterTest extends BaseEntityManagerFunctionalTestCase { } } ); - //tag::mapping-filter-entity-query-example[] + //tag::mapping-filter-entity-example[] + doInJPA( this::entityManagerFactory, entityManager -> { + log.infof( "Activate filter [%s]", "activeAccount"); + + entityManager + .unwrap( Session.class ) + .enableFilter( "activeAccount" ) + .setParameter( "active", true); + + Account account = entityManager.find( Account.class, 2L ); + assertFalse( account.isActive() ); + } ); + //end::mapping-filter-entity-example[] + + // tag::mapping-filter-entity-query-example[] doInJPA( this::entityManagerFactory, entityManager -> { List accounts = entityManager.createQuery( "select a from Account a", Account.class)