001/*
002 * Copyright 2002-2018 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.metadata;
018
019import java.sql.DatabaseMetaData;
020import java.sql.SQLException;
021import java.util.List;
022
023import org.springframework.jdbc.core.SqlParameter;
024import org.springframework.lang.Nullable;
025
026/**
027 * Interface specifying the API to be implemented by a class providing call meta-data.
028 *
029 * <p>This is intended for internal use by Spring's
030 * {@link org.springframework.jdbc.core.simple.SimpleJdbcCall}.
031 *
032 * @author Thomas Risberg
033 * @since 2.5
034 */
035public interface CallMetaDataProvider {
036
037        /**
038         * Initialize using the provided DatabaseMetData.
039         * @param databaseMetaData used to retrieve database specific information
040         * @throws SQLException in case of initialization failure
041         */
042        void initializeWithMetaData(DatabaseMetaData databaseMetaData) throws SQLException;
043
044        /**
045         * Initialize the database specific management of procedure column meta-data.
046         * This is only called for databases that are supported. This initialization
047         * can be turned off by specifying that column meta-data should not be used.
048         * @param databaseMetaData used to retrieve database specific information
049         * @param catalogName name of catalog to use (or {@code null} if none)
050         * @param schemaName name of schema name to use (or {@code null} if none)
051         * @param procedureName name of the stored procedure
052         * @throws SQLException in case of initialization failure
053         * @see org.springframework.jdbc.core.simple.SimpleJdbcCall#withoutProcedureColumnMetaDataAccess()
054         */
055        void initializeWithProcedureColumnMetaData(DatabaseMetaData databaseMetaData, @Nullable String catalogName,
056                        @Nullable String schemaName, @Nullable String procedureName) throws SQLException;
057
058        /**
059         * Provide any modification of the procedure name passed in to match the meta-data currently used.
060         * This could include altering the case.
061         */
062        @Nullable
063        String procedureNameToUse(@Nullable String procedureName);
064
065        /**
066         * Provide any modification of the catalog name passed in to match the meta-data currently used.
067         * This could include altering the case.
068         */
069        @Nullable
070        String catalogNameToUse(@Nullable String catalogName);
071
072        /**
073         * Provide any modification of the schema name passed in to match the meta-data currently used.
074         * This could include altering the case.
075         */
076        @Nullable
077        String schemaNameToUse(@Nullable String schemaName);
078
079        /**
080         * Provide any modification of the catalog name passed in to match the meta-data currently used.
081         * The returned value will be used for meta-data lookups. This could include altering the case
082         * used or providing a base catalog if none is provided.
083         */
084        @Nullable
085        String metaDataCatalogNameToUse(@Nullable String catalogName) ;
086
087        /**
088         * Provide any modification of the schema name passed in to match the meta-data currently used.
089         * The returned value will be used for meta-data lookups. This could include altering the case
090         * used or providing a base schema if none is provided.
091         */
092        @Nullable
093        String metaDataSchemaNameToUse(@Nullable String schemaName);
094
095        /**
096         * Provide any modification of the column name passed in to match the meta-data currently used.
097         * This could include altering the case.
098         * @param parameterName name of the parameter of column
099         */
100        @Nullable
101        String parameterNameToUse(@Nullable String parameterName);
102
103        /**
104         * Create a default out parameter based on the provided meta-data.
105         * This is used when no explicit parameter declaration has been made.
106         * @param parameterName the name of the parameter
107         * @param meta meta-data used for this call
108         * @return the configured SqlOutParameter
109         */
110        SqlParameter createDefaultOutParameter(String parameterName, CallParameterMetaData meta);
111
112        /**
113         * Create a default in/out parameter based on the provided meta-data.
114         * This is used when no explicit parameter declaration has been made.
115         * @param parameterName the name of the parameter
116         * @param meta meta-data used for this call
117         * @return the configured SqlInOutParameter
118         */
119        SqlParameter createDefaultInOutParameter(String parameterName, CallParameterMetaData meta);
120
121        /**
122         * Create a default in parameter based on the provided meta-data.
123         * This is used when no explicit parameter declaration has been made.
124         * @param parameterName the name of the parameter
125         * @param meta meta-data used for this call
126         * @return the configured SqlParameter
127         */
128        SqlParameter createDefaultInParameter(String parameterName, CallParameterMetaData meta);
129
130        /**
131         * Get the name of the current user. Useful for meta-data lookups etc.
132         * @return current user name from database connection
133         */
134        @Nullable
135        String getUserName();
136
137        /**
138         * Does this database support returning ResultSets that should be retrieved with the JDBC call:
139         * {@link java.sql.Statement#getResultSet()}?
140         */
141        boolean isReturnResultSetSupported();
142
143        /**
144         * Does this database support returning ResultSets as ref cursors to be retrieved with
145         * {@link java.sql.CallableStatement#getObject(int)} for the specified column.
146         */
147        boolean isRefCursorSupported();
148
149        /**
150         * Get the {@link java.sql.Types} type for columns that return ResultSets as ref cursors
151         * if this feature is supported.
152         */
153        int getRefCursorSqlType();
154
155        /**
156         * Are we using the meta-data for the procedure columns?
157         */
158        boolean isProcedureColumnMetaDataUsed();
159
160        /**
161         * Should we bypass the return parameter with the specified name.
162         * This allows the database specific implementation to skip the processing
163         * for specific results returned by the database call.
164         */
165        boolean byPassReturnParameter(String parameterName);
166
167        /**
168         * Get the call parameter meta-data that is currently used.
169         * @return a List of {@link CallParameterMetaData}
170         */
171        List<CallParameterMetaData> getCallParameterMetaData();
172
173        /**
174         * Does the database support the use of catalog name in procedure calls?
175         */
176        boolean isSupportsCatalogsInProcedureCalls();
177
178        /**
179         * Does the database support the use of schema name in procedure calls?
180         */
181        boolean isSupportsSchemasInProcedureCalls();
182
183}