HHH-4465 - Document @Entity.name != Hibernate entity name

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

@@ -25,6 +25,55 @@ crit.setMaxResults(50);
 List cats = crit.list();
 ----
 
+[[criteria-entity-name]]
+=== JPA vs Hibernate entity name
+
+When using the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/SharedSessionContract.html#createCriteria-java.lang.String-[`Session#createCriteria(String entityName)` or `StatelessSession#createCriteria(String entityName)`],
+the *entityName* means the fully-qualified name of the underlying entity and not the name denoted by the `name` attribute of the JPA `@Entity` annotation.
+
+Considering you have the following entity:
+
+[source,java]
+----
+@Entity(name = "ApplicationEvent")
+public static class Event {
+
+    @Id
+    private Long id;
+
+    private String name;
+}
+----
+
+If you provide the JPA entity name to a legacy Criteria query:
+
+[source,java]
+----
+List<Event> events =
+    entityManager.unwrap( Session.class )
+.createCriteria( "ApplicationEvent" )
+.list();
+----
+
+Hibernate is going to throw the following `MappingException`:
+
+[source,bash]
+----
+org.hibernate.MappingException: Unknown entity: ApplicationEvent
+----
+
+On the other hand, the Hibernate entity name (the fully qualified class name) works just fine:
+
+[source,java]
+----
+List<Event> events =
+    entityManager.unwrap( Session.class )
+.createCriteria( Event.class.getName() )
+.list();
+----
+
+For more about this topic, check out the https://hibernate.atlassian.net/browse/HHH-2597[HHH-2597] JIRA issue.
+
 [[criteria-narrowing]]
 === Narrowing the result set
 

documentation/src/test/java/org/hibernate/userguide/criteria/CriteriaTest.java

@@ -11,6 +11,8 @@ import java.sql.Timestamp;
 import java.time.LocalDateTime;
 import java.time.ZoneOffset;
 import java.util.List;
+import javax.persistence.Entity;
+import javax.persistence.Id;
 import javax.persistence.Tuple;
 import javax.persistence.TypedQuery;
 import javax.persistence.criteria.CriteriaBuilder;
@@ -22,6 +24,9 @@ import javax.persistence.criteria.Path;
 import javax.persistence.criteria.Predicate;
 import javax.persistence.criteria.Root;
 
+import org.hibernate.HibernateException;
+import org.hibernate.MappingException;
+import org.hibernate.Session;
 import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
 import org.hibernate.userguide.model.AddressType;
 import org.hibernate.userguide.model.Call;
@@ -54,7 +59,8 @@ public class CriteriaTest extends BaseEntityManagerFunctionalTestCase {
             Phone.class,
 			Call.class,
 			CreditCardPayment.class,
-			WireTransferPayment.class
+			WireTransferPayment.class,
+			Event.class
 		};
 	}
 
@@ -394,4 +400,47 @@ public class CriteriaTest extends BaseEntityManagerFunctionalTestCase {
 			assertEquals(2, tuples.size());
 		});
 	}
+
+	@Test
+	public void testLegacyCriteriaJpavsHibernateEntityName() {
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Event event1 = new Event();
+			event1.id = 1L;
+			event1.name = "E1";
+			entityManager.persist( event1 );
+
+			Event event2 = new Event();
+			event2.id = 2L;
+			event2.name = "E2";
+			entityManager.persist( event2 );
+
+			List<String> eventNames = entityManager.unwrap( Session.class )
+					.createQuery( "select ae.name from ApplicationEvent ae" )
+					.list();
+
+			try {
+				List<Event> events = entityManager.unwrap( Session.class )
+				.createCriteria( "ApplicationEvent" )
+				.list();
+			}
+			catch ( MappingException expected ) {
+				assertEquals( "Unknown entity: ApplicationEvent", expected.getMessage() );
+			}
+
+			List<Event> events = entityManager.unwrap( Session.class )
+			.createCriteria( Event.class.getName() )
+			.list();
+
+		});
+	}
+
+	@Entity(name = "ApplicationEvent")
+	public static class Event {
+
+		@Id
+		private Long id;
+
+		private String name;
+	}
 }