root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Chris Beams 2010-08-10 22:13:55 +00:00
parent abf523698c
commit 3d2dd447af
5 changed files with 4 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
spring-framework-reference/src/beans.xml
View File

@ -4106,8 +4106,7 @@ org.springframework.scripting.groovy.GroovyMessenger@272961</programlisting>
<para>Using callback interfaces or annotations in conjunction with a
custom <interfacename>BeanPostProcessor</interfacename> implementation
is a common means of extending the Spring IoC container. An example is
shown in <xref linkend="metadata-annotations-required" /> which
demonstrates the usage of a custom
Spring's <classname>RequiredAnnotationBeanPostProcessor</classname> -- a
<interfacename>BeanPostProcessor</interfacename> 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</programlisting>
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 <link
linkend="metadata-annotations-required">@Required</link> annotation. As of
linkend="beans-required-annotation">@Required</link> annotation. As of
Spring 2.5, it is now possible to follow that same general approach to
drive Spring's dependency injection. Essentially, the
<interfacename>@Autowired</interfacename> annotation provides the same

188
spring-framework-reference/src/metadata.xml
View File

@ -1,188 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="metadata">
<title>Annotations and Source Level Metadata Support</title>
<section id="metadata-introduction">
<title>Introduction</title>
<para>Java 5 introduced source-level metadata called annotations to
program elements, usually, classes and/or methods</para>
<para>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.</para>
<programlisting language="java">@Transactional
public class PetStoreImpl implements PetStoreFacade, OrderService {</programlisting>
<para>We could also add metadata to a method as follows:</para>
<programlisting>public class PetStoreImpl implements PetStoreFacade, OrderService {
. . .
@Transactional
public void insertOrder(Order order) {
this.orderDao.insertOrder(order);
this.itemDao.updateQuantity(order);
}
. . .
}</programlisting>
<para>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.</para>
<para>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.</para>
</section>
<section id="metadata-annotations">
<title>Annotations</title>
<para>The Spring Framework ships with a number of custom Java 5+
annotations.</para>
<section id="metadata-annotations-required">
<title><interfacename>@Required</interfacename></title>
<para>The <interfacename>@Required</interfacename> annotation in the
<literal>org.springframework.beans.factory.annotation</literal> package
can be used to <emphasis>mark</emphasis> a property as being
<emphasis>'required-to-be-set'</emphasis> (i.e. an annotated (setter)
method of a class must be configured to be dependency injected with a
value), else an <classname>Exception</classname> will be thrown by the
container at runtime.</para>
<para>The best way to illustrate the usage of this annotation is to show
an example:</para>
<programlisting language="java">public class SimpleMovieLister {
<lineannotation>// the <classname>SimpleMovieLister</classname> has a dependency on the <interfacename>MovieFinder</interfacename></lineannotation>
private MovieFinder movieFinder;
<lineannotation>// a setter method so that the Spring container can 'inject' a <interfacename>MovieFinder</interfacename></lineannotation>
@Required
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
<lineannotation>// business logic that actually 'uses' the injected <interfacename>MovieFinder</interfacename> is omitted...</lineannotation>
}</programlisting>
<para>Hopefully the above class definition reads easy on the eye. Any
and all <interfacename>BeanDefinitions</interfacename> for the
<classname>SimpleMovieLister</classname> class must be provided with a
value.</para>
<para>Let's look at an example of some XML configuration that will
<emphasis role="bold">not</emphasis> pass validation.</para>
<programlisting language="xml">&lt;bean id="movieLister" class="x.y.SimpleMovieLister"&gt;
<lineannotation>&lt;!-- whoops, no MovieFinder is set (and this property is <interfacename>@Required</interfacename>) --&gt;</lineannotation>
&lt;/bean&gt;</programlisting>
<para>At runtime the following message will be generated by the Spring
container (the rest of the stack trace has been truncated).</para>
<programlisting>Exception in thread "main" java.lang.IllegalArgumentException:
Property 'movieFinder' is required for bean 'movieLister'.</programlisting>
<para>There is one last bit of Spring configuration that is required to
actually <emphasis>'switch on'</emphasis> this behavior. Simply annotating
the <emphasis>'setter'</emphasis> properties of your classes is not enough
to get this behavior. You need to enable a component that is aware of
the <interfacename>@Required</interfacename> annotation and that can
process it appropriately.</para>
<para>This component is the
<classname>RequiredAnnotationBeanPostProcessor</classname> class. This
is a special <interfacename>BeanPostProcessor</interfacename>
implementation that is <interfacename>@Required</interfacename>-aware
and actually provides the <emphasis>'blow up if this required property
has not been set'</emphasis> logic. It is <emphasis>very</emphasis> easy
to configure; simply drop the following bean definition into your Spring
XML configuration.</para>
<programlisting language="xml">&lt;bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor"/&gt;</programlisting>
<para>Finally, one can configure an instance of the
<classname>RequiredAnnotationBeanPostProcessor</classname> class to look
for <emphasis>another</emphasis>
<interfacename>Annotation</interfacename> type. This is great if you
already have your own <interfacename>@Required</interfacename>-style
annotation. Simply plug it into the definition of a
<classname>RequiredAnnotationBeanPostProcessor</classname> and you are
good to go.</para>
<para>By way of an example, let's suppose you (or your organization /
team) have defined an attribute called @
<interfacename>Mandatory</interfacename>. You can make a
<classname>RequiredAnnotationBeanPostProcessor</classname> instance
<interfacename>@Mandatory</interfacename>-aware like so:</para>
<programlisting language="xml">&lt;bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor"&gt;
&lt;property name="requiredAnnotationType" value="your.company.package.Mandatory"/&gt;
&lt;/bean&gt;</programlisting>
<para>Here is the source code for the
<interfacename>@Mandatory</interfacename> annotation. You will need to
ensure that your custom annotation type is itself annotated with
appropriate annotations for its target and runtime retention
policy.</para>
<programlisting language="java">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 {
}</programlisting>
</section>
<section id="metadata-annotations-other">
<title>Other @Annotations in Spring</title>
<para>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.</para>
<itemizedlist>
<listitem>
<para><xref linkend="transaction-declarative-annotations" /></para>
</listitem>
<listitem>
<para><xref linkend="aop-atconfigurable" /></para>
</listitem>
<listitem>
<para><xref linkend="aop-ataspectj" /></para>
</listitem>
<listitem>
<para><xref linkend="beans-annotation-config" /></para>
</listitem>
<listitem>
<para><xref linkend="beans-classpath-scanning" /></para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>

2
spring-framework-reference/src/new-in-2.xml
View File

@ -503,7 +503,7 @@
<xref linkend="beans-annotation-config"/>
</listitem>
<listitem>
<xref linkend="metadata-annotations-required"/>
<xref linkend="beans-required-annotation"/>
</listitem>
<listitem>
<xref linkend="transaction-declarative-annotations"/>

6
spring-framework-reference/src/spring-framework-reference.xml
View File

@ -453,10 +453,6 @@
<listitem>
<para><xref linkend="dynamic-language" /></para>
</listitem>
<listitem>
<para><xref linkend="metadata" /></para>
</listitem>
</itemizedlist>
</partintro>
@ -477,8 +473,6 @@
<xi:include href="dynamic-languages.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="metadata.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
<!-- back matter -->

2
spring-framework-reference/src/xsd-configuration.xml
View File

@ -765,7 +765,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schem
<section id="xsd-config-body-schemas-context-ac">
<title><literal>&lt;annotation-config/&gt;</literal></title>
<para>Activates the Spring infrastructure for various annotations to be detected in bean classes:
Spring's <link linkend="metadata-annotations-required"><interfacename>@Required</interfacename></link>
Spring's <link linkend="beans-required-annotation"><interfacename>@Required</interfacename></link>
and <link linkend="beans-annotation-config"><interfacename>@Autowired</interfacename></link>, as well as
JSR 250's <interfacename>@PostConstruct</interfacename>, <interfacename>@PreDestroy</interfacename> and
<interfacename>@Resource</interfacename> (if available), and JPA's