/*

 * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.sql;

/**

 * Comprehensive information about the database as a whole.

 * <P>

 * This interface is implemented by driver vendors to let users know the capabilities

 * of a Database Management System (DBMS) in combination with

 * the driver based on JDBC™ technology

 * ("JDBC driver") that is used with it.  Different relational DBMSs often support

 * different features, implement features in different ways, and use different

 * data types.  In addition, a driver may implement a feature on top of what the

 * DBMS offers.  Information returned by methods in this interface applies

 * to the capabilities of a particular driver and a particular DBMS working

 * together. Note that as used in this documentation, the term "database" is

 * used generically to refer to both the driver and DBMS.

 * <P>

 * A user for this interface is commonly a tool that needs to discover how to

 * deal with the underlying DBMS.  This is especially true for applications

 * that are intended to be used with more than one DBMS. For example, a tool might use the method

 * <code>getTypeInfo</code> to find out what data types can be used in a

 * <code>CREATE TABLE</code> statement.  Or a user might call the method

 * <code>supportsCorrelatedSubqueries</code> to see if it is possible to use

 * a correlated subquery or <code>supportsBatchUpdates</code> to see if it is

 * possible to use batch updates.

 * <P>

 * Some <code>DatabaseMetaData</code> methods return lists of information

 * in the form of <code>ResultSet</code> objects.

 * Regular <code>ResultSet</code> methods, such as

 * <code>getString</code> and <code>getInt</code>, can be used

 * to retrieve the data from these <code>ResultSet</code> objects.  If

 * a given form of metadata is not available, an empty <code>ResultSet</code>

 * will be returned. Additional columns beyond the columns defined to be

 * returned by the <code>ResultSet</code> object for a given method

 * can be defined by the JDBC driver vendor and must be accessed

 * by their <B>column label</B>.

 * <P>

 * Some <code>DatabaseMetaData</code> methods take arguments that are

 * String patterns.  These arguments all have names such as fooPattern.

 * Within a pattern String, "%" means match any substring of 0 or more

 * characters, and "_" means match any one character. Only metadata

 * entries matching the search pattern are returned. If a search pattern

 * argument is set to <code>null</code>, that argument's criterion will

 * be dropped from the search.

 *

 */

public interface DatabaseMetaData extends Wrapper {

    //----------------------------------------------------------------------

    // First, a variety of minor information about the target database.

    /**

     * Retrieves whether the current user can call all the procedures

     * returned by the method <code>getProcedures</code>.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean allProceduresAreCallable() throws SQLException;

    /**

     * Retrieves whether the current user can use all the tables returned

     * by the method <code>getTables</code> in a <code>SELECT</code>

     * statement.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean allTablesAreSelectable() throws SQLException;

    /**

     * Retrieves the URL for this DBMS.

     *

     * @return the URL for this DBMS or <code>null</code> if it cannot be

     *          generated

     * @exception SQLException if a database access error occurs

     */

    String getURL() throws SQLException;

    /**

     * Retrieves the user name as known to this database.

     *

     * @return the database user name

     * @exception SQLException if a database access error occurs

     */

    String getUserName() throws SQLException;

    /**

     * Retrieves whether this database is in read-only mode.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean isReadOnly() throws SQLException;

    /**

     * Retrieves whether <code>NULL</code> values are sorted high.

     * Sorted high means that <code>NULL</code> values

     * sort higher than any other value in a domain.  In an ascending order,

     * if this method returns <code>true</code>,  <code>NULL</code> values

     * will appear at the end. By contrast, the method

     * <code>nullsAreSortedAtEnd</code> indicates whether <code>NULL</code> values

     * are sorted at the end regardless of sort order.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean nullsAreSortedHigh() throws SQLException;

    /**

     * Retrieves whether <code>NULL</code> values are sorted low.

     * Sorted low means that <code>NULL</code> values

     * sort lower than any other value in a domain.  In an ascending order,

     * if this method returns <code>true</code>,  <code>NULL</code> values

     * will appear at the beginning. By contrast, the method

     * <code>nullsAreSortedAtStart</code> indicates whether <code>NULL</code> values

     * are sorted at the beginning regardless of sort order.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean nullsAreSortedLow() throws SQLException;

    /**

     * Retrieves whether <code>NULL</code> values are sorted at the start regardless

     * of sort order.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean nullsAreSortedAtStart() throws SQLException;

    /**

     * Retrieves whether <code>NULL</code> values are sorted at the end regardless of

     * sort order.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean nullsAreSortedAtEnd() throws SQLException;

    /**

     * Retrieves the name of this database product.

     *

     * @return database product name

     * @exception SQLException if a database access error occurs

     */

    String getDatabaseProductName() throws SQLException;

    /**

     * Retrieves the version number of this database product.

     *

     * @return database version number

     * @exception SQLException if a database access error occurs

     */

    String getDatabaseProductVersion() throws SQLException;

    /**

     * Retrieves the name of this JDBC driver.

     *

     * @return JDBC driver name

     * @exception SQLException if a database access error occurs

     */

    String getDriverName() throws SQLException;

    /**

     * Retrieves the version number of this JDBC driver as a <code>String</code>.

     *

     * @return JDBC driver version

     * @exception SQLException if a database access error occurs

     */

    String getDriverVersion() throws SQLException;

    /**

     * Retrieves this JDBC driver's major version number.

     *

     * @return JDBC driver major version

     */

    int getDriverMajorVersion();

    /**

     * Retrieves this JDBC driver's minor version number.

     *

     * @return JDBC driver minor version number

     */

    int getDriverMinorVersion();

    /**

     * Retrieves whether this database stores tables in a local file.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean usesLocalFiles() throws SQLException;

    /**

     * Retrieves whether this database uses a file for each table.

     *

     * @return <code>true</code> if this database uses a local file for each table;

     *         <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean usesLocalFilePerTable() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case unquoted SQL identifiers as

     * case sensitive and as a result stores them in mixed case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsMixedCaseIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case unquoted SQL identifiers as

     * case insensitive and stores them in upper case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesUpperCaseIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case unquoted SQL identifiers as

     * case insensitive and stores them in lower case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesLowerCaseIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case unquoted SQL identifiers as

     * case insensitive and stores them in mixed case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesMixedCaseIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case quoted SQL identifiers as

     * case sensitive and as a result stores them in mixed case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsMixedCaseQuotedIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case quoted SQL identifiers as

     * case insensitive and stores them in upper case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesUpperCaseQuotedIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case quoted SQL identifiers as

     * case insensitive and stores them in lower case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesLowerCaseQuotedIdentifiers() throws SQLException;

    /**

     * Retrieves whether this database treats mixed case quoted SQL identifiers as

     * case insensitive and stores them in mixed case.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean storesMixedCaseQuotedIdentifiers() throws SQLException;

    /**

     * Retrieves the string used to quote SQL identifiers.

     * This method returns a space " " if identifier quoting is not supported.

     *

     * @return the quoting string or a space if quoting is not supported

     * @exception SQLException if a database access error occurs

     */

    String getIdentifierQuoteString() throws SQLException;

    /**

     * Retrieves a comma-separated list of all of this database's SQL keywords

     * that are NOT also SQL:2003 keywords.

     *

     * @return the list of this database's keywords that are not also

     *         SQL:2003 keywords

     * @exception SQLException if a database access error occurs

     */

    String getSQLKeywords() throws SQLException;

    /**

     * Retrieves a comma-separated list of math functions available with

     * this database.  These are the Open /Open CLI math function names used in

     * the JDBC function escape clause.

     *

     * @return the list of math functions supported by this database

     * @exception SQLException if a database access error occurs

     */

    String getNumericFunctions() throws SQLException;

    /**

     * Retrieves a comma-separated list of string functions available with

     * this database.  These are the  Open Group CLI string function names used

     * in the JDBC function escape clause.

     *

     * @return the list of string functions supported by this database

     * @exception SQLException if a database access error occurs

     */

    String getStringFunctions() throws SQLException;

    /**

     * Retrieves a comma-separated list of system functions available with

     * this database.  These are the  Open Group CLI system function names used

     * in the JDBC function escape clause.

     *

     * @return a list of system functions supported by this database

     * @exception SQLException if a database access error occurs

     */

    String getSystemFunctions() throws SQLException;

    /**

     * Retrieves a comma-separated list of the time and date functions available

     * with this database.

     *

     * @return the list of time and date functions supported by this database

     * @exception SQLException if a database access error occurs

     */

    String getTimeDateFunctions() throws SQLException;

    /**

     * Retrieves the string that can be used to escape wildcard characters.

     * This is the string that can be used to escape '_' or '%' in

     * the catalog search parameters that are a pattern (and therefore use one

     * of the wildcard characters).

     *

     * <P>The '_' character represents any single character;

     * the '%' character represents any sequence of zero or

     * more characters.

     *

     * @return the string used to escape wildcard characters

     * @exception SQLException if a database access error occurs

     */

    String getSearchStringEscape() throws SQLException;

    /**

     * Retrieves all the "extra" characters that can be used in unquoted

     * identifier names (those beyond a-z, A-Z, 0-9 and _).

     *

     * @return the string containing the extra characters

     * @exception SQLException if a database access error occurs

     */

    String getExtraNameCharacters() throws SQLException;

    //--------------------------------------------------------------------

    // Functions describing which features are supported.

    /**

     * Retrieves whether this database supports <code>ALTER TABLE</code>

     * with add column.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsAlterTableWithAddColumn() throws SQLException;

    /**

     * Retrieves whether this database supports <code>ALTER TABLE</code>

     * with drop column.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsAlterTableWithDropColumn() throws SQLException;

    /**

     * Retrieves whether this database supports column aliasing.

     *

     * <P>If so, the SQL AS clause can be used to provide names for

     * computed columns or to provide alias names for columns as

     * required.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsColumnAliasing() throws SQLException;

    /**

     * Retrieves whether this database supports concatenations between

     * <code>NULL</code> and non-<code>NULL</code> values being

     * <code>NULL</code>.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean nullPlusNonNullIsNull() throws SQLException;

    /**

     * Retrieves whether this database supports the JDBC scalar function

     * <code>CONVERT</code> for the conversion of one JDBC type to another.

     * The JDBC types are the generic SQL data types defined

     * in <code>java.sql.Types</code>.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsConvert() throws SQLException;

    /**

     * Retrieves whether this database supports the JDBC scalar function

     * <code>CONVERT</code> for conversions between the JDBC types <i>fromType</i>

     * and <i>toType</i>.  The JDBC types are the generic SQL data types defined

     * in <code>java.sql.Types</code>.

     *

     * @param fromType the type to convert from; one of the type codes from

     *        the class <code>java.sql.Types</code>

     * @param toType the type to convert to; one of the type codes from

     *        the class <code>java.sql.Types</code>

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     * @see Types

     */

    boolean supportsConvert(int fromType, int toType) throws SQLException;

    /**

     * Retrieves whether this database supports table correlation names.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsTableCorrelationNames() throws SQLException;

    /**

     * Retrieves whether, when table correlation names are supported, they

     * are restricted to being different from the names of the tables.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsDifferentTableCorrelationNames() throws SQLException;

    /**

     * Retrieves whether this database supports expressions in

     * <code>ORDER BY</code> lists.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsExpressionsInOrderBy() throws SQLException;

    /**

     * Retrieves whether this database supports using a column that is

     * not in the <code>SELECT</code> statement in an

     * <code>ORDER BY</code> clause.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsOrderByUnrelated() throws SQLException;

    /**

     * Retrieves whether this database supports some form of

     * <code>GROUP BY</code> clause.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsGroupBy() throws SQLException;

    /**

     * Retrieves whether this database supports using a column that is

     * not in the <code>SELECT</code> statement in a

     * <code>GROUP BY</code> clause.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsGroupByUnrelated() throws SQLException;

    /**

     * Retrieves whether this database supports using columns not included in

     * the <code>SELECT</code> statement in a <code>GROUP BY</code> clause

     * provided that all of the columns in the <code>SELECT</code> statement

     * are included in the <code>GROUP BY</code> clause.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsGroupByBeyondSelect() throws SQLException;

    /**

     * Retrieves whether this database supports specifying a

     * <code>LIKE</code> escape clause.

     *

     * @return <code>true</code> if so; <code>false</code> otherwise

     * @exception SQLException if a database access error occurs

     */

    boolean supportsLikeEscapeClause() throws SQLException;