4.3.9.RELEASE Spring Framework
734
32. JCA CCI
32.1 Introduction
Java EE provides a specification to standardize access to enterprise information systems EIS: the JCA Java EE Connector Architecture. This specification is divided into several different parts:
• SPI Service provider interfaces that the connector provider must implement. These interfaces constitute a resource adapter which can be deployed on a Java EE application server. In such a
scenario, the server manages connection pooling, transaction and security managed mode. The application server is also responsible for managing the configuration, which is held outside the client
application. A connector can be used without an application server as well; in this case, the application must configure it directly non-managed mode.
• CCI Common Client Interface that an application can use to interact with the connector and thus communicate with an EIS. An API for local transaction demarcation is provided as well.
The aim of the Spring CCI support is to provide classes to access a CCI connector in typical Spring style, leveraging the Spring Framework’s general resource and transaction management facilities.
Note
The client side of connectors doesn’t alway use CCI. Some connectors expose their own APIs, only providing JCA resource adapter to use the system contracts of a Java EE container
connection pooling, global transactions, security. Spring does not offer special support for such connector-specific APIs.
32.2 Configuring CCI
Connector configuration
The base resource to use JCA CCI is the ConnectionFactory
interface. The connector used must provide an implementation of this interface.
To use your connector, you can deploy it on your application server and fetch the ConnectionFactory
from the server’s JNDI environment managed mode. The connector must be packaged as a RAR file resource adapter archive and contain a
ra.xml file to describe its deployment characteristics. The
actual name of the resource is specified when you deploy it. To access it within Spring, simply use Spring’s
JndiObjectFactoryBean jee:jndi-lookup
fetch the factory by its JNDI name. Another way to use a connector is to embed it in your application non-managed mode, not using an
application server to deploy and configure it. Spring offers the possibility to configure a connector as a bean, through a provided
FactoryBean LocalConnectionFactoryBean
. In this manner, you only need the connector library in the classpath no RAR file and no
ra.xml descriptor needed. The
library must be extracted from the connector’s RAR file, if necessary. Once you have got access to your
ConnectionFactory instance, you can inject it into your
components. These components can either be coded against the plain CCI API or leverage Spring’s support classes for CCI access e.g.
CciTemplate .
4.3.9.RELEASE Spring Framework
735
Note
When you use a connector in non-managed mode, you can’t use global transactions because the resource is never enlisted delisted in the current global transaction of the current thread. The
resource is simply not aware of any global Java EE transactions that might be running.
ConnectionFactory configuration in Spring
In order to make connections to the EIS, you need to obtain a ConnectionFactory
from the application server if you are in a managed mode, or directly from Spring if you are in a non-managed
mode. In a managed mode, you access a
ConnectionFactory from JNDI; its properties will be configured
in the application server.
jee:jndi-lookup id
= eciConnectionFactory
jndi-name =
eiscicseci
In non-managed mode, you must configure the ConnectionFactory
you want to use in the configuration of Spring as a JavaBean. The
LocalConnectionFactoryBean class offers this setup
style, passing in the ManagedConnectionFactory
implementation of your connector, exposing the application-level CCI
ConnectionFactory .
bean id
= eciManagedConnectionFactory
class =
com.ibm.connector2.cics.ECIManagedConnectionFactory property
name =
serverName value
= TXSERIES
property name
= connectionURL
value =
tcp:localhost property
name =
portNumber value
= 2006
bean bean
id =
eciConnectionFactory class
= org.springframework.jca.support.LocalConnectionFactoryBean
property name
= managedConnectionFactory
ref =
eciManagedConnectionFactory bean
Note
You can’t directly instantiate a specific ConnectionFactory
. You need to go through the corresponding implementation of the
ManagedConnectionFactory interface for your
connector. This interface is part of the JCA SPI specification.
Configuring CCI connections
JCA CCI allow the developer to configure the connections to the EIS using the ConnectionSpec
implementation of your connector. In order to configure its properties, you need to wrap the target connection factory with a dedicated adapter,
ConnectionSpecConnectionFactoryAdapter . So,
the dedicated ConnectionSpec
can be configured with the property connectionSpec
as an inner bean.
This property is not mandatory because the CCI ConnectionFactory
interface defines two different methods to obtain a CCI connection. Some of the
ConnectionSpec properties can
often be configured in the application server in managed mode or on the corresponding local ManagedConnectionFactory
implementation.
public interface
ConnectionFactory implements
Serializable, Referenceable { ...
Connection getConnection throws
ResourceException; Connection getConnectionConnectionSpec connectionSpec
throws ResourceException;
... }
4.3.9.RELEASE Spring Framework
736
Spring provides a ConnectionSpecConnectionFactoryAdapter
that allows for specifying a
ConnectionSpec instance to use for all operations on a given factory. If the adapter’s
connectionSpec property is specified, the adapter uses the
getConnection variant with the
ConnectionSpec argument, otherwise the variant without argument.
bean id
= managedConnectionFactory
class =
com.sun.connector.cciblackbox.CciLocalTxManagedConnectionFactory property
name =
connectionURL value
= jdbc:hsqldb:hsql:localhost:9001
property name
= driverName
value =
org.hsqldb.jdbcDriver bean
bean id
= targetConnectionFactory
class =
org.springframework.jca.support.LocalConnectionFactoryBean property
name =
managedConnectionFactory ref
= managedConnectionFactory
bean bean
id =
connectionFactory class
= org.springframework.jca.cci.connection.ConnectionSpecConnectionFactoryAdapter
property name
= targetConnectionFactory
ref =
targetConnectionFactory property
name =
connectionSpec bean
class =
com.sun.connector.cciblackbox.CciConnectionSpec property
name =
user value
= sa
property name
= password
value =
bean property
bean
Using a single CCI connection
If you want to use a single CCI connection, Spring provides a further ConnectionFactory
adapter to manage this. The
SingleConnectionFactory adapter class will open a single connection lazily and
close it when this bean is destroyed at application shutdown. This class will expose special Connection
proxies that behave accordingly, all sharing the same underlying physical connection.
bean id
= eciManagedConnectionFactory
class =
com.ibm.connector2.cics.ECIManagedConnectionFactory property
name =
serverName value
= TEST
property name
= connectionURL
value =
tcp:localhost property
name =
portNumber value
= 2006
bean bean
id =
targetEciConnectionFactory class
= org.springframework.jca.support.LocalConnectionFactoryBean
property name
= managedConnectionFactory
ref =
eciManagedConnectionFactory bean
bean id
= eciConnectionFactory
class =
org.springframework.jca.cci.connection.SingleConnectionFactory property
name =
targetConnectionFactory ref
= targetEciConnectionFactory
bean
Note
This ConnectionFactory
adapter cannot
directly be
configured with
a ConnectionSpec
. Use an intermediary ConnectionSpecConnectionFactoryAdapter
that the SingleConnectionFactory
talks to if you require a single connection for a specific ConnectionSpec
.
4.3.9.RELEASE Spring Framework
737
32.3 Using Spring’s CCI access support