<document>
<localtoc/>

- The Resin EJB page gives more information about the EJB bean lifecycles and their integration with Resin IoC.
- The Resin messaging page gives more information about the message bean and its integration with Resin IoC.
- The Resin remoting page shows Resin's remoting integration.
- All Resin configuration, including all JavaEE specified files uses Resin-IoC as the configuration engine.

Resin's IoC support is integrated with EJB 3.0 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 `resin-web.xml` or discovered by classpath scanning.

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:

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

Before dependency injection, applications needed to use JNDI to grab resources managed by Resin: database connections, JMS queues, JCA `EntityManagers`, timers, `UserTransaction`, the JMX `MBeanServer`, 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 `DataSource` name didn't conflict with your JMS `Queue` was strictly structuring the JNDI names with patterns like `java:comp/env/jdbc/foo`.

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 `@In` annotation tells it to look for a `UserTransaction` and `DataSource` and use reflection to set the fields, before calling the servlet's `init()` method.

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

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 `UserTransaction` or `MBeanServer` or an application with a single `DataSource`, the `@In` is enough information. When you have multiple databases, you'll want to use `@Named` to specify the database name.

import javax.sql.DataSource; import javax.webbeans.Named; public class MyServlet extends GenericServlet { @Named("foo") private DataSource _ds; ... } <web-app xmlns="http://caucho.com/ns/resin"> <database> <name>foo</name> <driver type="org.gjt.mm.mysql.Driver"> <url>jdbc:mysql://localhost:3306/foo</url> </driver> </database> <database> <name>bar</name> <driver type="org.gjt.mm.mysql.Driver"> <url>jdbc:mysql://localhost:3306/bar</url> </driver> </database> </web-app>

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

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

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

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

import javax.webbeans.Named; public class MyBean { @Named DataSource _ds; ... }

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

import javax.webbeans.Named; public class MyBean { void foo(@Named("jdbc/foo") DataSource myDataSource) { ... } ... }

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

If the bean has multiple constructors, exactly one must be marked `@In` or have a `@BindingType` value.

import javax.webbeans.In; public class MyBean { @In public MyBean(DataSource myDataSource) { ... } ... }

Any Resin-managed object can use the entire WebBeans dependency-injection system and all of the managed objects, while objects you create using `new` 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:

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

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

`javax.webbeans.Container` provides a reference to the WebBeans container itself. Applications can use the `Container` to raise `WebBeans` events, and lookup components programmatically.

`javax.webbeans.Conversation` 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.

`javax.management.MBeanServer` 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 JavaDoc for an overview of Resin's resources.

`javax.transaction.TransactionManager` injects the XA transaction manager. Advanced applications which want to add their own `XAResource` or `Synchronization` objects to an active transaction can use `@In TransactionManager`.

`javax.transaction.UserTransaction` injects the XA user transaction manager. Applications controlling XA transactions programmatically will use the `UserTransaction` to `begin()`, `rollback()`, and `commit()` distributed transactions.

`java.util.concurrent.ScheduledExecutorService` 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 `ScheduleExecutorService` is classloader-safe, so Resin will automatically close your scheduled tasks when restarting a web-app.

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

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

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

`<database>` is a JDBC pooled database. The `name` attribute is assigned to the `@Named` binding. Databases are injected as `javax.sql.DataSource` types.

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

EJB stateful beans are automatically registered with WebBeans. The default `@Named` value is the ejb-name. Stateful beans can use the <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 `@Local` interface is registered separately in the WebBeans registry.

EntityManager and EntityManagerFactory objects from JPA are automatically registered with WebBeans. The default `@Named` value is the `persistence-unit` name.

<env-entry> tags register their values with WebBeans. The default `@Named` value is the `env-entry-name`. The registered type is the `env-entry-type`.

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

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

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

<remote-client> registers remoting clients with WebBeans. The <remote-client> tag will configure the protocol used and the expected proxy class. The registered type is the API `class` of the remote service.

<web-app xmlns="http://caucho.com/ns/resin"> <remote-client class="example.HelloService"> <url>hessian:http://localhost:8080/hello/</url> </remote-client> </web-app> public class MyServlet extends GenericServlet { @In example.HelloService _hello; ... }

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.

At startup, Resin will scan jars and class directories for a `META-INF/web-beans.xml` file. The presence of that file tells Resin to start scanning all the classes in the jar or directory for `@Component` annotations. Resin will register each class with a `@Component` market with the WebBeans directory. The `META-INF/web-beans.xml` 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 `@Component` jars to make startup fast.

<web-beans xmlns="http://caucho.com/ns/resin"> </web-beans>

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

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() { ... } }

The `@PostConstruct` annotation tells Resin to call the `init()` method once all the injection and configuration is complete.

Any other component or Resin-managed class like servlets can now use `@In Movie` to inject the movie resource.

import javax.webbeans.In; public class MyServlet extends GenericServlet { @In Movie _movie; ... }

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

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.

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

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

- `@Dependent` creates a new instance each time.
- `@RequestScoped` creates a new instance for each servlet request, reusing the instance for the same request.
- `@ConversationScoped` creates a new instance for each JSF conversation, i.e. for each JSF view page.
- `@SessionScoped` creates a new instance for each HTTP session, reusing the instance for the same session.
- `@ApplicationScoped` uses a single instance in each web-app. For web applications, this will have the same lifecycle as `@Singleton`.
- `@Singleton` uses a single instance in the container. For web applications, this will have the same lifecycle as `@ApplicationScoped`.

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

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; } }

You could also register the same calculator using XML:

<web-app xmlns="http://caucho.com/ns/resin"> <component class="example.Calculator" scope="request"/> </web-app>

The `@New` 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 `@New` replaces `@In`, it can be used anywhere `@In` can be used.

import javax.webbeans.New; public class MyServlet extends GenericServlet { @New Movie _movie; ... }

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

public class Movie { private String _title; public String getTitle() { return _title; } public void setTitle(String title) { _title = title; } @PostConstruct public void init() { ... } }

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

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 `@PreDestroy` before it destroys the method.

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

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); } }

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.

The XML-configuration lets you customize your application for a particular environment, e.g. setting configuration parameters. For example, Resin's `<database>` 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.

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.

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

<web-app xmlns="http://caucho.com/ns/resin"> <bean class="example.MyService"/> <component class="example.MyService"/> </web-app>

The `<bean>` and `<component>` tags have a number of optional attributes:

Attribute Description
binding the `@BindingType` annotations for custom bean matching
class the Java class of the bean or component (required)
init optional configuration/initialization block, using bean-style assignment
name the instance name, used for `@Named` and script integration
scope specifies scope of the instances: request, conversation, session, application, or singleton

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.

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 `<ref>`.

public class Hello { private String _greeting = "default"; public void setGreeting(String greeting) { _greeting = greeting; } public String getGreeting() { return _greeting; } }

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

<web-app xmlns="http://caucho.com/ns/resin"> <bean class="example.Hello"> <init> <greeting>Hello, World</greeting> </init> </bean> </web-app>

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 `@In` injection as well as the standard `@PostConstruct` annotations. Sub-beans are not automatically registered with WebBeans, i.e. they act like the servlet configuration.

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

public void setFoo(String data); public void setFoo(Movie data); public void addFoo(Movie data); public Movie createFoo(); public void setText(String data);

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

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

<web-app xmlns="http://caucho.com/ns/resin"> <bean class="example.Theater"> <init> <name>Balboa</name> <movie title="The Princess Bride"/> <movie title="The Maltese Falcon"/> </init> </bean> </web-app>

In this example, the `Theater` classes uses an inner `Movie` class to illustrate the use of the `create` pattern.

public class Theater { String _name; ArrayList<Movie> _movies = new ArrayList<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; } } }

Resin-IoC provides a number of built-in string conversion types as well as supporting JavaBeans `PropertyEditor` and custom converters.

Type Description
boolean, Boolean Java boolean
byte, Byte Java byte
short, Short Java short
int, Integer Java integer
long, Long Java long
float, Float Java float
double, Double Java double
char, Character Java char
String[] String array separated by commas
Class Java classes
Path Resin VFS Paths
File java.io.File
URL java.net.URL
Pattern java.util.regex.Pattern
Locale java.util.Locale
Date java.util.Date
Properties java.util.Properties
RawString com.caucho.config.type.RawString

Enumerations are automatically converted from their string representation.

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

public class MyBean { public MyBean(String value) { ... } }

For classes which implement a static `valueOf(String)` method, Resin will automatically convert to the given type using the `valueOf` method.

public class MyBean { ... public static MyBean valueOf(String text) { MyBean bean = new MyBean(); bean.setTextValue(text); bean.init(); return bean; } }

For objects with a `setValue` or `addText` method and a zero-argument constructor, Resin-IoC will convert using the following steps:

1. Create the object
2. Inject any dependencies
3. Call `setValue` or `setText` with the string
4. Call any @PostConstruct
5. Return the configured bean

Setters taking a `List` or array argument can be configured with list values.

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

<my-bean> <values> <value>a</value> <value>b</value> <value>c</value> </values> </my-bean> <my-bean> <values> <value>a</value> <value>b</value> <value>c</value> </values> </my-bean>

In the following example, the argument is an object, so we need a <list> element to tell Resin to create a list. The object created will be an `ArrayList`.

<my-bean> <values> <list> <value>a</value> <value>b</value> <value>c</value> </list> </values> </my-bean>

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

<my-bean> <value>a</value> <value>b</value> <value>c</value> </my-bean>

Generic maps can use an <entry> syntax to define property values.

<my-bean> <values> <entry key="a" value="one"/> <entry key="b" value="two"/> <entry key="c" value="three"/> </values> </my-bean>

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.

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.

<web-app xmlns="http://caucho.com/ns/resin"> <bean name="a" class="qa.FooBean"> <init bar="#{b}"/> </bean> <bean name="b" class="qa.BarBean"> <init foo="#{a}"/> </bean> </web-app>

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

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.

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 `@Named` or setting a `name` attribute in the `<component>` or `<bean>`.

@Component @RequestScoped public class Movie { ... }

In Quercus/PHP, the `java_bean(name)` 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.

<?php $movie = java_bean("movie"); echo "title: " . $movie->title . "\n"; ?>

Resin automatically provides the WebBeans variables to EL expressions for both JSP and JSF.

<c:out value="${movie.title}"/>

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

<f:view> <h:outputText value="#{movie.title}"/> </f:view>

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

import com.foo.webbeans.ReadOnly; import com.foo.webbeans.XA; public class MyServlet extends GenericServlet { @ReadOnly DataSource _readDatabase; @XA DataSource _xaDatabase; ... }

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

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

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

package com.foo.webbeans; @BindingType @Target({TYPE, METHOD, FIELD, PARAMETER}) @Retention(RUNTIME) public @interface ReadOnly { }

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 `@Produces` annotation. Resin will register the results of the method with WebBeans.

import javax.webbeans.Component; import javax.webbeans.Produces; import com.caucho.webbeans.Singleton; @Component @Singleton public class MyFactory { @Produces public List<Movie> currentMovies() { ... }

The produces method can be marked with `@ScopeType`, `@ComponentType` or `@BindingType` annotations just like a class-based component can.

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.

Your method will use an `@InterceptorType` annotation letting Resin know where it should apply the interceptor:

import com.foo.webbeans.Secure; @Component public class MyBean { @Secure public void doSomethingSafely() { ... } }

The implementation class will use the `javax.interceptor.*` API to implement the interceptor.

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(); } }

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

<web-beans xmlns="http://caucho.com/ns/resin"> <interceptors> <interceptor>com.foo.MySecureInterceptor</interceptor> </interceptors> </web-beans>

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

import javax.webbeans.Component; import javax.webbeans.Observes; @Component public class MyHandler { public void myHandlerMethod(@Observes Movie movie) { ... } }

Your application can throw events through the WebBeans `Container` API, which is available through injection:

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")); } }

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

`@AroundInvoke` marks an interception method on the bean or an interceptor class. The interceptor is invoked while processing a business method.

@Target(METHOD) @Retention(RUNTIME) public @interface AroundInvoke { } 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"; } }

`@DenyAll` annotation marks a method as forbidden to all users.

@Target({METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface DenyAll { }

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

@Target({TYPE}) @Retention(RUNTIME) public @interface Interceptor { }

`@InterceptorBindingType` is a WebBeans meta-annotation for creating interceptor binding types. Applications will use `@InterceptorBindingType` 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.

@Target({TYPE}) @Retention(RUNTIME) public @interface InterceptorBindingType { }

`@Interceptors` marks an method or class as being intercepted by the named classes. The interceptor classes will implement an `@AroundInvoke` method to process the `InvocationContext`.

Value Meaning Default
value Lists the interceptor classes to apply to the method.
@Target({TYPE,METHOD}) @Retention(RUNTIME) public @interface Interceptors { public Class []value(); } 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; } }

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

Method Description
getContextData Returns a map containing any context information
getMethod Returns the called API method
getParameters Returns the Java parameters for the call
getTarget Returns the target object, i.e. the Java object that will receive the call after all the interceptors complete.
proceed Call the next interceptor in the chain, or call the final object at the end of the chain.
setParameters Sets the Java parameters for the call
public interface InvocationContext { public Object proceed() throws Exception; public Map<String, Object> getContextData(); public Method getMethod(); public Object[] getParameters() throws IllegalStateException; public void setParameters(Object[] parameters) throws IllegalStateException; public Object getTarget(); }

`@PermitAll` annotation marks a method as allowed for all users.

@Target({METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface PermitAll { }

`@RolesAllowed` 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.

Value Meaning Default
value Lists the roles (permissions) that are allowed.
@Target({TYPE,METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface RolesAllowed { String []value(); }

`@RunAs` changes the security context user to a defined role. Security tests within the context of the `@RunAs` will match the specified role.

Value Meaning Default
value The role name to run as.
@Target({TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface RunAs { String value(); }

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

All Resin-managed beans can use `@TransactionAttribute`: @Stateful, @Stateless, @MessageDriven and plain Java beans.

Value Meaning
REQUIRED Start a new transaction if necessary
SUPPORTS Don't start a new transaction, but use one if it exists
MANDATORY Require the caller to have started a transaction
NEVER Forbid the caller to have started a transaction
REQUIRESNEW Always start a new transaction, suspending the old one
NOTSUPPORTED Suspend any active transaction

- SUPPORTS is typically used for read-only methods
- REQUIRED is typically used for updating (read/write) methods

@Target({TYPE,METHOD}) @Retention(RUNTIME) public @interface TransactionAttribute { TransactionAttributeType value() default REQUIRED; }

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

@Target({TYPE}) @Retention(RUNTIME) public @interface BindingType { } package demo; @BindingType @Target({TYPE, METHOD, FIELD, PARAMETER}) @Retention(RUNTIME) public @interface XA { } package demo; import javax.sql.*; public class MyBean { @XA DataSource _xa; @NonXA DataSource _nonXa; ... }

Configures EJB values for a field or method.

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

Property Description Default
businessInterface The EJB interface to lookup The field type
name The EJB name of the resource The field name
jndiName The jndi name of the resource The EJB name
@Target({TYPE, METHOD, FIELD, PARAMETER}) @Retention(RUNTIME) public @interface EJB { String name() default ""; String businessInterface() default ""; String jndiName() default ""; }

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

@EJB void setFoo(example.Test test) { _test = test; }

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.

@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER, TYPE}) @Retention(RUNTIME) public @interface In { }

`@Named` is a predefined `@BindingType` annotation for named objects. Many application objects can just use `@Named` to disambiguate multiple objects with the same type.

Property Description Default
value The name binding for the object to inject required
@BindingType @Target({METHOD, FIELD, PARAMETER, TYPE}) @Retention(RUNTIME) public @interface Named { String value(); }

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

@Target({METHOD, FIELD, PARAMETER, TYPE}) @Retention(RUNTIME) public @interface New { }

`@NonBinding` is a meta-annotation used for creating `@BindingType` 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 `@NonBinding` annotation skips the check for the annotated property.

@Target({FIELD, METHOD}) @Retention(RUNTIME) public @interface NonBinding { } package demo; @BindingType @Target({TYPE, METHOD, FIELD, PARAMETER}) @Retention(RUNTIME) public @interface Demo { @NonBinding String description() default ""; }

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

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

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

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.

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

- http://wiki.caucho.com/Mule
- http://wiki.caucho.com/Spring
- http://wiki.caucho.com/Struts2
- http://wiki.caucho.com/Wicket

Implementing new object factories for other frameworks is straightforward.

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

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); } }

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.

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); } }
</document>