Resin Documentation

embedding resin

Resin's embedding API lets developers embed Resin as the web interface for an existing application, simplifies unit testing, and improves IDE integration capabilities. The ResinEmbed JavaDoc gives more details.

1. Download Resin from http://caucho.com/download
2. Unzip Resin in /usr/local/share and make a symlink from /usr/local/share/resin
3. Add the jars in resin/lib/*.jar to the CLASSPATH
4. Create and compile a TestResin class as described below
5. Browse http://localhost:8080

package example;

import com.caucho.resin.*;

public class TestResin {

  public static void main(String []args)
  {
    ResinEmbed resin = new ResinEmbed();

    HttpEmbed http = new HttpEmbed(8080);
    resin.addPort(http);

    WebAppEmbed webApp = new WebAppEmbed("/", "/var/www/htdocs");
    resin.addWebApp(webApp);

    resin.start();
    resin.join();
  }
}

For testing, you can create an embedded Resin instance and browse URLs programmatically using the resin.request() method. Since the request method runs Resin's normal HTTP processing, you can use any HTTP requests or headers.

package example;

import com.caucho.resin.*;

public class TestResin {

  public void main(String []args)
  {
    ResinEmbed resin = new ResinEmbed();

    WebAppEmbed webApp = new WebAppEmbed("/", "/var/www/htdocs");
    resin.addWebApp(webApp);

    resin.start();

    String result = resin.request("GET /test.jsp");
    System.out.println(result);
  }
}

The ResinEmbed class represents a Resin instance. It contains:

• A set of ports (usually http)
• A set of beans available through WebBeans injection
• A set of web-apps
• Methods for starting/stopping
• Methods for Java-based HTTP requests

public class ResinEmbed {
  public ResinEmbed();
  public ResinEmbed(String resinConfPath);

  public void addBean(BeanEmbed bean);
  public void addPort(PortEmbed port);
  public void setServerHeader(String serverName);
  public void addWebApp(WebAppEmbed webApp);

  public void join();
  public void destroy();
  public void start();

  public void request(InputStream is, OutputStream os)
    throws IOException;
  public void request(String request, OutputStream os)
    throws IOException;
  public String request(String request)
    throws IOException;
}

A ResinEmbed can be created and started without any other classes, although it won't do anything useful. The following example will return a 404 Not Found response string from the request since there are no web-apps configured. The example will not listen to any ports at all, since no HttpEmbed objects have been added.

public static void main(String [])
{
  ResinEmbed resin = new ResinEmbed();

  resin.start();

  String result = resin.request("GET /test.jsp");

  System.out.println(result);
}

See also the ResinEmbed JavaDoc.

Beans are created using the BeanEmbed API. If your application wants to expose services to the embedded web-app, just add a BeanEmbed to the Resin instance. BeanEmbed can also create dynamically created service, by setting a class name instead of an object.

public class BeanEmbed {
  public BeanEmbed();
  public BeanEmbed(Object value);
  public BeanEmbed(Object value, String name);
  public BeanEmbed(String className, String name);

  public void setClass(String className);
  public void setName(String name);
  public void setValue(Object value);

  public void addProperty(String name, Object value);
}

public void main()
{
  MyService service = new MyService();

  ResinEmbed resin = new ResinEmbed();

  resin.addBean(new BeanEmbed(service, "my-service"));

  resin.addWebApp(new WebAppEmbed("/", "/var/www/htdocs"));
  resin.start();

  String result = resin.request("GET /test.php");

  System.out.println(result);
}

A testing PHP file could use java_bean() to retrieve the service.

my-service <?= java_bean("my-service") ?>

A testing servlet can inject the service with @javax.webbeans.In.

package qa;

import javax.servlet.*;
import javax.webbeans.*;

public class MyServlet extends GenericServlet {
  @In MyService _myService;

  ...
}

The following example configures a dynamically-created bean instance and adds some <init> property values.

BeanEmbed bean = new BeanEmbed("example.MyBean");

bean.setName("my-bean");

bean.addProperty("greeting", "hello, world");

webApp.addBean(bean);

You can add http ports using the HttpEmbed class. When you start Resin, it will listen to the configured ports.

public class HttpEmbed {
  public HttpEmbed();
  public HttpEmbed(int port);
  public HttpEmbed(int port, String ipAddress);
}

The following trivial example will start Resin as the web server listening to port 8080 and always returning 404 since there are no web-apps defined.

public static void main(String [])
{
  ResinEmbed resin = new ResinEmbed();

  HttpEmbed http = new HttpEmbed(8080);

  resin.addHttp(http);

  resin.start();
  resin.join();
}

WebAppEmbed represents a web-app. The defaults are the same as if Resin was started normally, i.e. the standard file, jsp, and php servlets are already defined, and will read the WEB-INF/web.xml and WEB-INF/resin-web.xml (and compile classes in WEB-INF/classes). Normally, an embedded web-app will just set the context-path, root-directory and possibly add extra beans, although it's possible to add servlets and filters as well.

• The context-path (i.e. the URL prefix)
• The root-directory
• An optional archive-path for a .war file
• Any added BeanEmbed beans
• Any added ServletMappingEmbed servlets
• Any added FilterMappingEmbed filters

For unit testing, you can use combination of BeanEmbed and test web-app directories as a unit test framework. Each test-x.php (or qa.TestServletX) can test a different aspect of the service.

public class WebAppEmbed {
  public WebAppEmbed();
  public WebAppEmbed(String contextPath);
  public WebAppEmbed(String contextPath, String rootDirectory);

  public void setArchivePath(String archivePath);
  public String getArchivePath();
  public String getContextPath();
  public void setContextPath(String contextPath);
  public String getRootDirectory();
  public void setContextParam(String name, String value);

  public void addBean(BeanEmbed bean);

  public void addFilter(FilterEmbed servlet);
  public void addFilterMapping(FilterMappingEmbed mapping);

  public void addServlet(ServletEmbed servlet);
  public void addServletMapping(ServletMappingEmbed mapping);
}

public void main()
{
  MyService service = new MyService();

  ResinEmbed resin = new ResinEmbed();

  WebAppEmbed webApp = new WebAppEmbed("/", "/home/qa/test1");
  webApp.addBean(new BeanEmbed(service));

  resin.addWebApp(webApp);

  resin.start();

  String result = resin.request("GET /test-a.php");
  System.out.println(result);

  result = resin.request("GET /test-b.php");
  System.out.println(result);
}

ServletMappingEmbed lets you configure servlets in an embedded Resin instance, e.g. if you want to expose an administration application or deployment application and not put these in the resin-web.xml. ServletMappingEmbed lets you configure <init-param> values as well as <init> properties.

public class ServletMappingEmbed {
  public ServletMappingEmbed();
  public ServletMappingEmbed(String servletName);
  public ServletMappingEmbed(String servletName, String urlPattern);
  public ServletMappingEmbed(String servletName, String urlPattern,
                             String servletClass);

  public String getServletClass();
  public void setServletClass(String servletClass);
  public String getServletName();
  public void setServletName(String servletName);
  public String getUrlPattern();
  public void setUrlPattern(String urlPattern);

  public void setLoadOnStartup(int loadOnStartup);
  public void setInitParam(String name, String value);
  public void addProperty(String name, Object value);

  public void setProtocol(ServletProtocolEmbed protocol);
}

webApp = new WebAppEmbed("/", "/home/qa/test1");

servlet = new ServletMappingEmbed("my-servlet", "/test", "example.MyServlet");
webApp.addServletMapping(servlet);

ServletProtocolEmbed lets you export remote services using Hessian, Burlap, or any other protocol implementation which provides a driver for Resin. The configuration for a remote service is exactly the same as for a servlet, i.e. using ServletMappingEmbed, and just adds a ServletProtocolEmbed to select the protocol.

public class ServletProtocolEmbed {
  public ServletProtocolEmbed();
  public ServletProtocolEmbed(String uri);

  public void setUri(String uri);
  public void addProperty(String name, Object value);
}

service = new ServletMappingEmbed("my-service", "/hessian",
                                  "example.MyService");

protocol = new ServletProtocolEmbed("hessian");

service.addProtocol(protocol);

webApp.addServlet(service);

• See wiki: jUnit and Resin

package qa;

import org.junit.*;
import static org.junit.Assert.*;
import com.caucho.resin.*;

public class MyTest {
  private static ResinEmbed _resin;

  @BeforeClass
  public static void setup()
  {
    _resin = new ResinEmbed();
    WebAppEmbed webApp = new WebAppEmbed("/", "file:/tmp/caucho/qa/test");
    _resin.addWebApp(webApp);
    _resin.start();
  }

  @Test 
  public void test1plus1()
    throws java.io.IOException
  {
    assertEquals(_resin.request("GET /test.php?a=1&b=1"), "1 + 1 = 2");
  }

  @Test 
  public void test1plus2()
    throws java.io.IOException
  {
    assertEquals(_resin.request("GET /test.php?a=1&b=2"), "1 + 2 = 3");
  }

  @AfterClass
  public static void shutdown()
  {
    if (_resin != null)
      _resin.destroy();
  }
}

The ResinEmbed class contains a main() method which can be used to launch an trivial instance of Resin. Its main use is for IDEs which want to launch a testing instance of Resin.

resin> java -classpath $CP com.caucho.resin.ResinEmbed --port=8080