Enterprise Integration Zone is brought to you in partnership with:

Jesper Pedersen leads the Java Connector Architecture (JCA) project within JBoss, a division of Red Hat. He also leads the projects JBoss Tattletale which focus on software quality, Papaki - an annotation scanner and JBoss Profiler 2 - an open source profiler suite. He also acts as the chairman for the Boston JBoss User Group. His blog is available at http://in.relation.to/Bloggers/Jesper Jesper has posted 2 posts at DZone. View Full User Profile

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

04.28.2010
| 24128 views |
  • submit to reddit
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.

So feel free to join our discussions in the forum (user) (developer) or drop by the jboss-dev channel  on FreeNode.

 

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).

Published at DZone with permission of its author, Jesper Pedersen.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Martijn Verburg replied on Thu, 2010/04/29 - 5:05am

Very interesting read and looking forward to being able to try the stand alone container! Developing JCA Connectors is still a bit of a dark art, but I do like some of the new features, especially the security inflow, retry of exceptions and bean validation. Cheers, Martijn - Ikasan EIP

Jesper Pedersen replied on Thu, 2010/04/29 - 2:21pm in response to: Martijn Verburg

Feel free to download our latest alpha release and send us your feedback.

Len DiMaggio replied on Thu, 2010/04/29 - 2:34pm

Nice article! - thanks for the link to the ShrinkWrap project - I've been looking for a test tool like this for a while...

 

 

Andrew Rubinger replied on Thu, 2010/04/29 - 3:28pm

Yep.  Len, ShrinkWrap is going to sit at the center of all JBoss testing strategies in the future.  For instance, check out how, when coupled with the Arquillian[1] project, we render real EJB integration tests as simple as testing POJOs:

http://anonsvn.jboss.org/repos/common/arquillian/trunk/containers/openejb/src/test/java/org/jboss/arquillian/openejb/OpenEJBIntegrationTestCase.java

 

S,
ALR

[1] http://jboss.org/arquillian 

Andrew Rubinger replied on Thu, 2010/04/29 - 3:27pm

[1] http://jboss.org/arquillian

Henk De Boer replied on Thu, 2010/04/29 - 6:08pm

Nice article and a concrats on what seems to be a great job.

I do wish there was some more documentation available for JCA. There's barely any book on the subject, and very few books about 'Java EE' devote more than a few lines to JCA. I know that JCA is mainly an API targeted at vendors, but even they have programmers who simply need to learn ;)

It also seems that there are some interesting APIs for 'regular' application developers in JCA. I'm not sure any other part of Java EE addresses distributed work. I'm vaguely imagining some JCA RA accepting jobs from an EJB and distributing these to my cluster of Java EE application servers. Only... I have no idea whether that's within the scope of the API and because of a lack of documentation I also can't really find out easily.

Other examples where JCA might be interesting to the regular app developer is stuff like the Quartz RA or an FTP RA

Jesper Pedersen replied on Fri, 2010/04/30 - 2:01pm in response to: Henk De Boer

Henk, I invite you you to stop by our user forum and let us know what you would like to see. The barrier for getting started with JCA development can be high, but one of the goals for the project is to lower that barrier with documentation, samples and of course the code generator.

 User - and even contributor  ;) - feedback is most welcomed !

Vijay Krishnan replied on Wed, 2010/05/05 - 10:17am

Where can I find the alpha download link?

Jesper Pedersen replied on Sun, 2010/05/09 - 9:34am in response to: Vijay Krishnan

You are looking for "Unstable" @ http://jboss.org/jca/downloads.html

Mike Francois replied on Tue, 2010/05/18 - 12:02pm

Hi Jesper,

Thanks for this article.

I translated your article and could you authorise me to publish it ?

http://x-plode.developpez.com/tutoriels/netbeans/nouvelles-fonctionnalites-dans-jca-1-6/

Sincerely,

Mike

Jesper Pedersen replied on Tue, 2010/06/01 - 1:20pm

Go ahead, Mike :)

Carla Brian replied on Wed, 2012/05/30 - 11:17am

This is an efficient application. It reduces or completely eliminates the need to deal with a deployment descriptor in many cases. - Kummetz Corp LLC

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.