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.jdbc.core.simple; 018 019import java.util.Map; 020 021import org.springframework.jdbc.core.namedparam.SqlParameterSource; 022import org.springframework.jdbc.support.KeyHolder; 023import org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor; 024 025/** 026 * Interface specifying the API for a Simple JDBC Insert implemented by {@link SimpleJdbcInsert}. 027 * This interface is not often used directly, but provides the option to enhance testability, 028 * as it can easily be mocked or stubbed. 029 * 030 * @author Thomas Risberg 031 * @since 2.5 032 */ 033public interface SimpleJdbcInsertOperations { 034 035 /** 036 * Specify the table name to be used for the insert. 037 * @param tableName the name of the stored table 038 * @return the instance of this SimpleJdbcInsert 039 */ 040 SimpleJdbcInsertOperations withTableName(String tableName); 041 042 /** 043 * Specify the schema name, if any, to be used for the insert. 044 * @param schemaName the name of the schema 045 * @return the instance of this SimpleJdbcInsert 046 */ 047 SimpleJdbcInsertOperations withSchemaName(String schemaName); 048 049 /** 050 * Specify the catalog name, if any, to be used for the insert. 051 * @param catalogName the name of the catalog 052 * @return the instance of this SimpleJdbcInsert 053 */ 054 SimpleJdbcInsertOperations withCatalogName(String catalogName); 055 056 /** 057 * Specify the column names that the insert statement should be limited to use. 058 * @param columnNames one or more column names 059 * @return the instance of this SimpleJdbcInsert 060 */ 061 SimpleJdbcInsertOperations usingColumns(String... columnNames); 062 063 /** 064 * Specify the names of any columns that have auto generated keys. 065 * @param columnNames one or more column names 066 * @return the instance of this SimpleJdbcInsert 067 */ 068 SimpleJdbcInsertOperations usingGeneratedKeyColumns(String... columnNames); 069 070 /** 071 * Turn off any processing of column meta-data information obtained via JDBC. 072 * @return the instance of this SimpleJdbcInsert 073 */ 074 SimpleJdbcInsertOperations withoutTableColumnMetaDataAccess(); 075 076 /** 077 * Include synonyms for the column meta-data lookups via JDBC. 078 * <p>Note: This is only necessary to include for Oracle since other databases 079 * supporting synonyms seems to include the synonyms automatically. 080 * @return the instance of this SimpleJdbcInsert 081 */ 082 SimpleJdbcInsertOperations includeSynonymsForTableColumnMetaData(); 083 084 /** 085 * Use a the provided NativeJdbcExtractor during the column meta data 086 * lookups via JDBC. 087 * <p>Note: This is only necessary to include when running with a connection pool 088 * that wraps the meta data connection and when using a database like Oracle 089 * where it is necessary to access the native connection to include synonyms. 090 * @return the instance of this SimpleJdbcInsert 091 */ 092 SimpleJdbcInsertOperations useNativeJdbcExtractorForMetaData(NativeJdbcExtractor nativeJdbcExtractor); 093 094 095 /** 096 * Execute the insert using the values passed in. 097 * @param args Map containing column names and corresponding value 098 * @return the number of rows affected as returned by the JDBC driver 099 */ 100 int execute(Map<String, ?> args); 101 102 /** 103 * Execute the insert using the values passed in. 104 * @param parameterSource SqlParameterSource containing values to use for insert 105 * @return the number of rows affected as returned by the JDBC driver 106 */ 107 int execute(SqlParameterSource parameterSource); 108 109 /** 110 * Execute the insert using the values passed in and return the generated key. 111 * <p>This requires that the name of the columns with auto generated keys have been specified. 112 * This method will always return a KeyHolder but the caller must verify that it actually 113 * contains the generated keys. 114 * @param args Map containing column names and corresponding value 115 * @return the generated key value 116 */ 117 Number executeAndReturnKey(Map<String, ?> args); 118 119 /** 120 * Execute the insert using the values passed in and return the generated key. 121 * <p>This requires that the name of the columns with auto generated keys have been specified. 122 * This method will always return a KeyHolder but the caller must verify that it actually 123 * contains the generated keys. 124 * @param parameterSource SqlParameterSource containing values to use for insert 125 * @return the generated key value. 126 */ 127 Number executeAndReturnKey(SqlParameterSource parameterSource); 128 129 /** 130 * Execute the insert using the values passed in and return the generated keys. 131 * <p>This requires that the name of the columns with auto generated keys have been specified. 132 * This method will always return a KeyHolder but the caller must verify that it actually 133 * contains the generated keys. 134 * @param args Map containing column names and corresponding value 135 * @return the KeyHolder containing all generated keys 136 */ 137 KeyHolder executeAndReturnKeyHolder(Map<String, ?> args); 138 139 /** 140 * Execute the insert using the values passed in and return the generated keys. 141 * <p>This requires that the name of the columns with auto generated keys have been specified. 142 * This method will always return a KeyHolder but the caller must verify that it actually 143 * contains the generated keys. 144 * @param parameterSource SqlParameterSource containing values to use for insert 145 * @return the KeyHolder containing all generated keys 146 */ 147 KeyHolder executeAndReturnKeyHolder(SqlParameterSource parameterSource); 148 149 /** 150 * Execute a batch insert using the batch of values passed in. 151 * @param batch an array of Maps containing a batch of column names and corresponding value 152 * @return the array of number of rows affected as returned by the JDBC driver 153 */ 154 @SuppressWarnings("unchecked") 155 int[] executeBatch(Map<String, ?>... batch); 156 157 /** 158 * Execute a batch insert using the batch of values passed in. 159 * @param batch an array of SqlParameterSource containing values for the batch 160 * @return the array of number of rows affected as returned by the JDBC driver 161 */ 162 int[] executeBatch(SqlParameterSource... batch); 163 164}