Resin Dependency Injection

Resin's dependency injection framework gives your application a type-safe architecture for designing and assembling services and components. Since injection is annotation-based, most components can avoid XML configuration, while XML is still available for components.

Injecting Resources

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;

  ...
}

@Named and bindings

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.

field, method, and constructor injection

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

WebBeans-enabled components (injectable objects)

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:

Resin global resources

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.

Resin configured resources

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

<resource> automatically registers the configured resource with WebBeans. In the future, the resource tag will likely be replaced by <bean> instances. The registered type is the resource type.

<web-service-client> registers remoting clients with WebBeans. The <web-service-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">

  <web-service-client class="example.HelloService">
    <url>hessian:http://localhost:8080/hello/</url>
  </web-service-client>

</web-app>

public class MyServlet extends GenericServlet {
  @In example.HelloService _hello;
  ...
}

Application components

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.

Annotation-based Component Discovery

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.

Scopes: @Singleton, @Dependent, @RequestScoped

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.

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

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

  <component class="example.Calculator" scope="request"/>

</web-app>

@New Component Discovery

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

XML configuration overview

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.

bean and component registration

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>

bean custom XML configuration

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

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

Lifecycle: @PostConstruct and @PreDestroy

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

Scripting: PHP, JSF and JSP

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

Quercus/PHP

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

?>

JSP/JSF EL

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>

@BindingType: custom injection binding

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

@Produces methods

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.

AOP/Method Interception

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 use use 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>

Event Handling

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.