org.springframework.jca.cci.core

Class CciTemplate

  • java.lang.Object
    • org.springframework.jca.cci.core.CciTemplate
  • All Implemented Interfaces:
    CciOperations


    public class CciTemplate
    extends java.lang.Object
    implements CciOperations
    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 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.

    Since:
    1.2
    Author:
    Thierry Templier, Juergen Hoeller
    See Also:
    RecordCreator, RecordExtractor
    • Constructor Detail

      • CciTemplate

        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 - the JCA ConnectionFactory to obtain Connections from
      • CciTemplate

        public CciTemplate(ConnectionFactory connectionFactory,
                           @Nullable
                           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 - the JCA ConnectionFactory to obtain Connections from
        connectionSpec - the CCI ConnectionSpec to obtain Connections for (may be null)
    • Method Detail

      • setConnectionFactory

        public void setConnectionFactory(@Nullable
                                         ConnectionFactory connectionFactory)
        Set the CCI ConnectionFactory to obtain Connections from.
      • getConnectionFactory

        @Nullable
        public ConnectionFactory getConnectionFactory()
        Return the CCI ConnectionFactory used by this template.
      • setConnectionSpec

        public void setConnectionSpec(@Nullable
                                      ConnectionSpec connectionSpec)
        Set the CCI ConnectionSpec that this template instance is supposed to obtain Connections for.
      • getConnectionSpec

        @Nullable
        public ConnectionSpec getConnectionSpec()
        Return the CCI ConnectionSpec used by this template, if any.
      • getOutputRecordCreator

        @Nullable
        public RecordCreator getOutputRecordCreator()
        Return a RecordCreator that should be used for creating default output Records.
      • afterPropertiesSet

        public void afterPropertiesSet()
      • getDerivedTemplate

        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:
        setConnectionSpec(javax.resource.cci.ConnectionSpec)
      • execute

        @Nullable
        public <T> T execute(ConnectionCallback<T> action)
                                throws DataAccessException
        Description copied from interface: CciOperations
        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.

        Specified by:
        execute in interface CciOperations
        Parameters:
        action - the callback object that specifies the action
        Returns:
        the result object returned by the action, if any
        Throws:
        DataAccessException - if there is any problem
      • execute

        @Nullable
        public <T> T execute(InteractionCallback<T> action)
                                throws DataAccessException
        Description copied from interface: CciOperations
        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.

        Specified by:
        execute in interface CciOperations
        Parameters:
        action - the callback object that specifies the action
        Returns:
        the result object returned by the action, if any
        Throws:
        DataAccessException - if there is any problem
      • execute

        public void execute(InteractionSpec spec,
                            Record inputRecord,
                            Record outputRecord)
                     throws DataAccessException
        Description copied from interface: CciOperations
        Execute the specified interaction on an EIS with CCI.
        Specified by:
        execute in interface CciOperations
        Parameters:
        spec - the CCI InteractionSpec instance that defines the interaction (connector-specific)
        inputRecord - the input record
        outputRecord - the output record
        Throws:
        DataAccessException - if there is any problem
      • execute

        public <T> T execute(InteractionSpec spec,
                             Record inputRecord,
                             RecordExtractor<T> outputExtractor)
                      throws DataAccessException
        Description copied from interface: CciOperations
        Execute the specified interaction on an EIS with CCI.
        Specified by:
        execute in interface CciOperations
        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 - if there is any problem
      • execute

        public <T> T execute(InteractionSpec spec,
                             RecordCreator inputCreator,
                             RecordExtractor<T> outputExtractor)
                      throws DataAccessException
        Description copied from interface: CciOperations
        Execute the specified interaction on an EIS with CCI.
        Specified by:
        execute in interface CciOperations
        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 - if there is any problem
      • doExecute

        @Nullable
        protected <T> T doExecute(InteractionSpec spec,
                                            Record inputRecord,
                                            @Nullable
                                            Record outputRecord,
                                            @Nullable
                                            RecordExtractor<T> outputExtractor)
                                     throws DataAccessException
        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
      • getRecordFactory

        protected RecordFactory getRecordFactory(ConnectionFactory connectionFactory)
                                          throws ResourceException
        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:
        ResourceException - if thrown by CCI methods
        See Also:
        NotSupportedRecordFactory