001/* 002 * Copyright 2002-2017 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; 023import org.springframework.lang.Nullable; 024 025/** 026 * Interface that specifies a basic set of CCI operations on an EIS. 027 * Implemented by CciTemplate. Not often used, but a useful option 028 * to enhance testability, as it can easily be mocked or stubbed. 029 * 030 * <p>Alternatively, the standard CCI infrastructure can be mocked. 031 * However, mocking this interface constitutes significantly less work. 032 * 033 * @author Juergen Hoeller 034 * @since 1.2 035 * @see CciTemplate 036 */ 037public interface CciOperations { 038 039 /** 040 * Execute a request on an EIS with CCI, implemented as callback action 041 * working on a CCI Connection. This allows for implementing arbitrary 042 * data access operations, within Spring's managed CCI environment: 043 * that is, participating in Spring-managed transactions and converting 044 * JCA ResourceExceptions into Spring's DataAccessException hierarchy. 045 * <p>The callback action can return a result object, for example a 046 * domain object or a collection of domain objects. 047 * @param action the callback object that specifies the action 048 * @return the result object returned by the action, if any 049 * @throws DataAccessException if there is any problem 050 */ 051 @Nullable 052 <T> T execute(ConnectionCallback<T> action) throws DataAccessException; 053 054 /** 055 * Execute a request on an EIS with CCI, implemented as callback action 056 * working on a CCI Interaction. This allows for implementing arbitrary 057 * data access operations on a single Interaction, within Spring's managed 058 * CCI environment: that is, participating in Spring-managed transactions 059 * and converting JCA ResourceExceptions into Spring's DataAccessException 060 * hierarchy. 061 * <p>The callback action can return a result object, for example a 062 * domain object or a collection of domain objects. 063 * @param action the callback object that specifies the action 064 * @return the result object returned by the action, if any 065 * @throws DataAccessException if there is any problem 066 */ 067 @Nullable 068 <T> T execute(InteractionCallback<T> action) throws DataAccessException; 069 070 /** 071 * Execute the specified interaction on an EIS with CCI. 072 * @param spec the CCI InteractionSpec instance that defines 073 * the interaction (connector-specific) 074 * @param inputRecord the input record 075 * @return the output record 076 * @throws DataAccessException if there is any problem 077 */ 078 @Nullable 079 Record execute(InteractionSpec spec, Record inputRecord) throws DataAccessException; 080 081 /** 082 * Execute the specified interaction on an EIS with CCI. 083 * @param spec the CCI InteractionSpec instance that defines 084 * the interaction (connector-specific) 085 * @param inputRecord the input record 086 * @param outputRecord the output record 087 * @throws DataAccessException if there is any problem 088 */ 089 void execute(InteractionSpec spec, Record inputRecord, Record outputRecord) throws DataAccessException; 090 091 /** 092 * Execute the specified interaction on an EIS with CCI. 093 * @param spec the CCI InteractionSpec instance that defines 094 * the interaction (connector-specific) 095 * @param inputCreator object that creates the input record to use 096 * @return the output record 097 * @throws DataAccessException if there is any problem 098 */ 099 Record execute(InteractionSpec spec, RecordCreator inputCreator) throws DataAccessException; 100 101 /** 102 * Execute the specified interaction on an EIS with CCI. 103 * @param spec the CCI InteractionSpec instance that defines 104 * the interaction (connector-specific) 105 * @param inputRecord the input record 106 * @param outputExtractor object to convert the output record to a result object 107 * @return the output data extracted with the RecordExtractor object 108 * @throws DataAccessException if there is any problem 109 */ 110 @Nullable 111 <T> T execute(InteractionSpec spec, Record inputRecord, RecordExtractor<T> outputExtractor) 112 throws DataAccessException; 113 114 /** 115 * Execute the specified interaction on an EIS with CCI. 116 * @param spec the CCI InteractionSpec instance that defines 117 * the interaction (connector-specific) 118 * @param inputCreator object that creates the input record to use 119 * @param outputExtractor object to convert the output record to a result object 120 * @return the output data extracted with the RecordExtractor object 121 * @throws DataAccessException if there is any problem 122 */ 123 @Nullable 124 <T> T execute(InteractionSpec spec, RecordCreator inputCreator, RecordExtractor<T> outputExtractor) 125 throws DataAccessException; 126 127}