From 3d2dd447af6aeb0b17e98ec56d7f9b532ff2e05e Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Tue, 10 Aug 2010 22:13:55 +0000 Subject: [PATCH] Remove Chapter 27 from reference documentation (SPR-7433) Chapter 27 covered @Required and RequiredAnnotationBeanPostProcessor but did not hold together as a chapter unto itself. The IoC chapter already makes mention of @Required and RequiredAnnotationBeanPostProcessor, though not in quite as much detail as Chapter 27 did. Links have been updated throughout to reference these sections and Chatper 27 has been eliminated entirely. --- spring-framework-reference/src/beans.xml | 5 +- spring-framework-reference/src/metadata.xml | 188 ------------------ spring-framework-reference/src/new-in-2.xml | 2 +- .../src/spring-framework-reference.xml | 6 - .../src/xsd-configuration.xml | 2 +- 5 files changed, 4 insertions(+), 199 deletions(-) delete mode 100644 spring-framework-reference/src/metadata.xml diff --git a/spring-framework-reference/src/beans.xml b/spring-framework-reference/src/beans.xml index f219dedddea..a3523309527 100644 --- a/spring-framework-reference/src/beans.xml +++ b/spring-framework-reference/src/beans.xml @@ -4106,8 +4106,7 @@ org.springframework.scripting.groovy.GroovyMessenger@272961 Using callback interfaces or annotations in conjunction with a custom BeanPostProcessor implementation is a common means of extending the Spring IoC container. An example is - shown in which - demonstrates the usage of a custom + Spring's RequiredAnnotationBeanPostProcessor -- a BeanPostProcessor implementation that ships with the Spring distribution which ensures that JavaBean properties on beans that are marked with an (arbitrary) annotation are @@ -4458,7 +4457,7 @@ dataSource.url=jdbc:mysql:mydb annotations is a common means of extending the Spring IoC container. For example, Spring 2.0 introduced the possibility of enforcing required properties with the @Required annotation. As of + linkend="beans-required-annotation">@Required annotation. As of Spring 2.5, it is now possible to follow that same general approach to drive Spring's dependency injection. Essentially, the @Autowired annotation provides the same diff --git a/spring-framework-reference/src/metadata.xml b/spring-framework-reference/src/metadata.xml deleted file mode 100644 index 6ce4407adf3..00000000000 --- a/spring-framework-reference/src/metadata.xml +++ /dev/null @@ -1,188 +0,0 @@ - - - - Annotations and Source Level Metadata Support - -
- Introduction - - Java 5 introduced source-level metadata called annotations to - program elements, usually, classes and/or methods - - For example we might add metadata at the class level using - Spring's @Transactional annotation that is used to support Spring's - declarative transaction management features. - - @Transactional -public class PetStoreImpl implements PetStoreFacade, OrderService { - - We could also add metadata to a method as follows: - - public class PetStoreImpl implements PetStoreFacade, OrderService { - - . . . - - @Transactional - public void insertOrder(Order order) { - this.orderDao.insertOrder(order); - this.itemDao.updateQuantity(order); - } - - . . . -} - - The value of using annoations has been broadly embraced by the Java - community. For example, it's much less verbose than traditional XML - deployment descriptors. While it is desirable to externalize some things - from program source code, some important enterprise settings - notably - transaction characteristics - arguably belong in program source. - - Spring uses Java 5 annotations throughout the framework and across a - wide range of features such as DI, MVC, and AOP and supports standardized - annotations such as @PreDestroy and @PostConstruct specified by JSR-250, and - @Inject specified by JSR-330. This chapter describes the @Required annotation - and provides links to other parts of the documentation where the various - annotations are described in more detail. -
- -
- Annotations - - The Spring Framework ships with a number of custom Java 5+ - annotations. - -
- <interfacename>@Required</interfacename> - - The @Required annotation in the - org.springframework.beans.factory.annotation package - can be used to mark a property as being - 'required-to-be-set' (i.e. an annotated (setter) - method of a class must be configured to be dependency injected with a - value), else an Exception will be thrown by the - container at runtime. - - The best way to illustrate the usage of this annotation is to show - an example: - - public class SimpleMovieLister { - - // the SimpleMovieLister has a dependency on the MovieFinder - private MovieFinder movieFinder; - - // a setter method so that the Spring container can 'inject' a MovieFinder - @Required - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // business logic that actually 'uses' the injected MovieFinder is omitted... -} - - Hopefully the above class definition reads easy on the eye. Any - and all BeanDefinitions for the - SimpleMovieLister class must be provided with a - value. - - Let's look at an example of some XML configuration that will - not pass validation. - - <bean id="movieLister" class="x.y.SimpleMovieLister"> - <!-- whoops, no MovieFinder is set (and this property is @Required) --> -</bean> - - At runtime the following message will be generated by the Spring - container (the rest of the stack trace has been truncated). - - Exception in thread "main" java.lang.IllegalArgumentException: - Property 'movieFinder' is required for bean 'movieLister'. - - There is one last bit of Spring configuration that is required to - actually 'switch on' this behavior. Simply annotating - the 'setter' properties of your classes is not enough - to get this behavior. You need to enable a component that is aware of - the @Required annotation and that can - process it appropriately. - - This component is the - RequiredAnnotationBeanPostProcessor class. This - is a special BeanPostProcessor - implementation that is @Required-aware - and actually provides the 'blow up if this required property - has not been set' logic. It is very easy - to configure; simply drop the following bean definition into your Spring - XML configuration. - - <bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor"/> - - Finally, one can configure an instance of the - RequiredAnnotationBeanPostProcessor class to look - for another - Annotation type. This is great if you - already have your own @Required-style - annotation. Simply plug it into the definition of a - RequiredAnnotationBeanPostProcessor and you are - good to go. - - By way of an example, let's suppose you (or your organization / - team) have defined an attribute called @ - Mandatory. You can make a - RequiredAnnotationBeanPostProcessor instance - @Mandatory-aware like so: - - <bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor"> - <property name="requiredAnnotationType" value="your.company.package.Mandatory"/> -</bean> - - Here is the source code for the - @Mandatory annotation. You will need to - ensure that your custom annotation type is itself annotated with - appropriate annotations for its target and runtime retention - policy. - - package your.company.package; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.METHOD) -public @interface Mandatory { -} -
- -
- Other @Annotations in Spring - - Annotations are also used in a number of other places throughout - Spring. Rather than being described here, these annotations are - described in that section or chapter of the reference documentation to - which they are most relevant. - - - - - - - - - - - - - - - - - - - - - - -
-
- diff --git a/spring-framework-reference/src/new-in-2.xml b/spring-framework-reference/src/new-in-2.xml index b588e425a45..02ac799ecc8 100644 --- a/spring-framework-reference/src/new-in-2.xml +++ b/spring-framework-reference/src/new-in-2.xml @@ -503,7 +503,7 @@ - + diff --git a/spring-framework-reference/src/spring-framework-reference.xml b/spring-framework-reference/src/spring-framework-reference.xml index 30396eaeac4..29001e840a7 100644 --- a/spring-framework-reference/src/spring-framework-reference.xml +++ b/spring-framework-reference/src/spring-framework-reference.xml @@ -453,10 +453,6 @@ - - - - @@ -477,8 +473,6 @@ - - diff --git a/spring-framework-reference/src/xsd-configuration.xml b/spring-framework-reference/src/xsd-configuration.xml index d53d9f4dfd1..2d5e05b9127 100644 --- a/spring-framework-reference/src/xsd-configuration.xml +++ b/spring-framework-reference/src/xsd-configuration.xml @@ -765,7 +765,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schem
<literal><annotation-config/></literal> Activates the Spring infrastructure for various annotations to be detected in bean classes: - Spring's @Required + Spring's @Required and @Autowired, as well as JSR 250's @PostConstruct, @PreDestroy and @Resource (if available), and JPA's