resin-ioc.xtp

RESIN 3.2 最新源码

<li><code>@SessionScoped</code> creates a new instance for each
HTTP session, reusing the instance for the same session.</li>
<li><code>@ApplicationScoped</code> uses a single instance in each
web-app.  For web applications, this will have the same lifecycle as
<code>@Singleton</code>.</li>
<li><code>@Singleton</code> uses a single instance in the
container.  For web applications, this will have the same lifecycle as
<code>@ApplicationScoped</code>.</li>
</ul>

<p>An example scoped resource might be a <code>Calculator</code> object which
is used only for a single instance.  It might fill the arguments while
processing a form and then calculate the result.  The
<code>@RequestScoped</code> makes sure scripts receive the same instance
each time it's called.</p>

<example title="Example: @RequestScoped Calculator">
import javax.webbeans.RequestScoped;
import javax.webbeans.Component;

@RequestScoped
@Component
public class Calculator {
  private int _a;
  private int _b;

  public void setA(int a) { _a = a; }
  public void setB(int b) { _b = b; }

  public int getSum() { return _a + _b; }
}
</example>

<p>You could also register the same calculator using XML:</p>

<example title="Example: resin-web.xml Calculator">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;component class="example.Calculator" scope="request"/>

&lt;/web-app>
</example>

</s2>

<s2 title="@New Component Discovery">

<p>The <code>@New</code> annotation automatically registers the target
class with the WebBeans registry and tells Resin to create a new instance
of the bean, even if the bean has a singleton scope definition.
Since <code>@New</code> replaces <code>@In</code>, it can be used anywhere
<code>@In</code> can be used.</p>

<example title="Example: MyServlet.java">
import javax.webbeans.New;

public class MyServlet extends GenericServlet {
  @New Movie _movie;

  ...
}
</example>

<p>The <code>Movie</code> is identical to the movie class defined
above, but doesn't need the <code>@Component</code> annotation and
doesn't need the <code>META-INF/web-beans.xml</code> marker file.
In many cases, the <code>@New</code> annotation can replace the Java
<code>new</code> operator.  If your application starts
using <code>@New</code> consistently, it can add injection capabilities to
a growing share of your code, letting you simplify and refactor incrementally.
</p>

<example title="Example: Movie.java">
public class Movie {
  private String _title;

  public String getTitle() { return _title; }
  public void setTitle(String title) { _title = title; }

  @PostConstruct
  public void init() { ... }
}
</example>

</s2>

<s2 title="Lifecycle: @PostConstruct and @PreDestroy">

<p>If your service needs to initialize itself after being configured, it
can annotation an initialization method with <code>@PostConstruct</code>.
After Resin creates, injects, and configures your component, it will call any
<code>@PostConstruct</code> methods.   Long-lived services or services that
need to register themselves with other services will typically need to
use the <code>@PostConstruct</code> annotation.</p>

<p>At the end of a component's lifetime, you might need to close some
resources, e.g. closing a socket or delisting from a timer service.  Resin
will call any component method marked with <code>@PreDestroy</code>
before it destroys the method.</p>

<p>For example, a <code>TimerService</code> may want to schedule a event
every 2 seconds.  The <code>@PostConstruct</code> method will start the timer
and the <code>@PreDestroy</code> method will stop the timer.</p>

<example title="Example: Timer Service">
import javax.annotation.PostConstruct;
import javax.webbeans.In;
import javax.webbeans.Component;
import java.util.concurrent.ScheduledExecutorService;
import com.caucho.webbeans.Singleton;

@Component
@Singleton
public class TimerService {
  @In ScheduledExecutorService _timer;

  @PostConstruct
  public void init()
  {
    _timerFuture = _timer.scheduleAtFixedRate(this, 0, 2, TimeUnit.SECONDS);
  }

  ...

  @PreDestroy
  public void close()
  {
    _timerFuture.cancel(false);
  }
}
</example>

</s2>

</s1>

<s1 title="XML configuration">

<p>You can register your components and services with Resin using the
resin.xml or resin-web.xml files.  Since the WebBeans registry is integrated
with Resin, your services be treated as first-class components along with
the Resin resources.  Although most components will not need XML, there
are a few advantages for the small number of services which do use XML.</p>

<p>The XML-configuration lets you customize your application for a
particular environment, e.g. setting configuration parameters.  For example,
Resin's <code>&lt;database></code> needs to select a database driver and
configure the URL, user and password of the database as well as configuring
connection pooling parameters.  Some application services will also need
configuration.</p>

<p>In addition, the XML-configuration documents the services
you've enabled.  For heavyweight services, this documentation is critical,
while lightweight components do not need this extra housekeeping overhead.</p>

<s2 title="bean and component registration">

<p>The <code>&lt;bean></code> and <code>&lt;component></code> tags register
application classes with Resin.  The two tags are identical except for the
expected lifecycle: <code>&lt;bean></code> configures singleton services while
<code>&lt;component></code> configures component template classes.
In other words, the default scope of a <code>&lt;bean></code>
is <code>@Singleton</code> while the default scope
of a <code>&lt;component></code> is <code>@Dependent</code>.
A <code>&lt;component></code> will create a new instance each time it's
injected or referenced, while a <code>&lt;bean></code> always returns
the same singleton instance.</p>

<example title="Example: bean and component resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;bean class="example.MyService"/>

  &lt;component class="example.MyService"/>

&lt;/web-app>
</example>

<p>The <code>&lt;bean></code> and <code>&lt;component></code> tags have a
number of optional attributes:</p>

<deftable title="bean and component attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>binding</td>
  <td>the <code>@BindingType</code> annotations for custom bean matching</td>
</tr>
<tr>
  <td>class</td>
  <td>the Java class of the bean or component (required)</td>
</tr>
<tr>
  <td>init</td>
  <td>optional configuration/initialization block, using bean-style assignment</td>
</tr>
<tr>
  <td>name</td>
  <td>the instance name, used for <code>@Named</code> and script integration</td>
</tr>
<tr>
  <td>scope</td>
  <td>specifies scope of the instances: request, conversation, session, application, or singleton</td>
</tr>
</deftable>

</s2>

<s2 title="Bean property configuration">

<p>Resin's XML configuration uses the standard JavaBeans patterns to
configure properties.  Resin uses the same mechanism for all of its own
configuration parsing, including every JavaEE configuration file, the
resin-web.xml and the resin.xml itself.  So your application will have
all the configuration flexibility it needs.</p>

<p>Since the component beans can use WebBeans
injections, injected components are typically not configured in
the resin-web.conf, avoiding the need for tags like <code>&lt;ref></code>.</p>

<example title="Example: Hello.java">
public class Hello {
  private String _greeting = "default";

  public void setGreeting(String greeting) { _greeting = greeting; }
  public String getGreeting() { return _greeting; }
}
</example>

<p>The basic example sets a <code>greeting</code> property of a hello, world
bean.  In this example, we're configuring a singleton, but the
<code>&lt;init></code> works for dependent components as well.  Resin will
apply the configuration to the instance as part of the creation process.</p>

<example title="Example: resin-web.xml configuring a singleton">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;bean class="example.Hello">
    &lt;init>
      &lt;greeting>Hello, World&lt;/greeting>
    &lt;/init>
  &lt;/bean>

&lt;/web-app>
</example>

<p>Resin's configuration uses 5 basic bean patterns, extending the JavaBeans
conventions.  It can configure literal values like string and integers as
well as configuring other beans.  Any component bean configured by Resin
has full access to <code>@In</code> injection as well as
the standard <code>@PostConstruct</code> annotations.  Sub-beans are
not automatically registered with WebBeans, i.e. they act like the
servlet configuration.</p>

<p>(Currently the patterns are name-based like JavaBeans, since Resin
was designed before annotations.  We may add configuration annotations
in the future.</p>

<example title="Example: Bean configuration patterns">
  public void setFoo(String data);

  public void setFoo(Movie data);

  public void addFoo(Movie data);

  public Movie createFoo();

  public void setText(String data);
</example>

<ol>
<li><code>setFoo(String)</code> configures a standard JavaBeans-style
literal.</li>
<li><code>setFoo(Movie)</code> creates a new instance of <code>Movie</code> and recursively configures it.</li>
<li><code>addFoo(Movie)</code> also creates a new instance of <code>Movie</code> and recursively configures it.  <code>addFoo</code> is an easy way of
configuring lists.</li>
<li><code>Movie createFoo()</code> lets the bean create
the <code>Movie</code> instance.  Many beans can
use <code>createFoo</code> with inner classes to
handle complex configuration.</li>
<li><code>setText</code> is called with the text contents of
the XML.  Value-style beans will use this.  (somewhat rare).</li>
</ol>

<p>As mentioned above, Resin uses these 5 patterns to handle all of the
JavaEE configuration files.  In particular, the <code>createFoo</code>
pattern returning inner classes is very handy for some complicated
configuration cases, and for cases where a sub-tag needs information about
the parent.</p>

<example title="Example: sub-bean configuration example">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;bean class="example.Theater">
    &lt;init>
      &lt;name>Balboa&lt;/name>

      &lt;movie title="The Princess Bride"/>

      &lt;movie title="The Maltese Falcon"/>
    &lt;/init>
  &lt;/bean>

&lt;/web-app>
</example>

<p>In this example, the <code>Theater</code> classes uses
an inner <code>Movie</code> class to illustrate the use of
the <code>create</code> pattern.</p>

<example title="Example: Theater.java">
public class Theater {
  String _name;

  ArrayList&lt;Movie> _movies = new ArrayList&lt;Movie>();

  public void setName(String name) { _name = name; }

  public Movie createMovie()
  {
    return new Movie(this);
  }

  public void addMovie(Movie movie)
  {
    _movies.add(movie);
  }

  public static class Movie {
    private Theater _theater;
    private String _title;

    Movie(Theater theater)
    {
      _theater = theater;
    }

    public void setTitle(String title) { _title = title; }
  }
}
</example>

</s2>

<s2 title="Base configuration: string conversions">

<p>Resin-IoC provides a number of built-in string conversion types as well
as supporting JavaBeans <code>PropertyEditor</code> and custom converters.</p>

<deftable title="Built-in String Converters">
<tr>
  <th>Type</th>
  <th>Description</th>
</tr>
<tr>
  <td>boolean, Boolean</td>
  <td>Java boolean</td>
</tr>
<tr>
  <td>byte, Byte</td>
  <td>Java byte</td>
</tr>
<tr>
  <td>short, Short</td>
  <td>Java short</td>
</tr>
<tr>
  <td>int, Integer</td>
  <td>Java integer</td>
</tr>
<tr>
  <td>long, Long</td>
  <td>Java long</td>
</tr>
<tr>
  <td>float, Float</td>
  <td>Java float</td>
</tr>
<tr>
  <td>double, Double</td>
  <td>Java double</td>
</tr>
<tr>
  <td>char, Character</td>
  <td>Java char</td>
</tr>
<tr>
  <td>String[]</td>
  <td>String array separated by commas</td>
</tr>
<tr>
  <td>Class</td>
  <td>Java classes</td>
</tr>
<tr>
  <td>Path</td>
  <td>Resin VFS Paths</td>
</tr>
<tr>
  <td>File</td>
  <td>java.io.File</td>
</tr>
<tr>
  <td>URL</td>
  <td>java.net.URL</td>
</tr>
<tr>
  <td>Pattern</td>
  <td>java.util.regex.Pattern</td>
</tr>
<tr>
  <td>Locale</td>
  <td>java.util.Locale</td>
</tr>
<tr>
  <td>Date</td>
  <td>java.util.Date</td>
</tr>
<tr>
  <td>Properties</td>
  <td>java.util.Properties</td>
</tr>
<tr>
  <td>RawString</td>
  <td>com.caucho.config.type.RawString</td>
</tr>
</deftable>

<s3 title="enumerations">

<p>Enumerations are automatically converted from their
string representation.</p>

</s3>

<s3 title="String constructor">

<p>Resin-IoC will automatically convert a string to an object if the
object has a single String argument constructor.</p>

<example title="Example: MyBean with constructor">
public class MyBean {
  public MyBean(String value)
  {
    ...
  }
}
</example>

</s3>

<s3 title="valueOf">

<p>For classes which implement a static <code>valueOf(String)</code> method,
Resin will automatically convert to the given type using
the <code>valueOf</code> method.</p>

<example title="Example: MyBean with valueOf">
public class MyBean {
  ...

  public static MyBean valueOf(String text)
  {
    MyBean bean = new MyBean();
    bean.setTextValue(text);
    bean.init();
    return bean;
  }
}
</example>

</s3>

<s3 title="setValue">

<p>For objects with a <code>setValue</code> or <code>addText</code> method
and a zero-argument constructor, Resin-IoC will convert using the
following steps:</p>

<ol>
<li>Create the object</li>
<li>Inject any dependencies</li>
<li>Call <code>setValue</code> or <code>setText</code> with the string</li>
<li>Call any @PostConstruct</li>
<li>Return the configured bean</li>
</ol>

</s3>

</s2>

<s2 title="Compound types">

<s3 title="list">