diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/CannotCreateRecordException.java b/spring-tx/src/main/java/org/springframework/jca/cci/CannotCreateRecordException.java index 066bb9ae9d0..5685b061c97 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/CannotCreateRecordException.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/CannotCreateRecordException.java @@ -26,7 +26,10 @@ import org.springframework.dao.DataAccessResourceFailureException; * * @author Juergen Hoeller * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class CannotCreateRecordException extends DataAccessResourceFailureException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/CannotGetCciConnectionException.java b/spring-tx/src/main/java/org/springframework/jca/cci/CannotGetCciConnectionException.java index 1d9c23de48d..dcd68cecc40 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/CannotGetCciConnectionException.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/CannotGetCciConnectionException.java @@ -26,7 +26,10 @@ import org.springframework.dao.DataAccessResourceFailureException; * @author Thierry Templier * @author Juergen Hoeller * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class CannotGetCciConnectionException extends DataAccessResourceFailureException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/CciOperationNotSupportedException.java b/spring-tx/src/main/java/org/springframework/jca/cci/CciOperationNotSupportedException.java index 41d1f4252fd..bc2d9df4be8 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/CciOperationNotSupportedException.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/CciOperationNotSupportedException.java @@ -25,7 +25,10 @@ import org.springframework.dao.InvalidDataAccessResourceUsageException; * * @author Juergen Hoeller * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class CciOperationNotSupportedException extends InvalidDataAccessResourceUsageException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/InvalidResultSetAccessException.java b/spring-tx/src/main/java/org/springframework/jca/cci/InvalidResultSetAccessException.java index 090fc528925..f7a1895cf9c 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/InvalidResultSetAccessException.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/InvalidResultSetAccessException.java @@ -30,7 +30,10 @@ import org.springframework.dao.InvalidDataAccessResourceUsageException; * @author Juergen Hoeller * @since 1.2 * @see javax.resource.cci.ResultSet + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class InvalidResultSetAccessException extends InvalidDataAccessResourceUsageException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/RecordTypeNotSupportedException.java b/spring-tx/src/main/java/org/springframework/jca/cci/RecordTypeNotSupportedException.java index bda7bf24a4a..b4e9bacc7a4 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/RecordTypeNotSupportedException.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/RecordTypeNotSupportedException.java @@ -26,7 +26,10 @@ import org.springframework.dao.InvalidDataAccessResourceUsageException; * * @author Juergen Hoeller * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class RecordTypeNotSupportedException extends InvalidDataAccessResourceUsageException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/CciLocalTransactionManager.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/CciLocalTransactionManager.java index 5d5ea978154..4b0ad9d51c0 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/CciLocalTransactionManager.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/CciLocalTransactionManager.java @@ -61,7 +61,10 @@ import org.springframework.util.Assert; * @see ConnectionFactoryUtils#releaseConnection * @see TransactionAwareConnectionFactoryProxy * @see org.springframework.jca.cci.core.CciTemplate + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class CciLocalTransactionManager extends AbstractPlatformTransactionManager implements ResourceTransactionManager, InitializingBean { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionFactoryUtils.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionFactoryUtils.java index 5a30ccfcb3e..2f690e35cb6 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionFactoryUtils.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionFactoryUtils.java @@ -24,7 +24,6 @@ import javax.resource.cci.ConnectionSpec; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.springframework.jca.cci.CannotGetCciConnectionException; import org.springframework.lang.Nullable; import org.springframework.transaction.support.ResourceHolderSynchronization; import org.springframework.transaction.support.TransactionSynchronizationManager; @@ -49,7 +48,10 @@ import org.springframework.util.Assert; * @see CciLocalTransactionManager * @see org.springframework.transaction.jta.JtaTransactionManager * @see org.springframework.transaction.support.TransactionSynchronizationManager + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public abstract class ConnectionFactoryUtils { private static final Log logger = LogFactory.getLog(ConnectionFactoryUtils.class); @@ -68,7 +70,9 @@ public abstract class ConnectionFactoryUtils { * if the attempt to get a Connection failed * @see #releaseConnection */ - public static Connection getConnection(ConnectionFactory cf) throws CannotGetCciConnectionException { + public static Connection getConnection(ConnectionFactory cf) + throws org.springframework.jca.cci.CannotGetCciConnectionException { + return getConnection(cf, null); } @@ -89,7 +93,7 @@ public abstract class ConnectionFactoryUtils { * @see #releaseConnection */ public static Connection getConnection(ConnectionFactory cf, @Nullable ConnectionSpec spec) - throws CannotGetCciConnectionException { + throws org.springframework.jca.cci.CannotGetCciConnectionException { try { if (spec != null) { Assert.notNull(cf, "No ConnectionFactory specified"); @@ -100,7 +104,7 @@ public abstract class ConnectionFactoryUtils { } } catch (ResourceException ex) { - throw new CannotGetCciConnectionException("Could not get CCI Connection", ex); + throw new org.springframework.jca.cci.CannotGetCciConnectionException("Could not get CCI Connection", ex); } } diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionHolder.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionHolder.java index d705d4831d9..35e5afcf4d0 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionHolder.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionHolder.java @@ -32,7 +32,10 @@ import org.springframework.transaction.support.ResourceHolderSupport; * @since 1.2 * @see CciLocalTransactionManager * @see ConnectionFactoryUtils + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public class ConnectionHolder extends ResourceHolderSupport { private final Connection connection; diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionSpecConnectionFactoryAdapter.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionSpecConnectionFactoryAdapter.java index a9cca7cb315..2f80f0cefe5 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionSpecConnectionFactoryAdapter.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/ConnectionSpecConnectionFactoryAdapter.java @@ -64,7 +64,10 @@ import org.springframework.util.Assert; * @author Juergen Hoeller * @since 1.2 * @see #getConnection + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class ConnectionSpecConnectionFactoryAdapter extends DelegatingConnectionFactory { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/DelegatingConnectionFactory.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/DelegatingConnectionFactory.java index 01edac23855..08c9ac20722 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/DelegatingConnectionFactory.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/DelegatingConnectionFactory.java @@ -40,7 +40,10 @@ import org.springframework.util.Assert; * @author Juergen Hoeller * @since 1.2 * @see #getConnection + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class DelegatingConnectionFactory implements ConnectionFactory, InitializingBean { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/NotSupportedRecordFactory.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/NotSupportedRecordFactory.java index 9a20266fdec..dc613f6d4c5 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/NotSupportedRecordFactory.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/NotSupportedRecordFactory.java @@ -38,7 +38,10 @@ import javax.resource.cci.RecordFactory; * @see org.springframework.jca.cci.core.CciTemplate#getRecordFactory(javax.resource.cci.ConnectionFactory) * @see javax.resource.cci.ConnectionFactory#getRecordFactory() * @see javax.resource.NotSupportedException + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public class NotSupportedRecordFactory implements RecordFactory { @Override diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/SingleConnectionFactory.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/SingleConnectionFactory.java index 94561b3b32a..312fed4d4fa 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/SingleConnectionFactory.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/SingleConnectionFactory.java @@ -51,7 +51,10 @@ import org.springframework.util.Assert; * @see #getConnection() * @see javax.resource.cci.Connection#close() * @see org.springframework.jca.cci.core.CciTemplate + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class SingleConnectionFactory extends DelegatingConnectionFactory implements DisposableBean { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/connection/TransactionAwareConnectionFactoryProxy.java b/spring-tx/src/main/java/org/springframework/jca/cci/connection/TransactionAwareConnectionFactoryProxy.java index 51f03f4a36d..e8fe835594b 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/connection/TransactionAwareConnectionFactoryProxy.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/connection/TransactionAwareConnectionFactoryProxy.java @@ -65,7 +65,10 @@ import org.springframework.lang.Nullable; * @see javax.resource.cci.Connection#close * @see ConnectionFactoryUtils#doGetConnection * @see ConnectionFactoryUtils#doReleaseConnection + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class TransactionAwareConnectionFactoryProxy extends DelegatingConnectionFactory { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/CciOperations.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/CciOperations.java index e12342695db..313d16f24a4 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/CciOperations.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/CciOperations.java @@ -33,7 +33,10 @@ import org.springframework.lang.Nullable; * @author Juergen Hoeller * @since 1.2 * @see CciTemplate + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public interface CciOperations { /** diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/CciTemplate.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/CciTemplate.java index d9d2e01b805..181321e888a 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/CciTemplate.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/CciTemplate.java @@ -36,12 +36,6 @@ import org.apache.commons.logging.LogFactory; import org.springframework.dao.DataAccessException; import org.springframework.dao.DataAccessResourceFailureException; -import org.springframework.jca.cci.CannotCreateRecordException; -import org.springframework.jca.cci.CciOperationNotSupportedException; -import org.springframework.jca.cci.InvalidResultSetAccessException; -import org.springframework.jca.cci.RecordTypeNotSupportedException; -import org.springframework.jca.cci.connection.ConnectionFactoryUtils; -import org.springframework.jca.cci.connection.NotSupportedRecordFactory; import org.springframework.lang.Nullable; import org.springframework.util.Assert; @@ -68,7 +62,10 @@ import org.springframework.util.Assert; * @since 1.2 * @see RecordCreator * @see RecordExtractor + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public class CciTemplate implements CciOperations { private final Log logger = LogFactory.getLog(getClass()); @@ -209,21 +206,25 @@ public class CciTemplate implements CciOperations { public T execute(ConnectionCallback action) throws DataAccessException { Assert.notNull(action, "Callback object must not be null"); ConnectionFactory connectionFactory = obtainConnectionFactory(); - Connection con = ConnectionFactoryUtils.getConnection(connectionFactory, getConnectionSpec()); + Connection con = org.springframework.jca.cci.connection.ConnectionFactoryUtils.getConnection( + connectionFactory, getConnectionSpec()); try { return action.doInConnection(con, connectionFactory); } catch (NotSupportedException ex) { - throw new CciOperationNotSupportedException("CCI operation not supported by connector", ex); + throw new org.springframework.jca.cci.CciOperationNotSupportedException( + "CCI operation not supported by connector", ex); } catch (ResourceException ex) { throw new DataAccessResourceFailureException("CCI operation failed", ex); } catch (SQLException ex) { - throw new InvalidResultSetAccessException("Parsing of CCI ResultSet failed", ex); + throw new org.springframework.jca.cci.InvalidResultSetAccessException( + "Parsing of CCI ResultSet failed", ex); } finally { - ConnectionFactoryUtils.releaseConnection(con, getConnectionFactory()); + org.springframework.jca.cci.connection.ConnectionFactoryUtils.releaseConnection( + con, getConnectionFactory()); } } @@ -329,10 +330,12 @@ public class CciTemplate implements CciOperations { return recordFactory.createIndexedRecord(name); } catch (NotSupportedException ex) { - throw new RecordTypeNotSupportedException("Creation of indexed Record not supported by connector", ex); + throw new org.springframework.jca.cci.RecordTypeNotSupportedException( + "Creation of indexed Record not supported by connector", ex); } catch (ResourceException ex) { - throw new CannotCreateRecordException("Creation of indexed Record failed", ex); + throw new org.springframework.jca.cci.CannotCreateRecordException( + "Creation of indexed Record failed", ex); } } @@ -350,10 +353,12 @@ public class CciTemplate implements CciOperations { return recordFactory.createMappedRecord(name); } catch (NotSupportedException ex) { - throw new RecordTypeNotSupportedException("Creation of mapped Record not supported by connector", ex); + throw new org.springframework.jca.cci.RecordTypeNotSupportedException( + "Creation of mapped Record not supported by connector", ex); } catch (ResourceException ex) { - throw new CannotCreateRecordException("Creation of mapped Record failed", ex); + throw new org.springframework.jca.cci.CannotCreateRecordException( + "Creation of mapped Record failed", ex); } } @@ -372,11 +377,12 @@ public class CciTemplate implements CciOperations { return recordCreator.createRecord(recordFactory); } catch (NotSupportedException ex) { - throw new RecordTypeNotSupportedException( + throw new org.springframework.jca.cci.RecordTypeNotSupportedException( "Creation of the desired Record type not supported by connector", ex); } catch (ResourceException ex) { - throw new CannotCreateRecordException("Creation of the desired Record failed", ex); + throw new org.springframework.jca.cci.CannotCreateRecordException( + "Creation of the desired Record failed", ex); } } @@ -396,7 +402,7 @@ public class CciTemplate implements CciOperations { return connectionFactory.getRecordFactory(); } catch (NotSupportedException ex) { - return new NotSupportedRecordFactory(); + return new org.springframework.jca.cci.connection.NotSupportedRecordFactory(); } } diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/ConnectionCallback.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/ConnectionCallback.java index 8893341e21a..a573f3583e6 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/ConnectionCallback.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/ConnectionCallback.java @@ -42,7 +42,10 @@ import org.springframework.lang.Nullable; * @see CciTemplate#execute(ConnectionCallback) * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, javax.resource.cci.Record) * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, RecordCreator, RecordExtractor) + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @FunctionalInterface public interface ConnectionCallback { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/InteractionCallback.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/InteractionCallback.java index ef7f14add53..447a1432eb9 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/InteractionCallback.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/InteractionCallback.java @@ -43,7 +43,10 @@ import org.springframework.lang.Nullable; * @see CciTemplate#execute(InteractionCallback) * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, javax.resource.cci.Record) * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, RecordCreator, RecordExtractor) + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @FunctionalInterface public interface InteractionCallback { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordCreator.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordCreator.java index 77bf91a21b0..18836887e03 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordCreator.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordCreator.java @@ -44,7 +44,10 @@ import org.springframework.dao.DataAccessException; * @see CciTemplate#createIndexedRecord(String) * @see CciTemplate#createMappedRecord(String) * @see CciTemplate#setOutputRecordCreator(RecordCreator) + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @FunctionalInterface public interface RecordCreator { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordExtractor.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordExtractor.java index f0344b4f22c..8c5e9e2b666 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordExtractor.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/RecordExtractor.java @@ -44,7 +44,10 @@ import org.springframework.lang.Nullable; * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, Record, RecordExtractor) * @see CciTemplate#execute(javax.resource.cci.InteractionSpec, RecordCreator, RecordExtractor) * @see javax.resource.cci.ResultSet + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @FunctionalInterface public interface RecordExtractor { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CciDaoSupport.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CciDaoSupport.java index 2f523c38fdf..e650bae6051 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CciDaoSupport.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CciDaoSupport.java @@ -21,9 +21,6 @@ import javax.resource.cci.ConnectionFactory; import javax.resource.cci.ConnectionSpec; import org.springframework.dao.support.DaoSupport; -import org.springframework.jca.cci.CannotGetCciConnectionException; -import org.springframework.jca.cci.connection.ConnectionFactoryUtils; -import org.springframework.jca.cci.core.CciTemplate; import org.springframework.lang.Nullable; import org.springframework.util.Assert; @@ -44,11 +41,14 @@ import org.springframework.util.Assert; * @see #setConnectionFactory * @see #getCciTemplate * @see org.springframework.jca.cci.core.CciTemplate + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public abstract class CciDaoSupport extends DaoSupport { @Nullable - private CciTemplate cciTemplate; + private org.springframework.jca.cci.core.CciTemplate cciTemplate; /** @@ -69,8 +69,8 @@ public abstract class CciDaoSupport extends DaoSupport { * @return the new CciTemplate instance * @see #setConnectionFactory(javax.resource.cci.ConnectionFactory) */ - protected CciTemplate createCciTemplate(ConnectionFactory connectionFactory) { - return new CciTemplate(connectionFactory); + protected org.springframework.jca.cci.core.CciTemplate createCciTemplate(ConnectionFactory connectionFactory) { + return new org.springframework.jca.cci.core.CciTemplate(connectionFactory); } /** @@ -85,7 +85,7 @@ public abstract class CciDaoSupport extends DaoSupport { * Set the CciTemplate for this DAO explicitly, * as an alternative to specifying a ConnectionFactory. */ - public final void setCciTemplate(CciTemplate cciTemplate) { + public final void setCciTemplate(org.springframework.jca.cci.core.CciTemplate cciTemplate) { this.cciTemplate = cciTemplate; } @@ -94,7 +94,7 @@ public abstract class CciDaoSupport extends DaoSupport { * pre-initialized with the ConnectionFactory or set explicitly. */ @Nullable - public final CciTemplate getCciTemplate() { + public final org.springframework.jca.cci.core.CciTemplate getCciTemplate() { return this.cciTemplate; } @@ -115,8 +115,8 @@ public abstract class CciDaoSupport extends DaoSupport { * @return the derived template instance * @see org.springframework.jca.cci.core.CciTemplate#getDerivedTemplate(javax.resource.cci.ConnectionSpec) */ - protected final CciTemplate getCciTemplate(ConnectionSpec connectionSpec) { - CciTemplate cciTemplate = getCciTemplate(); + protected final org.springframework.jca.cci.core.CciTemplate getCciTemplate(ConnectionSpec connectionSpec) { + org.springframework.jca.cci.core.CciTemplate cciTemplate = getCciTemplate(); Assert.state(cciTemplate != null, "No CciTemplate set"); return cciTemplate.getDerivedTemplate(connectionSpec); } @@ -128,10 +128,10 @@ public abstract class CciDaoSupport extends DaoSupport { * if the attempt to get a Connection failed * @see org.springframework.jca.cci.connection.ConnectionFactoryUtils#getConnection(javax.resource.cci.ConnectionFactory) */ - protected final Connection getConnection() throws CannotGetCciConnectionException { + protected final Connection getConnection() throws org.springframework.jca.cci.CannotGetCciConnectionException { ConnectionFactory connectionFactory = getConnectionFactory(); Assert.state(connectionFactory != null, "No ConnectionFactory set"); - return ConnectionFactoryUtils.getConnection(connectionFactory); + return org.springframework.jca.cci.connection.ConnectionFactoryUtils.getConnection(connectionFactory); } /** @@ -141,7 +141,7 @@ public abstract class CciDaoSupport extends DaoSupport { * @see org.springframework.jca.cci.connection.ConnectionFactoryUtils#releaseConnection */ protected final void releaseConnection(Connection con) { - ConnectionFactoryUtils.releaseConnection(con, getConnectionFactory()); + org.springframework.jca.cci.connection.ConnectionFactoryUtils.releaseConnection(con, getConnectionFactory()); } } diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CommAreaRecord.java b/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CommAreaRecord.java index 7011eb19247..6f54b8b03ce 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CommAreaRecord.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/core/support/CommAreaRecord.java @@ -32,7 +32,10 @@ import org.springframework.util.FileCopyUtils; * @author Juergen Hoeller * @since 1.2 * @see org.springframework.jca.cci.object.MappingCommAreaOperation + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated @SuppressWarnings("serial") public class CommAreaRecord implements Record, Streamable { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/object/EisOperation.java b/spring-tx/src/main/java/org/springframework/jca/cci/object/EisOperation.java index d0d522c115c..7cbe685ef03 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/object/EisOperation.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/object/EisOperation.java @@ -20,7 +20,6 @@ import javax.resource.cci.ConnectionFactory; import javax.resource.cci.InteractionSpec; import org.springframework.beans.factory.InitializingBean; -import org.springframework.jca.cci.core.CciTemplate; import org.springframework.lang.Nullable; import org.springframework.util.Assert; @@ -35,10 +34,14 @@ import org.springframework.util.Assert; * @since 1.2 * @see #setConnectionFactory * @see #setInteractionSpec + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public abstract class EisOperation implements InitializingBean { - private CciTemplate cciTemplate = new CciTemplate(); + private org.springframework.jca.cci.core.CciTemplate cciTemplate = + new org.springframework.jca.cci.core.CciTemplate(); @Nullable private InteractionSpec interactionSpec; @@ -49,7 +52,7 @@ public abstract class EisOperation implements InitializingBean { * Alternatively, specify a CCI ConnectionFactory. * @see #setConnectionFactory */ - public void setCciTemplate(CciTemplate cciTemplate) { + public void setCciTemplate(org.springframework.jca.cci.core.CciTemplate cciTemplate) { Assert.notNull(cciTemplate, "CciTemplate must not be null"); this.cciTemplate = cciTemplate; } @@ -57,7 +60,7 @@ public abstract class EisOperation implements InitializingBean { /** * Return the CciTemplate used by this operation. */ - public CciTemplate getCciTemplate() { + public org.springframework.jca.cci.core.CciTemplate getCciTemplate() { return this.cciTemplate; } diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingCommAreaOperation.java b/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingCommAreaOperation.java index a6f886cdd78..25db832ae20 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingCommAreaOperation.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingCommAreaOperation.java @@ -25,7 +25,6 @@ import javax.resource.cci.RecordFactory; import org.springframework.dao.DataAccessException; import org.springframework.dao.DataRetrievalFailureException; -import org.springframework.jca.cci.core.support.CommAreaRecord; /** * EIS operation object for access to COMMAREA records. @@ -33,7 +32,10 @@ import org.springframework.jca.cci.core.support.CommAreaRecord; * * @author Thierry Templier * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public abstract class MappingCommAreaOperation extends MappingRecordOperation { /** @@ -57,7 +59,7 @@ public abstract class MappingCommAreaOperation extends MappingRecordOperation { @Override protected final Record createInputRecord(RecordFactory recordFactory, Object inObject) { try { - return new CommAreaRecord(objectToBytes(inObject)); + return new org.springframework.jca.cci.core.support.CommAreaRecord(objectToBytes(inObject)); } catch (IOException ex) { throw new DataRetrievalFailureException("I/O exception during bytes conversion", ex); @@ -66,7 +68,8 @@ public abstract class MappingCommAreaOperation extends MappingRecordOperation { @Override protected final Object extractOutputData(Record record) throws DataAccessException { - CommAreaRecord commAreaRecord = (CommAreaRecord) record; + org.springframework.jca.cci.core.support.CommAreaRecord commAreaRecord = + (org.springframework.jca.cci.core.support.CommAreaRecord) record; try { return bytesToObject(commAreaRecord.toByteArray()); } diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingRecordOperation.java b/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingRecordOperation.java index b80630f156d..148c181a44d 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingRecordOperation.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/object/MappingRecordOperation.java @@ -25,8 +25,6 @@ import javax.resource.cci.Record; import javax.resource.cci.RecordFactory; import org.springframework.dao.DataAccessException; -import org.springframework.jca.cci.core.RecordCreator; -import org.springframework.jca.cci.core.RecordExtractor; import org.springframework.lang.Nullable; import org.springframework.util.Assert; @@ -45,7 +43,10 @@ import org.springframework.util.Assert; * @since 1.2 * @see #createInputRecord(javax.resource.cci.RecordFactory, Object) * @see #extractOutputData(javax.resource.cci.Record) + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public abstract class MappingRecordOperation extends EisOperation { /** @@ -75,7 +76,7 @@ public abstract class MappingRecordOperation extends EisOperation { * @see javax.resource.cci.Interaction#execute(javax.resource.cci.InteractionSpec, Record, Record) * @see org.springframework.jca.cci.core.CciTemplate#setOutputRecordCreator */ - public void setOutputRecordCreator(RecordCreator creator) { + public void setOutputRecordCreator(org.springframework.jca.cci.core.RecordCreator creator) { getCciTemplate().setOutputRecordCreator(creator); } @@ -126,7 +127,7 @@ public abstract class MappingRecordOperation extends EisOperation { * Implementation of RecordCreator that calls the enclosing * class's {@code createInputRecord} method. */ - protected class RecordCreatorImpl implements RecordCreator { + protected class RecordCreatorImpl implements org.springframework.jca.cci.core.RecordCreator { private final Object inputObject; @@ -145,7 +146,7 @@ public abstract class MappingRecordOperation extends EisOperation { * Implementation of RecordExtractor that calls the enclosing * class's {@code extractOutputData} method. */ - protected class RecordExtractorImpl implements RecordExtractor { + protected class RecordExtractorImpl implements org.springframework.jca.cci.core.RecordExtractor { @Override public Object extractData(Record record) throws ResourceException, SQLException, DataAccessException { diff --git a/spring-tx/src/main/java/org/springframework/jca/cci/object/SimpleRecordOperation.java b/spring-tx/src/main/java/org/springframework/jca/cci/object/SimpleRecordOperation.java index 519891dca75..5799ca935a8 100644 --- a/spring-tx/src/main/java/org/springframework/jca/cci/object/SimpleRecordOperation.java +++ b/spring-tx/src/main/java/org/springframework/jca/cci/object/SimpleRecordOperation.java @@ -30,7 +30,10 @@ import org.springframework.util.Assert; * * @author Juergen Hoeller * @since 1.2 + * @deprecated as of 5.3, in favor of specific data access APIs + * (or native CCI usage if there is no alternative) */ +@Deprecated public class SimpleRecordOperation extends EisOperation { /** diff --git a/spring-tx/src/test/java/org/springframework/jca/cci/CciLocalTransactionTests.java b/spring-tx/src/test/java/org/springframework/jca/cci/CciLocalTransactionTests.java index 0c027d11c8e..d45b326c090 100644 --- a/spring-tx/src/test/java/org/springframework/jca/cci/CciLocalTransactionTests.java +++ b/spring-tx/src/test/java/org/springframework/jca/cci/CciLocalTransactionTests.java @@ -44,6 +44,7 @@ import static org.mockito.Mockito.verify; * @author Thierry Templier * @author Chris Beams */ +@Deprecated public class CciLocalTransactionTests { /** diff --git a/spring-tx/src/test/java/org/springframework/jca/cci/CciTemplateTests.java b/spring-tx/src/test/java/org/springframework/jca/cci/CciTemplateTests.java index 6f8996dc38b..a67028f162a 100644 --- a/spring-tx/src/test/java/org/springframework/jca/cci/CciTemplateTests.java +++ b/spring-tx/src/test/java/org/springframework/jca/cci/CciTemplateTests.java @@ -51,6 +51,7 @@ import static org.mockito.Mockito.verify; * @author Juergen Hoeller * @author Chris Beams */ +@Deprecated public class CciTemplateTests { @Test diff --git a/spring-tx/src/test/java/org/springframework/jca/cci/EisOperationTests.java b/spring-tx/src/test/java/org/springframework/jca/cci/EisOperationTests.java index 4775f45bad7..30f6febbda2 100644 --- a/spring-tx/src/test/java/org/springframework/jca/cci/EisOperationTests.java +++ b/spring-tx/src/test/java/org/springframework/jca/cci/EisOperationTests.java @@ -39,6 +39,7 @@ import static org.mockito.Mockito.verify; * @author Thierry Templier * @author Chris Beams */ +@Deprecated public class EisOperationTests { @Test diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 740241b7309..e02e1f4f134 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -4045,11 +4045,6 @@ dependency type. The following table summarizes the most important `Aware` inter | Name of the declaring bean. | <> -| `BootstrapContextAware` -| Resource adapter `BootstrapContext` the container runs in. Typically available only in - JCA-aware `ApplicationContext` instances. -| <> - | `LoadTimeWeaverAware` | Defined weaver for processing class definition at load time. | <> diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index b1da44a06dd..bd16cf6667e 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -2361,7 +2361,7 @@ for more details. Spring also provides a generic JCA message endpoint manager that is not tied to JMS: `org.springframework.jca.endpoint.GenericMessageEndpointManager`. This component allows -for using any message listener type (such as a CCI `MessageListener`) and any +for using any message listener type (such as a JMS `MessageListener`) and any provider-specific `ActivationSpec` object. See your JCA provider's documentation to find out about the actual capabilities of your connector, and see the {api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`] @@ -4396,1150 +4396,6 @@ homepage] at Oracle. -[[cci]] -== JCA CCI - -Java EE provides a specification to standardize access to enterprise information systems -(EIS): the JCA (Java EE Connector Architecture). This specification is divided into -two different parts: - -* SPI (Service Provider Interfaces) that the connector provider must implement. These - interfaces constitute a resource adapter that can be deployed on a Java EE - application server. In such a scenario, the server manages connection pooling, - transactions, 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, using the Spring Framework's general resource and transaction -management facilities. - -NOTE: The client side of connectors does not always use CCI. Some connectors expose their own -APIs, providing a JCA resource adapter to use the system contracts of a Java EE container -(connection pooling, global transactions, and security). Spring does not offer special -support for such connector-specific APIs. - - - -[[cci-config]] -=== Configuring CCI - -This section covers how to configure a Common Client Interface (CCI). It includes the -following topics: - -* <> -* <> -* <> -* <> - - -[[cci-config-connector]] -==== Connector Configuration - -The base resource to use JCA CCI is the `ConnectionFactory` interface. The connector -you use 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, you can use Spring's -`JndiObjectFactoryBean` or `` to fetch the factory by its JNDI name. - -Another way to use a connector is to embed it in your application (non-managed mode) and -not use an application server to deploy and configure it. Spring offers the -possibility to configure a connector as a bean, through a `FactoryBean` implementation called -(`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 access to your `ConnectionFactory` instance, you can inject it into -your components. These components can either be coded against the plain CCI API or -use Spring's support classes for CCI access (e.g. `CciTemplate`). - -NOTE: When you use a connector in non-managed mode, you cannot use global transactions, because -the resource is never enlisted or delisted in the current global transaction of the -current thread. The resource is not aware of any global Java EE transactions that -might be running. - - -[[cci-config-connectionfactory]] -==== `ConnectionFactory` Configuration in Spring - -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 managed mode, you can access a `ConnectionFactory` from JNDI. Its properties are -configured in the application server. The following example shows how to do so: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - ----- - -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`. The following example -shows how to do so: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -NOTE: You cannot 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. - - -[[cci-config-cci-connections]] -==== Configuring CCI Connections - -JCA CCI lets you configure the connections to the EIS by using the -`ConnectionSpec` implementation of your connector. To configure its properties, -you need to wrap the target connection factory with a dedicated adapter, -`ConnectionSpecConnectionFactoryAdapter`. You can configure the dedicated `ConnectionSpec` -with the `connectionSpec` property (as an inner bean). - -This property is not mandatory, because the CCI `ConnectionFactory` interface defines two -different methods to obtain a CCI connection. You can often configure some of the `ConnectionSpec` properties -in the application server (in managed mode) or on the -corresponding local `ManagedConnectionFactory` implementation. The following listing -shows the relevant parts of the `ConnectionFactory` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface ConnectionFactory implements Serializable, Referenceable { - ... - Connection getConnection() throws ResourceException; - Connection getConnection(ConnectionSpec connectionSpec) throws ResourceException; - ... - } ----- - -Spring provides a `ConnectionSpecConnectionFactoryAdapter` that lets you specify 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 adapter uses the variant without that argument. -The following example shows how to configure a `ConnectionSpecConnectionFactoryAdapter`: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - ----- - - -[[cci-config-single-connection]] -==== 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 -lazily opens a single connection and closes it when this bean is destroyed at -application shutdown. This class exposes special `Connection` proxies that behave -accordingly, all sharing the same underlying physical connection. The following example -shows how to use the `SingleConnectionFactory` adapter class: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -NOTE: This `ConnectionFactory` adapter cannot directly be configured with a `ConnectionSpec`. -You can use an intermediary `ConnectionSpecConnectionFactoryAdapter` that the -`SingleConnectionFactory` talks to if you require a single connection for a specific -`ConnectionSpec`. - - - -[[cci-using]] -=== Using Spring's CCI Access Support - -This section describes how to use Spring's support for CCI to achieve various purposes. -It includes the following topics: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> - - -[[cci-record-creator]] -==== Record Conversion - -One of the aims of Spring's JCA CCI support is to provide convenient facilities for -manipulating CCI records. You can specify the strategy to create records and extract -data from records, for use with Spring's `CciTemplate`. The interfaces described in -this section configure the strategy to use input and output records if you do not want -to work with records directly in your application. - -To create an input `Record`, you can use a dedicated implementation of the `RecordCreator` -interface. The following listing shows the `RecordCreator` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface RecordCreator { - - Record createRecord(RecordFactory recordFactory) throws ResourceException, DataAccessException; - - } ----- - -The `createRecord(..)` method receives a `RecordFactory` instance as a -parameter, which corresponds to the `RecordFactory` of the `ConnectionFactory` used. -You can use this reference to create `IndexedRecord` or `MappedRecord` instances. The -following sample shows how to use the `RecordCreator` interface and indexed or mapped -records: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyRecordCreator implements RecordCreator { - - public Record createRecord(RecordFactory recordFactory) throws ResourceException { - IndexedRecord input = recordFactory.createIndexedRecord("input"); - input.add(new Integer(id)); - return input; - } - - } ----- - -You can use an output `Record` to receive data back from the EIS. Hence, you can pass a specific -implementation of the `RecordExtractor` interface to Spring's -`CciTemplate` to extract data from the output `Record`. The following listing shows the -`RecordExtractor` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface RecordExtractor { - - Object extractData(Record record) throws ResourceException, SQLException, DataAccessException; - - } ----- - -The following example shows how to use the `RecordExtractor` interface: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyRecordExtractor implements RecordExtractor { - - public Object extractData(Record record) throws ResourceException { - CommAreaRecord commAreaRecord = (CommAreaRecord) record; - String str = new String(commAreaRecord.toByteArray()); - String field1 = string.substring(0,6); - String field2 = string.substring(6,1); - return new OutputObject(Long.parseLong(field1), field2); - } - - } ----- - - -[[cci-using-template]] -==== Using `CciTemplate` - -The `CciTemplate` is the central class of the core CCI support package ( -`org.springframework.jca.cci.core`). It simplifies the use of CCI, since it handles the -creation and release of resources. This helps to avoid common errors, such as forgetting to -always close the connection. It cares for the lifecycle of connection and interaction -objects, letting application code focus on generating input records from application -data and extracting application data from output records. - -The JCA CCI specification defines two distinct methods to call operations on an EIS. The -CCI `Interaction` interface provides two execute method signatures, as the following -listing shows: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface javax.resource.cci.Interaction { - - ... - - boolean execute(InteractionSpec spec, Record input, Record output) throws ResourceException; - - Record execute(InteractionSpec spec, Record input) throws ResourceException; - - ... - - } ----- - -Depending on the template method called, `CciTemplate` knows which `execute` method -to call on the interaction. In any case, a correctly initialized `InteractionSpec` -instance is mandatory. - -You can use `CciTemplate.execute(..)` in two ways: - -* With direct `Record` arguments. In this case, you need to pass in the CCI input - record, and the returned object is the corresponding CCI output record. -* With application objects, by using record mapping. In this case, you need to provide - corresponding `RecordCreator` and `RecordExtractor` instances. - -With the first approach, the following methods (which directly correspond to those on the -`Interaction` interface) of the template are used: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class CciTemplate implements CciOperations { - - public Record execute(InteractionSpec spec, Record inputRecord) - throws DataAccessException { ... } - - public void execute(InteractionSpec spec, Record inputRecord, Record outputRecord) - throws DataAccessException { ... } - - } ----- - -With the second approach, we need to specify the record creation and record -extraction strategies as arguments. The interfaces used are those describe in the -<>. The following -listing shows the corresponding `CciTemplate` methods: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class CciTemplate implements CciOperations { - - public Record execute(InteractionSpec spec, - RecordCreator inputCreator) throws DataAccessException { - // ... - } - - public Object execute(InteractionSpec spec, Record inputRecord, - RecordExtractor outputExtractor) throws DataAccessException { - // ... - } - - public Object execute(InteractionSpec spec, RecordCreator creator, - RecordExtractor extractor) throws DataAccessException { - // ... - } - - } ----- - -Unless the `outputRecordCreator` property is set on the template (see the following -section), every method calls the corresponding `execute` method of the CCI -`Interaction` with two parameters: `InteractionSpec` and an input `Record`. It receives an -output `Record` as its return value. - -`CciTemplate` also provides methods to create `IndexRecord` and `MappedRecord` outside of a -`RecordCreator` implementation, through its `createIndexRecord(..)` and -`createMappedRecord(..)` methods. You can use this within DAO implementations to create -`Record` instances to pass into corresponding `CciTemplate.execute(..)` methods. -The following listing shows the `CciTemplate` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class CciTemplate implements CciOperations { - - public IndexedRecord createIndexedRecord(String name) throws DataAccessException { ... } - - public MappedRecord createMappedRecord(String name) throws DataAccessException { ... } - - } ----- - - -[[cci-using-dao]] -==== Using DAO Support - -Spring's CCI support provides an abstract class for DAOs, supporting injection of a -`ConnectionFactory` or a `CciTemplate` instance. The name of the class is -`CciDaoSupport`. It provides simple `setConnectionFactory` and `setCciTemplate` methods. -Internally, this class creates a `CciTemplate` instance for a passed-in -`ConnectionFactory`, exposing it to concrete data access implementations in subclasses. -The following example shows how to use `CciDaoSupport`: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public abstract class CciDaoSupport { - - public void setConnectionFactory(ConnectionFactory connectionFactory) { - // ... - } - - public ConnectionFactory getConnectionFactory() { - // ... - } - - public void setCciTemplate(CciTemplate cciTemplate) { - // ... - } - - public CciTemplate getCciTemplate() { - // ... - } - - } ----- - - -[[automatic-output-generation]] -==== Automatic Output Record Generation - -If the connector you use supports only the `Interaction.execute(..)` method with input and -output records as parameters (that is, it requires the desired output record to be passed -in instead of returning an appropriate output record), you can set the `outputRecordCreator` -property of the `CciTemplate` to automatically generate an output record to be filled by -the JCA connector when the response is received. This record is then returned to the caller -of the template. - -This property holds an implementation of the <>, -to be used for that purpose. You must directly specify the `outputRecordCreator` property on -the `CciTemplate`. The following example shows how to do so: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - cciTemplate.setOutputRecordCreator(new EciOutputRecordCreator()); ----- - -Alternatively (and we recommend this approach), in the Spring configuration, if the -`CciTemplate` is configured as a dedicated bean instance, you can define beans in the -following fashion: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - ----- - -NOTE: As the `CciTemplate` class is thread-safe, it is usually configured as a shared -instance. - - -[[template-summary]] -==== `CciTemplate` `Interaction` Summary - -The following table summarizes the mechanisms of the `CciTemplate` class and the -corresponding methods called on the CCI `Interaction` interface: - -[[cci-interaction-execute-methods]] -.Usage of Interaction execute methods -[cols="3,1,3"] -|=== -| `CciTemplate` method signature | `CciTemplate` `outputRecordCreator` property | `execute` method called on the CCI Interaction - -| `Record execute(InteractionSpec, Record)` -| Not set -| `Record execute(InteractionSpec, Record)` - -| `Record execute(InteractionSpec, Record)` -| Set -| `boolean execute(InteractionSpec, Record, Record)` - -| void execute(InteractionSpec, Record, Record) -| Not set -| void execute(InteractionSpec, Record, Record) - -| `void execute(InteractionSpec, Record, Record)` -| Set -| `void execute(InteractionSpec, Record, Record)` - -| `Record execute(InteractionSpec, RecordCreator)` -| Not set -| `Record execute(InteractionSpec, Record)` - -| `Record execute(InteractionSpec, RecordCreator)` -| Set -| `void execute(InteractionSpec, Record, Record)` - -| `Record execute(InteractionSpec, Record, RecordExtractor)` -| Not set -| `Record execute(InteractionSpec, Record)` - -| `Record execute(InteractionSpec, Record, RecordExtractor)` -| Set -| `void execute(InteractionSpec, Record, Record)` - -| `Record execute(InteractionSpec, RecordCreator, RecordExtractor)` -| Not set -| `Record execute(InteractionSpec, Record)` - -| `Record execute(InteractionSpec, RecordCreator, RecordExtractor)` -| Set -| `void execute(InteractionSpec, Record, Record)` -|=== - - -[[cci-straight]] -==== Using a CCI Connection and an Interaction Directly - -`CciTemplate` also lets you work directly with CCI connections and -interactions, in the same manner as `JdbcTemplate` and `JmsTemplate`. This is useful -when you want to perform multiple operations on a CCI connection or interaction, for -example. - -The `ConnectionCallback` interface provides a CCI `Connection` as an argument (to -perform custom operations on it) plus the CCI `ConnectionFactory` with which the `Connection` -was created. The latter can be useful (for example, to get an associated -`RecordFactory` instance and create indexed/mapped records). -The following listing shows the `ConnectionCallback` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface ConnectionCallback { - - Object doInConnection(Connection connection, ConnectionFactory connectionFactory) - throws ResourceException, SQLException, DataAccessException; - - } ----- - -The `InteractionCallback` interface provides the CCI `Interaction` (to perform -custom operations on it) plus the corresponding CCI `ConnectionFactory`. -The following listing shows the `InteractionCallback` interface definition: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public interface InteractionCallback { - - Object doInInteraction(Interaction interaction, ConnectionFactory connectionFactory) - throws ResourceException, SQLException, DataAccessException; - - } ----- - -NOTE: `InteractionSpec` objects can either be shared across multiple template calls or be newly -created inside every callback method. This is completely up to the DAO implementation. - - -[[cci-template-example]] -==== Example of `CciTemplate` Usage - -In this section, we show the usage of the `CciTemplate` to access a CICS with -ECI mode, with the IBM CICS ECI connector. - -First, we must do some initializations on the CCI `InteractionSpec` to specify which -CICS program to access and how to interact with it, as the following example shows: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - ECIInteractionSpec interactionSpec = new ECIInteractionSpec(); - interactionSpec.setFunctionName("MYPROG"); - interactionSpec.setInteractionVerb(ECIInteractionSpec.SYNC_SEND_RECEIVE); ----- - -Then the program can use CCI through Spring's template and specify mappings between custom -objects and CCI `Records`, as the following example shows: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyDaoImpl extends CciDaoSupport implements MyDao { - - public OutputObject getData(InputObject input) { - ECIInteractionSpec interactionSpec = ...; - - OutputObject output = (ObjectOutput) getCciTemplate().execute(interactionSpec, - new RecordCreator() { - public Record createRecord(RecordFactory recordFactory) throws ResourceException { - return new CommAreaRecord(input.toString().getBytes()); - } - }, - new RecordExtractor() { - public Object extractData(Record record) throws ResourceException { - CommAreaRecord commAreaRecord = (CommAreaRecord)record; - String str = new String(commAreaRecord.toByteArray()); - String field1 = string.substring(0,6); - String field2 = string.substring(6,1); - return new OutputObject(Long.parseLong(field1), field2); - } - }); - - return output; - } - } ----- - -As discussed previously, you can use callbacks to work directly on CCI connections or -interactions. The following example shows how to do so: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyDaoImpl extends CciDaoSupport implements MyDao { - - public OutputObject getData(InputObject input) { - ObjectOutput output = (ObjectOutput) getCciTemplate().execute( - new ConnectionCallback() { - public Object doInConnection(Connection connection, - ConnectionFactory factory) throws ResourceException { - - // do something... - - } - }); - } - return output; - } - - } ----- - -NOTE: With a `ConnectionCallback`, the `Connection` used is managed and closed by the -`CciTemplate`, but the callback implementation must manage any interactions created on the -connection. - -For a more specific callback, you can implement an `InteractionCallback`. If you do so, the passed-in -`Interaction` is managed and closed by the `CciTemplate`. The following example shows how to do so: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyDaoImpl extends CciDaoSupport implements MyDao { - - public String getData(String input) { - ECIInteractionSpec interactionSpec = ...; - String output = (String) getCciTemplate().execute(interactionSpec, - new InteractionCallback() { - public Object doInInteraction(Interaction interaction, - ConnectionFactory factory) throws ResourceException { - Record input = new CommAreaRecord(inputString.getBytes()); - Record output = new CommAreaRecord(); - interaction.execute(holder.getInteractionSpec(), input, output); - return new String(output.toByteArray()); - } - }); - return output; - } - - } ----- - -For the preceding examples, the corresponding configuration of the involved Spring beans -could resemble the following example in non-managed mode: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - -In managed mode (that is, in a Java EE environment), the configuration could resemble -the following example: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - ----- - - - -[[cci-object]] -=== Modeling CCI Access as Operation Objects - -The `org.springframework.jca.cci.object` package contains support classes that let you -access the EIS in a different style: through reusable operation objects, analogous to -Spring's JDBC operation objects (see the <>). This usually encapsulates the CCI API. An application-level -input object is passed to the operation object, so it can construct the input record and -then convert the received record data to an application-level output object and return it. - -NOTE: This approach is internally based on the `CciTemplate` class and the `RecordCreator` -or `RecordExtractor` interfaces, reusing the machinery of Spring's core CCI support. - - -[[cci-object-mapping-record]] -==== Using `MappingRecordOperation` - -`MappingRecordOperation` essentially performs the same work as `CciTemplate` but -represents a specific, pre-configured operation as an object. It provides two template -methods to specify how to convert an input object to an input record and how to convert -an output record to an output object (record mapping): - -* `createInputRecord(..)`: to specify how to convert an input object to an input `Record` -* `extractOutputData(..)`: to specify how to extract an output object from an output `Record` - -The following listing shows the signatures of these methods: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public abstract class MappingRecordOperation extends EisOperation { - - ... - - protected abstract Record createInputRecord(RecordFactory recordFactory, - Object inputObject) throws ResourceException, DataAccessException { - // ... - } - - protected abstract Object extractOutputData(Record outputRecord) - throws ResourceException, SQLException, DataAccessException { - // ... - } - - ... - - } ----- - -Thereafter, ito execute an EIS operation, you need to use a single `execute` -method, passing in an application-level input object and receiving an application-level -output object as the result. The following example shows how to do so: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public abstract class MappingRecordOperation extends EisOperation { - - ... - - public Object execute(Object inputObject) throws DataAccessException { - } - - ... - } ----- - -Contrary to the `CciTemplate` class, this `execute(..)` method does not -have an `InteractionSpec` as an argument. Instead, the `InteractionSpec` is global to the -operation. You must use the following constructor to instantiate an operation object -with a specific `InteractionSpec`. The following example shows how to do so: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - InteractionSpec spec = ...; - MyMappingRecordOperation eisOperation = new MyMappingRecordOperation(getConnectionFactory(), spec); - ... ----- - - -[[cci-object-mapping-comm-area]] -==== Using `MappingCommAreaOperation` - -Some connectors use records based on a COMMAREA, which represents an array of bytes -that contain parameters to send to the EIS and the data returned by it. Spring provides a -special operation class for working directly on COMMAREA rather than on records. The -`MappingCommAreaOperation` class extends the `MappingRecordOperation` class to provide -this special COMMAREA support. It implicitly uses the `CommAreaRecord` class as the input -and output record type and provides two new methods to convert an input object into an -input COMMAREA and convert the output COMMAREA into an output object. The following -listing shows the relevant method signatures: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public abstract class MappingCommAreaOperation extends MappingRecordOperation { - - ... - - protected abstract byte[] objectToBytes(Object inObject) - throws IOException, DataAccessException; - - protected abstract Object bytesToObject(byte[] bytes) - throws IOException, DataAccessException; - - ... - - } ----- - - -[[cci-automatic-record-gen]] -==== Automatic Output Record Generation - -As every `MappingRecordOperation` subclass is based on CciTemplate internally, the same -way to automatically generate output records as with `CciTemplate` is available. -Every operation object provides a corresponding `setOutputRecordCreator(..)` method. -For further information, see <>. - - -[[cci-object-summary]] -==== Summary - -The operation object approach uses records in the same manner as the `CciTemplate` class. - -[[cci-interaction-methods]] -.Usage of Interaction execute methods -[cols="3,1,3"] -|=== -| `MappingRecordOperation` method signature | `MappingRecordOperation` `outputRecordCreator` property | `execute` method called on the CCI Interaction - -| `Object execute(Object)` -| Not set -| `Record execute(InteractionSpec, Record)` - -| `Object execute(Object)` -| Set -| `boolean execute(InteractionSpec, Record, Record)` -|=== - - -[[cci-objects-mappring-record-example]] -==== Example of `MappingRecordOperation` Usage - -In this section, we show how to use `MappingRecordOperation` to access a -database with the Blackbox CCI connector. - -NOTE: The original version of this connector is provided by the Java EE SDK (version 1.3), -which is available from Oracle. - -First, you must do some initializations on the CCI `InteractionSpec` to specify which -SQL request to execute. In the following example, we directly define the way to convert the -parameters of the request to a CCI record and the way to convert the CCI result record -to an instance of the `Person` class: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class PersonMappingOperation extends MappingRecordOperation { - - public PersonMappingOperation(ConnectionFactory connectionFactory) { - setConnectionFactory(connectionFactory); - CciInteractionSpec interactionSpec = new CciConnectionSpec(); - interactionSpec.setSql("select * from person where person_id=?"); - setInteractionSpec(interactionSpec); - } - - protected Record createInputRecord(RecordFactory recordFactory, - Object inputObject) throws ResourceException { - Integer id = (Integer) inputObject; - IndexedRecord input = recordFactory.createIndexedRecord("input"); - input.add(new Integer(id)); - return input; - } - - protected Object extractOutputData(Record outputRecord) - throws ResourceException, SQLException { - ResultSet rs = (ResultSet) outputRecord; - Person person = null; - if (rs.next()) { - Person person = new Person(); - person.setId(rs.getInt("person_id")); - person.setLastName(rs.getString("person_last_name")); - person.setFirstName(rs.getString("person_first_name")); - } - return person; - } - } ----- - -Then the application can execute the operation object, with the person identifier as an -argument. Note that you could set up the operation object as a shared instance, as it is -thread-safe. The following executes the operation object with the person identifier as an -argument: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyDaoImpl extends CciDaoSupport implements MyDao { - - public Person getPerson(int id) { - PersonMappingOperation query = new PersonMappingOperation(getConnectionFactory()); - Person person = (Person) query.execute(new Integer(id)); - return person; - } - } ----- - -The corresponding configuration of Spring beans could be as follows in non-managed mode: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - ----- - -In managed mode (that is, in a Java EE environment), the configuration could be as -follows: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - ----- - - -[[cci-objects-mapping-comm-area-example]] -==== Example of `MappingCommAreaOperation` Usage - -In this section, we show how to use the usage of the `MappingCommAreaOperation` to access a -CICS with ECI mode with the IBM CICS ECI connector. - -First, we need to initialize the CCI `InteractionSpec` to specify which CICS program -to access and how to interact with it, as the following example shows: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public abstract class EciMappingOperation extends MappingCommAreaOperation { - - public EciMappingOperation(ConnectionFactory connectionFactory, String programName) { - setConnectionFactory(connectionFactory); - ECIInteractionSpec interactionSpec = new ECIInteractionSpec(), - interactionSpec.setFunctionName(programName); - interactionSpec.setInteractionVerb(ECIInteractionSpec.SYNC_SEND_RECEIVE); - interactionSpec.setCommareaLength(30); - setInteractionSpec(interactionSpec); - setOutputRecordCreator(new EciOutputRecordCreator()); - } - - private static class EciOutputRecordCreator implements RecordCreator { - public Record createRecord(RecordFactory recordFactory) throws ResourceException { - return new CommAreaRecord(); - } - } - - } ----- - -We can then subclass the abstract `EciMappingOperation` class to specify mappings -between custom objects and `Records`, as the following example shows: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class MyDaoImpl extends CciDaoSupport implements MyDao { - - public OutputObject getData(Integer id) { - EciMappingOperation query = new EciMappingOperation(getConnectionFactory(), "MYPROG") { - - protected abstract byte[] objectToBytes(Object inObject) throws IOException { - Integer id = (Integer) inObject; - return String.valueOf(id); - } - - protected abstract Object bytesToObject(byte[] bytes) throws IOException; - String str = new String(bytes); - String field1 = str.substring(0,6); - String field2 = str.substring(6,1); - String field3 = str.substring(7,1); - return new OutputObject(field1, field2, field3); - } - }); - - return (OutputObject) query.execute(new Integer(id)); - } - - } ----- - -The corresponding configuration of Spring beans could be as follows in non-managed mode: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - -In managed mode (that is, in a Java EE environment), the configuration could be as -follows: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - ----- - - - -[[cci-tx]] -=== Transactions - -JCA specifies several levels of transaction support for resource adapters. The kind of -transactions that your resource adapter supports is specified in its `ra.xml` file. -There are essentially three options: none (for example, with the CICS EPI connector), local -transactions (for example, with a CICS ECI connector), and global transactions (for example, -with an IMS connector). The following example configures the global option: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - XATransaction - - ----- - -For global transactions, you can use Spring's generic transaction infrastructure to -demarcate transactions, with `JtaTransactionManager` as the backend (delegating to the Java -EE server's distributed transaction coordinator underneath). - -For local transactions on a single CCI `ConnectionFactory`, Spring provides a specific -transaction-management strategy for CCI, analogous to the `DataSourceTransactionManager` -for JDBC. The CCI API defines a local transaction object and corresponding local -transaction demarcation methods. Spring's `CciLocalTransactionManager` executes such -local CCI transactions in a fashion that is fully compliant with Spring's generic -`PlatformTransactionManager` abstraction. The following example configures a `CciLocalTransactionManager`: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - ----- - -You can use both transaction strategies with any of Spring's transaction demarcation -facilities, be it declarative or programmatic. This is a consequence of Spring's generic -`PlatformTransactionManager` abstraction, which decouples transaction demarcation from -the actual execution strategy. You can switch between `JtaTransactionManager` and -`CciLocalTransactionManager` as needed, keeping your transaction demarcation as-is. - -For more information on Spring's transaction facilities, see -<>. - - - - [[mail]] == Email