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.

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

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.

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

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.

<Beans xmlns="urn:java:ee" xmlns:example="urn:java:example">

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

  <example:MyComponent>
  </example:MyComponent>

</Beans>

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

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.

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

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

  <qa:FooBean>
    <Named>b</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()}.

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

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.

<Beans xmlns="urn:java:ee" xmlns:example="urn:java:example">

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

</Beans>

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

public class Theater {
  public void setName(String name);

  public void addMovie(Movie movie)
}

public class Movie {
  public void setTitle(String title);
}

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

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

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

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

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

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.

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

public class MyBean {
  public MyBean(String a, String b)
  {
    ...
  }
}

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

</web-app>

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

</web-app>

public class MyBean {
  ...

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

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.

<mypkg:MyBean>
  <resin:BamService name="my-service"/>
</mypkg:MyBean>

<mypkg:MyApi>
  <resin:HessianClient
               url="http://localhost:8080/test"/>
</mypkg:MyApi>

<mypkg:MyBean>
  <resin:HessianService urlPattern="/test"/>
</mypkg:MyBean>

<mypkg:MyBean>
  <resin:JmsListener destination="my_queue"/>
</mypkg:MyBean>

<mypkg:MyBean>
  <ee:MessageDriven>
    <ee:activationConfig
               propertyName="destination"
               propertyValue="my_queue"/>
  </ee:MessageDriven>
</mypkg:MyBean>

<mypkg:MyBean>
  <ee:Startup/>
</mypkg:MyBean>

<mypkg:MyBean>
  <ee:Stateful/>
</mypkg:MyBean>

<mypkg:MyBean>
  <ee:Stateless/>
</mypkg:MyBean>

<mypkg:MyServlet>
  <ee:WebServlet value="/test"/>
</mypkg:MyServlet>