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",
- * "a mechanism for encapsulating storage, retrieval,
- * and search behaviour which emulates a collection of objects”.
- * 
+ * Indicates that an annotated class is a "Repository", originally defined by
+ * Domain-Driven Design (Evans, 2003) as "a mechanism for encapsulating storage,
+ * 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
- * annotated class is also clarified as to its role in the overall
- * application architecture for the purpose of tools, aspects, etc.
+ * {@link org.springframework.dao.DataAccessException DataAccessException} translation
+ * when used in conjunction with a {@link
+ * 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
- * of {@link Component @Component}, allowing for implementation classes
- * to be autodetected through classpath scanning.
+ * <p>As of Spring 2.5, this annotation also serves as a specialization of
+ * {@link Component @Component}, allowing for implementation classes to be autodetected
+ * 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
- * translation to any bean that carries the
- * {@link org.springframework.stereotype.Repository} annotation,
- * adding a corresponding {@link PersistenceExceptionTranslationAdvisor}
- * to the exposed proxy (either an existing AOP proxy or a newly generated
- * proxy that implements all of the target's interfaces).
+ * Bean post-processor that automatically applies persistence exception translation to any
+ * bean marked with Spring's @{@link org.springframework.stereotype.Repository Repository}
+ * annotation, adding a corresponding {@link PersistenceExceptionTranslationAdvisor} to
+ * the exposed proxy (either an existing AOP proxy or a newly generated 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}
- * interface, which are subsequently asked to translate candidate exceptions.
+ * {@link org.springframework.dao.support.PersistenceExceptionTranslator
+ * 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.
- * As a consequence, all that is usually needed to enable automatic exception
- * translation is marking all affected beans (such as DAOs) with the
- * <code>Repository</code> annotation, along with defining this post-processor
- * as bean in the application context.
+
+ * <p>All of Spring's applicable resource factories (e.g. {@link
+ * org.springframework.orm.hibernate3.LocalSessionFactoryBean LocalSessionFactoryBean},
+ * {@link org.springframework.orm.jpa.LocalEntityManagerFactoryBean
+ * LocalEntityManagerFactoryBean}) implement the {@code PersistenceExceptionTranslator}
+ * 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);