<document>
  <header>
    <product>resin</product>
    <title>Dependency Injection for Resources</title>
    <type>tutorial</type>
    <description>
<p>
The Dependency Injection pattern simplifies application
code, and increases configuration flexibility by deferring
component configuration and assembly to the container.

Resin calls setters on the configured objects to assemble the
resource dependencies.</p>

</description>
 <tutorial-startpage>movies?director=Jackson</tutorial-startpage>

</header>

  <body>
    <summary/>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/resin-web.xml"/>
    <td>Configures the movie application
<tr><td><viewfile-link file="WEB-INF/classes/example/Movie.java"/>
    <td>The movie bean.
<tr><td><viewfile-link file="WEB-INF/classes/example/MovieFinder.java"/>
    <td>The MovieFinder interface
<tr><td><viewfile-link file="WEB-INF/classes/example/MovieFinderImpl.java"/>
    <td>A MovieFinder implementation
<tr><td><viewfile-link file="WEB-INF/classes/example/MovieLister.java"/>
    <td>The MovieLister to be configured with the finder implementation
<tr><td><viewfile-link file="WEB-INF/classes/example/MovieServlet.java"/>
    <td>The MovieServlet to be configured with the finder implementation
</deftable>

</section>

<section title="Dependency Injection">

<p>
<i>Dependency injection</i> is a term used to describe a separation between the
implementation of an object and the construction of an object it
depends on, and the ability for a container like Resin
to resolve the dependency.
</p>

<p>Since the container instantiates and assembles the dependencies,
the code is simpler and the configuration is more flexible.
It's easy to substitute test implementations as the
dependent resources, for example.
</p>

<p>The MovieFinder example for this tutorial comes from
Martin Fowler's
<a href="http://www.martinfowler.com/articles/injection.html">Dependency
Injection</a> article.</p>

<p>More details on Resin's configuration is available at the <a
href="config|init.xtp">bean-style configuration</a> page.</p>

<section title="Configuration as Assembly Line">

<p><figure src="../../../../images/assembler-eg1.gif"/></p>

<p>The Dependency Injector pattern could also be called
the Assembly pattern because it resembles an assembly
line making cars.<p>

<ul>
<li>Parts are interchangable components like wheels.  The parts might
also be assembled like an engine in a car.
<li>Parts are attached to the Chassis like a car's frame receiving an
engine.
<li>The Registry is holds partially-completed parts like a factory
conveyor belt.
<li>The Assembler provides the Registry and assembles the Chassis and
Parts into a completed resource.
</ul>

<p>Some important points:</p>

<ul>
<li>The application code (Chassis and Parts) is independent of the
Assembler.
<li>Parts are interchangeable.
<li>The code needs to select an assembly pattern, e.g. Setter Injection.
</ul>

<p>Because the Assembler is independent of the code, a project could
change the Assembler from Spring to Resin with no code changes.
So using the Assembler/Dependency Injection pattern reduces
dependencies on the framework.  Only the configuration changes
when changing Assemblers, not the code.</p>

<p>While testing, the test case or the harness plays the Assembler
role, simplifying the test suite and ensuring that the code under test
is the production code.  A test can create a test implementation of
the Part, e.g. <code>TestMovieFinder</code>, for testing.</p>

<p>In some cases, the application code can provide its own
<code>assemble()</code> method for situations where the container is
incapabile of assembling the components.  For example, the
<code>MovieServlet</code> could create an <code>assemble()</code>
method that grabbed the <code>MovieLocator</code> from JNDI.</p>

</section>

</section>

<section title="Code for the Dependency Injection pattern">

<p>The only code specific to the setter-based injection pattern
is the addition of a setter method for the dependent resource.
In many application, that setter will already be written, so
no additional code would be required.</p>

<p>Either an interface or a class can be used
for the dependent resource, depending on the application's
architecture.  This example uses both: the MovieListener uses a dependent
MovieFinder interface, and the MovieServlet uses the dependent
MovieListener class.</p>

<example>
public class MovieListener {
  private MovieFinder _finder;

  public void setMovieFinder(MovieFinder finder)
  {
    _finder = finder;
  }

  ...
}
</example>

</section>

<section title="Configuration">

<example title="Configuring the MovieFinder">
&lt;resource jndi-name="movie-finder"
          type="example.MovieFinderImpl">
  &lt;init>
    &lt;movie director="Jackson" title="Fellowship of the Ring"/>
    &lt;movie director="Jackson" title="The Two Towers"/>

    &lt;movie director="Lucas" title="Star Wars"/>

    &lt;movie director="Gilliam" title="Brazil"/>
  &lt;/init>
&lt;/resource>
</example>

<example title="Configuring the MovieLister">
&lt;resource jndi-name="movie-lister"
          type="example.MovieLister">
  &lt;init>
    &lt;movie-finder>\${jndi("movie-finder")}&lt;/movie-finder>
  &lt;/init>
&lt;/resource>
</example>

</section>

<section title="JMX as a Registry">

<p>Resin can use JMX as the registry instead of JNDI. In this example,
only the configuration needs to be changed.  JMX uses the mbean-name
instead of the jndi-name, and the jndi uses the "mbean:" schema.
</p>

<example title="Configuring the MovieFinder">
&lt;resource mbean-name="example:type=MovieFinder"
          mbean-interface="example.MovieFinder"
          type="example.MovieFinderImpl">
  &lt;init>
    &lt;movie director="Jackson" title="Fellowship of the Ring"/>
    &lt;movie director="Jackson" title="The Two Towers"/>

    &lt;movie director="Lucas" title="Star Wars"/>
  &lt;/init>
&lt;/resource>

&lt;resource jndi-name="movie-lister"
          type="example.MovieLister">
  &lt;init>
    &lt;movie-finder>\${jndi("mbean:example:type=MovieFinder")}&lt;/movie-finder>
  &lt;/init>
&lt;/resource>
</example>

<p>Using JMX as the registry has some restrictions over JNDI.
JMX requires an interface class. So the servlet's &lt;movie-lister>
setting can't be stored in JMX.  JMX also can't support object references.
All JMX getters and method values are value objects, never references.
This limits the kinds of structures you can use easily with JMX.</p>

</section>

<section title="Dependency Injection for Servlets">

<p>The Dependency Injection pattern is just as useful for servlet
configuration as it is for resources.  This example makes the
MovieLister a parameter of the servlet.  The resin-web.xml will configure
the servlet with the appropriate MovieLister</p>

<p>The advantages of using dependency injection for the servlet are
the same as for the resource:</p>

<ul>
<li>The servlet code becomes simpler.
<li>The servlet is no longer dependent on JNDI.
<li>The servlet is more easily testable by configuring it with test
versions of the MovieListener.
</ul>

<example title="Configuring the MovieServlet">
&lt;servlet servlet-name="movies"
         type="example.MovieServlet">
  &lt;init>
    &lt;movie-lister>\${jndi("movie-lister")}&lt;/movie-lister>
  &lt;/init>
&lt;/resource>
</example>

<section title="Compatibility">

<p>For compatibility, Servlets will generally add an
<code>assemble()</code> method to cover cases where the
container cannot assemble the Servlet.  The
<code>assemble()</code> method will call JNDI with appropriate names
from the &lt;init-param> values to assemble the dependencies.</p>

</section>

</section>

<section title="See also">

<ul>
<li><a href="doc|config|init">Bean-style init</a>
<li><a href="db|tutorial/jdbc-ioc/index.xtp">Servlet DataSource Configuration</a>
<li><a href="protocols|tutorial/hessian-ioc/index.xtp">Hessian
with Dependency Injection</a>
</ul>

</section>

  </body>
</document>
