A Look Inside the JBoss JCA Project; New Features in JCA 1.6

The Java Enterprise Edition 6 standard includes an updated version of the Java EE Connector Architecture specification which improves the standard in key areas.

The Java EE Connector Architecture (JCA) specification defines a standard architecture for connecting the Java EE platform to heterogeneous Enterprise Information Systems (EIS). Examples of EISs include Enterprise Resource Planning (ERP), mainframe transaction processing (TP), database and messaging systems.

The Java EE Connector Architecture 1.6 specification were developed under the Java Community Process (JCP) umbrella as JSR-322 and included in the full profile of the Java EE 6 specification.

In this article we will take a look at the new Java EE Connector Architecture specification and look at how you can get started to develop your resource adapters using the JBoss JCA project.

What's new in JCA 1.6

The Java EE Connector Architecture 1.6 specification is a backwards compatible update to the JCA specification which adds new key areas to the specification.

The specification was updated in the following areas:

1. Ease of Development
2. Generic WorkContext
3. Security Inflow
4. Other enhancements

In the following sections we will take a brief look at what these new areas has to offer.


Ease of Development

One of the major focuses in the Java Enterprise Edition 5 specification was the use of annotations to ease development of various technologies.

Applying the same ease of use principles to the Java EE Connector Architecture specification will allow for a much easier way to develop resource adapter, since you doesn't have to specify a META-INF/ra.xml deployment descriptor.

Developers can now make use of the following annotations:

• @Connector
•  @AuthenticationMechanism
•  @SecurityPermission
•  @ConfigProperty
•  @ConnectionDefinitions / @ConnectionDefinition
•  @Activation
•  @AdministeredObject

...to help minimize the metadata work load.

An example of a resource adapter class could be:

import javax.resource.spi.Connector;
import javax.resource.spi.ConfigProperty;
import javax.resource.spi.ResourceAdapter;

/**
 * My resource adapter
 */
@Connector
public class MyResourceAdapter implements ResourceAdapter
{
   @ConfigProperty(defaultValue="5")
   private Integer myIntegerProperty;

   ...
}

The specification allows the developer to use a sparse XML file if configuration parameters for the resource adapter should be left up to the person deploying the archive.

Generic WorkContext

The generic WorkContext functionality provides a way for the resource adapter to propogate contextual information from the EIS during message delivery or a Work submission.

This enables the JCA container to support new message delivery inflow and delivery schemes.

The contextual information is passed along by using the WorkContextProvider interface that specifies the context supported. The standard supports the following three contexts:

• TransactionContext
• SecurityContext
• HintsContext

public interface WorkContextProvider extends Serializable
{
   /**
    * Gets an instance of <code>WorkContexts</code> that needs to be used
    * by the <code>WorkManager</code> to set up the execution context while
    * executing a <code>Work</code> instance.
    *
    * @return a <code>List</code> of <code>WorkContext</code> instances.
    */
   List<WorkContext> getWorkContexts();
}

The TransactionContext which deals the transactional context of the operation, the SecurityContext which we will take a look at in the next section and the HintsContext that allow propagation of hints about the execution, QoS or other properties about the work that needs to be performed.

This will for example allow a developer to specify that the Work instance submitted is a long running task, and thereby allow the JCA container to execute that instance in a thread pool handling such tasks.


Security Inflow

The SecurityContext functionality was added to provide end-to-end application level security when executing a Work instance or delivering a message to an endpoint.

This allows that the Work can be executed in the security context in the established identity and for the propagation of a Principal from the EIS to the MessageEndpoint.

The functionality leverages the work done in the Java Authentication Service Provider Interface for Containers (JSR-196) which uses callbacks to establish the caller identity.

package javax.resource.spi.work;

import javax.security.auth.Subject;
import javax.security.auth.callback.CallbackHandler;

public abstract class SecurityContext implements WorkContext
{
   ...

   public abstract void setupSecurityContext(CallbackHandler handler,
                                             Subject executionSubject,
                                             Subject serviceSubject);

This is really a key new feature of the JCA specification as it will allow for a much better integration of the security information between the Java EE platform and the EIS.


Other Enhancements

There were a couple of other enhancements in the specification.

• It is now possible to specify the transaction support level at run-time
• There is a definition of a distributed work manager
• For message inflow createMessageEndpoint() now supports a timeout value
• The notion of retryable exceptions were introduced
• Bean validation (JSR-303) was integrated to allow validation of the properties
• Class loader sematics was clarified

And finally a standalone container environment was defined to specify a JCA environment running outside an application server - more on that later.

The JBoss JCA container

The JBoss JCA project aims to implement the Java EE Connector Architecture 1.6 specification using a light-weight Plain Old Java Object (POJO) approach, such that the container can run on any Java kernel.

The container is made up of POJOs that are wired together using injection and thereby makes it easy to configure the container which is done through XML files.

The JBoss JCA project supports two different POJO kernels: the JBoss Microcontainer and the project's own kernel called Fungal.

This makes it possible to use the container in different flavors.

Three flavors

The project focuses on three different flavors of providing the JCA functionality:

1. Inside the JBoss Application Server
2. Complete standalone container
3. Embedded solution

The following sections will describe the goals of these flavors.

Inside the JBoss Application Server

The main goal of the project is to be included inside the JBoss Application Server as its JCA container implementation and thereby enable JCA 1.6 deployments, which are supported in the Java Enterprise Edition 6 full profile.

This integration will of course use the JBoss Microcontainer profile of the project as the JBoss Application Server uses this kernel for its foundation.

Standalone profile

The standalone profile implements the "Standalone Container Environment" part of the specification as defined in Chapter 3 Section 5.

This environment specifies a JCA platform for outbound - and possible inbound - communication and which aspects of the specification that are mandatory.

In short you will have access to at least an outbound JCA container and all the services that JCA makes use of, including transactions, security and bean validation.

It is up to each vendor to fill in the "blanks" - such as the application component model, kernel environment and any additional services.

The JBoss JCA project uses POJOs as the application component model meaning that you will write your services as standard POJOs that uses the lifecycle provided by the kernel environment. The project have included a web server for basic web based management capabilities.

The standalone environment provides an excellent base-line for the JBoss Application Server integration
as it can be tested outside of the application server environment before being included.

Embedded profile

The project also exists in an embedded profile which allows developers to include the container inside
their application.

This profile is based on the standalone profile, and therefore share the same functionality.

In order to make testing resource adapters very easy the embedded container integrates with the
ShrinkWrap project, hosted on JBoss.org.

This project allows to easy setup a JUnit test case and programmatically assemble the
resource adapter archive that you wish to test, like

package org.jboss.jca.embedded.unit;

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.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 org.jboss.logging.Logger;
import org.jboss.shrinkwrap.api.Archives;
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);

   /*
    * Embedded
    */
   private static EmbeddedJCA embedded;

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

   /**
    * Basic ShrinkWrap ResourceAdapterArchive test case
    * @exception Throwable Thrown if case of an error
    */
   @Test
   public void testBasic() throws Throwable
   {
      ResourceAdapterArchive raa =
         Archives.create(UUID.randomUUID().toString() + ".rar", ResourceAdapterArchive.class);

      JavaArchive ja = Archives.create(UUID.randomUUID().toString() + ".jar", JavaArchive.class);
      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");

      try
      {
         embedded.deploy(raa);

         // Lookup ConnectionFactory and start making asserts
      }
      catch (Throwable t)
      {
         log.error(t.getMessage(), t);
         fail(t.getMessage());
      }
      finally
      {
         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 = new EmbeddedJCA();

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

...which deploys a simple resource adapter archive.

Testing resource adapters have never been this easy.

In a future release the embedded container will also integrate with the Arquillian project in order to make testing even easier.

Tools for usability

The project features a resource adapter validator component which will check the resource adapter archive
against implementation rules defined in the specification. The validator will output which rules
have been triggered during startup of the container and - if configured - fail the deployment of the
resource adapter.

An example of the output 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 would fail the deployment, but give the developer insight to what needs to be fixed and where to find the requirements in the JCA specification.

The validator can also be used from the command line or through an Apache Ant task.

The project also features a resource adapter code generator that provides the developer with a code skeleton based on the input given from the command line or through a configuration file.

The generated code will also provide hints on where to look in the specification for implementation requirements.

The generator will of course support the various JCA specifications as well as the different types of resource adapters.

The project will also include some sample resource adapter implementations that will help developers get started as part of the documentation in a future release.


Getting involved

The JBoss JCA project is always looking for new talent to help out with the project. Contributions can take any form, from developing new functionality, reporting bugs to helping out with improving the documentation.

What have we covered ?

In this article we took a look at the Java EE Connector Architecture 1.6 specification included in the full profile of the Java Enterprise Edition 6 standard.

We saw how new areas will help developers with ease of use and provide them with powerful new functionality to control work execution and take advantage of security inflow using callback handlers.

We also took a look at the JBoss JCA project which will provide an implementation of the specification and offer key value-adds that will help resource adapter developers in their daily work.


About the Author

Jesper Pedersen  works as a Core Developer at JBoss, by Red Hat where he is leading the JBoss JCA project and other projects. He served on the expert group for the Java EE Connector Architecture 1.6 specification (JSR-322).