public class

CciTemplate

extends Object
implements CciOperations
java.lang.Object
   ↳ org.springframework.jca.cci.core.CciTemplate

Class Overview

This is the central class in the CCI core package. It simplifies the use of CCI and helps to avoid common errors. It executes core CCI workflow, leaving application code to provide parameters to CCI and extract results. This class executes EIS queries or updates, catching ResourceExceptions and translating them to the generic exception hierarchy defined in the org.springframework.dao package.

Code using this class can pass in and receive javax.resource.cci.Record instances, or alternatively implement callback interfaces for creating input Records and extracting result objects from output Records (or CCI ResultSets).

Can be used within a service implementation via direct instantiation with a ConnectionFactory reference, or get prepared in an application context and given to services as bean reference. Note: The ConnectionFactory should always be configured as a bean in the application context, in the first case given to the service directly, in the second case to the prepared template.

See Also

Summary

Public Constructors
CciTemplate()
Construct a new CciTemplate for bean usage.
CciTemplate(ConnectionFactory connectionFactory)
Construct a new CciTemplate, given a ConnectionFactory to obtain Connections from.
CciTemplate(ConnectionFactory connectionFactory, ConnectionSpec connectionSpec)
Construct a new CciTemplate, given a ConnectionFactory to obtain Connections from.
Public Methods
void afterPropertiesSet()
IndexedRecord createIndexedRecord(String name)
Create an indexed Record through the ConnectionFactory's RecordFactory.
MappedRecord createMappedRecord(String name)
Create a mapped Record from the ConnectionFactory's RecordFactory.
<T> T execute(InteractionSpec spec, RecordCreator inputCreator, RecordExtractor<T> outputExtractor)
Execute the specified interaction on an EIS with CCI.
<T> T execute(InteractionSpec spec, Record inputRecord, RecordExtractor<T> outputExtractor)
Execute the specified interaction on an EIS with CCI.
Record execute(InteractionSpec spec, RecordCreator inputCreator)
Execute the specified interaction on an EIS with CCI.
Record execute(InteractionSpec spec, Record inputRecord)
Execute the specified interaction on an EIS with CCI.
void execute(InteractionSpec spec, Record inputRecord, Record outputRecord)
Execute the specified interaction on an EIS with CCI.
<T> T execute(InteractionCallback<T> action)
Execute a request on an EIS with CCI, implemented as callback action working on a CCI Interaction.
<T> T execute(ConnectionCallback<T> action)
Execute a request on an EIS with CCI, implemented as callback action working on a CCI Connection.
ConnectionFactory getConnectionFactory()
Return the CCI ConnectionFactory used by this template.
ConnectionSpec getConnectionSpec()
Return the CCI ConnectionSpec used by this template, if any.
CciTemplate getDerivedTemplate(ConnectionSpec connectionSpec)
Create a template derived from this template instance, inheriting the ConnectionFactory and other settings but overriding the ConnectionSpec used for obtaining Connections.
RecordCreator getOutputRecordCreator()
Return a RecordCreator that should be used for creating default output Records.
void setConnectionFactory(ConnectionFactory connectionFactory)
Set the CCI ConnectionFactory to obtain Connections from.
void setConnectionSpec(ConnectionSpec connectionSpec)
Set the CCI ConnectionSpec that this template instance is supposed to obtain Connections for.
void setOutputRecordCreator(RecordCreator creator)
Set a RecordCreator that should be used for creating default output Records.
Protected Methods
Record createRecord(RecordCreator recordCreator)
Invoke the given RecordCreator, converting JCA ResourceExceptions to Spring's DataAccessException hierarchy.
<T> T doExecute(InteractionSpec spec, Record inputRecord, Record outputRecord, RecordExtractor<T> outputExtractor)
Execute the specified interaction on an EIS with CCI.
RecordFactory getRecordFactory(ConnectionFactory connectionFactory)
Return a RecordFactory for the given ConnectionFactory.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.springframework.jca.cci.core.CciOperations

Public Constructors

public CciTemplate ()

Construct a new CciTemplate for bean usage.

Note: The ConnectionFactory has to be set before using the instance.

See Also

public CciTemplate (ConnectionFactory connectionFactory)

Construct a new CciTemplate, given a ConnectionFactory to obtain Connections from. Note: This will trigger eager initialization of the exception translator.

Parameters
connectionFactory JCA ConnectionFactory to obtain Connections from

public CciTemplate (ConnectionFactory connectionFactory, ConnectionSpec connectionSpec)

Construct a new CciTemplate, given a ConnectionFactory to obtain Connections from. Note: This will trigger eager initialization of the exception translator.

Parameters
connectionFactory JCA ConnectionFactory to obtain Connections from
connectionSpec the CCI ConnectionSpec to obtain Connections for (may be null)

Public Methods

public void afterPropertiesSet ()

public IndexedRecord createIndexedRecord (String name)

Create an indexed Record through the ConnectionFactory's RecordFactory.

Parameters
name the name of the record
Returns
  • the Record
Throws
DataAccessException if creation of the Record failed
See Also
  • #getRecordFactory(javax.resource.cci.ConnectionFactory)
  • javax.resource.cci.RecordFactory#createIndexedRecord(String)

public MappedRecord createMappedRecord (String name)

Create a mapped Record from the ConnectionFactory's RecordFactory.

Parameters
name record name
Returns
  • the Record
Throws
DataAccessException if creation of the Record failed
See Also
  • #getRecordFactory(javax.resource.cci.ConnectionFactory)
  • javax.resource.cci.RecordFactory#createMappedRecord(String)

public T execute (InteractionSpec spec, RecordCreator inputCreator, RecordExtractor<T> outputExtractor)

Execute the specified interaction on an EIS with CCI.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputCreator object that creates the input record to use
outputExtractor object to convert the output record to a result object
Returns
  • the output data extracted with the RecordExtractor object
Throws
DataAccessException

public T execute (InteractionSpec spec, Record inputRecord, RecordExtractor<T> outputExtractor)

Execute the specified interaction on an EIS with CCI.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputRecord the input record
outputExtractor object to convert the output record to a result object
Returns
  • the output data extracted with the RecordExtractor object
Throws
DataAccessException

public Record execute (InteractionSpec spec, RecordCreator inputCreator)

Execute the specified interaction on an EIS with CCI.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputCreator object that creates the input record to use
Returns
  • the output record
Throws
DataAccessException

public Record execute (InteractionSpec spec, Record inputRecord)

Execute the specified interaction on an EIS with CCI.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputRecord the input record
Returns
  • the output record
Throws
DataAccessException

public void execute (InteractionSpec spec, Record inputRecord, Record outputRecord)

Execute the specified interaction on an EIS with CCI.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputRecord the input record
outputRecord the output record
Throws
DataAccessException

public T execute (InteractionCallback<T> action)

Execute a request on an EIS with CCI, implemented as callback action working on a CCI Interaction. This allows for implementing arbitrary data access operations on a single Interaction, within Spring's managed CCI environment: that is, participating in Spring-managed transactions and converting JCA ResourceExceptions into Spring's DataAccessException hierarchy.

The callback action can return a result object, for example a domain object or a collection of domain objects.

Parameters
action the callback object that specifies the action
Returns
  • the result object returned by the action, if any
Throws
DataAccessException

public T execute (ConnectionCallback<T> action)

Execute a request on an EIS with CCI, implemented as callback action working on a CCI Connection. This allows for implementing arbitrary data access operations, within Spring's managed CCI environment: that is, participating in Spring-managed transactions and converting JCA ResourceExceptions into Spring's DataAccessException hierarchy.

The callback action can return a result object, for example a domain object or a collection of domain objects.

Parameters
action the callback object that specifies the action
Returns
  • the result object returned by the action, if any
Throws
DataAccessException

public ConnectionFactory getConnectionFactory ()

Return the CCI ConnectionFactory used by this template.

public ConnectionSpec getConnectionSpec ()

Return the CCI ConnectionSpec used by this template, if any.

public CciTemplate getDerivedTemplate (ConnectionSpec connectionSpec)

Create a template derived from this template instance, inheriting the ConnectionFactory and other settings but overriding the ConnectionSpec used for obtaining Connections.

Parameters
connectionSpec the CCI ConnectionSpec that the derived template instance is supposed to obtain Connections for
Returns
  • the derived template instance
See Also

public RecordCreator getOutputRecordCreator ()

Return a RecordCreator that should be used for creating default output Records.

public void setConnectionFactory (ConnectionFactory connectionFactory)

Set the CCI ConnectionFactory to obtain Connections from.

public void setConnectionSpec (ConnectionSpec connectionSpec)

Set the CCI ConnectionSpec that this template instance is supposed to obtain Connections for.

public void setOutputRecordCreator (RecordCreator creator)

Set a RecordCreator that should be used for creating default output Records.

Default is none: When no explicit output Record gets passed into an execute method, CCI's Interaction.execute variant that returns an output Record will be called.

Specify a RecordCreator here if you always need to call CCI's Interaction.execute variant with a passed-in output Record. Unless there is an explicitly specified output Record, CciTemplate will then invoke this RecordCreator to create a default output Record instance.

See Also
  • javax.resource.cci.Interaction#execute(javax.resource.cci.InteractionSpec, Record)
  • javax.resource.cci.Interaction#execute(javax.resource.cci.InteractionSpec, Record, Record)

Protected Methods

protected Record createRecord (RecordCreator recordCreator)

Invoke the given RecordCreator, converting JCA ResourceExceptions to Spring's DataAccessException hierarchy.

Parameters
recordCreator the RecordCreator to invoke
Returns
  • the created Record
Throws
DataAccessException if creation of the Record failed
See Also
  • #getRecordFactory(javax.resource.cci.ConnectionFactory)
  • RecordCreator#createRecord(javax.resource.cci.RecordFactory)

protected T doExecute (InteractionSpec spec, Record inputRecord, Record outputRecord, RecordExtractor<T> outputExtractor)

Execute the specified interaction on an EIS with CCI. All other interaction execution methods go through this.

Parameters
spec the CCI InteractionSpec instance that defines the interaction (connector-specific)
inputRecord the input record
outputRecord output record (can be null)
outputExtractor object to convert the output record to a result object
Returns
  • the output data extracted with the RecordExtractor object
Throws
DataAccessException if there is any problem

protected RecordFactory getRecordFactory (ConnectionFactory connectionFactory)

Return a RecordFactory for the given ConnectionFactory.

Default implementation returns the connector's RecordFactory if available, falling back to a NotSupportedRecordFactory placeholder. This allows to invoke a RecordCreator callback with a non-null RecordFactory reference in any case.

Parameters
connectionFactory the CCI ConnectionFactory
Returns
  • the CCI RecordFactory for the ConnectionFactory
Throws
if thrown by CCI methods
ResourceException
See Also