Chapter 10. Embedded

Chapter 10. Embedded
Prev		Next

10.1. Overview

The JBoss JCA embedded configuration provides a way of running a JCA container in-VM.

The configuration is useful when you want a

JCA container within your environment
JCA container when doing unit testing

Especially the ability to unit test your resource adapter archives before deploying them into a testing or a production environment will benefit developers.

10.2. Deployment

Currently you will need all the JAR files located in the

$JBOSS_JCA_HOME/lib

directory as well as sub-directories on your application class loader - f.ex.

java -classpath allthejarfiles.jar yourapp

in order to use the embedded configuration.

10.3. Usage

JBoss JCA Embedded supports both a simple and an advanced usage model, using pre-assembled resource adapter archives (.rar) or dynamic resource adapter archives based on ShrinkWrap.

10.3.1. Simple usage

The code sample below shows a simple usage of deploying a pre-assembled resource adapter archive into the JBoss JCA Embedded environment.

import org.jboss.jca.embedded.EmbeddedJCA;

import java.net.URL;

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import static org.junit.Assert.*;

public class MyTestCase
{
   /** Embedded */
   private static EmbeddedJCA embedded;

   /** JNDI prefix */
   private static final String JNDI_PREFIX = "java:/eis/";

   /**
    * Simple test to verify deployment of myresourceadapter.rar
    * @throws Throwable throwable exception 
    */
   @Test
   public void testDeployment() throws Throwable
   {
      URL archive = getURL("myresourceadapter.rar");
 
      Context context = null;
 
      try
      {
         embedded.deploy(archive);

         context = new InitialContext();
         Object o = context.lookup(JNDI_PREFIX + "myresourceadapter");
         assertNotNull(o);
      }
      catch (Throwable t)
      {
         fail(t.getMessage());
      }
      finally
      {
         embedded.undeploy(archive);

         if (context != null)
         {
            try
            {
               context.close();
            }
            catch (NamingException ne)
            {
               // Ignore
            }
         }
      }
   }

   @BeforeClass
   public static void beforeClass() throws Throwable
   {
      // Create an embedded JCA instance
      embedded = new EmbeddedJCA();

      // Startup
      embedded.startup();
   }

   @AfterClass
   public static void afterClass() throws Throwable
   {
      // Shutdown
      embedded.shutdown();
   }
}

Note

Note that, the url for the archive must end with the .rar extension - either representing a file or a directory.

See the JBoss JCA Embedded API documentation for additional functionality.

10.3.2. Advanced usage

The JBoss JCA Embedded container environment supports the following open source testing projects:

These extensions allow the developer to use the embedded platform with greater ease as there doesn't have to be a physical representation of the resource adapter archive located to the disk.

The Arquillian integration furthermore allows the developer to leave all the embedded container setup to the integration instead.

10.3.2.1. ShrinkWrap integration

The code sample below shows an advanced usage of deploying a dynamic ShrinkWrap resource adapter archive into the JBoss JCA Embedded environment.


import org.jboss.jca.embedded.EmbeddedJCA;
import org.jboss.jca.embedded.rars.simple.MessageListener;
import org.jboss.jca.embedded.rars.simple.TestActivationSpec;
import org.jboss.jca.embedded.rars.simple.TestConnection;
import org.jboss.jca.embedded.rars.simple.TestConnectionInterface;
import org.jboss.jca.embedded.rars.simple.TestManagedConnection;
import org.jboss.jca.embedded.rars.simple.TestManagedConnectionFactory;
import org.jboss.jca.embedded.rars.simple.TestResourceAdapter;

import java.util.UUID;

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import org.jboss.logging.Logger;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;

import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import static org.junit.Assert.*;

public class ShrinkWrapTestCase
{
   private static Logger log = Logger.getLogger(ShrinkWrapTestCase.class);

   /** Embedded */
   private static EmbeddedJCA embedded;

   /** JNDI prefix */
   private static final String JNDI_PREFIX = "java:/eis/";

   /**
    * Basic ShrinkWrap ResourceAdapterArchive test case
    * @exception Throwable Thrown if case of an error
    */
   @Test
   public void testBasic() throws Throwable
   {
      String deploymentName = UUID.randomUUID().toString();

      ResourceAdapterArchive raa = ShrinkWrap.create(ResourceAdapterArchive.class,
                                                     deploymentName + ".rar");

      JavaArchive ja = 
         ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addClasses(MessageListener.class, TestActivationSpec.class, 
                    TestConnection.class, TestConnectionInterface.class, 
                    TestManagedConnection.class, TestManagedConnectionFactory.class,
                    TestResourceAdapter.class);

      raa.addLibrary(ja);
      raa.addManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");

      Context context = null;
 
      try
      {
         embedded.deploy(raa);

         context = new InitialContext();
         Object o = context.lookup(JNDI_PREFIX + deploymentName);
         assertNotNull(o);
      }
      catch (Throwable t)
      {
         log.error(t.getMessage(), t);
         fail(t.getMessage());
      }
      finally
      {
         embedded.undeploy(raa);

         if (context != null)
         {
            try
            {
               context.close();
            }
            catch (NamingException ne)
            {
               // Ignore
            }
         }
      }
   }

   /**
    * Lifecycle start, before the suite is executed
    * @exception Throwable Thrown if case of an error
    */
   @BeforeClass
   public static void beforeClass() throws Throwable
   {
      // Create and set an embedded JCA instance
      embedded = new EmbeddedJCA();

      // Startup
      embedded.startup();
   }

   /**
    * Lifecycle stop, after the suite is executed
    * @exception Throwable Thrown if case of an error
    */
   @AfterClass
   public static void afterClass() throws Throwable
   {
      // Shutdown embedded
      embedded.shutdown();

      // Set embedded to null
      embedded = null;
   }
}

Note

Note that, the name for the ResourceAdapterArchive must end with the .rar extension.

See the ShrinkWrap web site for a full description of the project and additional documentation.

10.3.2.2. Arquillian integration

The code sample below shows an advanced usage of deploying a dynamic ShrinkWrap resource adapter archive into the JBoss JCA Embedded environment using Arquillian.

This setup allows the developer to skip the entire JBoss JCA Embedded container setup and handling of its lifecycle methods.


package org.jboss.jca.embedded.unit;

import org.jboss.jca.embedded.rars.simple.MessageListener;
import org.jboss.jca.embedded.rars.simple.TestActivationSpec;
import org.jboss.jca.embedded.rars.simple.TestConnection;
import org.jboss.jca.embedded.rars.simple.TestConnectionFactory;
import org.jboss.jca.embedded.rars.simple.TestConnectionInterface;
import org.jboss.jca.embedded.rars.simple.TestConnectionManager;
import org.jboss.jca.embedded.rars.simple.TestManagedConnection;
import org.jboss.jca.embedded.rars.simple.TestManagedConnectionFactory;
import org.jboss.jca.embedded.rars.simple.TestResourceAdapter;

import java.util.UUID;

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import org.jboss.arquillian.api.Deployment;
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.logging.Logger;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;

import org.junit.Test;
import org.junit.runner.RunWith;
import static org.junit.Assert.*;

/**
 * Unit test for Arquillian integration
 * 
 * @author <a href="mailto:jesper.pedersen@jboss.org">Jesper Pedersen</a>
 */
@RunWith(Arquillian.class)
public class ArquillianTestCase
{
   // --------------------------------------------------------------------------------||
   // Class Members ------------------------------------------------------------------||
   // --------------------------------------------------------------------------------||

   private static Logger log = Logger.getLogger(ArquillianTestCase.class);

   private static final String JNDI_PREFIX = "java:/eis/";
   private static String deploymentName = null;

   /**
    * Define the deployment
    * @return The deployment archive
    */
   @Deployment
   public static ResourceAdapterArchive createDeployment()
   {
      deploymentName = UUID.randomUUID().toString();

      ResourceAdapterArchive raa =
         ShrinkWrap.create(ResourceAdapterArchive.class, deploymentName + ".rar");

      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, 
                                         UUID.randomUUID().toString() + ".jar");
      ja.addClasses(MessageListener.class, TestActivationSpec.class, TestConnection.class,
                    TestConnectionFactory.class, TestConnectionManager.class, 
                    TestConnectionInterface.class, TestManagedConnection.class, 
                    TestManagedConnectionFactory.class, TestResourceAdapter.class);

      raa.addLibrary(ja);
      raa.addManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");

      return raa;
   }

   //-------------------------------------------------------------------------------------||
   // Tests ------------------------------------------------------------------------------||
   //-------------------------------------------------------------------------------------||

   /**
    * Basic
    * @exception Throwable Thrown if case of an error
    */
   @Test
   public void testBasic() throws Throwable
   {
      Context context = null;
 
      try
      {
         context = new InitialContext();
         Object o = context.lookup(JNDI_PREFIX + deploymentName);
         assertNotNull(o);
      }
      catch (Throwable t)
      {
         log.error(t.getMessage(), t);
         fail(t.getMessage());
      }
      finally
      {
         if (context != null)
         {
            try
            {
               context.close();
            }
            catch (NamingException ne)
            {
               // Ignore
            }
         }
      }
   }
}

Note

Note that, the name for the ResourceAdapterArchive must end with the .rar extension.

See the Arquillian web site for a full description of the project and additional documentation.

Prev	Up	Next
Chapter 9. Code generator	Home	Chapter 11. Community