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