JBoss JCA 1.0 User's Guide

Jesper Pedersen acts as the lead for the JBoss JCA project. He can be reached at jesper (dot) pedersen (at) jboss (dot) org.

Jeff Zhang is a core developer on the JBoss JCA project. He can be reached at jizhang (at) redhat (dot) com.

Gurkan Erdogdu is a core developer on the JBoss JCA project. He can be reached at gurkanerdogdu (at) yahoo (dot) com.

Stefano Maestri is a core developer on the JBoss JCA project. He can be reached at stefano.maestri (at) javalinux (dot) it.

Dimitris Andreadis, Carlo de Wolf, Jason Green, Jonathan Halliday, Søren Hilmer, Vicky Kak, Aslak Knutsen, Sacha Labourey, Alexey Loubyansky, Patrick MacDonald, Andrig Miller, Andrew Lee Rubinger, Anil Saldhana and Scott Stark.

And a special thanks goes to Adrian Brock and Ales Justin for their continuous support of this project.

The Java Connector Architecture 1.6 specification adds the following major areas:

The download location is zone: http://www.jboss.org/jca/downloads/

Each release is labelled with a version number and an identifier.

jboss-jca-<major>.<minor>.<patch>[.<identifier>]
      

where

An example

jboss-jca-1.0.0.tar.gz
      

which is the first stable release of the project.

If you want to experiment with the latest developments you may checkout the latest code from SVN trunk. Be aware that the information provided in this manual might then not be accurate.

The anonymous SVN repository is located under:

svn co http://anonsvn.jboss.org/repos/jbossas/projects/jboss-jca/trunk/ jbossjca-trunk
      

You can find additional information about this in the developer guide.

Extract the distribution using

tar xzf jboss-jca-1.0.0.tar.gz
     

The distribution will be located in a directory named

jboss-jca-1.0.0
     

Extract the distribution using

unzip jboss-jca-1.0.0.tar.gz
     

or any program capable of handling Zip archives such as WinZip and WinRar.

The distribution will be located in a directory named

jboss-jca-1.0.0
     

The JBoss JCA container has the following directory structure:

The JBoss JCA container uses JBoss Logging framework as the implementation.

The configuration is done in the

config/logging.properties
      

file.

Consult the JBoss Logging documentation on how the service can be configured.

The JBoss JCA container uses the JBoss Transaction Manager as its transaction implementation.

The configuration is done in the

config/transaction.xml
      

file.

Consult the JBoss Transaction documentation on how the service can be configured.

The JBoss JCA project features a web server which is used to serve web archive deployments.

The configuration is done in the

system/web.xml
      

file.

The web server can be removed from the environment by removing the web.xml file in

system/
      

Furthermore all .WAR files in the same directory should be removed too.

Resource adapters (.rar) are deployed by copying the resource adapters into the deploy/ directory

cp example.rar jboss-jca-1.0.0/deploy
     

on a Un*x based system or

copy example.rar jboss-jca-1.0.0\deploy
     

on Windows.

The JBoss JCA container is started by entering the bin/ directory

cd jboss-jca-1.0.0/bin
     

and executing

./run.sh
     

on a Un*x based system or

run.bat
     

on Windows.

The command takes an optional -b argument to define the binding address of the naming server

./run.sh -b 192.168.0.199
     

Once the container has started you should see a log entry like

13:33:10,999 INFO  [Main] Server started in 941ms
     

in the console where the command was executed.

After the container has started you can browse to

http://localhost:8080
     

to view the project documentation and use the administration console.

The JBoss JCA container can be controlled by a command line interface.

java -jar fungal-cli.jar deploy <file>
        

java -jar fungal-cli.jar undeploy <file>
        

java -jar fungal-cli.jar shutdown
        

The JBoss JCA container features a validator which checks resource adapter archives against the Java Connector Architecture (JCA) specification.

The validator is doing a static analysis of the resource adapter classes and checks them against the rules defined in the validator.

The validator is used in the deployer chain of the JCA container, and is available as a standalone tool and an Apache Ant too.

The validator works by scanning the resource adapter in question and output a report which lists which rules have been violated.

An example could be

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl
      

which means that com.mycompany.myproject.ResourceAdapterImpl is missing an equals and hashCode implementation.

The validator can be run on the command line by

java -jar jboss-jca-validator.jar <file>
      

The reports will be generated into the current directory under the name of <file>.log.

The validator integrates with Apache Ant such that you can generate the reports directly from your build environment before deploying the resoruce adapter into the JBoss JCA container.

First you have to define the taskdef for the task

<taskdef name="validator"
         classname="org.jboss.jca.validator.ant.ValidatorTask"
         classpathref="jbossjca.lib.path.id"/>
      

See the Apache Ant documentation for additional instructions on installation.

<validator rarFile="${myArchive.rar}" outputDir="${report.dir}"/>
        

The JBoss JCA project includes a resource adapter code generator which can generate a complete code skeleton that will help developers get started with their development tasks.

The code generator will generate a resource adapter code skeleton based on the user input. The code generator supports

The code generator can be run on the command line by

./codegenerator.sh
      

from the doc/codegenerator directory.

The code generator supports the following arguments

The developer must then answer various questions regarding the properties of the resource adapter.

The generated code will consist of the classes making up the resource adapter and a test suite environment based on the embedded distribution.

The following targets are supported in the Apache Ant build environment

The JBoss JCA 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.

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.

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.

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();
   }
}
        

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;
   }
}

          

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
            }
         }
      }
   }
}

          

The website contains the latest information about the project and links to important information.

The website is located at http://www.jboss.org/jca/

The user forum is where we discuss matters about the usage of the JBoss JCA project.

Our forum is located at http://www.jboss.org/index.html?module=bb&op=viewforum&f=136

The developer forum is where we discuss the implementation of the JBoss JCA project. This means the internals of the project and not how the project is used.

User questions doesn't belong here - they should go in the user forum instead.

The forum is located at http://www.jboss.org/index.html?module=bb&op=viewforum&f=165

We are using JIRA to manage our issues in the project.

These are divided into the following categories

For all of these you should post your request to our user forum first.

The rest of the categories are for team use only.

Our issue tracking system located at https://jira.jboss.org/jira/browse/JBJCA

If you think you have found a bug you should verify this by posting to our forum first.

Our forum is located at http://www.jboss.org/index.html?module=bb&op=viewforum&f=136

You can also search our issue tracking system located at https://jira.jboss.org/jira/browse/JBJCA

So you have found an area where you are missing a feature and would like to submit a patch for it, great !

There are a couple of steps to get a feature included

First, you should create a new thread in our development forum where you describe the feature, its design and implementation.

Once there is an agreement on the feature and the design you should proceed with creating the patch.

To maximize your chances of getting the feature in the official build as soon as possible make sure that you run through the following steps:

ant clean test
ant clean checkstyle
ant clean findbugs
ant clean cobertura
      

All these should show that,

when done, create a JIRA task (Patch) in our JIRA environment. See the developer guide for additional details.

Happy Coding !

We can't cover every single issue in this guide, so feel free to drop by our forums to see if a solution has already been provided. Otherwise feel free to ask your question there.

Our forum is located at http://www.jboss.org/index.html?module=bb&op=viewforum&f=136