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”.
- * 
- * <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.
+ * 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>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>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 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.
  *
  * @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)