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

Resin Documentation

bean configuration (setter injection)

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
Property Configuration: setXXX
1. Type conversion
2. Compatibility
Setter Injection: setXXX
1. Compatibility
Container Properties: addXXX
Validation and Assembly: @PostConstruct
1. Validation Exceptions
Nested Beans: createXXX
Setting with the body text
Returning a different object
resin:type
1. resin:type
Configuring beans from XML files

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.

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.

resin:type

This special attribute can be used with all sub-beans to instantiate a different bean class than the one defined in the parent bean.

If a sub-bean is returned from method like SubBean createSubBean() then resin:type cannot be used. A void setParent(Object obj) method in the sub-bean, which is called before the other setters, provides an opportunity for the sub-bean instance to know it's enclosing object.

The resin: in resin:type is a namespace prefix automatically mapped to http://caucho.com/ns/resin. You could use another namespace prefix, for example if you defined xmlns:foo="http://caucho.com/ns/resin", you could use foo:type.

Bean-style configuration for using resin:type

<resource jndi-name="env/message">
  <type>example.MessageBean</type>
  <init>
    <message>This is message 1</message>
    <message>This is message 2</message>
    <message resin:type="example.CustomMessage">This is message 3</message>
  </init>
</resource>

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 resin:type with createSubBean. So the setParent is useful when the @PostConstruct method needs the parent, and you need to use resin:type.

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

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

  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>

Resin Documentation

bean configuration (setter injection)

Overview

Property Configuration: setXXX

Type conversion

Compatibility

Setter Injection: setXXX

Compatibility

Container Properties: addXXX

Validation and Assembly: @PostConstruct

Validation Exceptions

Nested Beans: createXXX

Setting with the body text

Returning a different object

resin:type

resin:type

Configuring beans from XML files

NodeBuilder

RNC validation

resin:import

See also