From 4bd891ac223668fe923b8ac40909be3096a1fe08 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. git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@3559 50f2f4bb-b051-0410-bef5-90022cba6387 --- 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