001/* 002 * Copyright 2002-2019 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.namedparam; 018 019import org.springframework.jdbc.support.JdbcUtils; 020import org.springframework.lang.Nullable; 021 022/** 023 * Interface that defines common functionality for objects that can 024 * offer parameter values for named SQL parameters, serving as argument 025 * for {@link NamedParameterJdbcTemplate} operations. 026 * 027 * <p>This interface allows for the specification of SQL type in addition 028 * to parameter values. All parameter values and types are identified by 029 * specifying the name of the parameter. 030 * 031 * <p>Intended to wrap various implementations like a Map or a JavaBean 032 * with a consistent interface. 033 * 034 * @author Thomas Risberg 035 * @author Juergen Hoeller 036 * @since 2.0 037 * @see NamedParameterJdbcOperations 038 * @see NamedParameterJdbcTemplate 039 * @see MapSqlParameterSource 040 * @see BeanPropertySqlParameterSource 041 */ 042public interface SqlParameterSource { 043 044 /** 045 * Constant that indicates an unknown (or unspecified) SQL type. 046 * To be returned from {@code getType} when no specific SQL type known. 047 * @see #getSqlType 048 * @see java.sql.Types 049 */ 050 int TYPE_UNKNOWN = JdbcUtils.TYPE_UNKNOWN; 051 052 053 /** 054 * Determine whether there is a value for the specified named parameter. 055 * @param paramName the name of the parameter 056 * @return whether there is a value defined 057 */ 058 boolean hasValue(String paramName); 059 060 /** 061 * Return the parameter value for the requested named parameter. 062 * @param paramName the name of the parameter 063 * @return the value of the specified parameter 064 * @throws IllegalArgumentException if there is no value for the requested parameter 065 */ 066 @Nullable 067 Object getValue(String paramName) throws IllegalArgumentException; 068 069 /** 070 * Determine the SQL type for the specified named parameter. 071 * @param paramName the name of the parameter 072 * @return the SQL type of the specified parameter, 073 * or {@code TYPE_UNKNOWN} if not known 074 * @see #TYPE_UNKNOWN 075 */ 076 default int getSqlType(String paramName) { 077 return TYPE_UNKNOWN; 078 } 079 080 /** 081 * Determine the type name for the specified named parameter. 082 * @param paramName the name of the parameter 083 * @return the type name of the specified parameter, 084 * or {@code null} if not known 085 */ 086 @Nullable 087 default String getTypeName(String paramName) { 088 return null; 089 } 090 091 /** 092 * Enumerate all available parameter names if possible. 093 * <p>This is an optional operation, primarily for use with 094 * {@link org.springframework.jdbc.core.simple.SimpleJdbcInsert} 095 * and {@link org.springframework.jdbc.core.simple.SimpleJdbcCall}. 096 * @return the array of parameter names, or {@code null} if not determinable 097 * @since 5.0.3 098 * @see SqlParameterSourceUtils#extractCaseInsensitiveParameterNames 099 */ 100 @Nullable 101 default String[] getParameterNames() { 102 return null; 103 } 104 105}