From 15a8f776b9436fa8a74fc73b7004fdf830879c77 Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Tue, 13 Sep 2011 17:53:15 +0000 Subject: [PATCH] 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 --- .../stereotype/Repository.java | 35 +++++++++++------ .../springframework/stereotype/Service.java | 12 ++++-- ...enceExceptionTranslationPostProcessor.java | 38 ++++++++++--------- 3 files changed, 53 insertions(+), 32 deletions(-) diff --git a/org.springframework.context/src/main/java/org/springframework/stereotype/Repository.java b/org.springframework.context/src/main/java/org/springframework/stereotype/Repository.java index d97c7b23f5..0709b72bfe 100644 --- a/org.springframework.context/src/main/java/org/springframework/stereotype/Repository.java +++ b/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". + * + *

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. + * *

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. * - *

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. + *

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) diff --git a/org.springframework.context/src/main/java/org/springframework/stereotype/Service.java b/org.springframework.context/src/main/java/org/springframework/stereotype/Service.java index 58c055961d..0930738396 100644 --- a/org.springframework.context/src/main/java/org/springframework/stereotype/Service.java +++ b/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." + * + *

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. * *

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) diff --git a/org.springframework.transaction/src/main/java/org/springframework/dao/annotation/PersistenceExceptionTranslationPostProcessor.java b/org.springframework.transaction/src/main/java/org/springframework/dao/annotation/PersistenceExceptionTranslationPostProcessor.java index df8ec516d2..6f25b69a79 100644 --- a/org.springframework.transaction/src/main/java/org/springframework/dao/annotation/PersistenceExceptionTranslationPostProcessor.java +++ b/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). * *

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. * - *

All of Spring's applicable resource factories implement the - * 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 DAOs) with the - * Repository annotation, along with defining this post-processor - * as bean in the application context. + + *

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);