001/*
002 * Copyright 2002-2008 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.jca.cci.core;
018
019import javax.resource.cci.InteractionSpec;
020import javax.resource.cci.Record;
021
022import org.springframework.dao.DataAccessException;
023
024/**
025 * Interface that specifies a basic set of CCI operations on an EIS.
026 * Implemented by CciTemplate. Not often used, but a useful option
027 * to enhance testability, as it can easily be mocked or stubbed.
028 *
029 * <p>Alternatively, the standard CCI infrastructure can be mocked.
030 * However, mocking this interface constitutes significantly less work.
031 *
032 * @author Juergen Hoeller
033 * @since 1.2
034 * @see CciTemplate
035 */
036public interface CciOperations {
037
038        /**
039         * Execute a request on an EIS with CCI, implemented as callback action
040         * working on a CCI Connection. This allows for implementing arbitrary
041         * data access operations, within Spring's managed CCI environment:
042         * that is, participating in Spring-managed transactions and converting
043         * JCA ResourceExceptions into Spring's DataAccessException hierarchy.
044         * <p>The callback action can return a result object, for example a
045         * domain object or a collection of domain objects.
046         * @param action the callback object that specifies the action
047         * @return the result object returned by the action, if any
048         * @throws DataAccessException if there is any problem
049         */
050        <T> T execute(ConnectionCallback<T> action) throws DataAccessException;
051
052        /**
053         * Execute a request on an EIS with CCI, implemented as callback action
054         * working on a CCI Interaction. This allows for implementing arbitrary
055         * data access operations on a single Interaction, within Spring's managed
056         * CCI environment: that is, participating in Spring-managed transactions
057         * and converting JCA ResourceExceptions into Spring's DataAccessException
058         * hierarchy.
059         * <p>The callback action can return a result object, for example a
060         * domain object or a collection of domain objects.
061         * @param action the callback object that specifies the action
062         * @return the result object returned by the action, if any
063         * @throws DataAccessException if there is any problem
064         */
065        <T> T execute(InteractionCallback<T> action) throws DataAccessException;
066
067        /**
068         * Execute the specified interaction on an EIS with CCI.
069         * @param spec the CCI InteractionSpec instance that defines
070         * the interaction (connector-specific)
071         * @param inputRecord the input record
072         * @return the output record
073         * @throws DataAccessException if there is any problem
074         */
075        Record execute(InteractionSpec spec, Record inputRecord) throws DataAccessException;
076
077        /**
078         * Execute the specified interaction on an EIS with CCI.
079         * @param spec the CCI InteractionSpec instance that defines
080         * the interaction (connector-specific)
081         * @param inputRecord the input record
082         * @param outputRecord the output record
083         * @throws DataAccessException if there is any problem
084         */
085        void execute(InteractionSpec spec, Record inputRecord, Record outputRecord) throws DataAccessException;
086
087        /**
088         * Execute the specified interaction on an EIS with CCI.
089         * @param spec the CCI InteractionSpec instance that defines
090         * the interaction (connector-specific)
091         * @param inputCreator object that creates the input record to use
092         * @return the output record
093         * @throws DataAccessException if there is any problem
094         */
095        Record execute(InteractionSpec spec, RecordCreator inputCreator) throws DataAccessException;
096
097        /**
098         * Execute the specified interaction on an EIS with CCI.
099         * @param spec the CCI InteractionSpec instance that defines
100         * the interaction (connector-specific)
101         * @param inputRecord the input record
102         * @param outputExtractor object to convert the output record to a result object
103         * @return the output data extracted with the RecordExtractor object
104         * @throws DataAccessException if there is any problem
105         */
106        <T> T execute(InteractionSpec spec, Record inputRecord, RecordExtractor<T> outputExtractor)
107                        throws DataAccessException;
108
109        /**
110         * Execute the specified interaction on an EIS with CCI.
111         * @param spec the CCI InteractionSpec instance that defines
112         * the interaction (connector-specific)
113         * @param inputCreator object that creates the input record to use
114         * @param outputExtractor object to convert the output record to a result object
115         * @return the output data extracted with the RecordExtractor object
116         * @throws DataAccessException if there is any problem
117         */
118        <T> T execute(InteractionSpec spec, RecordCreator inputCreator, RecordExtractor<T> outputExtractor)
119                        throws DataAccessException;
120
121}