No Pain, No Pain | Embedded APIs for JBossAS

I patronize the Boston Sports Clubs. Every month they suck cash out of my checking account; in return I get to say I belong to the gym. My membership keychain promotes me as a fit young professional, and I’m comfortable with this positioning. False advertising at its finest.

But every now and then I get ambitious and join the ranks of the walking biceps intent on whipping my programmer’s physique into some presentable form. Jocks on all sides gruntily hoist iron plates into the air as they mainline Eminem straight from iPod to ear. Dudes, followed by mirrors reflecting an infinite row of yet more dudes. And they all cry the same anthem: “No pain, no gain”.

This is some BS, but I don’t think the weight floor is a proper venue for some lesson on the merits of working “smarter not harder”. Brute force or go home.

So I went home.

You know what I’ve found painful? Writing integration tests for application servers. I’ve a clear history towards promoting JBossAS over something more lightweight[1], and in my opinion any non-trivial application that doesn’t take advantage of a decent runtime environment is a bad joke masquarading as an enterprise-class solution. But I couldn’t get around the argument that writing decent integration tests was a time-consuming and frustrating endeavor, until now.

Some time back[2] I’d reported on the progress made in prototyping an Embedded API for the JBoss Application Server, and we’re now at our first early-access release compatible with JBossAS 6.0.0.M1[13]. For the time being these Embedded libraries are shipped as an extension to AS, and I expect that after some community feedback we’ll push out a few more releases before locking things down and eventually bring everything into the AS distribution.

Now we’re all very proud to reintroduce JBoss EmbeddedAS[3] 1.0.0-alpha-1.

What’s in this Release

Very simply, this gives you the API hooks to create, configure, start, deploy into, and stop the server in a POJO environment. Slap your favorite testing framework into the mix and integrate with your build system, and you’re on the path to automated integration tests.

The syntax is so easy, it’s barely worth covering. Our API Guide[4] should touch upon the more common use cases.

@BeforeClass
public static void startEmbedddedAS() throws Exception
{
  // Make Server
  server = JBossASEmbeddedServerFactory.createServer();
  // Configure
  server.getConfiguration().serverName("all")
    .jbossHome("/path/to/$JBOSS_HOME");
  // Start
  server.start();
}

@AfterClass
public static void stopEmbeddedAS() throws Exception
{
  // If exists and started
  if (server != null &&
     server.getState().equals(LifecycleState.STARTED))
  {
    // Shutdown
    server.shutdown();
  }
}

Testing is now a matter of assembling resources together into a unified view, then deploying into the server. Currently supported are Files, URLs, and ShrinkWrap[14] archives, though you’re welcome to use your own Deployable implementation. As an example:

@Test
public void testStatelessSessionBean() throws Exception
{
  // Make a ShrinkWrap archive
  final String name = "slsb.jar";
  final JavaArchive archive = Archives.create(name, JavaArchive.class).
    addClasses(OutputBean.class,OutputLocalBusiness.class);
  // Deploy
  server.deploy(archive);
  // Test
  final OutputLocalBusiness bean = (OutputLocalBusiness) NAMING_CONTEXT.lookup
    (OutputBean.class.getSimpleName()
    + JNDI_SUFFIX_LOCAL_BUSINESS);
  final String output = bean.getOutput();
  Assert.assertEquals(OutputLocalBusiness.EXPECTED_OUTPUT, output);
  // Undeploy
  server.undeploy(archive);
}

Because the server is within the same JVM as the tests, we can now:

* Invoke upon EJB3 local views
* Reliably test asynchronous invocations (eg. by setting a Barrier in an EJB3 Message-Driven Bean)
* Test operations which use pass-by-reference
* Gain access to the server’s internal Microcontainer Kernel

Examples of each are in the EmbeddedAS Integration Testsuite[5].

One interesting complication of running the server in a host JavaSE environment is that you’ll have to make some choices regarding the ClassLoading model used. If your test relies upon AS internals (ie. uses Microcontainer directly), it’s likely that you’ll need the entire AS dependency set upon your application classpath; we provide more information and suggested instructions for this technique here[6]. However, this imposes a great number of libraries be passed into your test process via “-classpath”, and it’s likely you’ll want to opt for a slimmer boot profile. If you’ve got good separation and call upon the EmbeddedAS APIs only, you may pull in the remaining runtime dependencies via a “JBossHomeClassLoader” upon server creation; more details here[7].

Looking Forward

At the moment we’re offering EmbeddedAS as a preview for community input, and openly encourage your participation in our forums[8]. The current links upon the Wiki are a bit Maven-centric, though folks preferring to set up the test runtime via Ant should be able to do so as well – feel free to add to the documentation.

One of the current limitations is that EmbeddedAS 1.0.0-alpha-1 will be released only through the JBoss Maven Repository[9]. It may still be manually downloaded, but in subsequent releases we’ll also provide a unified ZIP (or move everything into AS itself).

Already we’ve received interest in and are considering a Maven2 Plugin similar to Cargo for launching the server and deploying artifacts. This could remove the need to manually code these steps.

Contributions by Aslak Knutsen and the Arquillian[10] project aim to abstract out the server creation/start/deployment steps as well, instead making way for syntax like:

@RunWith(Arquillian.class)
public class GreetingManagerTest
{
  @Deployment
  public static JavaArchive createDeployment()
  {
    return Archives.create("test.jar", JavaArchive.class)
      .addClasses(
      GreetingManager.class,
      GreetingManagerBean.class);
  }

  @EJB
  private GreetingManager greetingManager;

  @Test
  public void shouldGreetUser() throws Exception
  {
    String userName = "Devoxx";
    Assert.assertEquals(
      "Hello " + userName,
      greetingManager.greet(userName));
  }
}

Adrian Cole of jclouds[11] has also expressed a desire to investigate EmbeddedAS as a provisioning engine for transporting workflows. I hope to continue these discussions looking forward.

In the meantime, glance over our Wiki and give everything a spin. We’ve got a neat screencast[12] and interview, Dimitris[15] and Jason[17] have nice summaries of AS 6.0.0.M1, and Brian discusses[16] some new clustering features as well.

We’ll offer bug fixes, feature enhancements, and API changes in subsequent releases to be compatible with the latest available release of JBossAS, starting with 6.0.0.M1.

What we can make easier, we will. I’ve a low tolerance for all things unpleasant, so no pain, no pain.

S,

ALR

[1] http://exitcondition.alrubinger.com/2008/01/05/heavy-is-a-perception/
[2] http://exitcondition.alrubinger.com/2009/07/29/were-gonna-be-good-embed/
[3] http://www.jboss.org/community/docs/DOC-13843
[4] http://www.jboss.org/community/docs/DOC-14437
[5] http://anonsvn.jboss.org/repos/jbossas/projects/embedded/trunk/testsuite/src/test/java/org/jboss/embedded/testsuite/ServerIntegrationTest.java
[6] http://www.jboss.org/community/docs/DOC-14441
[7] http://www.jboss.org/community/docs/DOC-14447
[8] http://www.jboss.org/index.html?module=bb&op=viewforum&f=265
[9] http://repository.jboss.org/maven2/org/jboss/embedded/
[10] http://www.jboss.org/community/docs/DOC-14376
[11] http://code.google.com/p/jclouds/
[12] http://java.dzone.com/videos/embedded-jboss
[13] http://www.jboss.org/jbossas/downloads/
[14] http://jboss.org/shrinkwrap/
[15] http://dandreadis.blogspot.com/2009/12/jboss-as-600-m1.html
[16] http://bstansberry.wordpress.com/2009/12/02/clustering-features-in-jboss-application-server-6-0-0-m1/
[17] http://in.relation.to/Bloggers/IntroducingJBossAS600M1