From d8245c800bd8be235cbe9b363d4f6fe7dc4a5e77 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Fri, 25 Sep 2009 08:17:12 +0000 Subject: [PATCH] Add minimal doc for JSR 330 support. --- spring-framework-reference/src/beans.xml | 135 ++++++++++++++------ spring-framework-reference/src/new-in-3.xml | 41 +++--- 2 files changed, 117 insertions(+), 59 deletions(-) diff --git a/spring-framework-reference/src/beans.xml b/spring-framework-reference/src/beans.xml index 618645df003..652f1a4a996 100644 --- a/spring-framework-reference/src/beans.xml +++ b/spring-framework-reference/src/beans.xml @@ -1077,11 +1077,11 @@ public class ExampleBean { properties themselves are not set until the bean is actually created. Beans that are singleton-scoped and set to be pre-instantiated (the default) are created when the container is - created. Scopes are defined in Otherwise, the bean is created only - when it is requested. Creation of a bean potentially causes a graph of - beans to be created, as the bean's dependencies and its dependencies' - dependencies (and so on) are created and assigned. + created. Scopes are defined in + Otherwise, the bean is created only when it is requested. Creation of + a bean potentially causes a graph of beans to be created, as the + bean's dependencies and its dependencies' dependencies (and so on) are + created and assigned. Circular dependencies @@ -2232,7 +2232,8 @@ support=support@example.co.uk If you use Java 5 and thus have access to source-level annotations, you may find to be of interest. + linkend="metadata-annotations-required" /> to be of + interest.
@@ -2566,13 +2567,16 @@ public class ReplacementComputeValue implements MethodReplacer { + Thread-scoped beans - As of Spring 3.0, a thread scope is available, but is - not registered by default. For more information, see the documentation for - SimpleThreadScope. + + As of Spring 3.0, a thread scope is + available, but is not registered by default. For more information, see + the documentation for SimpleThreadScope. For instructions on how to register this or any other custom scope, see - . + .
@@ -3111,10 +3115,12 @@ public class ReplacementComputeValue implements MethodReplacer { Suppose that you write your custom Scope implementation, and then register it as below. + - The example below uses SimpleThreadScope - which is included with Spring, but not registered by default. The instructions - would be the same for your own custom Scope implementations. + The example below uses SimpleThreadScope + which is included with Spring, but not registered by default. The + instructions would be the same for your own custom + Scope implementations. @@ -3528,8 +3534,7 @@ public final class Boot { BeanFactory type if the field, constructor, or method in question carries the @Autowired annotation. For more - information, see . + information, see . When an ApplicationContext creates a class that implements the org.springframework.beans.factory.BeanNameAware @@ -3846,12 +3851,12 @@ 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 BeanPostProcessor - implementation that ships with the Spring distribution which ensures - that JavaBean properties on beans that are marked with an (arbitrary) - annotation are actually (configured to be) dependency-injected with a - value. + shown in which + demonstrates the usage of a custom + BeanPostProcessor implementation that + ships with the Spring distribution which ensures that JavaBean + properties on beans that are marked with an (arbitrary) annotation are + actually (configured to be) dependency-injected with a value.
@@ -4178,12 +4183,16 @@ dataSource.url=jdbc:mysql:mydb adds support for JSR-250 annotations such as @Resource, @PostConstruct, and - @PreDestroy. Use of these annotations also - requires that certain BeanPostProcessors be - registered within the Spring container. As always, you can register them - as individual bean definitions, but they can also be implicitly registered - by including the following tag in an XML-based Spring configuration - (notice the inclusion of the context namespace): + @PreDestroy. Spring 3.0 adds support for + JSR-330 (Dependency Injection for Java) annotations contained in the + javax.inject package such as @Inject, + @Qualifier, @Named, and @Provider if the JSR330 jar is + present on the classpath. Use of these annotations also requires that + certain BeanPostProcessors be registered + within the Spring container. As always, you can register them as + individual bean definitions, but they can also be implicitly registered by + including the following tag in an XML-based Spring configuration (notice + the inclusion of the context namespace): <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" @@ -4250,12 +4259,22 @@ dataSource.url=jdbc:mysql:mydb
- <interfacename>@Autowired</interfacename> + <interfacename>@Autowired and @Inject</interfacename> As expected, you can apply the @Autowired annotation to "traditional" setter methods: + + JSR 330's @Inject annotation can be used in place of Spring's + @Autowired in the examples below. + @Inject does not have a required + property unlike Spring's @Autowire + annotation which as a required property to indicate if the value being + injected is optional. This behavior is enabled automatically if you + have the JSR 330 jar on the classpath. + + public class SimpleMovieLister { private MovieFinder movieFinder; @@ -4423,6 +4442,14 @@ dataSource.url=jdbc:mysql:mydb matches so that a specific bean is chosen for each argument. In the simplest case, this can be a plain descriptive value: + + Note that the JSR 330 @Qualifier + annotation can only be applied as a meta-annotation unlike Spring's + @Qualifier which takes a string property to discriminate among + multiple injection candidates and can be placed on annotation as well + as types, fields, methods, contstructors and parameters. + + public class MovieRecommender { @Autowired @@ -4537,6 +4564,14 @@ dataSource.url=jdbc:mysql:mydb @Qualifier annotation within your definition: + + You can use JSR 330's @Qualifier + annotation in the manner described below in place of + Spring's @Qualifier annotation. This + behavior is enabled automatically if you have the JSR 330 jar on the + classpath. + + @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Qualifier @@ -5046,6 +5081,18 @@ public class JpaMovieFinder implements MovieFinder { by including the annotation-config attribute with a value of false. + + + In Spring 3.0 RC1 you can use JSR 330's + @Named annotation in place of + stereotpye annotations and they will be automatically detected during + component-scanning. The value of the + @Named property will be used as the + Bean Name. At this time Spring default for bean scope will be applied + when using @Named. This behavior as well as mapping of JSR 330 and + JSR299 scopes is planned for Spring 3.0 GA assuming the JSRs are + stable at that time. +
@@ -5129,8 +5176,7 @@ public class JpaMovieFinder implements MovieFinder { A custom implementation of the org.springframework.core.type - .TypeFilter - interface. + .TypeFilter interface. @@ -5194,7 +5240,8 @@ public class FactoryMethodComponent { annotations that can be specified are @Scope, @Lazy, and custom qualifier annotations. Autowired fields and methods are supported as previously discussed, with - additional support for autowiring of @Bean methods: + additional support for autowiring of @Bean + methods: @Component public class FactoryMethodComponent { @@ -5265,12 +5312,20 @@ public class FactoryMethodComponent { @Service, and @Controller) that contains a name value will thereby provide that name to the - corresponding bean definition. If such an annotation contains no - name value or for any other detected component (such - as those discovered by custom filters), the default bean name generator - returns the uncapitalized non-qualified class name. For example, if the - following two components were detected, the names would be myMovieLister - and movieFinderImpl: + corresponding bean definition. + + + JSR 330's @Named annotation can be used as a mean to both detect + components and to provide them with a name. This behavior is enabled + automatically if you have the JSR 330 jar on the classpath. + + + If such an annotation contains no name value or + for any other detected component (such as those discovered by custom + filters), the default bean name generator returns the uncapitalized + non-qualified class name. For example, if the following two components + were detected, the names would be myMovieLister and + movieFinderImpl: @Service("myMovieLister") public class SimpleMovieLister { @@ -5516,7 +5571,8 @@ public class AppConfig { @Configuration-annotated class supports the regular lifecycle callbacks. Any classes defined with the @Bean annotation can use the @PostConstruct and @PreDestroy annotations from - JSR-250, see JSR-250 + JSR-250, see JSR-250 annotations for further details. The regular Spring The standard set of *Aware interfaces such as BeanFactoryAware, - BeanNameAware, + BeanNameAware, MessageSourceAware, Note: - This document is not yet available. It will - be available for the Spring 3.0 final release. + This document is not yet available. It will be available for the + Spring 3.0 final release.
@@ -186,7 +186,8 @@ - General-purpose type conversion system and UI field formatting system + General-purpose type conversion system and UI field formatting + system @@ -384,15 +385,18 @@ public class AppConfig {
- General purpose type conversion system and UI field formatting system - - A general purpose type conversion system has been introduced. - The system is currently used by SpEL for type coersion, and may also be used by a Spring Container when binding bean property values. - - - In addition, a ui.format system has been introduced for formatting UI field values. - This system provides a simpler and more robust alternative to JavaBean PropertyEditors in UI environments such as Spring MVC. - + General purpose type conversion system and UI field formatting + system + + A general purpose type conversion + system has been introduced. The system is currently used by SpEL + for type coersion, and may also be used by a Spring Container when + binding bean property values. + + In addition, a ui.format system + has been introduced for formatting UI field values. This system provides + a simpler and more robust alternative to JavaBean PropertyEditors in UI + environments such as Spring MVC.
@@ -431,9 +435,9 @@ public class AppConfig { the Object to XML mapping functionality mentioned earlier. - Refer to the section on MVC and - the RestTemplate - for more information. + Refer to the section on MVC and the RestTemplate for more + information.
@@ -452,9 +456,8 @@ public class AppConfig {
Declarative model validation - Hibernate Validator, JSR 303 - - Work in progress... not part of the Spring 3.0 M3 release. + JSR 303 support using Hibernate Validator as the + implementation.
@@ -464,7 +467,7 @@ public class AppConfig { use of the new @Async annotation (or EJB 3.1's @Asynchronous annotation). - JSF 2.0, JPA 2.0, etc + JSR 303, JSF 2.0, JPA 2.0, etc Work in progress... not part of the Spring 3.0 M3 release.