SPR-7858

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@3844 50f2f4bb-b051-0410-bef5-90022cba6387

spring-framework-reference/src/beans-standard-annotations.xml

@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="beans-standard-annotations">
+  <title>Using JSR 330 standard annotations</title>
+  
+  <para>Starting from Spring 3.0, Spring offers support for JSR-330 standard annotations  (Dependency Injection).
+  Those annotations are scanned in the same way as the Spring annotations. You just need to have the relevant jars in your classpath.
+  </para>
+  <note>
+  If you are using Maven, the <interfacename>javax.inject</interfacename> artifact is available on the standard Maven repository (<ulink url="http://repo1.maven.org/maven2/javax/inject/javax.inject/1/">http://repo1.maven.org/maven2/javax/inject/javax.inject/1/</ulink>). You just need to add the following dependency to your file pom.xml:
+  <programlisting language="xml">
+		&lt;dependency&gt;
+			&lt;groupId&gt;javax.inject&lt;/groupId&gt;
+			&lt;artifactId&gt;javax.inject&lt;/artifactId&gt;
+			&lt;version&gt;1&lt;/version&gt;
+		&lt;/dependency&gt;
+  </programlisting>
+  </note>
+  
+  <section id="beans-inject-named">
+    <title>Dependency Injection with <interfacename>@Inject</interfacename> and <interfacename>@Named</interfacename></title>
+    <para>
+    Instead of <interfacename>@Autowired</interfacename>, <interfacename>javax.inject.Inject</interfacename> may be used as follows:
+    
+    <programlisting language="java">
+  import javax.inject.Inject;
+  public class SimpleMovieLister {
+
+  private MovieFinder movieFinder;
+
+  @Inject
+  public void setMovieFinder(MovieFinder movieFinder) {
+      this.movieFinder = movieFinder;
+  }
+  <lineannotation>// ...</lineannotation>
+}</programlisting>
+
+	As for <interfacename>@Autowired</interfacename>, it is possible to use <interfacename>@Inject</interfacename> at the class-level, field-level, method-level and constructor-argument level.
+
+	If you would like to use a qualified name for the dependency that should be injected, you should use the <interfacename>@Named</interfacename> annotation as follows:
+    <programlisting language="java">
+  import javax.inject.Inject;
+  import javax.inject.Named;
+  
+  public class SimpleMovieLister {
+
+  private MovieFinder movieFinder;
+
+  @Inject
+  public void setMovieFinder(@Named("main") MovieFinder movieFinder) {
+      this.movieFinder = movieFinder;
+  }
+  <lineannotation>// ...</lineannotation>
+}</programlisting>	
+	
+    </para>
+  </section>
+
+<section id="beans-named">
+    <title><interfacename>@Named</interfacename>: a standard equivalent to the <interfacename>@Component</interfacename> annotation</title>
+    <para>
+    Instead of <interfacename>@Component</interfacename>, <interfacename>javax.inject.Named</interfacename> may be used as follows:
+        <programlisting language="java">
+  import javax.inject.Inject;
+  import javax.inject.Named;
+  
+  @Named("movieListener")
+  public class SimpleMovieLister {
+
+  private MovieFinder movieFinder;
+
+  @Inject
+  public void setMovieFinder(MovieFinder movieFinder) {
+      this.movieFinder = movieFinder;
+  }
+  <lineannotation>// ...</lineannotation>
+}</programlisting>	
+</para>
+<para>
+It is very common to use <interfacename>@Component</interfacename> without specifying a name for the component. <interfacename>@Named</interfacename> can be used in a similar fashion:
+    <programlisting language="java">
+  import javax.inject.Inject;
+  import javax.inject.Named;
+  
+  @Named
+  public class SimpleMovieLister {
+
+  private MovieFinder movieFinder;
+
+  @Inject
+  public void setMovieFinder(MovieFinder movieFinder) {
+      this.movieFinder = movieFinder;
+  }
+  <lineannotation>// ...</lineannotation>
+}
+</programlisting>
+</para>
+<para>
+When using <interfacename>@Named</interfacename>, it is possible to use component-scanning in the exact same way as when using Spring annotations:
+    <programlisting language="xml">
+    &lt;beans&gt;
+    	&lt;context:component-scan base-package="org.example"/&gt;
+    &lt;/beans&gt;
+</programlisting>	
+</para>
+</section>
+<section id="beans-standard-annotations-limitations">
+    <title>Limitations of the standard approach</title>
+	<para>When working with standard annotations, it is important to know that some significant  features are not available as shown in the table below:</para>
+	
+	 <para><table id="annotations-comparison">
+          <title>Spring annotations vs standard annotations</title>
+
+          <tgroup cols="3">
+
+            <colspec colnum="1" colwidth="0.7*" />
+
+            <colspec colnum="2" colwidth="0.6*" />
+
+            <colspec colnum="3" colwidth="1.5*" />
+
+            <thead>
+              <row>
+                <entry>Spring</entry>
+
+                <entry>javax.inject.*</entry>
+
+                <entry>javax.inject restrictions / comments</entry>
+              </row>
+            </thead>
+
+            <tbody>
+              <row>
+                <entry>@Autowired</entry>
+
+                <entry>@Inject</entry>
+
+                <entry>@Inject has no 'required' attribute</entry>
+              </row>
+              <row>
+                <entry>@Component</entry>
+
+                <entry>@Named</entry>
+
+                <entry></entry>
+              </row>
+              <row>
+                <entry>@Scope("singleton")</entry>
+
+                <entry>@Singleton</entry>
+
+                <entry>
+                	<para>
+                		jsr-330 default scope is like Spring's <interfacename>prototype</interfacename>. However, in order to keep it consistent with Spring's general defaults, a jsr-330 bean declared in the Spring container is a <interfacename>singleton</interfacename> by default. In order to use another scope than <interfacename>singleton</interfacename>, you should use Spring's <interfacename>@Scope</interfacename> annotation.
+                	</para>
+                	<para>
+                		<interfacename>javax.inject</interfacename> also provides a <ulink url="http://download.oracle.com/javaee/6/api/javax/inject/Scope.html">@Scope</ulink> annotation. Nevertheless, this one only aims to be used for creating your own annotations. 
+                	</para>
+                </entry>
+              </row>              
+              <row>
+                <entry>@Qualifier</entry>
+
+                <entry>@Named</entry>
+
+                <entry></entry>
+              </row>  
+               <row>
+                <entry>@Value</entry>
+
+                <entry>-</entry>
+
+                <entry>no equivalent</entry>
+              </row> 
+               <row>
+                <entry>@Required</entry>
+
+                <entry>-</entry>
+
+                <entry>no equivalent</entry>
+              </row> 
+               <row>
+                <entry>@Lazy</entry>
+
+                <entry>-</entry>
+
+                <entry>no equivalent</entry>
+              </row> 
+            </tbody>     
+          </tgroup>
+         </table>
+        </para>
+	
+	</section>
+</section>

spring-framework-reference/src/beans.xml

@@ -942,6 +942,9 @@ List userList service.getUsernameList();
 
   <xi:include href="beans-classpath-scanning.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    
+  <xi:include href="beans-standard-annotations.xml"
+    xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
   <xi:include href="beans-java.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>