<document>
<localtoc/>

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.

--port=8080 TCP port to listen to
--deploy: Enables the local deployment web-app for IDEs
resin> java -classpath $CP com.caucho.resin.ResinEmbed --port=8080
</document>