<document>
<header>
<title>Java Injection (JSR-299)</title>
<description>

<p>Resin is designed around the Java Dependency Injection specification
(JSR-299), an inversion-of-control framework used for all configuration
and resources including servlets, EJBs, messaging,
remoting, and databases.  Applications can take advantage of Java
Injection using standard annotations and interfaces.</p>

<p>Since CanDI is used for servlets, managed beans and EJBs, any application
bean can use EJB annotations like @TransactionAttribute or CanDI
@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 Java Injection 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 Java Injection 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 Java Injection 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 from <code>javax.enterprise.inject</code>: <code>@Current</code>, <code>@Named</code>, <code>@BindingType</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 Java Injection <code>@Interceptor</code>, <code>@InterceptorBindingType</code>, and <code>@Decorator</code> are available to all beans.</li>
<li><b>Event handling:</b> the Java Injection <code>javax.event</code>, <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.enterprise.inject.Current;

public class MyServlet extends GenericServlet {
  @Current private DataSource _ds;
  @Current 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>@Current</code> is enough
information.  When you have multiple databases, you'll want to
use <code>@Name</code> to specify the database name.</p>

<example title="Example: @Name with DataSource">
import javax.sql.DataSource;
import com.caucho.config.Name;

public class MyServlet extends GenericServlet {
  @Name("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>@Name</code> binding annotation is still
typed.  You can have a database with <code>@Name("foo")</code> and
a JMS queue with <code>@Name("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>@Name</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>@Current</code>, <code>@New</code>,
<code>@Name</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 @Name">
import com.caucho.config.Name;

public class MyBean {
  @Name 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>@Current</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 @Name">
import com.caucho.config.Name;

public class MyBean {
  void foo(@Name("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>@Name</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>@Current</code> or have a <code>@BindingType</code> value.</p>

<example title="Example: constructor injection">
import javax.enterprise.inject.Current;

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

</s2>

<s2 title="Java Injection simple beans (injectable objects)">

<p>Any Resin-managed object can use the entire Java
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
Java injection 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;my:MyBean> (simple beans) defined in the META-INF/beans.xml, resin.xml or resin-web.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>Servlets</li>
<li>Servlet Listeners defined in the web.xml</li>
<li>Simple beans discovered through the classpath scan (see below)</li>
<li>Java Injection simple beans 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>@Current</code> as the annotation.</p>

<p><b><code>javax.enterprise.inject.spi.BeanManager</code></b> provides a reference to
the Java Injection manager itself.  Applications can use the
<code>Manager</code> to raise <code>javax.enterprise.event</code> events, and
lookup components programmatically.</p>

<p><b><code>javax.enterprise.context.Conversation</code></b> injects the Java
Injection 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>@Current 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.xml.  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 CanDI, since
Resin uses CanDI as its internal registry.</p>

<p><b><code>&lt;my:MyBean></code></b> is an application-specific
custom bean.  They can
either use Java Inject annotations or just be POJO objects.
The simple beans 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>@com.caucho.config.Name</code>
binding. Databases are injected as <code>javax.sql.DataSource</code> types.</p>

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

<p><b>EJB stateful beans</b> are automatically registered with
Java Injection.  The Resin <code>@Name</code> binding is the ejb-name.
Stateful beans can use the &lt;Stateful> 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 CanDI registry.</p>

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

<p><b>&lt;env-entry></b> tags register their values with
Java Inject.  The default <code>@Name</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 CanDI. 
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 CanDI.  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 CanDI.  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 CanDI.
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 {
  @Current 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 CanDI 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/beans.xml</code> file.  The presence of that file
tells Resin to start scanning all the classes in the jar or directory
Resin will register each class with the Java Injection registry.
The <code>META-INF/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 beans.xml jars to make
startup fast.</p>

<example title="Example: META-INF/beans.xml">
&lt;Beans xmlns="urn:java:ee">
&lt;/Beans>
</example>

<p>The component itself can be any Java class.  Since Resin manages the
component, it can use <code>@Current</code>, <code>@BindingType</code>
annotations and Resin's <code>@Name</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;

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>@Current Movie</code> to inject the movie resource.</p>

<example title="Example: MyServlet.java">
import javax.exterprise.inject.Current;

public class MyServlet extends GenericServlet {
  @Current Movie _movie;

  ...
}
</example>

<p>Most application components will use the Java Injection
class scanning mechanism.  Except for the <code>META-INF/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>@Current</code>.  The target class of the <code>@New</code>
annotation is automatically registered with Java Injection even if the 
<code>META-INF/beans.xml</code> is missing.  In other words, any plain
Java class can become a part of the Java Injection system without overhead.</p>

</s2>

<s2 title="Scopes: @ApplicationScoped, @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;my:MyBean></code> tag.  The
predefined scope values are: <code>@Dependent</code>,
<code>@RequestScoped</code>, <code>@ConversationScoped</code>,
<code>@SessionScoped</code>, and <code>@ApplicationScoped</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 for the
application.  For web applications, this will be the same lifecycle as
&lt;web-app>  For virtual hosts, this will be the same lifecycle as
&lt;host>.</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">
package example;

import javax.context.RequestScoped;

@RequestScoped
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: META-INF/beans.xml Calculator">
&lt;Beans xmlns="urn:java:ee" xmlns:example="urn:java:example">

  &lt;example:Calculator>
    &lt;RequestScoped/>
  &lt;/example:Calculator>

&lt;/Beans>
</example>

</s2>

<s2 title="@New bean discovery">

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

<example title="Example: MyServlet.java">
import javax.enterprise.inject.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>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">
package example;

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.enterprise.inject.Current;
import java.util.concurrent.ScheduledExecutorService;
import javax.ejb.Startup;

@Startup
public class TimerService {
  @Current 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 as well as the META-INF/beans.xml.
Since the Java Injection 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;my:MyBean></code> tags register
application classes with Resin.
The default scope of a <code>&lt;my:MyBean></code> is <code>@Dependent</code>.
A <code>&lt;my:MyBean></code> will create a new instance each time it's
injected or referenced.</p>

<example title="Example: bean and component META-INF/beans.xml">
&lt;Beans xmlns="urn:java:ee" xmlns:example="urn:java:example">

  &lt;example:MyService>
    &lt;ApplicationScoped/>
  &lt;/example:MyService>

  &lt;example:MyComponent>
  &lt;/example:MyComponent>

&lt;/Beans>
</example>

<p>The <code>&lt;my:MyBean></code> tags can configure fields and
annotations:</p>

<deftable title="XML annotations">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>&lt;Named></td>
  <td>the <code>@javax.annotation.Name</code> annotations for EL naming</td>
</tr>
<tr>
  <td>&lt;BindingType></td>
  <td>any <code>@javax.annotation.BindingType</code> annotations for
  injection</td>
</tr>
<tr>
  <td>my:myField</td>
  <td>optional configuration, using bean-style assignment</td>
</tr>
<tr>
  <td>&lt;SessionScoped></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 Java Injection 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 Java
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">
package example;

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.  Resin will
apply the configuration to the instance as part of the creation process.</p>

<example title="Example: META-INF/beans.xml configuring a singleton">
&lt;Beans xmlns="urn:java:ee" xmlns:example="urn:java:example">

  &lt;example:Hello>
    &lt;example:greeting>Hello, World&lt;/example:greeting>
  &lt;/example:Hello>

&lt;/Beans>
</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>@BindingType</code> injection as well as
the standard <code>@PostConstruct</code> annotations.  Sub-beans are
not automatically registered with Java Inection, 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;example:Theater xmlns:example="urn:java:example">
    &lt;example:name>Balboa&lt;/example:name>

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

    &lt;example:movie title="The Maltese Falcon"/>
  &lt;/example:Theater>

&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>Java Injection 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 CanDI 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 CanDI registry provides a simple interface to
use your components and services.  Although Java Injection injection is typed,
each simple bean can bean registered under its name for scripting applications.
The name must be globally unique, of course, unlike the typed injection
binding.</p>

<p>By default, beans do not have a name, so you'll need to specify it
by an annotation or the configuration file.  You can change the name by adding
a <code>@Named</code> annotation or &lt;Named> XML configuration.</p>

<example title="Example: Movie.java">
pakcage example;

import javax.annotation;
import javax.context;

@RequestScoped
@Named
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 Java Injection 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>Applications will typically create custom <code>@BindingType</code>
annotations to clearly specify their expected beans.
In many cases, <code>@Current</code> will be appropriate for unique beans,
and Resin <code>@com.caucho.config.Named</code> is used for Resin's resources
like &lt;database>.  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;

import javax.enterprise.inject.BindingType;

@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 CanDI.</p>

<example title="Example: @Produces">
import javax.enterprise.inject.Produces;
import javax.enterprise.context.ApplicationScoped;

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

<p>The produces method can be marked with <code>@ScopeType</code>,
<code>@DeploymentType</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 CanDI 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;

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.*;

@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/beans.xml</code> file.  This protects your code
from any surprising interceptors.</p>

<example title="Example: META-INF/beans.xml">
&lt;Beans xmlns="urn:java:ee" xmlns:foo="urn:java:com.foo">

  &lt;Interceptors>
  
    &lt;foo:MySecureInterceptor/>
    
  &lt;/Interceptors>
  
&lt;/Beans>
</example>

</s1>

<s1 title="Event Handling">

<p>Your components can also handle events thrown through the CanDI 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.context.ApplicationScoped;
import javax.event.Observes;

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

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

<example title="Example: raising events">
import javax.enterprise.inject.spi.BeanManager;

public void MyServlet extends GenericServlet {
  @Current BeanManager _beanManager;

  public void service(ServletRequest req, ServletResponse res)
  {
    _beanManager.fireEvent(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
CanDI-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.interceptor.Interceptor">
@Target({TYPE})
@Retention(RUNTIME)
public @interface Interceptor {
}
</def>

</s2>

<s2 title="@InterceptorBindingType">

<p><code>@InterceptorBindingType</code> is a Java Injection meta-annotation for
creating interceptor binding types.  Applications will use
<code>@InterceptorBindingType</code> to create application-specific
interceptors.  The Java Injection binding of interception decouples the
interception declaration from the interceptor classes.</p>

<def title="javax.interceptor.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>@Name</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.enterprise.inject.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="@Current" 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.enterprise.inject.Current">
@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Current {
}
</def>
</s2>

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

<p><code>@Named</code> is used to define an EL name for the bean
used for JSP, JSF and PHP named objects.
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.annotation.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 CanDI directory, it will
be registered automatically..</p>

<def title="javax.enterprise.inject.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.annotation.NonBinding">
@Target({FIELD, METHOD})
@Retention(RUNTIME)
public @interface NonBinding {
}
</def>

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

import javax.enterprise.inject.BindingType;

@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 Java Injection
annotations: <code>@Current</code>, Resin's <code>@Name</code>
or custom <code>@BindingType</code> annotations, since they use the
type-safe CanDI 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.config.inject.*;
import com.opensymphony.xwork2.ObjectFactory;
import java.util.*;
import javax.enterprise.inject.*;

public class ResinObjectFactory extends ObjectFactory
{
  private final InjectManager _webBeans = InjectManager.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.config.inject.*;

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

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

</s2>

</s1>

</body>
</document>
