Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

injection-based resource configuration (candi)


Resin's configuration uses a powerful, general dependency injection system (CanDI) to configure servlets, Resin resources, databases, application components, third-party libraries and drivers. By understanding a few rules matching the XML to the configured resources, an administrator can have full control over the application server behavior.

Because of the importance of verifying and debugging configuration, Resin's configuration is stateless, meaning that the XML files fully describe the configuration of the system. Resin avoids hidden state by avoiding deployment tools and internal, hidden database configuration.

Overview

Because Resin's configuration (CanDI) creates and updates Java objects, each XML tag exactly matches either a Java class or a Java property. For security and rewrite rules, the JavaDoc helps document the configuration. Your own application's configuration can use its JavaDoc to describe the XML tags, and Resin's configuration files like the META-INF/resin-web.xml to customize your application.

  • Selecting drivers and services: by specifying the Java class, like choosing a JDBC database driver, or application services. The Java classes should be self-documented in the application's JavaDoc.
  • Configuring properties: with XML values for each important property of the Java class, like setting URLs, timeouts, and connection limited. More complicated configuration is supported allowing configuration similar to domain-specific languages, for example Resin's rewrite rules and security configuration.
  • Registration for the application: the application looks up configured resources either through Java Injection or in JNDI. The application will already have defined names and binding types for the XML configuration to use.
  • Linking references: in some more complicated applications, the configuration can link resources and services together using the JSP expression language, specifying resources by name like #{myResource}.

XML configuration

Services, drivers, and third-party libraries are registered and configured using the standard Resin configuration files resin.xml or resin-web.xml files as well as the META-INF/beans.xml. Application services and libraryes are treated as first-class components just like Resin-internal resources, because Resin's own configuration uses the same CanDI configuration. Even standard JavaEE configuration like servlets, JSP .tld files, and EJBs are configured with CanDI.

The configuration in Resin is smaller than some other dependency frameworks because only components which need customization need to be in the XML. If your application is using Java Injection internally, most of the wiring occurs automatically through Java code annotations instead of being configured in XML. The annotation focus makes the Java code self-describing, and also simplifies the management by shrinking the needed 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.

Component overview

Component/Bean configuration template
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:mypkg="urn:java:com.mycom.mypkg">
	   
  <mypkg:MyBean>
    [class annotations, service, and registration]
    
    [bean constructor args]
    
    [property configuration]
    
    [method annotation configuration]
  </mypkg:MyBean>
  
</web-app>
  1. The Bean/Component name and package is the Java class which implements the resource you're configuring, either your own application class, or a library class.
  2. The class annotations register up the bean using a binding-type, or a name and may register the bean as a service, like a servlet, or EJB or remote service.
  3. The optional bean constructor args are needed for some specialized beans. The application or library JavaDocs will document if you need to use the constructor.
  4. The properties configure the bean, like setting a database's url or max-connections. Each XML tag represents a bean property, and matches exactly with the bean's JavaDoc.
  5. The optional and rare method annotations are for special cases like aspect-oriented interception. Typically, these annotations are configured by the library developers.

Service and component registration

The <my:MyBean> tags register application classes with Resin. The default scope of a <my:MyBean> is @Dependent. A <my:MyBean> will create a new instance each time it's injected or referenced.

Example: bean and component META-INF/beans.xml
<beans xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:ee="urn:java:ee"
        xmlns:example="urn:java:example">

  <example:MyService>
    <ee:ApplicationScoped/>
  </example:MyService>

  <example:MyComponent>
  </example:MyComponent>

</beans>

The <my:MyBean> tags can configure fields and annotations:

XML annotations
ATTRIBUTEDESCRIPTION
<ee:Named>the @javax.inject.Named annotations for EL naming
<ee:Qualifier>any @javax.inject.Qualifier annotations for injection
my:myFieldoptional configuration, using bean-style assignment
<ee:SessionScoped>specifies scope of the instances: request, conversation, session, application, or singleton

References and EL Expressions

Some services and components need a name because they're used as a JSP or JSF reference, or because the configuration needs a reference to the component. Resin configuration files can use EL expressions to get references to resources, beans, system properties, and calculate generatal expressions based on those values. Because all Resin's resources are added to the CanDI 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, because CanDI initializes beans lazily to handle circular references.

Example: circular references in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
       xmlns:ee="urn:java:ee">
       xmlns:qa="urn:java:qa">

  <qa:FooBean>
    <ee:Named>a</ee:Named>
    <qa:bar>#{b}</qa:bar>
  </qa:FooBean>

  <qa:FooBean>
    <ee:Named>b</ee:Named>
    <qa:bar>#{a}</qa:bar>
  </qa:FooBean>

</web-app>

You can also use beans as factories in the EL expressions, because Resin's EL implementation allows method expressions. If the bean's create method is named create(), the EL expression will look something like #{foo.create()}.

Property configuration

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.

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

Example: Hello.java
package example;

public class Hello {
  public void setGreeting(String greeting);
}

The basic example sets a greeting property of a hello, world bean. Resin will apply the configuration to the instance as part of the creation process.

Example: META-INF/beans.xml configuring a singleton
<beans xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:example="urn:java:example">

  <example:Hello>
    <example:greeting>Hello, World</example:greeting>
  </example:Hello>

</beans>

primitive conversions

Resin automatically converts XML values to the Java property types for most primitive values. For other primitive types, it also supports the JavaBeans PropertyEditor and custom converters.

Built-in String Converters
TYPEEXAMPLES
Stringhello, world
booleantrue, false
numbers3, -4, 3.14, 9.3e-20
chara, b
String[]foo, bar, baz
Classcom.foo.MyBean
Pathfile:/var/data/file
File/var/data/file
URLhttp://hessian.caucho.com/test
Patterna+[bcd]*
Date2009-07-14 10:13
Propertiesa=value
EnumerationRED, BLUE

enumerations

Enumerations are automatically converted from their string representation.

compound types

Full sub-bean configuration is also available when a service needs a more complicated configuration than primitives allow. The service class can add sub-beans as properties and the sub-beans themselves are configured recursively using Resin's configuration. Since all JavaEE configuration files like the web.xml and the *.tld files are configured using Resin's recursive sub-bean configuration, your application has full access to a powerful recursive configuration.

A sophisticated application can use Resin's sub-bean configuration to create a full domain-specific language, allowing extensive user control of the application.

custom sub-beans

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

  <example:Theater xmlns:example="urn:java:example">
    <example:name>Balboa</example:name>

    <example:movie title="The Princess Bride"/>

    <example:movie title="The Maltese Falcon"/>
  </example:Theater>

</web-app>

In this example, the Theater is configured with multiple Movie classes, each added with the addMovie method.

Example: Theater.java
public class Theater {
  public void setName(String name);

  public void addMovie(Movie movie)
}
Example: Movie.java
public class Movie {
  public void setTitle(String title);
}

list

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

Example: MyBean.setValues(List)
<my-bean>
  <values>
    <value>a</value>
    <value>b</value>
    <value>c</value>
  </values>
</my-bean>
Example: MyBean.setValues(String [])
<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.

Example: MyBean.setValues(Object)
<my-bean>
  <values>
    <list>
      <value>a</value>
      <value>b</value>
      <value>c</value>
    </list>
  </values>
</my-bean>

Resin 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.

Example: MyBean.addValue(String)
<my-bean>
  <value>a</value>
  <value>b</value>
  <value>c</value>
</my-bean>

map

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

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

Constructors

Some beans require constructor configuration because the service or library designer prefers constructors to method configuration. Resin's configuration can support these constructor beans with the <new> syntax.

Example: MyBean configuration
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:example="urn:java:example">
	    
  <example:MyBean>
    <new>
      <value>first arg<value>
      <value>second arg<value>
    </new>
  </example:MyBean>

</web-app>
Example: MyBean with constructor
public class MyBean {
  public MyBean(String a, String b)
  {
    ...
  }
}

Single constructor

As a convenience, Resin provides short form of the constructor configuration if there's only a single argument. You can either omit the <value> and just use the <new> tag, or you can even omit the <new> tag entirely.

Example: MyBean short form
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:example="urn:java:example">
	    
  <example:MyBean>
    <new>single arg</new>
  </example:MyBean>

</web-app>
Example: MyBean ultra-short form
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:example="urn:java:example">
	    
  <example:MyBean>single arg<example:MyBean>

</web-app>

valueOf

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

Example: MyBean with valueOf
public class MyBean {
  ...

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

setValue

For objects with a setValue or addText method and a zero-argument constructor, Resin-CanDI 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

Custom Services

Some of your application's beans will be configured as custom services, like Java servlets or Hessian services, using CanDI to configure a service annotation. These custom services combine your own Java code with Resin capabilities, usually to expose them as external web services.

Custom Service Configuration
ANNOTATIONDESCRIPTIONSAMPLE
@BamServiceBAM service
<mypkg:MyBean>
  <resin:BamService name="my-service"/>
</mypkg:MyBean>
@HessianClientHessian client proxy
<mypkg:MyApi>
  <resin:HessianClient
               url="http://localhost:8080/test"/>
</mypkg:MyApi>
@HessianServiceHessian service
<mypkg:MyBean>
  <resin:HessianService urlPattern="/test"/>
</mypkg:MyBean>
@JmsMessageListenerJMS based EJB message driven bean
<mypkg:MyBean>
  <resin:JmsMessageListener destination="my_queue"/>
</mypkg:MyBean>
@MessageDrivenEJB message driven bean
<mypkg:MyBean>
  <ee:MessageDriven>
    <ee:activationConfig
               propertyName="destination"
               propertyValue="my_queue"/>
  </ee:MessageDriven>
</mypkg:MyBean>
@StartupStart on initialization
<mypkg:MyBean>
  <ee:Startup/>
</mypkg:MyBean>
@StatefulEJB stateful session bean
<mypkg:MyBean>
  <ee:Stateful/>
</mypkg:MyBean>
@StatelessEJB stateless session bean
<mypkg:MyBean>
  <ee:Stateless/>
</mypkg:MyBean>
@WebServletServlet mapping
<mypkg:MyServlet>
  <ee:WebServlet value="/test"/>
</mypkg:MyServlet>

Resin CanDI

Resin is designed around the Java Contexts and Dependency Injection specification (Java CanDI, 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.

Since Resin-CanDI is used for servlets, Java objects 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.

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.

Overview

Resin's Java Injection support is integrated with EJB 3.1 Lite 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 resin-web.xml or discovered by classpath scanning.

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:

  • Lifecycle model: Java, @Stateless, @Stateful, or @MessageDriven. Resin-managed objects like Servlets and Filters are Java model beans.
  • Dependency injection: injection annotations from javax.inject: @Default, @Named, @Qualifier, @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 Java Injection @Interceptor, @InterceptorBindingType, and @Decorator are available to all beans.
  • Event handling: the Java Injection javax.enterprise.event, @Observes capability is available to all beans.

XML configuration

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 and WEB-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.

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 <my:MyBean> tags register application classes with Resin. The default scope of a <my:MyBean> is @Dependent. A <my:MyBean> will create a new instance each time it's injected or referenced.

Example: bean and component META-INF/beans.xml
<beans xmlns="http://java.sun.com/xml/ns/javaee"
   xmlns:example="urn:java:example">

  <example:MyService>
    <ee:ApplicationScoped/>
  </example:MyService>

  <example:MyComponent>
  </example:MyComponent>

</beans>

The <my:MyBean> tags can configure fields and annotations:

XML annotations
ATTRIBUTEDESCRIPTION
<ee:Named>the @javax.inject.Name annotations for EL naming
<ee:Qualifier>any @javax.inject.Qualifier annotations for injection
my:myFieldoptional configuration, using bean-style assignment
<ee:SessionScoped>specifies scope of the instances: request, conversation, session, application, or singleton

Bean property configuration

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.

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

Example: Hello.java
package example;

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

Example: META-INF/beans.xml configuring a singleton
<beans xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:example="urn:java:example">

  <example:Hello>
    <example:greeting>Hello, World</example:greeting>
  </example:Hello>

</beans>

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 @Qualifier injection as well as the standard @PostConstruct annotations. Sub-beans are not automatically registered with Java Inection, 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.

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

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

  <example:Theater xmlns:example="urn:java:example">
    <example:name>Balboa</example:name>

    <example:movie title="The Princess Bride"/>

    <example:movie title="The Maltese Falcon"/>
  </example:Theater>

</web-app>

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

Example: Theater.java
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; }
  }
}

Base configuration: string conversions

Java Injection provides a number of built-in string conversion types as well as supporting JavaBeans PropertyEditor and custom converters.

Built-in String Converters
TYPEDESCRIPTION
boolean, BooleanJava boolean
byte, ByteJava byte
short, ShortJava short
int, IntegerJava integer
long, LongJava long
float, FloatJava float
double, DoubleJava double
char, CharacterJava char
String[]String array separated by commas
ClassJava classes
PathResin VFS Paths
Filejava.io.File
URLjava.net.URL
Patternjava.util.regex.Pattern
Localejava.util.Locale
Datejava.util.Date
Propertiesjava.util.Properties
RawStringcom.caucho.config.type.RawString

enumerations

Enumerations are automatically converted from their string representation.

String constructor

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

Example: MyBean with constructor
public class MyBean {
  public MyBean(String value)
  {
    ...
  }
}

valueOf

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

Example: MyBean with valueOf
public class MyBean {
  ...

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

setValue

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

list

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

Example: MyBean.setValues(List)
<my-bean>
  <values>
    <value>a</value>
    <value>b</value>
    <value>c</value>
  </values>
</my-bean>
Example: MyBean.setValues(String [])
<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.

Example: MyBean.setValues(Object)
<my-bean>
  <values>
    <list>
      <value>a</value>
      <value>b</value>
      <value>c</value>
    </list>
  </values>
</my-bean>

Resin-CanDI 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.

Example: MyBean.addValue(String)
<my-bean>
  <value>a</value>
  <value>b</value>
  <value>c</value>
</my-bean>

map

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

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

References and EL Expressions

Resin-CanDI 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.

Example: circular references in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
  xmlns:ee="urn:java:ee"
  xmlns:qa="urn:java:qa">

  <qa:FooBean ee:Named="a">
    <bar>#{b}</bar>
  </qa:FooBean>

  <qa:BarBean ee:Named="b">
    <foo>#{a}</foo>
  </qa:BarBean>

</web-app>

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

IoC annotations

@EJB

@EJB requests the injection of an EJB session bean.

@EJB
@Target({TYPE, METHOD, FIELD})
public @interface EJB {
  String name() default "";
  Class beanInterface() default Object.class;
  String beanName() default "";
  String mappedName() default "";
}

@PersistenceContext

@PersistenceContext requests the injection of a JPA PersistenceContext.

@PersistenceContext(unitName="test")
EntityManager _em;
@PersistenceContext
package javax.persistence;

@Target({TYPE, METHOD, FIELD})
public @interface PersistenceUnit {
  String name() default "";
  String unitName() default "";
  PersistenceContextType type() default TRANSACTION;
  PersistenceProperty[] properties() default {};
}

@PersistenceUnit

@PersistenceUnit requests the injection of a JPA PersistenceUnit.

@PersistenceUnit(unitName="test")
EntityManagerFactory _emf;
@PersistenceUnit
package javax.persistence;

@Target({TYPE, METHOD, FIELD})
public @interface PersistenceUnit {
  String name() default "";
  String unitName() default "";
}

@PostConstruct

javax.annotation.PostConstruct tells the assembler to call a method after the bean has been built, but before it is active.

@PostConstruct
package javax.annotation;

@Target(value={PACKAGE,TYPE})
public @interface PostConstruct {
}

@PreDestroy

javax.annotation.PreDestroy tells the container to call the annotated method before it is destroyed.

@PreDestroy
package javax.annotation;

@Target(value={PACKAGE,TYPE})
public @interface PreDestroy {
}

@Resource

@Resource tells the assembler to retrieve a resource an assign it to a field or property. Typically, the resource will be stored in JNDI.

Known types
TYPEDESCRIPTION
DataSourceConfigured by <database>
UserTransactionUser XA interface provided by Resin
ExecutorJDK 1.5 thread pool interface (see java.util.concurrent)
@Resource
package javax.annotation;

@Target({TYPE, METHOD, FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resource {
  String name() default "";

  Class<?> type() default Object.class;
  AuthenticationType authenticationType() default CONTAINER;
  boolean shareable() default true;
  String mappedName() default "";
  String description() default "";
}

Bean Configuration

Resin configures beans using bean-style (setter injection) patterns, supporting the Inversion-of-Control design pattern. A "bean" is any plain-old Java object which follows standard configuration patterns. Because Resin can find the bean-style setters from looking at the class, it can configure those setters in a configuration file like the web.xml.

Resin's configuration follows the Assembly Line or Dependency Injection pattern.

Overview

The Assembly Line pattern gives configuration responsibility to the container where it belongs, while keeping the application code independent of the container. Bean-style configuration setters for simple properties form the foundation for the Assembly Line pattern. If an application follows the bean patterns, it can be configuration in any container following the Assembly Line (setter injection) pattern.

We strongly recommend following the Assembly Line pattern throughout an application, even if your application does not use Resin to configure itself. Following the Assembly Line pattern makes application code easier to understand, maintain, configure and test.

Assembler(Resin),Registry(JNDI) -> (MovieLocator,MovieFinderImpl)

Property Configuration: setXXX

The bean configuration form the foundation of the Assembly Line pattern. Since most applications already follow the bean patterns, they get property configuration with no changes.

Each configuration parameter foo has a corresponding setter method setFoo with a single argument for the value. Resin looks at the class using Java's reflection to find the setFoo method.

Bean-style configuration for a single value setter
<init>
  <greeting>Hello, World!</greeting>
  <another-greeting>Hello, Mom!</another-greeting>
</init>
Bean-style java code for a single value setter
public class MyBean {
  private String _greeting;
  private String _anotherGreeting;

  public void setGreeting(String greeting) 
  {
    _greeting = greeting;
  }

  public void setAnotherGreeting(String anotherGreeting) 
  {
    _anotherGreeting = anotherGreeting;
  }
}

Type conversion

A setter can have a parameter that has a type other than String. Resin will perform any type conversion necessary, so you can use integers and doubles as well as strings.

Bean-style configuration for type conversion
<init>
  <host>www.gryffindor.com</host>
  <port>80</port>
</init>
Bean-style java code for type conversion
public class MyBean {
  private String _host;
  private int _port;

  public void setHost(String host) 
  {
    _host = host;
  }

  public void setPort(int port) 
  {
    _port = port;
  }
}

Compatibility

Property configuration is very portable. Any serious configuration system will configure bean-style properties.

Setter Injection: setXXX

Setter injection connects resources following the same bean-style setter pattern. Where bean properties configure simple values like strings and integers, setter injection configures other resources like databases and application components.

Resin uses JNDI to store the intermediate resources, e.g. storing a database in java:comp/env/jdbc/test. The configuration file specifies the JNDI resource using the JSP expression language and jndi.

Configuration for Setter Injection
<init>
  <data-source>\${jndi("jdbc/test")}<data-source>
</init>
Setter Injection for a DataSource
public class MyBean {
  private DataSource _dataSource;

  public void setDataSource(DataSource ds)
  {
    _dataSource = ds;
  }
}

Compatibility

Setter injection is portable to containers which support dependency injection.

Container Properties: addXXX

Resources often act as containers for lists of values and map values. The addXXX pattern adds multiple values for a single property.

A setter method addFoo allows multiple values to be specified from the configuration.

Bean-style configuration for setting multiple values
<init>
  <greeting>Hello, World!</greeting>
  <greeting>Hello, Mom!</greeting>
</init>
Bean-style java code for setting multiple values
public class MyBean {
  private LinkedList _greetings = new LinkedList();

  public void addGreeting(String greeting) 
  {
    _greetings.add(greeting);
  }

}

Validation and Assembly: @PostConstruct

Well-written resources will validate their configuration and may perform additional assembly tasks. Resin calls methods marked with the @PostConstruct annotation after all the setter methods have been called.

Bean-style @PostConstruct
import javax.annotation.PostConstruct;

public class MyBean {
  private String _language;
  private String _country;
  Locale locale;

  public void setLanguage(String language) 
  {
    _language = language;
  }

  public void setCountry(int country) 
  {
    _country = country;
  }

  @PostConstruct
  public void init()
  {
    locale = new Locale(language, country);
  }
}

Validation Exceptions

If an exception is thrown from any of the methods in the bean, Resin will attach a file name and line number that correspond to the configuration file.

Bean-style exceptions
import java.util.Locale;
import javax.annotation.PostConstruct;

public class MyBean {
  private String _language;
  private String _country;
  Locale _locale;

  public void setLanguage(String language) 
    throws Exception
  {
    if (language.length() != 2)
      throw new Exception("'language' must be a two-character string");
    _language = language;
  }

  public void setCountry(int country) 
    throws Exception
  {
    if (country.length() != 2)
      throw new Exception("'country' must be a two-character string");
    _country = country;
  }

  @PostConstruct
  public void init() 
  {
    if (_country == null)
      throw new Exception("'country' is required");
    if (_language == null)
      throw new Exception("'language' is required");

    _locale = new Locale(language,country);
  }
}
500 Servlet Exception

WEB-INF/web.xml:9: java.lang.Exception: 'country' must be a two-character string

Nested Beans: createXXX

Beans can be nested, allowing a bean to have setters that have other sub-beans as the type.

Bean-style configuration for sub-beans
<init>
  <table>
    <name>Foo</name>
    <timestamp-field>tstamp</timestamp-field>
  </table>

  <table name="Bar" timestamp-field="ts"/>
</init>
Bean-style java code for sub-beans
import javax.annotation.PostConstruct;
import javax.sql.*;

// a class to periodically clean old log records from the database
public class LogCleaner {
  List _logTables = new LinkedList();

  // the createXXX method is optional, and allows use something other than
  // the default constructor for a sub-bean
  public LogTable createTable()
  {
    return new LogTable();
  }

  // you could also use setTable(LogTable logTable)
  public void addTable(LogTable logTable)
  {
    _logTables.add(logTable);
  }

  public class LogTable {
    String _name;
    String _timestampField;

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

    public void setTimestampField(String timestampField)
    {
      _timestampField = timestampField;
    }

    @PostConstruct
    public void init()
        throws Exception
    {
      if (_name == null)
        throw new Exception("'name' is required");
      if (_timestampField == null)
        throw new Exception("'timestamp-field' is required");
    }

    public void cleanTable(DataSource pool)
    {
      Connection conn = null;
      try {
        conn = pool.getConnection();
        ...
      } catch (SQLException e) {
        throw new ServletException(e);
      } finally {
        try {
          if (conn != null)
            conn.close();
        } catch (SQLException e) {
        }
      }
    }
  }

  ...
 
}

Setting with the body text

The addText() method will capture the body of the tag for a bean setter.

Bean-style configuration for setting with the body text
<init>
  <message>This is the message</message>
</init>
Bean-style java code for setting with the body text
public class MyBean {
  Message _msg;

  public Message createMessage() { return new Message(); }

  public void setMessage(Message msg) { _msg = msg; }

  public class Message {
    String _text;
    public void addText(String text) { _text = text; }
    public String getText() { return _text; }
  }
}

Returning a different object

There are some unusual cases where the configured bean is just a configuration object and you want to return a different bean. The bean can implement a method Object replaceObject() to return a different object. Called after the @PostConstruct.

Inline custom Beans

Inline custom beans
<beans xmlns="http://caucho.com/ns/resin"
  xmlns:resin="urn:java:com.caucho.resin"
  xmlns:example="urn:java:com.foo.example">

<example:MessageBean resin:Jndi="env/message">
  <message>This is message 1</message>
  <message>This is message 2</message>
  <message>
     <example:CustomMessage/>
   </message>
</example:MessageBean>

</beans>
MessageBean.java
package example;

import java.util.*;

public class MessageBean {
  List _msgs = new LinkedList();

  public void addMessage(Message msg) 
  { 
    _msgs.add(msg); 
    System.out.println("MessageBean.addMessage(): " + msg);
  }

  // this never get's called, because MessageBean has no parent
  public void setParent(Object obj) 
  { 
    System.out.println("MessageBean.setParent(): " + obj);
  }

}
Message.java
package example;

public class Message {
  String _text;
  public void addText(String text) 
  { 
    _text = text; 
    System.out.println("Message.addText(): " + text);
  }

  public void setParent(Object obj) 
  { 
    System.out.println("Message.setParent(): " + obj);
  }

  public String toString()
  {
    return super.toString() + ": " + _text;
  }
}
Message.java
package example;

public class CustomMessage extends Message {
  public void addText(String text) 
  { 
    _text = text; 
    System.out.println("CustomMessage.addText(): " + text);
  }

  public void setParent(Object obj) 
  { 
    System.out.println("CustomMessage.setParent(): " + obj);
  }
}
Message.setParent(): example.MessageBean@ffb35e
Message.addText(): This is message 1
MessageBean.addMessage(): example.Message@1591b4d: This is message 1
Message.setParent(): example.MessageBean@ffb35e
Message.addText(): This is message 2
MessageBean.addMessage(): example.Message@10f965e: This is message 2
CustomMessage.setParent(): example.MessageBean@ffb35e
CustomMessage.addText(): This is message 3
MessageBean.addMessage(): example.CustomMessage@12164ea: This is message 3

In practice, it may make more sense to use createSubBean or addSubBean to set a parent-child relationship for beans, instead of setParent. The possible issue with addSubBean is that @PostConstruct methods are called before addSubBean. The possible issue with createSubBean is that it's not possible to use a <mypkg:MySubBean> with createSubBean. So the setParent is useful when the @PostConstruct method needs the parent, and you need to use <mypkg:MySubBean>.

Configuring beans from XML files

The facilities provided by Resin make it very easy to read XML files. Java classes that follow the java bean pattern are defined to match the schema of the xml file.

rss-example.xml
<rss version="0.91">
  <channel>
    <title>Hogwarts</title> 
    <link>http://hogwarts.com</link> 
    <description>Hogwart's News</description>
    <image>
      <title>Hogwarts</title> 
      <url>http://hogwarts.com/images/logo.gif</url> 
      <link>http://hogwarts.com</link> 
      <width>88</width> 
      <height>31</height> 
      <description>Hogwart's News</description> 
    </image>
    <item>
      <title>New Course Additions</title>
      <link>http://hogwarts.com/news/00123.html</link>
      <description>New course's are now available at Hogwart's.</description>
    </item>
    <item>
      <title>Dumbledore is back!</title>
      <link>http://hogwarts.com/news/00122.html</link>
      <description>
        After a short hiatus, Professor Dumbledore is back as 
        Headmaster of Hogwart's.
      </description>
    </item>
  </channel>
</rss>
example/rss/Rss.java
package example.rss;

import java.util.ArrayList;

public class Rss {
  private String _version;
  private ArrayList<Channel> _channels = new ArrayList<Channel>;

  public void setVersion(String version)
  {
    _version = version;
  }

  public String getVersion()
  {
    return _version;
  }

  public void addChannel(Channel channel)
  {
    _channels.add(channel);
  }

  public ArrayList<Channel> getChannels()
  {
    return _channels;
  }
}

example/rss/Channel.java
package example.rss;

import java.util.ArrayList;

public class Channel {
  private String _title;
  private String _link;
  private String _description;
  private String _language;
  private Image _image;
  private ArrayList<Item> _items = new ArrayList<Item>;

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

  public String getTitle()
  {
    return _title;
  }

  public void setLink(String link)
  {
    _link = link;
  }

  public String getLink()
  {
    return _link;
  }

  public void setDescription(String description)
  {
    _description = description;
  }

  public String getDescription()
  {
    return _description;
  }

  public void setImage(Image image)
  {
    _image = image;
  }

  public Image getImage()
  {
    return _image;
  }

  public void addItem(Item item)
  {
    _items.add(item);
  }

  public ArrayList<Items> getItems()
  {
    return _items;
  }
}
example/rss/Image.java
package example.rss;

public class Image {
  private String _title;
  private String _url;
  private String _link;
  private int _width;
  private String _height;
  private String _description;

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

  public String getTitle()
  {
    return _title;
  }

  public void setLink(String link)
  {
    _link = link;
  }

  public String getLink()
  {
    return _link;
  }

  public void setWidth(int width)
  {
    _width = width;
  }

  public int getWidth()
  {
    return _width;
  }

  public void setHeigth(int height)
  {
    _height = height;
  }

  public int getHeight()
  {
    return _height;
  }

  public void setDescription(String description)
  {
    _description = description;
  }

  public String getDescription()
  {
    return _description;
  }
}
example/rss/Item.java
package example.rss;

public class Item {
  private String _title;
  private String _link;
  private String _description;

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

  public String getTitle()
  {
    return _title;
  }

  public void setLink(String link)
  {
    _link = link;
  }

  public String getLink()
  {
    return _link;
  }

  public void setDescription(String description)
  {
    _description = description;
  }

  public String getDescription()
  {
    return _description;
  }
}

NodeBuilder

com.caucho.config.NodeBuilder is used to configure beans from an xml file.

NodeBuilder constructs beans from rss-example.xml
  import com.caucho.config.NodeBuilder;
  import com.caucho.vfs.Path;

  ...

  Rss rss = new Rss();
  NodeBuilder builder = new NodeBuilder();

  Path rssPath = new Path("WEB-INF/rss-example.xml");

  builder.configure(rss,rssPath);

RNC validation

RNC validation
  import com.caucho.config.NodeBuilder;
  import com.caucho.vfs.Path;

  ...

  Rss rss = new Rss();
  NodeBuilder builder = new NodeBuilder();

  Path rssPath = new Path("WEB-INF/rss-example.xml");
  Path schemaPath = new Path("WEB-INF/rss.rnc")builder.setCompactSchema(schemaPath);

  builder.configure(rss,rssPath);

resin:import

resin:import is used to read configuration information from another file.

rss-example.xml
<rss version="0.91">
 <resin:import>
   <fileset dir="channels/">
     <include name="*.xml"/>
   </fileset>
  </resin:import>
channels/hogwarts.xml
<channel>
  <title>Hogwarts</title> 
  <link>http://hogwarts.com</link> 
  <description>Hogwart's News</description>
  <image>
    <title>Hogwarts</title> 
    <url>http://hogwarts.com/images/logo.gif</url> 
    <link>http://hogwarts.com</link> 
    <width>88</width> 
    <height>31</height> 
    <description>Hogwart's News</description> 
  </image>
  <item>
    <title>New Course Additions</title>
    <link>http://hogwarts.com/news/00123.html</link>
    <description>New course's are now available at Hogwart's.</description>
  </item>
  <item>
    <title>Dumbledore is back!</title>
    <link>http://hogwarts.com/news/00122.html</link>
    <description>
      After a short hiatus, Professor Dumbledore is back as 
      Headmaster of Hogwart's.
    </description>
  </item>
</channel>

Administration

Administration
NAMEDESCRIPTION
<resin:JmxService>Enables cluster-wide JMX administration.
<resin:LogService>Stores high-priority log messages in a database.
<resin:PingMailer>Mails a notification when a ping check fails.
<resin:PingThread>Checks status of Resin sutomatically.
<resin:StatService>Gathers timed runtime status of Resin for graphing.
<resin:XaLogService>Transaction log service.
<resin:RemoteAdminService>Enables administration by remote agents, like an eclipse console.

Clustered Caching (JCache)

Caches
NAMEDESCRIPTION
<resin:ByteStreamCache>Distributed cache of InputStream/OutputStream byte streams across a cluster pod.
<resin:ClusterCache>JCache-style distributed object cache across a cluster pod (java.util.Map).
<resin:GlobalCache>JCache-style distributed object cache across the entire Resin system.

JMS

JMS
NAMEDESCRIPTION
<resin:JmsConnectionFactory>Combined Queue and Topic ConnectionFactory.
<resin:ClusterQueue>Clustered queue.
<resin:FileQueue>Filesystem based queue.
<resin:FileTopic>Filesystem based topic.
<resin:MemoryQueue>Memory based queue.
<resin:MemoryTopic>Memory based topic.

Protocols

Protocols
NAMEDESCRIPTION
<resin:FastCgiPort>FastCGI requests, e.g. from nginx.

Rewrite

Dispatch rules
NAMEDESCRIPTION
<resin:Dispatch>Normal servlet dispatching with optional target rewriting.
<resin:FastCgiProxy>Proxies the request to a backend server using FastCGI as a proxy protocol.
<resin:Forbidden>Send a HTTP forbidden response.
<resin:Forward>Forwards to the new URL using RequestDispatcher.forward with the target URL.
<resin:HttpProxy>Proxies the request to a backend server using HTTP as a proxy protocol.
<resin:LoadBalance>Load balance to a cluster of backend Resin servers.
<resin:Redirect>Send a HTTP redirect to a new URL specified by target.
<resin:SendError>Send a HTTP error response.
AbstractTargetDispatchRuleBase class for custom dispatch rules.
Rewrite filters
NAMEDESCRIPTION
<resin:SetHeader>Sets a response header.
<resin:SetRequestSecure>Marks the request as secure.
<mypkg:MyFilter>Servlet filters.

Repository

Repository
NAMEDESCRIPTION
<resin:ProjectJarRepository>Maven-style library jar management for webapps.

Request Conditions

Basic conditions
NAMEDESCRIPTION
<resin:IfAuthType>Checks for the authentication type, request.getAuthType().
<resin:IfCookie>Checks for the presence of a named HTTP cookie from request.getCookies().
<resin:IfCron>Matches if the current time is in an active range configured by cron-style times.
<resin:IfFileExists>Matches if the URL corresponds to an actual file.
<resin:IfHeader>Tests for a HTTP header and value match.
<resin:IfLocale>Tests for a Locale match from the HTTP request.
<resin:IfLocalPort>Compares the local port of the request, request.getLocalPort().
<resin:IfMethod>Compares the HTTP method, request.getMethod().
<resin:IfNetwork>Compares the remote IP address to a network pattern like 192.168/16.
<resin:IfQueryParam>Tests for a HTTP query parameger, request.getParameter().
<resin:IfRemoteAddr>Tests against the remote IP address, request.getRemoteAddr().
<resin:IfRemoteUser>Tests against the remote user, request.getRemoteUser().
<resin:IfSecure>True for SSL requests, i.e. if request.isSecure() is true.
<resin:IfUserInRole>Tests is the user is in the servlet security role.
RequestPredicateInterface for custom request predicates.
Combining conditions
NAMEDESCRIPTION
<resin:And>Matches if all children match.
<resin:Or>Matches if any children match.
<resin:Not>Matches if the child does not match.
<resin:NotAnd>Matches if any child does not match.
<resin:NotOr>Matches if all the children do not match.

Scheduling

Scheduling
NAMEDESCRIPTION
<resin:ScheduledTask>cron-style task scheduling.

Security

Authenticators
NAMEDESCRIPTION
<resin:AdminAuthenticator>Resin administration authentication (same syntax as XmlAuthenticator).
<resin:DatabaseAuthenticator>Authentication using a JDBC database schema.
<resin:JaasAuthenticator>Java authentication service authenticator.
<resin:LdapAuthenticator>LDAP authentication using JNDI.
<resin:PropertiesAuthenticator>.properties file authentication.
<resin:XmlAuthenticator>.xml file authentication.
AbstractAuthenticatorAbstract class for custom authentication.
Single Signon
NAMEDESCRIPTION
<resin:ClusterSingleSignon>Cluster-based single signon.
<resin:MemorySingleSignon>Memory-based single signon.
Login managers
NAMEDESCRIPTION
<resin:BasicLogin>HTTP basic authentication.
<resin:DigestLogin>HTTP digest authentication.
<resin:FormLogin>Servlet form authentication.
AbstractLoginAbstract class for custom login.
Authorization rules
NAMEDESCRIPTION
<resin:Allow>Allows access to a URL pattern.
<resin:Deny>Denies access to a URL pattern.
Permission Mapping
NAMEDESCRIPTION
<resin:XmlRoleMap>Role to group permission mapping.
AbstractRoleMapAbstract class for custom role to group permission mapping.

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.