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}