<document>
<header>
<title>Resin IoC</title>
<description>

<p>Resin is designed around an internal inversion-of-control framework
used for all configuration and resources including servlets, EJBs, messaging,
remoting, and databases.  Applications can take advantage of Resin's
IoC capabilities using WebBeans-standard annotations and interfaces.</p>

<p>Since Resin-IoC is used for servlets, WebBeans and EJBs, any application
bean can use EJB annotations like @TransactionAttribute or WebBeans
@InterceptionTypes or event @Observes capabilities, in addition to the
dependency injection and IoC configuration.</p>

<p>The dependency injection framework is type-safe, meaning the registry
is organized around Java types, not a flat namespace, which gives more
power and flexibility for component assembly.
Since injection is annotation-based, most components can avoid XML
configuration, while XML is still available for components.</p>

</description>
</header>
<body>

<localtoc/>

<s1 title="See Also">

<ul>

<li>The <a href="resin-ejb.xtp">Resin EJB</a> page gives more information
about the EJB bean lifecycles and their integration with Resin IoC.</li>

<li>The <a href="resin-messaging.xtp">Resin messaging</a> page gives
more information about the message bean and its integration with Resin IoC.</li>

<li>The <a href="resin-remoting.xtp">Resin remoting</a> page shows
Resin's remoting integration.</li>

<li>All <a href="config.xtp">Resin configuration</a>, including
all JavaEE specified files uses Resin-IoC as the configuration engine.
</li>

</ul>

</s1>

<s1 title="Overview">

<p>Resin's IoC support is integrated with <a href="resin-ejb.xtp">EJB 3.0
</a> and the core components like Servlets, Filters and remote objects.
This integration means plain Java beans can use EJB annotations
and interception, EJBs can use Resin IoC annotations, and both kinds of
beans can be configured directly from the <code>resin-web.xml</code>
or discovered by classpath scanning.</p>

<p>So it's best to think of Resin-IoC as a set of orthogonal capabilities that
are available to any registered bean.  The basic capability types are:</p>

<ul>
<li><b>Lifecycle model:</b> Java, <code>@Stateless</code>, <code>@Stateful</code>,
or <code>@MessageDriven</code>.
Resin-managed objects like Servlets and Filters are Java model beans.</li>
<li><b>Dependency injection:</b> injection annotations <code>@In</code>, <code>@Named</code>, <code>@EJB</code>, <code>@PersistenceUnit</code>, etc are
available to all beans.</li>
<li><b>Registration:</b> all beans are registered in a unified typed-namespace
registry (i.e. the registration half of dependency injection.)</li>
<li><b>Lifecycle events:</b> the <code>@PostConstruct</code> and <code>@PreDestroy</code></li>
<li><b>Predefined aspects:</b> the <code>@TransactionAttribute</code>, <code>@RunAs</code>, <code>@RolesAllowed</code>, etc. annotations are
available to all beans.</li>
<li><b>Custom interceptors:</b> EJB-style <code>@AroundInvoke</code>, and <code>@Interceptors</code>, as well
as WebBeans-style <code>@Interceptor</code> and <code>@InterceptorBindingType</code> are available to all beans.</li>
<li><b>Event handling:</b> the WebBeans <code>@Observes</code> capability is available to all beans.</li>
</ul>
</s1>

<s1 title="Injecting Resources">

<p>Before dependency injection, applications needed to use JNDI to
grab resources managed by Resin: database connections, JMS queues, JCA
<code>EntityManagers</code>, timers, <code>UserTransaction</code>, the
JMX <code>MBeanServer</code>, etc.  The JNDI lookup had two main
flaws: it required a good chunk of boilerplate code to solve a simple
problem, and it was untyped.  Since JNDI is essentially a big HashMap,
the only way of making sure your <code>DataSource</code> name didn't
conflict with your JMS <code>Queue</code> was strictly structuring the
JNDI names with patterns like <code>java:comp/env/jdbc/foo</code>.
</p>

<p>With dependency injection, Resin will lookup, verify and inject
the resource when it creates your managed class, for example when creating
a servlet.  In the following example, when Resin creates MyServlet, the <code>@In</code> annotation tells it to look for a <code>UserTransaction</code>
and <code>DataSource</code> and use reflection to set the fields,
before calling the servlet's <code>init()</code> method.</p>

<example title="Example: DataSource and UserTransaction">
import javax.sql.DataSource;
import javax.transaction.UserTransaction;
import javax.webbeans.In;

public class MyServlet extends GenericServlet {
  @In private DataSource _ds;
  @In private UserTransaction _ut;

  ...
}
</example>

<s2 title="@Named and bindings">

<p>Since many applications use multiple resources like named databases,
your injection may need to specify a name or other binding to uniquely
identify the resource you want.  In the case of a unique resource like
<code>UserTransaction</code> or <code>MBeanServer</code> or an application
with a single <code>DataSource</code>, the <code>@In</code> is enough
information.  When you have multiple databases, you'll want to
use <code>@Named</code> to specify the database name.</p>

<example title="Example: @Named with DataSource">
import javax.sql.DataSource;
import javax.webbeans.Named;

public class MyServlet extends GenericServlet {
  @Named("foo") private DataSource _ds;

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

  &lt;database>
    &lt;name>foo&lt;/name>
    &lt;driver type="org.gjt.mm.mysql.Driver">
      &lt;url>jdbc:mysql://localhost:3306/foo&lt;/url>
    &lt;/driver>
  &lt;/database>

  &lt;database>
    &lt;name>bar&lt;/name>
    &lt;driver type="org.gjt.mm.mysql.Driver">
      &lt;url>jdbc:mysql://localhost:3306/bar&lt;/url>
    &lt;/driver>
  &lt;/database>

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

<p>Injection using a <code>@Named</code> binding annotation is still
typed.  You can have a database with <code>@Named("foo")</code> and
a JMS queue with <code>@Named("foo")</code>, i.e. each type has its own
namespace.  The typed injection is a big improvement from the JNDI
<code>java:comp/env/jdbc/foo</code> vs <code>java:comp/env/jms/foo</code>
conventions.</p>

<p>Although many applications will just use <code>@In</code>
and <code>@Named</code>, you can also create your
own <code>BindingType</code> annotations to match resources
and components.</p>

</s2>

<s2 title="field, method, and constructor injection">

<p>Since Resin implements all three flavors of dependency injection: field,
method and constructor, the choice of style is up to you.</p>

<p>You can mark any field with <code>@In</code>, <code>@New</code>,
<code>@Named</code> or any other <code>@BindingType</code> to tell Resin
to inject the field.  When a <code>@BindingType</code> is used, Resin will
only match components configured with that binding type.</p>

<example title="Example: field injection with @Named">
import javax.webbeans.Named;

public class MyBean {
  @Named DataSource _ds;
  ...
}
</example>

<p>Method injection can use any binding annotation on any of the parameters.
When Resin introspects the component class and it finds
any <code>@BindingType</code> or <code>@In</code> parameter on a method, it
will schedule that method to be injected.  Method parameters can
also use <code>@New</code>.  The method does not need to follow bean-style
setting conventions; any method will work.</p>

<example title="Example: method injection with @Named">
import javax.webbeans.Named;

public class MyBean {
  void foo(@Named("jdbc/foo") DataSource myDataSource) { ... }
  ...
}
</example>

<p>Construction injection is available for components and singleton beans.
Like method injection, the <code>@BindingType</code> values
like <code>@Named</code> assigned to the parameters determine the
values to be injected.</p>

<p>If the bean has multiple constructors, exactly one must be marked
<code>@In</code> or have a <code>@BindingType</code> value.</p>

<example title="Example: constructor injection">
import javax.webbeans.In;

public class MyBean {
  @In
  public MyBean(DataSource myDataSource) { ... }
  ...
}
</example>

</s2>

<s2 title="WebBeans-enabled components (injectable objects)">

<p>Any Resin-managed object can use the entire WebBeans
dependency-injection system and all of the managed objects, while objects
you create using <code>new</code> are still plain Java objects.
Once you've got a root object managed by the system, any futher
WebBeans components or singletons you bring in will also be managed.
The starting set of managed objects is pretty broad and includes:</p>

<ul>
<li>&lt;bean> (singletons) defined in the resin.conf or resin-web.xml</li>
<li>&lt;component> (WebBeans components) defined in the resin.conf,
resin-web.xml or web-beans.xml</li>
<li>EJB message-driven beans</li>
<li>EJB session beans</li>
<li>Filters (servlet)</li>
<li>JSF resources (currently only model beans)</li>
<li>JSP pages</li>
<li>JSP tag libraries</li>
<li>&lt;resource> components (Resin will be migrating to use &lt;bean> for resources in the future.)</li>
<li>Servlets</li>
<li>Servlet Listeners defined in the web.xml</li>
<li>WebBeans annotated components (<code>@Component</code>)
discovered through the classpath scan (see below)</li>
<li>WebBeans components injected with <code>@New</code> (see below)</li>
<li>Remote services defined by &lt;servlet> (e.g. Hessian or SOAP).</li>
</ul>

</s2>

<s2 title="Resin global resources">

<p>Resin automatically provides several global resources to any
injectable code. Since these resources are unique, your application
will use <code>@In</code> as the annotation.</p>

<p><b><code>javax.webbeans.Container</code></b> provides a reference to
the WebBeans container itself.  Applications can use the
<code>Container</code> to raise <code>WebBeans</code> events, and
lookup components programmatically.</p>

<p><b><code>javax.webbeans.Conversation</code></b> injects the WebBeans
conversation scope for a JSF application.  The conversatio scope lets
JSF views store data local to the page itself, separate from the
HTTP session scope.</p>

<p><b><code>javax.management.MBeanServer</code></b> injects the JMX
management server.  JMX manages Resin's resources, so an application
can use JMX to view the current state of Resin.  See the
<a href="http://caucho.com/resin-javadoc/com/caucho/management/server/package-summary.html">JavaDoc</a> for an overview of Resin's resources.</p>

<p><b><code>javax.transaction.TransactionManager</code></b> injects the
XA transaction manager.  Advanced applications which want to add their
own <code>XAResource</code> or <code>Synchronization</code> objects
to an active transaction can use <code>@In TransactionManager</code>.</p>

<p><b><code>javax.transaction.UserTransaction</code></b> injects the
XA user transaction manager.  Applications controlling XA transactions
programmatically will use the <code>UserTransaction</code>
to <code>begin()</code>, <code>rollback()</code>, and
<code>commit()</code> distributed transactions.</p>

<p><b><code>java.util.concurrent.ScheduledExecutorService</code></b>
lets applications schedule threads and timed events controlled by
Resin's thread pool, and restricted by the thread-max configuration
in the resin.conf.  This <code>ScheduleExecutorService</code> is
classloader-safe, so Resin will automatically close your scheduled
tasks when restarting a web-app.</p>

</s2>

<s2 title="Resin configured resources">

<p>All Resin configured resources are available through WebBeans, since
Resin uses WebBeans as its internal registry.</p>

<p><b><code>&lt;bean></code></b> singletons are application-specific
custom services.  They are exactly like the &lt;component> beans but
default to singleton scope.  Like &lt;component> they can
either use WebBeans annotations or just be POJO objects.
The &lt;bean> tag makes the beans available to any other WebBeans
component.  The bean default to <code>@Singleton</code> scope, which
means that a unique instance is created at Resin start time.
The injected type will depend on the <code>class</code> attribute of
the bean.</p>

<p><b><code>&lt;component></code></b> objects are application-specific custom
beans.  They can either use WebBeans annotations or just be POJO objects.
The &lt;component> tag makes the beans available to any other WebBeans
component.  The components default to <code>@Dependent</code> scope, which
means a new instance is created each time they're referenced or injected.
The injected type will depend on the <code>class</code> attribute of
the bean.</p>

<p><b><code>&lt;database></code></b> is a JDBC pooled database.
The <code>name</code> attribute is assigned to the <code>@Named</code>
binding. Databases are injected as <code>javax.sql.DataSource</code> types.</p>

<p><b>EJB stateless beans</b> are automatically registered the
WebBeans.  The default <code>@Named</code> value is the ejb-name.
Stateless beans can use the &lt;ejb-stateless-bean> tag for custom
configuration, or rely on the standard EJB discovery mechanism.
Each EJB 3.0 <code>@Local</code> interface is registered separately
in the WebBeans registry.</p>

<p><b>EJB stateful beans</b> are automatically registered with
WebBeans.  The default <code>@Named</code> value is the ejb-name.
Stateful beans can use the &lt;ejb-stateful-bean> tag for custom
configuration, or rely on the standard EJB discovery mechanism.
Each injection or bean lookup will return a new stateful bean
reference, modified by the bean's scope (see below.)
Each EJB 3.0 <code>@Local</code> interface is registered separately
in the WebBeans registry.</p>

<p><b>EntityManager</b> and <b>EntityManagerFactory</b> objects
from JPA are automatically registered with WebBeans.  The default
<code>@Named</code> value is the <code>persistence-unit</code> name.</p>

<p><b>&lt;env-entry></b> tags register their values with
WebBeans.  The default <code>@Named</code> value is
the <code>env-entry-name</code>.  The registered type is the
<code>env-entry-type</code>.</p>

<p><b>&lt;jms-connection-factory></b> automatically registers the configured
factory with WebBeans. 
Connection factories can also be configured with &lt;bean> or &lt;resource>,
depending on the JMS provider.  The registered type is the <code>class</code>
of the connection factory, usually <code>javax.jms.ConnectionFactory</code></p>

<p><b>&lt;jms-topic></b> automatically registers the configured
topic with WebBeans.  The default <code>@Named</code> value is the
topic name.  Topic can also be configured with &lt;bean> or &lt;resource>,
depending on the JMS provider.  The registered type is
<code>javax.jms.Topic</code></p>

<p><b>&lt;jms-queue></b> automatically registers the configured
queue with WebBeans.  The default <code>@Named</code> value is the
queue name.  Queue can also be configured with &lt;bean> or &lt;resource>,
depending on the JMS provider.  The registered type is
<code>javax.jms.Queue</code></p>

<p><b>&lt;remote-client></b> registers remoting clients with WebBeans.
The &lt;remote-client> tag will configure the protocol used and the
expected proxy class.  The registered type is the API <code>class</code>
of the remote service.</p>

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

  &lt;remote-client class="example.HelloService">
    &lt;url>hessian:http://localhost:8080/hello/&lt;/url>
  &lt;/remote-client>

&lt;/web-app>
</example>
<example title="Example: Injecting for remote-client">
public class MyServlet extends GenericServlet {
  @In example.HelloService _hello;
  ...
}
</example>

</s2>

</s1>

<s1 title="Application components">

<p>The primary value of Resin's dependency injection system is as a
type-safe component and service organization registry.  Module and
component-oriented software has been a goal of software developers
for decades, but in practice developing components and services is
a difficult task, in large part because the configuration and
assembly of the components has been just as
complicated as the code itself.  There are no silver bullets in software,
but the WebBeans registry does significatly reduce the housekeeping code
and XML which gets in the way of good design.</p>

<s2 title="Annotation-based Component Discovery">

<p>At startup, Resin will scan jars and class directories for a
<code>META-INF/web-beans.xml</code> file.  The presence of that file
tells Resin to start scanning all the classes in the jar or directory
for <code>@Component</code> annotations.  Resin will register each
class with a <code>@Component</code> market with the WebBeans directory.
The <code>META-INF/web-beans.xml</code> can be trivial, since its primary
purpose is speeding up startup time by letting Resin scan only the jars
which contain components.  So, applications will generally want to minimize
the number of classes in <code>@Component</code> jars to make
startup fast.</p>

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

<p>The component itself can be any Java class.  Since Resin manages the
component, it can use <code>@In</code> and <code>@Named</code> to inject
any other component or resource.  Resin will take care of any circular
dependencies automatically.</p>

<example title="Example: Movie.java">
import javax.annotation.PostConstruct;
import javax.webbeans.Component;

@Component
public class Movie {
  private String _title;
  private String _director;

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

  public String getDirector() { return _director; }
  public void setDirector(String director) { _director = director; }

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

<p>The <code>@PostConstruct</code> annotation tells Resin to call the
<code>init()</code> method once all the injection and configuration is
complete.</p>

<p>Any other component or Resin-managed class like servlets can now
use <code>@In Movie</code> to inject the movie resource.</p>

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

public class MyServlet extends GenericServlet {
  @In Movie _movie;

  ...
}
</example>

<p>Most application components will use the <code>@Component</code>
discovery mechanism.  Except for the <code>META-INF/web-beans.xml</code>
marker file, no additional housekeeping code or XML is
required.  As described below, applications can reduce the configuration
by one more step with the <code>@New</code> annotation
replacing <code>@In</code>.  The target class of the <code>@New</code>
annotation is automatically registered with WebBeans even if the class
has no <code>@Component</code> annotation or if the
<code>META-INF/web-beans.xml</code> is missing.  In other words, any plain
Java class can become a part of the WebBeans system without overhead.</p>

</s2>

<s2 title="Scopes: @Singleton, @Dependent, @RequestScoped">

<p>The scope of the component determines when Resin will create a new
component and when it will reuse an old one.  Singletons will always
return the same object, while dependent components will always return
a new object instance.  Long-lived services will typically be singletons,
while scratch-space modules will be dependent components.</p>

<p>Components default to <code>@Dependent</code> scope.  Since many
components will be used as pieces of other components,
<code>@Dependent</code> is the least-surprising value as a default.</p>

<p>You can specify a component's scope with an annotation or in
the <code>&lt;bean></code> or <code>&lt;component></code> tag.  The
predefined scope values are: <code>@Dependent</code>,
<code>@RequestScoped</code>, <code>@ConversationScoped</code>,
<code>@SessionScoped</code>, <code>@ApplicationScoped</code> and
<code>@Singleton</code>.</p>

<ul>
<li><code>@Dependent</code> creates a new instance each time.</li>
<li><code>@RequestScoped</code> creates a new instance for each
servlet request, reusing the instance for the same request.</li>
<li><code>@ConversationScoped</code> creates a new instance for each
JSF conversation, i.e. for each JSF view page.</li>
<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.conf 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.conf 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">

<p>Setters taking a <code>List</code> or array argument can be configured
with list values.</p>

<p>List items are specified directly with &lt;value> elements.  There is
no extra &lt;list> element required.  The &lt;list> element is only used
when creating a sub-list or sub-element (see below.)</p>

<example title="Example: MyBean.setValues(List)">
&lt;my-bean>
  &lt;values>
    &lt;value>a&lt;/value>
    &lt;value>b&lt;/value>
    &lt;value>c&lt;/value>
  &lt;/values>
&lt;/my-bean>
</example>

<example title="Example: MyBean.setValues(String [])">
&lt;my-bean>
  &lt;values>
    &lt;value>a&lt;/value>
    &lt;value>b&lt;/value>
    &lt;value>c&lt;/value>
  &lt;/values>
&lt;/my-bean>
</example>

<p>In the following example, the argument is an object, so we need
a &lt;list> element to tell Resin to create a list.  The object
created will be an <code>ArrayList</code>.</p>
<example title="Example: MyBean.setValues(Object)">
&lt;my-bean>
  &lt;values>
    &lt;list>
      &lt;value>a&lt;/value>
      &lt;value>b&lt;/value>
      &lt;value>c&lt;/value>
    &lt;/list>
  &lt;/values>
&lt;/my-bean>
</example>

<p>Resin-IoC can always use the <code>addXXX</code> pattern to add
a variable number of items.  Normally, the <code>addXXX</code> pattern
is easier and more maintainable than the <code>addList</code> pattern.
In particular, validation of the item values is quicker and more accurate
with <code>addXXX</code>.</p>

<example title="Example: MyBean.addValue(String)">
&lt;my-bean>
  &lt;value>a&lt;/value>
  &lt;value>b&lt;/value>
  &lt;value>c&lt;/value>
&lt;/my-bean>
</example>

</s3>

<s3 title="map">

<p>Generic maps can use an &lt;entry> syntax to define property values.</p>

<example title="Example: MyBean.setValues(Map)">
&lt;my-bean>
  &lt;values>
    &lt;entry key="a" value="one"/>
    &lt;entry key="b" value="two"/>
    &lt;entry key="c" value="three"/>
  &lt;/values>
&lt;/my-bean>
</example>

</s3>

</s2>

<s2 title="References and EL Expressions">

<p>Resin-IoC configuration files can use EL expressions to get references
to resources, beans, system properties, and calculate generatal expressions
based on those values.  Since all Resin's resources are added to
the WebBeans registry automatically, application components have access to
anything they need.</p>

<p>Both the JSP immediate syntax and deferred syntax are
supported (${...} vs #{...}).  Currently, there is no distinction
between the two, but the deferred syntax is preferred, since Resin-IoC
initializes beans lazily to handle circular references.</p>

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

  &lt;bean name="a" class="qa.FooBean">
    &lt;init bar="#{b}"/>
  &lt;/bean>

  &lt;bean name="b" class="qa.BarBean">
    &lt;init foo="#{a}"/>
  &lt;/bean>

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

<p>Because Resin's EL implementation allows method expressions, you can
use beans as factories in the EL expressions.</p>

</s2>

</s1>

<s1 title="Scripting: PHP, JSF and JSP">

<p>If your application is using a scripting language like PHP for the
presentation layer, the WebBeans registry provides a simple interface to
use your components and services.  Although WebBeans injection is typed,
each WebBean is also registered under its name for scripting applications.
The name must be globally unique, of course, unlike the typed injection
binding.</p>

<p>The default scripting name is the name of the component's class, with
the first character lowercased.  You can change the name by adding
a <code>@Named</code> or setting a <code>name</code> attribute in the
<code>&lt;component></code> or <code>&lt;bean></code>.</p>

<example title="Example: Movie.java">
@Component
@RequestScoped
public class Movie {
  ...
}
</example>

<s2 title="Quercus/PHP">

<p>In Quercus/PHP, the <code>java_bean(name)</code> method returns the
component with the given name.  For singletons, Resin will return the unique
bean.  For other beans, Resin will create the bean if necessary and
store it in the configured scope.</p>

<example title="Example: accessing the movie from PHP">
&lt;?php

$movie = java_bean("movie");

echo "title: " . $movie->title . "\n";

?>
</example>

</s2>

<s2 title="JSP/JSF EL">

<p>Resin automatically provides the WebBeans variables to EL expressions
for both JSP and JSF.</p>

<example title="Example: accessing the movie from JSP">
&lt;c:out value="${movie.title}"/>
</example>

<p>The JSF also uses the expression language, but uses the deferred syntax,
since JSF needs to build a component tree first.</p>

<example title="Example: accessing the movie from JSF">
&lt;f:view>
  &lt;h:outputText value="#{movie.title}"/>
&lt;/f:view>
</example>

</s2>

</s1>

<s1 title="@BindingType: custom injection binding">

<p>Although many applications will just use <code>@In</code> and
<code>@Named</code> injection binding, applications can create their
own binding annotations.  Some bindings might be more
logical, for example an <code>@XA</code> annotation might mark the
transactional <code>DataSource</code>, while <code>@ReadOnly</code> might
mark a read-only <code>DataSource</code>.  Drivers might
use <code>Scheme("mysql")</code> to allow for URL-based configuration,
like the "jdbc:mysql://localhost:3306/test" of JDBC.</p>

<example title="Example: ReadOnly and XA databases">
import com.foo.webbeans.ReadOnly;
import com.foo.webbeans.XA;

public class MyServlet extends GenericServlet {
  @ReadOnly DataSource _readDatabase;
  @XA DataSource _xaDatabase;

  ...
}
</example>

<p>You can create a custom binding annotation using
the <code>@BindingType</code> annotation.  When Resin introspects the
injection point and the components, it will look for any annotation
with the <code>@BindingType</code> meta-annotation.</p>

<p>The annotation can also have annotation parameters.  If they exist,
Resin will make sure only matching components will be injected.</p>

<p>The custom binding annotation can be used anywhere predefined
binding annotations can, including fields, methods, constructor,
producers, or event observers.</p>

<example title="Example: ReadOnly.java">
package com.foo.webbeans;

@BindingType
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface ReadOnly {
}
</example>

</s1>

<s1 title="@Produces methods">

<p>Some components are more easily produced using a factory method rather
than getting instantiated directly.  In those cases, your application
can mark a factory component's method with the <code>@Produces</code>
annotation.  Resin will register the results of the method with WebBeans.</p>

<example title="Example: @Produces">
import javax.webbeans.Component;
import javax.webbeans.Produces;
import com.caucho.webbeans.Singleton;

@Component
@Singleton
public class MyFactory {
  @Produces public List&lt;Movie> currentMovies()
  {
    ...
  }
</example>

<p>The produces method can be marked with <code>@ScopeType</code>,
<code>@ComponentType</code> or <code>@BindingType</code> annotations just
like a class-based component can.</p>

</s1>

<s1 title="Aspects: Method Interception">

<p>Some functions like security, logging and transaction handing need
to be used for each method invidually, but require a common
implementation pattern.  The WebBeans AOP uses a single method as
a interceptor for each method invocation.</p>

<p>Your method will use an <code>@InterceptorType</code> annotation
letting Resin know where it should apply the interceptor:</p>

<example title="Example: secure method">
import com.foo.webbeans.Secure;

@Component
public class MyBean {
  @Secure
  public void doSomethingSafely() { ... }
}
</example>

<p>The implementation class will use the
<code>javax.interceptor.*</code> API to implement the
interceptor.</p>

<example title="Example: security implementation">
import javax.interceptor.*;
import javax.webbeans.Interceptor;

@Secure @Interceptor
public class MySecureInterceptor {
  @AroundInvoke
  public Object checkSecurity(InvocationContext inv) throws Exception
  {
    if (! myContextIsSecure())
      throw new MySecurityException("permissiong denied");

    return inv.proceed();
  }
}
</example>

<p>The interceptors must be enabled in the
<code>META-INF/web-beans.xml</code> file.  This protects your code
from any surprising interceptors.</p>

<example title="Example: META-INF/web-beans.xml">
&lt;web-beans xmlns="http://caucho.com/ns/resin">
  &lt;interceptors>
    &lt;interceptor>com.foo.MySecureInterceptor&lt;/interceptor>
  &lt;/interceptors>
&lt;/web-beans>
</example>

</s1>

<s1 title="Event Handling">

<p>Your components can also handle events thrown through the WebBeans API.
Any method with an <code>@Observes</code> parameter will receive events
with the proper type.  The event can be any Java class.</p>

<example title="Example: event handler">
import javax.webbeans.Component;
import javax.webbeans.Observes;

@Component
public class MyHandler {
  public void myHandlerMethod(@Observes Movie movie)
  {
    ...
  }
}
</example>

<p>Your application can throw events through the WebBeans
<code>Container</code> API, which is available through injection:</p>

<example title="Example: raising events">
import javax.webbeans.Container;

public void MyServlet extends GenericServlet {
  @In Container _webbeans;

  public void service(ServletRequest req, ServletResponse res)
  {
    _webbeans.raiseEvent(new Movie("A Bridge Too Far"));
  }
}
</example>

<p>For the above example, Resin will look for all components which
have an <code>@Observes</code> method receiving a <code>Movie</code>
and deliver the event to that component.</p>

</s1>


<s1 title="Aspect Annotations">

<s2 title="@AroundInvoke">

<p><code>@AroundInvoke</code> marks an interception method on the
bean or an interceptor class.  The interceptor is invoked while
processing a business method.</p>

<def title="javax.interceptor.AroundInvoke">
@Target(METHOD)
@Retention(RUNTIME)
public @interface AroundInvoke {
}
</def>

<example title="Example: @AroundInvoke method">
import javax.interceptor.*;

public class MyBean {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }

  public String hello()
  {
    return "hello, world";
  }
}
</example>

</s2>

<s2 title="@DenyAll">

<p><code>@DenyAll</code> annotation marks a method as forbidden to all
users.</p>

<def title="javax.annotation.security.DenyAll">
@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DenyAll {
}
</def>
</s2>

<s2 title="@Interceptor">

<p><code>@Interceptor</code> marks a class as an interceptor using
WebBeans-style interception.  The class will normally also have
an <code>@AroundInvoke</code> method as well as any
<code>InterceptorBindingType</code> annotations.</p>

<def title="javax.webbeans.Interceptor">
@Target({TYPE})
@Retention(RUNTIME)
public @interface Interceptor {
}
</def>

</s2>

<s2 title="@InterceptorBindingType">

<p><code>@InterceptorBindingType</code> is a WebBeans meta-annotation for
creating interceptor binding types.  Applications will use
<code>@InterceptorBindingType</code> to create application-specific
interceptors.  The WebBeans-style of interception decouples the
interception declaration from the interceptor classes, in contrast
with the EJB-style which specifies the interceptor class directly.</p>

<def title="javax.webbeans.InterceptorBindingType">
@Target({TYPE})
@Retention(RUNTIME)
public @interface InterceptorBindingType {
}
</def>

</s2>

<s2 title="@Interceptors">

<p><code>@Interceptors</code> marks an method or class as being
intercepted by the named classes.  The interceptor classes will
implement an <code>@AroundInvoke</code> method to process the
<code>InvocationContext</code>.</p>

<deftable title="@Interceptors properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the interceptor classes to apply to the method.</td>
</tr>
</deftable>

<def title="javax.interceptor.Interceptors">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface Interceptors {
  public Class []value();
}
</def>

<example title="Example: @Interceptor method">
import javax.interceptor.*;

public class MyBean {
  @Interceptors(MyInterceptor.class)
  public String hello()
  {
    return "hello, world";
  }
}

public class MyInterceptor {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }
}
</example>

</s2>

<s2 title="InvocationContext">

<p>The <code>InvocationContext</code> API is used by invocation
methods to examine the calling context, and possibly set parameters.
A no-op interceptor would just call the <code>proceed()</code> method.</p>

<deftable title="InvocationContext methods">
<tr>
  <th>Method</th>
  <th>Description</th>
</tr>
<tr>
  <td>getContextData</td>
  <td>Returns a map containing any context information</td>
</tr>
<tr>
  <td>getMethod</td>
  <td>Returns the called API method</td>
</tr>
<tr>
  <td>getParameters</td>
  <td>Returns the Java parameters for the call</td>
</tr>
<tr>
  <td>getTarget</td>
  <td>Returns the target object, i.e. the Java object that will
receive the call after all the interceptors complete.</td>
</tr>
<tr>
  <td>proceed</td>
  <td>Call the next interceptor in the chain, or call the final object
at the end of the chain.</td>
</tr>
<tr>
  <td>setParameters</td>
  <td>Sets the Java parameters for the call</td>
</tr>
</deftable>

<def title="javax.interceptor.InvocationContext">
public interface InvocationContext {
  public Object proceed() throws Exception;

  public Map&lt;String, Object> getContextData();
  public Method getMethod();
  public Object[] getParameters() throws IllegalStateException;
  public void setParameters(Object[] parameters) throws IllegalStateException;
  public Object getTarget();
}
</def>
</s2>

<s2 title="@PermitAll">

<p><code>@PermitAll</code> annotation marks a method as allowed for all
users.</p>

<def title="javax.annotation.security.PermitAll">
@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PermitAll {
}
</def>
</s2>

<s2 title="@RolesAllowed">

<p><code>@RolesAllowed</code> lists all the roles (i.e. permissions) allowed
to access the method.  If the user in the security context does not match
the role, an exception will be thrown.</p>

<deftable title="RolesAllowed properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the roles (permissions) that are allowed.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RolesAllowed">
@Target({TYPE,METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RolesAllowed {
  String []value();
}
</def>
</s2>

<s2 title="@RunAs">

<p><code>@RunAs</code> changes the security context user to a defined
role.  Security tests within the context of the <code>@RunAs</code> will
match the specified role.</p>

<deftable title="RunAs properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>The role name to run as.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RunAs">
@Target({TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RunAs {
  String value();
}
</def>
</s2>

<s2 title="@TransactionAttribute">

<p>Defines the transaction boundary for business methods.  The
default value is REQUIRED.  If @TransactionAttribute annotates the class,
it defines the default value. </p>

<p>All Resin-managed beans can use <code>@TransactionAttribute</code>:
@Stateful, @Stateless, @MessageDriven and plain Java beans.</p>

<deftable title="TransactionAttributeType">
<tr>
  <th>Value</th>
  <th>Meaning</th>
</tr>
<tr>
  <td>REQUIRED</td>
  <td>Start a new transaction if necessary</td>
</tr>
<tr>
  <td>SUPPORTS</td>
  <td>Don't start a new transaction, but use one if it exists</td>
</tr>
<tr>
  <td>MANDATORY</td>
  <td>Require the caller to have started a transaction</td>
</tr>
<tr>
  <td>NEVER</td>
  <td>Forbid the caller to have started a transaction</td>
</tr>
<tr>
  <td>REQUIRESNEW</td>
  <td>Always start a new transaction, suspending the old one</td>
</tr>
<tr>
  <td>NOTSUPPORTED</td>
  <td>Suspend any active transaction</td>
</tr>
</deftable>

<ul>
<li>SUPPORTS is typically used for read-only methods</li>
<li>REQUIRED is typically used for updating (read/write) methods</li>
</ul>

<def title="javax.ejb.TransactionAttribute">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface TransactionAttribute {
  TransactionAttributeType value() default REQUIRED;
}
</def>

</s2>

</s1>

<s1 title="Dependency Injection Annotations">

<s2 title="@BindingType" type="defun">

<p><code>@BindingType</code> is a meta-annotation for creating custom
injection binding types.  Applications can create their own injection
annotations like <code>@Named</code> to provide application-specific
binding.  For example, a database might have a <code>@XA</code>
and a <code>@NonXA</code> connector implemented.</p>

<def title="javax.webbeans.BindingType">
@Target({TYPE})
@Retention(RUNTIME)
public @interface BindingType {
}
</def>

<example title="Example: custom @XA binding type">
package demo;

@BindingType
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface XA {
}
</example>

<example title="Example: using the custom @XA binding type">
package demo;

import javax.sql.*;

public class MyBean {
  @XA DataSource _xa;
  @NonXA DataSource _nonXa;

  ...
}
</example>

</s2>

<s2 title="@EJB" type="defun">

<p>Configures EJB values for a field or method.</p>

<p>@EJB is essentially a @Resource where it's known that the
result is an EJB interface.</p>

<deftable-childtags>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>businessInterface</td>
  <td>The EJB interface to lookup</td>
  <td>The field type</td>
</tr>
<tr>
  <td>name</td>
  <td>The EJB name of the resource</td>
  <td>The field name</td>
</tr>
<tr>
  <td>jndiName</td>
  <td>The jndi name of the resource</td>
  <td>The EJB name</td>
</tr>
</deftable-childtags>

<def title="javax.ejb.EJB">
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface EJB {
  String name() default "";
  String businessInterface() default "";
  String jndiName() default "";
}
</def>

<p>In the following exaple, Resin will call <code>setFoo</code>
method with the bean in "java:comp/env/ejb/foo" before the
session is started.</p>

<example title="Example: @EJB method injection">
@EJB
void setFoo(example.Test test)
{
  _test = test;
}
</example>

</s2>

<s2 title="@In" type="defun">

<p>Marks a field, method, or parameter for injection.
When used with a constructor, it marks the given constructor as
the constructor to use when creating new instances.</p>

<def title="javax.webbeans.In">
@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface In {
}
</def>
</s2>

<s2 title="@Named" type="defun">

<p><code>@Named</code> is a predefined <code>@BindingType</code>
annotation for named objects.  Many application objects can just use
<code>@Named</code> to disambiguate multiple objects with the same
type.
</p>

<deftable title="@Named parameters">
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>The name binding for the object to inject</td>
  <td>required</td>
</tr>
</deftable>

<def title="javax.webbeans.Named">
@BindingType
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Named {
  String value();
}
</def>
</s2>

<s2 title="@New" type="defun">

<p>Marks a field, method, or parameter for injection with a new
instance of the object.  If the type of the <code>@New</code>
has not yet been registered with the WebBeans directory, it will
be registered automatically..</p>

<def title="javax.webbeans.New">
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface New {
}
</def>
</s2>

<s2 title="@NonBinding" type="defun">

<p><code>@NonBinding</code> is a meta-annotation used for
creating <code>@BindingType</code> annotations.   It excludes an
annotation property from the binding algorithm.  Normally, the
injection binding must matches all the propeties in the object's
annotations with the properties in the injection property.  The
<code>@NonBinding</code> annotation skips the check for the annotated
property.
</p>

<def title="javax.webbeans.NonBinding">
@Target({FIELD, METHOD})
@Retention(RUNTIME)
public @interface NonBinding {
}
</def>

<example title="Example: @Demo with @NonBinding">
package demo;

@BindingType
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface Demo {
  @NonBinding String description() default "";
}
</example>

</s2>

<s2 title="@Resource" type="defun">

<p><code>@Resource</code> provides JNDI-based resource injection.
<code>@Resource</code> can also be used at the Class level to
declare a dependency in cases where the session bean loads the
JNDI value by itself.</p>

<p>In general, it's better to use the WebBeans
annotations: <code>@In</code>, <code>@Named</code>
or custom <code>@BindingType</code> annotations, since they use the
type-safe WebBeans registry instead of JNDI.  <code>@Resource</code>
is supported for backwards compatibility.</p>

<deftable-childtags>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>authenticationType</td>
  <td>What kind of authentication is expected for the resource: APPLICATION or
CONTAINER</td>
  <td>CONTAINER</td>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the resource</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The jndi-name of the resource</td>
  <td>java:comp/env/<var>class-name</var>#<var>field-name</var></td>
</tr>
<tr>
  <td>type</td>
  <td>The class of the expected resource</td>
  <td>The field type</td>
</tr>
<tr>
  <td>shareable</td>
  <td>True if the bean follows JCA shareability requirements.</td>
  <td>true</td>
</tr>
<tr>
  <td>mappedName</td>
  <td>The produce-specific name of the resource</td>
  <td>The field name</td>
</tr>
</deftable-childtags>

</s2>

</s1>

<s1 title="Framework Integration">

<p>Frameworks like Struts2, Wicket, and Mule can delegate object creation
to Resin-IoC.  By configuration Resin-IoC to create the framework
objects, your application's components can directly inject Resin resources
and application components configured with Resin.</p>

<p>Integration information for the frameworks is maintained on the
Caucho wiki site.  Currently supported frameworks include:</p>

<ul>
<li><a href="http://wiki.caucho.com/Mule">http://wiki.caucho.com/Mule</a></li>
<li><a href="http://wiki.caucho.com/Spring">http://wiki.caucho.com/Spring</a></li>
<li><a href="http://wiki.caucho.com/Struts2">http://wiki.caucho.com/Struts2</a></li>
<li><a href="http://wiki.caucho.com/Wicket">http://wiki.caucho.com/Wicket</a></li>
</ul>

<p>Implementing new object factories for other frameworks is straightforward.
</p>

<s2 title="ObjectFactory pattern">

<p>Frameworks like Struts2 provide an <code>ObjectFactory</code> pattern.
In this case, the framework gives a <code>Class</code> object and asks
the factory to create a new instance.  The <code>ObjectFactory</code> is
the most powerful pattern, since objects can use @Observes, @InterceptionType,
@TransactionAttribute and even @Stateless, as well as the usual dependency
injection.</p>

<example title="Example: Struts2 integration">
package com.caucho.xwork2;

import com.caucho.webbeans.manager.*;
import com.opensymphony.xwork2.ObjectFactory;
import java.util.*;
import javax.webbeans.*;

public class ResinObjectFactory extends ObjectFactory
{
  private final WebBeansContainer _webBeans = WebBeansContainer.create();
  
  @Override
  public Object buildBean(Class clazz, Map extraContext)
    throws Exception
  {
    return _webBeans.getObject(clazz);
  }
}
</example>

</s2>

<s2 title="Injection pattern">

<p>Some frameworks, like Wicket, prefer to instantiate the object, but
can call Resin-IoC for a dependency-injection step.  With this kind of
framework integration, the created object only gets dependency-injection;
it does not get any aspects or interception.</p>

<example title="Example: Wicket injection">
package com.caucho.wicket;

import com.caucho.webbeans.manager.*;

import org.apache.wicket.Component;
import org.apache.wicket.application.*;

public class ResinComponentInjector implements IComponentInstantiationListener
{
  private WebBeansContainer _webBeans = WebBeansContainer.create();
  
  public void onInstantiation(Component component)
  {
    _webBeans.injectObject(component);
  }
}
</example>

</s2>

</s1>

</body>
</document>
