There is a common prejudice that JCA connectors have to be too complicated for day to day use. "Custom & lightweight" solutions are built instead, which are usually orders of magnitudes more complex, than a pragmatic JCA implementation. So, how to built one:
JCA connectors are deployed as .rar archives with internal structure similar to ejb-jar archives. You can reuse your existing packaging and just change the ending from .jar to .rar
Start with the ra.xml deployment descriptor. You "only" have to implement the elements listed in this deployment descriptor:
GenericManagedConnectionFactory and GenericManagedConnection are mostly reusable. These classes care about connection management. You will be able to manage a connector through e.g. the Glassfish admin console. The code is surprisingly simple - its mainly book keeping and logging. See http://kenai.com/projects/javaee-patterns/, project GenericJCA.
The "core" business logic resides in the FileConnection:
public class FileConnection implements Connection, LocalTransaction{
The nice thing are transaction callbacks. You will be notified about the transaction progress by the container. At commit time, you just write the buffer to the file - in case of a rollback you have to clear the buffer. This sample is not fully transactional - because in general you will have to deal with corrupted files etc. - but it should be clear how it works.
After installation, you will be able to inject the interface (and so the FileConnection) to your business logic.
@Stateless
public class JCAClientBean implements JCAClientRemote {
@Resource(mappedName="jca/FileFactory")
private DataSource dataSource;
...and the transactions will be propagated transparently for you.
JCA connectors are not as lean as simple as EJB 3.1 or CDI, but orders of magnitude more robust and more maintainable, than solutions and workarounds which are usually built instead.
The example presented here is based on the ancient Java EE 5 technology. JCA 1.6 connectors are lot simpler and more elegant - stay tuned.
Comments:
Hi Adam,
Thanks a lot for the JCA Adpater!
Kind Regards,
Simon
Posted by
Simon Martinelli
on September 09, 2010 at 03:53 PM CEST
#
@Simon,
you are welcome! This implementation was tested, but not stress tested - so don't use it in production.
Contributions are welcome!,
thanks!,
adam
Posted by
adam-bien.com
on September 09, 2010 at 04:13 PM CEST
#
Hi Adam,
Thanks for sharing this! I always feel that those of us who write JCA connectors are in a small club :).
We're currently exploring writing fully 2-phase transactional FTP/SFTP connectors for Ikasan (open source middleware), it's an interesting problem to crack!
If anyone out there has given this a go we're happy to share ideas!
We're definitely looking forward to JCA 1.6, anything that simplifies this space is welcome.
Here's hoping that JCA 1.7 will utilise DI, it'll make testing for us much simpler :)
Cheers,
Martijn
Posted by
Martijn Verburg
on September 09, 2010 at 04:19 PM CEST
#
Great sample! But it's quite funny to hear about JEE 5 being ancient ;-) There're plenty of companies that haven't switched from 1.4 yet.
Posted by
Jakub Grabowski
on September 09, 2010 at 10:32 PM CEST
#
Adam, thank you for bringing back JCA to the public interest. I hardly thought that I am the only one writing adapters. ;-)
Reading the title I was curious to see how you solved transactions with files, as that is what the GPL'ed FileRA (available at http://sourceforge.net/projects/filera/ and used in production since 2005) is missing. Unfortunately I can't apply your solution to FileRA, as FileRA would need to transact much more complex scenarios like rolling back deletes and moves, isolate transaction on structure operations, etc., which can only be handled by some kind of rollback logs IMHO. If anybody is interested in contribution this, please write to markus@headcrashing.eu. :-)
A little more promotion: See also the GPL'ed SMTP-Inbound adapter available since 2008 at http://sourceforge.net/projects/mailra/. It can trigger MDBs by processing incoming STMP, so it preserves processing time by not polling using POP3 and such provides results in real time due to the missing delay. :-)
Posted by
Markus KARG
on September 11, 2010 at 01:45 PM CEST
#
JCA, the hidden gem in the Java EE API ;)
Anyway, *REALLY* looking forward to a JCA 1.6 example.
Posted by
Robert Tuinman
on September 11, 2010 at 06:49 PM CEST
#
Hi Adam,
tried Your example from Kenai:
packagenames in ra.xml are partially wrong (you missed some "spi"s...).
Works for me on GF2.
On GF3 one has to package Connector and Client into one EAR in order to get it running out of the box.
Deploying Connector and Client separately ends up in
Caused by: javax.naming.NamingException: Lookup failed for '__SYSTEM/pools/abien' in SerialContext [Root exception is javax.naming.NameNotFoundException: abien not found]
("abien" was the name of the pool :)
I was not able to figure out what's wrong, yet...
I also replaced the ra-descriptor using annotations, is it JCA 1.6 now? ;-)
Thanks for the example!
Björn
Posted by
Björn Behrens
on September 14, 2010 at 04:23 PM CEST
#
Hi Adam
I have been trying to write a connector in JCA for my EIS by providing user name, password and TCP/IP under JBoss server. Can you please suggest a solution for that.
Posted by
jashmeet
on October 07, 2010 at 09:59 AM CEST
#
Hello,
first of all thanks for this article.
My question is the following: I want to parse XML-Files in my EJB.
If I open a connection to the file with your JCA adapter and make the internal FileInputStream available to my EJB for read-only access(parsing), does this meet the EJB restrictions concerning file access?
If this breaks the restrictions, what would be a correct way to do this?
Thanks and greetings,
Johann
Posted by
Johann Mayer
on October 27, 2010 at 03:12 PM CEST
#
Hi Adam,
is there a working example of an JCA 1.6 implementation (with the omit of the ra.xml) planned for your patterns-project@kenai?
Would be nice, due to SecurityContext, WorkManager and these interesting new features with JavaEE6...
Regards,
Robert
Posted by
Robert
on November 12, 2010 at 11:21 PM CET
#
Hi,
...just FYI
A JCA 1.5 connector to do similar stuff (transactional behavior over file-systems, with XA) is available as XADisk (https://xadisk.dev.java.net/); an open-source project I have been involved in. I thought, it may be interesting to people coming across this relevant article.
Thanks,
Nitin
Posted by
Nitin
on January 07, 2011 at 09:57 PM CET
#
Really interesting! Thanks for sharing it.
But how can it be modified to access a file in a given directory, passing the file name at run-time? Like a simple file uploader? Or better as a document manager: the system builds a document for the user, and the document must be archived in a fixed directory with a name composed from various parameters (as request type, user-id, etc.).
Posted by
Daniele
on January 20, 2011 at 02:02 PM CET
#
Hello adam ,
Thanks for your useful articles.
I have a misunderstanding regarding the connection handle sharing in JCA.
I want to know if the connection sharing only happens during a phase of transaction ( multiple components call ) or the connection sharing is possible amongst multiple clients accessing a component that has the same EIS destination.
I created my own resource adapter on Glassfish application server 3.1. The problem is the resource adapter doesn't perform any connection sharing (no associateConnection method call).
Thanks,
Posted by
Sam
on September 24, 2012 at 12:15 PM CEST
#
Hi Sam,
please also checkout: http://connectorz.adam-bien.com (see also http://realworldpatterns.com). It is a newer JCA 1.6 implementation.
Whether a connection is shared, or not, depends on the ManagedConnectionFactory#matchManagedConnections method implementation.
thanks!,
adam
Posted by
Adam Bien
on September 24, 2012 at 09:32 PM CEST
#
Post a Comment:
Number of posts: 2352
Number of comments: 6162
Yesterday's hits: 14682
Today's hits: 12106
Post reads / hour: 689
Top posts:
Trending (last hour):
Hi Adam,
Thanks a lot for the JCA Adpater!
Kind Regards,
Simon
Posted by Simon Martinelli on September 09, 2010 at 03:53 PM CEST #
@Simon,
you are welcome! This implementation was tested, but not stress tested - so don't use it in production.
Contributions are welcome!,
thanks!,
adam
Posted by adam-bien.com on September 09, 2010 at 04:13 PM CEST #
Hi Adam,
Thanks for sharing this! I always feel that those of us who write JCA connectors are in a small club :).
We're currently exploring writing fully 2-phase transactional FTP/SFTP connectors for Ikasan (open source middleware), it's an interesting problem to crack!
If anyone out there has given this a go we're happy to share ideas!
We're definitely looking forward to JCA 1.6, anything that simplifies this space is welcome.
Here's hoping that JCA 1.7 will utilise DI, it'll make testing for us much simpler :)
Cheers,
Martijn
Posted by Martijn Verburg on September 09, 2010 at 04:19 PM CEST #
Great sample! But it's quite funny to hear about JEE 5 being ancient ;-) There're plenty of companies that haven't switched from 1.4 yet.
Posted by Jakub Grabowski on September 09, 2010 at 10:32 PM CEST #
Adam, thank you for bringing back JCA to the public interest. I hardly thought that I am the only one writing adapters. ;-)
Reading the title I was curious to see how you solved transactions with files, as that is what the GPL'ed FileRA (available at http://sourceforge.net/projects/filera/ and used in production since 2005) is missing. Unfortunately I can't apply your solution to FileRA, as FileRA would need to transact much more complex scenarios like rolling back deletes and moves, isolate transaction on structure operations, etc., which can only be handled by some kind of rollback logs IMHO. If anybody is interested in contribution this, please write to markus@headcrashing.eu. :-)
A little more promotion: See also the GPL'ed SMTP-Inbound adapter available since 2008 at http://sourceforge.net/projects/mailra/. It can trigger MDBs by processing incoming STMP, so it preserves processing time by not polling using POP3 and such provides results in real time due to the missing delay. :-)
Posted by Markus KARG on September 11, 2010 at 01:45 PM CEST #
JCA, the hidden gem in the Java EE API ;)
Anyway, *REALLY* looking forward to a JCA 1.6 example.
Posted by Robert Tuinman on September 11, 2010 at 06:49 PM CEST #
Hi Adam,
tried Your example from Kenai:
packagenames in ra.xml are partially wrong (you missed some "spi"s...).
Works for me on GF2.
On GF3 one has to package Connector and Client into one EAR in order to get it running out of the box.
Deploying Connector and Client separately ends up in
Caused by: javax.naming.NamingException: Lookup failed for '__SYSTEM/pools/abien' in SerialContext [Root exception is javax.naming.NameNotFoundException: abien not found]
("abien" was the name of the pool :)
I was not able to figure out what's wrong, yet...
I also replaced the ra-descriptor using annotations, is it JCA 1.6 now? ;-)
Thanks for the example!
Björn
Posted by Björn Behrens on September 14, 2010 at 04:23 PM CEST #
Hi Adam
I have been trying to write a connector in JCA for my EIS by providing user name, password and TCP/IP under JBoss server. Can you please suggest a solution for that.
Posted by jashmeet on October 07, 2010 at 09:59 AM CEST #
Hello,
first of all thanks for this article.
My question is the following: I want to parse XML-Files in my EJB.
If I open a connection to the file with your JCA adapter and make the internal FileInputStream available to my EJB for read-only access(parsing), does this meet the EJB restrictions concerning file access?
If this breaks the restrictions, what would be a correct way to do this?
Thanks and greetings,
Johann
Posted by Johann Mayer on October 27, 2010 at 03:12 PM CEST #
Hi Adam,
is there a working example of an JCA 1.6 implementation (with the omit of the ra.xml) planned for your patterns-project@kenai?
Would be nice, due to SecurityContext, WorkManager and these interesting new features with JavaEE6...
Regards,
Robert
Posted by Robert on November 12, 2010 at 11:21 PM CET #
Hi,
...just FYI
A JCA 1.5 connector to do similar stuff (transactional behavior over file-systems, with XA) is available as XADisk (https://xadisk.dev.java.net/); an open-source project I have been involved in. I thought, it may be interesting to people coming across this relevant article.
Thanks,
Nitin
Posted by Nitin on January 07, 2011 at 09:57 PM CET #
Really interesting! Thanks for sharing it.
But how can it be modified to access a file in a given directory, passing the file name at run-time? Like a simple file uploader? Or better as a document manager: the system builds a document for the user, and the document must be archived in a fixed directory with a name composed from various parameters (as request type, user-id, etc.).
Posted by Daniele on January 20, 2011 at 02:02 PM CET #
Hello adam ,
Thanks for your useful articles.
I have a misunderstanding regarding the connection handle sharing in JCA.
I want to know if the connection sharing only happens during a phase of transaction ( multiple components call ) or the connection sharing is possible amongst multiple clients accessing a component that has the same EIS destination.
I created my own resource adapter on Glassfish application server 3.1. The problem is the resource adapter doesn't perform any connection sharing (no associateConnection method call).
Thanks,
Posted by Sam on September 24, 2012 at 12:15 PM CEST #
Hi Sam,
please also checkout: http://connectorz.adam-bien.com (see also http://realworldpatterns.com). It is a newer JCA 1.6 implementation.
Whether a connection is shared, or not, depends on the ManagedConnectionFactory#matchManagedConnections method implementation.
thanks!,
adam
Posted by Adam Bien on September 24, 2012 at 09:32 PM CEST #