Clarify stereotype and exception translation Javadoc

Cite original inspiriation by Domain-Driven Design, but make clear the
flexible and general-purpose nature of Spring's stereotype annotations
such as @Repository and @Service.

Also update @Repository Javadoc with more explicit instructions about
switching on exception translation through use of
PersistenceExceptionTranslationPostProcessor, and update PETPP Javadoc
for style as well as concrete examples of 'resource factories' that
implement the PersistenceExceptionTranslator interface

Issue: SPR-8691

org.springframework.context/src/main/java/org/springframework/stereotype/Repository.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -23,24 +23,35 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Indicates that an annotated class is a "Repository",
+ * Indicates that an annotated class is a "Repository", originally defined by
- * "a mechanism for encapsulating storage, retrieval,
+ * Domain-Driven Design (Evans, 2003) as "a mechanism for encapsulating storage,
- * and search behaviour which emulates a collection of objects”.
+ * retrieval, and search behavior which emulates a collection of objects".
+ *
+ * <p>Teams implementing traditional J2EE patterns such as "Data Access Object"
+ * may also apply this stereotype to DAO classes, though care should be taken to
+ * understand the distinction between Data Access Object and DDD-style repositories
+ * before doing so. This annotation is a general-purpose stereotype and individual teams
+ * may narrow their semantics and use as appropriate.
  *
  * <p>A class thus annotated is eligible for Spring
- * {@link org.springframework.dao.DataAccessException} translation. The
+ * {@link org.springframework.dao.DataAccessException DataAccessException} translation
- * annotated class is also clarified as to its role in the overall
+ * when used in conjunction with a {@link
- * application architecture for the purpose of tools, aspects, etc.
+ * org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor
+ * PersistenceExceptionTranslationPostProcessor}. The annotated class is also clarified as
+ * to its role in the overall application architecture for the purpose of tooling,
+ * aspects, etc.
  *
- * <p>As of Spring 2.5, this annotation also serves as a specialization
+ * <p>As of Spring 2.5, this annotation also serves as a specialization of
- * of {@link Component @Component}, allowing for implementation classes
+ * {@link Component @Component}, allowing for implementation classes to be autodetected
- * to be autodetected through classpath scanning.
+ * through classpath scanning.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
  * @since 2.0
  * @see Component
- * @see org.springframework.context.annotation.ClassPathBeanDefinitionScanner
+ * @see Service
+ * @see org.springframework.dao.DataAccessException
+ * @see org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

org.springframework.context/src/main/java/org/springframework/stereotype/Service.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -23,7 +23,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Indicates that an annotated class is a "Service" (e.g. a business service facade).
+ * Indicates that an annotated class is a "Service", originally defined by Domain-Driven
+ * Design (Evans, 2003) as "an operation offered as an interface that stands alone in the
+ * model, with no encapsulated state."
+ *
+ * <p>May also indicate that a class is a "Business Service Facade" (in the Core J2EE
+ * patterns sense), or something similar. This annotation is a general-purpose stereotype
+ * and individual teams may narrow their semantics and use as appropriate.
  *
  * <p>This annotation serves as a specialization of {@link Component @Component},
  * allowing for implementation classes to be autodetected through classpath scanning.
@@ -31,7 +37,7 @@ import java.lang.annotation.Target;
  * @author Juergen Hoeller
  * @since 2.5
  * @see Component
- * @see org.springframework.context.annotation.ClassPathBeanDefinitionScanner
+ * @see Repository
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

org.springframework.transaction/src/main/java/org/springframework/dao/annotation/PersistenceExceptionTranslationPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -35,25 +35,28 @@ import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
 /**
- * Bean post-processor that automatically applies persistence exception
+ * Bean post-processor that automatically applies persistence exception translation to any
- * translation to any bean that carries the
+ * bean marked with Spring's @{@link org.springframework.stereotype.Repository Repository}
- * {@link org.springframework.stereotype.Repository} annotation,
+ * annotation, adding a corresponding {@link PersistenceExceptionTranslationAdvisor} to
- * adding a corresponding {@link PersistenceExceptionTranslationAdvisor}
+ * the exposed proxy (either an existing AOP proxy or a newly generated proxy that
- * to the exposed proxy (either an existing AOP proxy or a newly generated
+ * implements all of the target's interfaces).
- * proxy that implements all of the target's interfaces).
  *
  * <p>Translates native resource exceptions to Spring's
- * {@link org.springframework.dao.DataAccessException} hierarchy.
+ * {@link org.springframework.dao.DataAccessException DataAccessException} hierarchy.
  * Autodetects beans that implement the
- * {@link org.springframework.dao.support.PersistenceExceptionTranslator}
+ * {@link org.springframework.dao.support.PersistenceExceptionTranslator
- * interface, which are subsequently asked to translate candidate exceptions.
+ * PersistenceExceptionTranslator} interface, which are subsequently asked to translate
+ * candidate exceptions.
  *
- * <p>All of Spring's applicable resource factories implement the
+
- * <code>PersistenceExceptionTranslator</code> interface out of the box.
+ * <p>All of Spring's applicable resource factories (e.g. {@link
- * As a consequence, all that is usually needed to enable automatic exception
+ * org.springframework.orm.hibernate3.LocalSessionFactoryBean LocalSessionFactoryBean},
- * translation is marking all affected beans (such as DAOs) with the
+ * {@link org.springframework.orm.jpa.LocalEntityManagerFactoryBean
- * <code>Repository</code> annotation, along with defining this post-processor
+ * LocalEntityManagerFactoryBean}) implement the {@code PersistenceExceptionTranslator}
- * as bean in the application context.
+ * interface out of the box. As a consequence, all that is usually needed to enable
+ * automatic exception translation is marking all affected beans (such as Repositories or
+ * DAOs) with the {@code @Repository} annotation, along with defining this post-processor
+ * as a bean in the application context.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
@@ -63,6 +66,7 @@ import org.springframework.util.ClassUtils;
  * @see org.springframework.dao.DataAccessException
  * @see org.springframework.dao.support.PersistenceExceptionTranslator
  */
+@SuppressWarnings("serial")
 public class PersistenceExceptionTranslationPostProcessor extends ProxyConfig
 		implements BeanPostProcessor, BeanClassLoaderAware, BeanFactoryAware, Ordered {
 
@@ -115,7 +119,7 @@ public class PersistenceExceptionTranslationPostProcessor extends ProxyConfig
 			// Ignore AOP infrastructure such as scoped proxies.
 			return bean;
 		}
-		Class targetClass = AopUtils.getTargetClass(bean);
+		Class<?> targetClass = AopUtils.getTargetClass(bean);
 		if (AopUtils.canApply(this.persistenceExceptionTranslationAdvisor, targetClass)) {
 			if (bean instanceof Advised) {
 				((Advised) bean).addAdvisor(this.persistenceExceptionTranslationAdvisor);