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


 

Resin Documentation

home company blog wiki docs 
app server web server 
health cloud java ee pro 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

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.

Example: creating a standalone web server

  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
Example: example/TestResin.java
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();
  }
}

Example: embedding Resin for testing

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.

Example: example/TestResin.java
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);
  }
}

ResinEmbed

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
com.caucho.resin.ResinEmbed
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.

Example: Trivial ResinEmbed call
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.

BeanEmbed

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.

com.caucho.resin.BeanEmbed
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);
}
Example: Adding Bean services
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.

Example: test.php
my-service <?= java_bean("my-service") ?>

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

Example: qa/MyServlet.java
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.

Example: Dynamic Bean
BeanEmbed bean = new BeanEmbed("example.MyBean");

bean.setName("my-bean");

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

webApp.addBean(bean);

HttpEmbed

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

com.caucho.resin.HttpEmbed
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.

Example: Trivial HttpEmbed call
public static void main(String [])
{
  ResinEmbed resin = new ResinEmbed();

  HttpEmbed http = new HttpEmbed(8080);

  resin.addHttp(http);

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

WebAppEmbed

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.

com.caucho.resin.WebAppEmbed
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);
}
Example: Adding Bean to a web-app
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

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.

com.caucho.resin.ServletMappingEmbed
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);
}
Adding Servlet to a web-app
webApp = new WebAppEmbed("/", "/home/qa/test1");

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

ServletProtocolEmbed

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.

com.caucho.resin.ServletProtocolEmbed
public class ServletProtocolEmbed {
  public ServletProtocolEmbed();
  public ServletProtocolEmbed(String uri);

  public void setUri(String uri);
  public void addProperty(String name, Object value);
}
Example: Hessian service
service = new ServletMappingEmbed("my-service", "/hessian",
                                  "example.MyService");

protocol = new ServletProtocolEmbed("hessian");

service.addProtocol(protocol);

webApp.addServlet(service);

jUnit

Example: jUnit test
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();
  }
}

command-line, ResinEmbed main()

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.

command-line arguments
--port=8080TCP port to listen to
--deploy:Enables the local deployment web-app for IDEs
Example: launching embedded Resin from the command line
resin> java -classpath $CP com.caucho.resin.ResinEmbed --port=8080

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

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company blog wiki docs 
app server web server 
health cloud java ee pro