JBoss.orgCommunity Documentation
The IronJacamar embedded configuration provides a way of running a JCA container in-VM.
The configuration is useful when you want a
Especially the ability to unit test your resource adapter archives before deploying them into a testing or a production environment will benefit developers.
In order to enhance the experience with working with the embedded configuration the container integrates with the ShrinkWrap and Arquillian frameworks.
You will need all the JAR files located in the
$IRON_JACAMAR_HOME/bin
$IRON_JACAMAR_HOME/lib
$IRON_JACAMAR_HOME/lib/embedded
directories on your application class loader - f.ex.
java -classpath allthejarfiles.jar yourapp
in order to use the embedded configuration.
If you want integration with the Arquillian framework you need to add the JAR files located in the
$IRON_JACAMAR_HOME/lib/embedded/arquillian
directory as well.
Furthermore you will need to configure Java Naming and Directory Interface (JNDI) and logging using for example property files.
jndi.properties file:
java.naming.factory.initial=org.jnp.interfaces.LocalOnlyContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
logging.properties file:
# Additional logger names to configure (root logger is always configured)
loggers=org.jboss.jca,org.jboss,org.jnp,com.arjuna
# Root logger level
logger.level=${iron.jacamar.log.level:INFO}
logger.handlers=CONSOLE, FILE
# org.jboss.jca
logger.org.jboss.jca.level=DEBUG
# org.jboss
logger.org.jboss.level=INFO
# org.jnp
logger.org.jnp.level=INFO
# com.arjuna
logger.com.arjuna.level=INFO
# Console handler configuration
handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
handler.CONSOLE.properties=autoFlush
handler.CONSOLE.level=${iron.jacamar.log.console.level:INFO}
handler.CONSOLE.autoFlush=true
handler.CONSOLE.formatter=PATTERN
# File handler configuration
handler.FILE=org.jboss.logmanager.handlers.FileHandler
handler.FILE.level=${iron.jacamar.log.file.level:DEBUG}
handler.FILE.properties=autoFlush,fileName
handler.FILE.autoFlush=true
handler.FILE.fileName=${test.dir}/embedded/test.log
handler.FILE.formatter=PATTERN
# Formatter pattern configuration
formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
formatter.PATTERN.properties=pattern
formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c{1}] %m%n
These files needs to be available to the application classloader.
The code generator will generate a test suite based on the Arquillian functionality, so that environment can be used as a starting point for your own integration.
This setup will show you how to use dependencies from the JBoss Nexus Maven repository instead if you choose the Maven or Ant+Ivy based build environment.
jdbc-local.rar
for <datasource> support, or jdbc-xa.rar
for <xa-datasource> support. Both archives can be found in the
system/ directory.IronJacamar 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.
The embedded environment supports registering resource adapters and datasources in the platform
MBeanServer by setting the system property
ironjacamar.embedded.management to true before starting the environment.
The code sample below shows a simple usage of deploying a pre-assembled resource adapter archive into the IronJacamar Embedded environment.
import org.jboss.jca.embedded.Embedded;
import org.jboss.jca.embedded.EmbeddedFactory;
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 Embedded 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 = EmbeddedFactory.create();
// Startup
embedded.startup();
}
@AfterClass
public static void afterClass() throws Throwable
{
// Shutdown
embedded.shutdown();
}
}
.rar extension
- either representing a file or a directory.See the IronJacamar Embedded API documentation for additional functionality.
IronJacamar features a bean called RAActivator which will automatic
create a JNDI binding for connection factories and administration objects. However,
sometimes it is of benefit to define these bindings in a -ra.xml file, and therefore
RAActivator has to be disabled during that deployment phase.
This done by using the following code snippet
import org.jboss.jca.deployers.fungal.RAActivator;
// Disable RAActivator
RAActivator raa = embedded.lookup("RAActivator", RAActivator.class);
if (raa == null)
throw new IllegalStateException("RAActivator not defined");
raa.setEnabled(false);
embedded.deploy("myrar.rar");
embedded.deploy("myrar-ra.xml");
raa.setEnabled(true);
which disables the bean, does the deployments and then reenables the bean again.
The IronJacamar 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.
The code sample below shows an advanced usage of deploying a dynamic ShrinkWrap resource adapter archive into the IronJacamar Embedded environment.
/*
* JBoss, Home of Professional Open Source.
* Copyright 2009, Red Hat Middleware LLC, and individual contributors
* as indicated by the @author tags. See the copyright.txt file in the
* distribution for a full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.jboss.jca.embedded.unit;
import org.jboss.jca.embedded.Embedded;
import org.jboss.jca.embedded.EmbeddedFactory;
import org.jboss.jca.embedded.rars.simple.TestConnection;
import org.jboss.jca.embedded.rars.simple.TestConnectionFactory;
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.*;
/**
* Test cases for deploying resource adapter archives (.RAR)
* using ShrinkWrap
*
* @author <a href="mailto:jesper.pedersen@jboss.org">Jesper Pedersen</a>
* @version $Revision: $
*/
public class ShrinkWrapTestCase
{
// --------------------------------------------------------------------------------||
// Class Members ------------------------------------------------------------------||
// --------------------------------------------------------------------------------||
private static Logger log = Logger.getLogger(ShrinkWrapTestCase.class);
private static final String JNDI_PREFIX = "java:/eis/";
/*
* Embedded
*/
private static Embedded embedded;
// --------------------------------------------------------------------------------||
// Tests --------------------------------------------------------------------------||
// --------------------------------------------------------------------------------||
/**
* Null ShrinkWrap ResourceAdapterArchive test case
* @exception Throwable Thrown if case of an error
*/
@Test
public void testNull() throws Throwable
{
ResourceAdapterArchive raa = null;
try
{
embedded.deploy(raa);
fail("Null deployment successful");
}
catch (Exception t)
{
// Ok
}
finally
{
try
{
embedded.undeploy(raa);
fail("Null undeployment successful");
}
catch (Exception t)
{
// Ok
}
}
}
/**
* Basic ShrinkWrap ResourceAdapterArchive test case
* @exception Throwable Thrown if case of an error
*/
@Test
public void testBasic() throws Throwable
{
Context context = null;
String name = UUID.randomUUID().toString();
ResourceAdapterArchive raa =
ShrinkWrap.create(ResourceAdapterArchive.class, name + ".rar");
JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");
ja.addPackage(TestConnection.class.getPackage());
raa.addAsLibrary(ja);
raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");
try
{
embedded.deploy(raa);
context = new InitialContext();
TestConnectionFactory tcf = (TestConnectionFactory)context.lookup(JNDI_PREFIX + name);
assertNotNull(tcf);
TestConnection tc = tcf.getConnection();
tc.callMe();
tc.close();
}
catch (Throwable t)
{
log.error(t.getMessage(), t);
fail(t.getMessage());
}
finally
{
if (context != null)
{
try
{
context.close();
}
catch (NamingException ne)
{
// Ignore
}
}
embedded.undeploy(raa);
}
}
// --------------------------------------------------------------------------------||
// Lifecycle Methods --------------------------------------------------------------||
// --------------------------------------------------------------------------------||
/**
* Lifecycle start, before the suite is executed
* @throws Throwable throwable exception
*/
@BeforeClass
public static void beforeClass() throws Throwable
{
// Create and set an embedded JCA instance
embedded = EmbeddedFactory.create();
// Startup
embedded.startup();
}
/**
* Lifecycle stop, after the suite is executed
* @throws Throwable throwable exception
*/
@AfterClass
public static void afterClass() throws Throwable
{
// Shutdown embedded
embedded.shutdown();
// Set embedded to null
embedded = null;
}
}
ResourceAdapterArchive must end with the
.rar extension.See the ShrinkWrap web site for a full description of the project and additional documentation.
The code sample below shows an advanced usage of deploying a dynamic ShrinkWrap resource adapter archive into the IronJacamar Embedded environment using Arquillian.
This setup allows the developer to skip the entire IronJacamar Embedded container setup and handling of its lifecycle methods.
/*
* JBoss, Home of Professional Open Source.
* Copyright 2012, Red Hat Middleware LLC, and individual contributors
* as indicated by the @author tags. See the copyright.txt file in the
* distribution for a full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.jboss.jca.embedded.unit;
import org.jboss.jca.embedded.rars.simple.TestConnection;
import org.jboss.jca.embedded.rars.simple.TestConnectionFactory;
import java.util.UUID;
import javax.annotation.Resource;
import org.jboss.arquillian.container.test.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.assertNotNull;
/**
* 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 String deploymentName = "ArquillianTest";
/**
* Define the deployment
* @return The deployment archive
*/
@Deployment
public static ResourceAdapterArchive createDeployment()
{
ResourceAdapterArchive raa =
ShrinkWrap.create(ResourceAdapterArchive.class, deploymentName + ".rar");
JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");
ja.addPackage(TestConnection.class.getPackage());
raa.addAsLibrary(ja);
raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");
return raa;
}
//-------------------------------------------------------------------------------------||
// Tests ------------------------------------------------------------------------------||
//-------------------------------------------------------------------------------------||
@Resource(mappedName = "java:/eis/ArquillianTest")
private TestConnectionFactory connectionFactory;
/**
* Basic
* @exception Throwable Thrown if case of an error
*/
@Test
public void testBasic() throws Throwable
{
assertNotNull(connectionFactory);
TestConnection c = connectionFactory.getConnection();
assertNotNull(c);
c.callMe();
c.close();
}
}
ResourceAdapterArchive must end with the
.rar extension.See the Arquillian web site for a full description of the project and additional documentation.