Introduction Configuring CCI JCA CCI

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