Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move reference docs => src/reference

Browse Source 
This change eliminates the spring-framework-reference subproject, moving
these sources into the root project's own src directory.

This makes sense because the reference docs span all submodules, and
also because api Javadoc is created at the root project level as well.
This means that both api and reference documentation output will now
reside in the root project's 'build' directory. This is more consistent
and easy to discover.
This commit is contained in:
Chris Beams
2012-01-25 13:11:43 +01:00
parent 0a07a0ed92
commit 62e94461f4
120 changed files with 0 additions and 985 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
src/reference/docbook/beans-standard-annotations.xml Normal file
View File

@@ -0,0 +1,200 @@
<?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 with 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>
<para>
If you are using Maven, the <interfacename>javax.inject</interfacename> artifact is available
in 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 can add the following dependency to your file pom.xml:
</para>
<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>
</para>
<para>As with <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>&mdash;</entry>
</row>
<row>
<entry>@Scope("singleton")</entry>
<entry>@Singleton</entry>
<entry>
<para>
The 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 a
scope other 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 is only intended to be used for creating your own annotations.
</para>
</entry>
</row>
<row>
<entry>@Qualifier</entry>
<entry>@Named</entry>
<entry>&mdash;</entry>
</row>
<row>
<entry>@Value</entry>
<entry>&mdash;</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>@Required</entry>
<entry>&mdash;</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>@Lazy</entry>
<entry>&mdash;</entry>
<entry>no equivalent</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</section>