Javadoc coverage of package metadata detection (supported for Hibernate, not needed for EclipseLink and OpenJPA)

Issue: SPR-10910

spring-orm/src/main/java/org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.java

@@ -149,6 +149,11 @@ public class LocalContainerEntityManagerFactoryBean extends AbstractEntityManage
 	 * <p>Default is none. Specify packages to search for autodetection of your entity
 	 * classes in the classpath. This is analogous to Spring's component-scan feature
 	 * ({@link org.springframework.context.annotation.ClassPathBeanDefinitionScanner}).
+	 * <p><p>Note: There may be limitations in comparison to regular JPA scanning.</b>
+	 * In particular, JPA providers may pick up annotated packages for provider-specific
+	 * annotations only when driven by {@code persistence.xml}. As of 4.1, Spring's
+	 * scan can detect annotated packages as well if supported by the given
+	 * {@link JpaVendorAdapter} (e.g. for Hibernate).
 	 * <p>If no explicit {@link #setMappingResources mapping resources} have been
 	 * specified in addition to these packages, Spring's setup looks for a default
 	 * {@code META-INF/orm.xml} file in the classpath, registering it as a mapping

spring-orm/src/main/java/org/springframework/orm/jpa/persistenceunit/DefaultPersistenceUnitManager.java

@@ -215,6 +215,11 @@ public class DefaultPersistenceUnitManager
 	 * may live next to regularly defined units originating from {@code persistence.xml}.
 	 * Its name is determined by {@link #setDefaultPersistenceUnitName}: by default,
 	 * it's simply "default".
+	 * <p><p>Note: There may be limitations in comparison to regular JPA scanning.</b>
+	 * In particular, JPA providers may pick up annotated packages for provider-specific
+	 * annotations only when driven by {@code persistence.xml}. As of 4.1, Spring's
+	 * scan can detect annotated packages as well if supported by the given
+	 * {@link org.springframework.orm.jpa.JpaVendorAdapter} (e.g. for Hibernate).
 	 * <p>If no explicit {@link #setMappingResources mapping resources} have been
 	 * specified in addition to these packages, this manager looks for a default
 	 * {@code META-INF/orm.xml} file in the classpath, registering it as a mapping

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/EclipseLinkJpaVendorAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,11 +33,15 @@ import org.springframework.orm.jpa.JpaDialect;
  * Persistence Services (EclipseLink). Developed and tested against EclipseLink 2.4.
  *
  * <p>Exposes EclipseLink's persistence provider and EntityManager extension interface,
- * and supports {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * and adapts {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * No support for the detection of annotated packages (through
+ * {@link org.springframework.orm.jpa.persistenceunit.SmartPersistenceUnitInfo#getManagedPackages()})
+ * since EclipseLink doesn't use package-level metadata.
  *
  * @author Juergen Hoeller
  * @author Thomas Risberg
  * @since 2.5.2
+ * @see EclipseLinkJpaDialect
  * @see org.eclipse.persistence.jpa.PersistenceProvider
  * @see org.eclipse.persistence.jpa.JpaEntityManager
  */

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/HibernateJpaVendorAdapter.java

@@ -40,7 +40,12 @@ import org.springframework.orm.jpa.JpaDialect;
  * Hibernate EntityManager. Developed and tested against Hibernate 3.6 and 4.2/4.3.
  *
  * <p>Exposes Hibernate's persistence provider and EntityManager extension interface,
- * and supports {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * and adapts {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * Also supports the detection of annotated packages (through
+ * {@link org.springframework.orm.jpa.persistenceunit.SmartPersistenceUnitInfo#getManagedPackages()}),
+ * e.g. containing Hibernate {@link org.hibernate.annotations.FilterDef} annotations,
+ * along with Spring-driven entity scanning which requires no {@code persistence.xml}
+ * ({@link org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean#setPackagesToScan}).
  *
  * <p>Note that the package location of Hibernate's JPA support changed from 4.2 to 4.3:
  * from {@code org.hibernate.ejb.HibernateEntityManager(Factory)} to
@@ -51,6 +56,9 @@ import org.springframework.orm.jpa.JpaDialect;
  * @author Juergen Hoeller
  * @author Rod Johnson
  * @since 2.0
+ * @see HibernateJpaDialect
+ * @see org.hibernate.ejb.HibernatePersistence
+ * @see org.hibernate.ejb.HibernateEntityManager
  */
 public class HibernateJpaVendorAdapter extends AbstractJpaVendorAdapter {
 

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/OpenJpaVendorAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,11 +33,15 @@ import org.springframework.orm.jpa.JpaDialect;
  * Developed and tested against OpenJPA 2.2.
  *
  * <p>Exposes OpenJPA's persistence provider and EntityManager extension interface,
- * and supports {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * and adapts {@link AbstractJpaVendorAdapter}'s common configuration settings.
+ * No support for the detection of annotated packages (through
+ * {@link org.springframework.orm.jpa.persistenceunit.SmartPersistenceUnitInfo#getManagedPackages()})
+ * since OpenJPA doesn't use package-level metadata.
  *
  * @author Costin Leau
  * @author Juergen Hoeller
  * @since 2.0
+ * @see OpenJpaDialect
  * @see org.apache.openjpa.persistence.PersistenceProviderImpl
  * @see org.apache.openjpa.persistence.OpenJPAEntityManager
  */

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/SpringHibernateEjbPersistenceProvider.java

@@ -33,7 +33,9 @@ import org.springframework.orm.jpa.persistenceunit.SmartPersistenceUnitInfo;
  * <p>Compatible with Hibernate 3.6 as well as 4.0-4.2.
  *
  * @author Juergen Hoeller
+ * @author Joris Kuipers
  * @since 4.1
+ * @see Ejb3Configuration#addPackage
  */
 class SpringHibernateEjbPersistenceProvider extends HibernatePersistence {