include/connectivity/dbmetadata.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_CONNECTIVITY_DBMETADATA_HXX
  21 #define INCLUDED_CONNECTIVITY_DBMETADATA_HXX
  22
  23 #include <com/sun/star/uno/Reference.hxx>
  24
  25 #include <memory>
  26 #include <connectivity/dbtoolsdllapi.hxx>
  27
  28 namespace com::sun::star::sdbc { class XConnection; }
  29 namespace com::sun::star::uno { class XComponentContext; }
  30
  31 namespace dbtools
  32 {
  33
  34
  35     //= DatabaseMetaData
  36
  37     struct DatabaseMetaData_Impl;
  38     /** encapsulates meta data about a database/connection which cannot be obtained
  39         from the usual XDatabaseMetaData result set.
  40
  41         Meta data perhaps isn't really the right term ... Some of the methods
  42         in this class involved heuristics, some are just a convenient wrapper
  43         around more complex ways to obtain the same information.
  44
  45         @todo
  46             Once CWS dba30 is integrated, we could easily add all the meta data
  47             which is part of the "Info" property of a data source.
  48     */
  49     class OOO_DLLPUBLIC_DBTOOLS DatabaseMetaData
  50     {
  51     private:
  52         ::std::unique_ptr< DatabaseMetaData_Impl >    m_pImpl;
  53
  54     public:
  55         DatabaseMetaData();
  56         /** constructs a DatabaseMetaData instance
  57             @param  _rxConnection
  58                 is the connection whose meta data you're interested in.
  59                 Note that some of the information provided by this class can only be obtained
  60                 if this connection denotes an application-level connection, i.e. supports
  61                 the com.sun.star.sdb.Connection service.
  62
  63             @throws css::lang::IllegalArgumentException
  64                 if the given connection is not <NULL/>, but the XDatabaseMetaData provided by it
  65                 are <NULL/>
  66             @throws css::sdbc::SQLException
  67                 if obtaining the meta data from the connection throws an SQLException
  68             @throws css::uno::RuntimeException
  69                 if obtaining the meta data from the connection throws a RuntimeException
  70         */
  71         DatabaseMetaData(
  72             const css::uno::Reference< css::sdbc::XConnection >& _connection );
  73         DatabaseMetaData( const DatabaseMetaData& _copyFrom );
  74         DatabaseMetaData& operator=( const DatabaseMetaData& _copyFrom );
  75         DatabaseMetaData(DatabaseMetaData&& _copyFrom) noexcept;
  76         DatabaseMetaData& operator=(DatabaseMetaData&& _copyFrom) noexcept;
  77
  78         ~DatabaseMetaData();
  79
  80     public:
  81         /** determines whether or not the instances is based on a valid connection
  82
  83             As long as this method returns true<TRUE/>, you should expect all other
  84             methods throwing an SQLException when called.
  85         */
  86         bool    isConnected() const;
  87
  88         /** resets the instance so that it's based on a new connection
  89         */
  90         void    reset( const css::uno::Reference< css::sdbc::XConnection >& _connection )
  91         {
  92             *this = DatabaseMetaData( _connection );
  93         }
  94
  95         /// wraps XDatabaseMetaData::getIdentifierQuoteString
  96         const OUString&  getIdentifierQuoteString() const;
  97
  98         /// wraps XDatabaseMetaData::getCatalogSeparator
  99         const OUString&  getCatalogSeparator() const;
 100
 101         /** determines whether the database supports sub queries in the FROM part
 102             of a SELECT clause are supported.
 103             @throws css::sdbc::SQLException
 104                 with SQLState 08003 (connection does not exist) if the instances was
 105                 default-constructed and does not have a connection, yet.
 106         */
 107         bool supportsSubqueriesInFrom() const;
 108
 109         /** checks whether the database supports primary keys
 110
 111             Since there's no dedicated API to ask a database for this, a heuristics needs to be applied.
 112             First, the <code>PrimaryKeySupport<code> settings of the data source is examined. If it is <TRUE/>
 113             or <FALSE/>, then value is returned. If it is <NULL/>, then the database meta data are examined
 114             for support of core SQL grammar, and the result is returned. The assumption is that a database/driver
 115             which supports core SQL grammar usually also supports primary keys, and vice versa. At least, experience
 116             shows this is true most of the time.
 117         */
 118         bool supportsPrimaryKeys() const;
 119
 120         /** determines whether names in the database should be restricted to SQL-92 identifiers
 121
 122             Effectively, this method checks the EnableSQL92Check property of the data source settings,
 123             if present.
 124         */
 125         bool restrictIdentifiersToSQL92() const;
 126
 127         /** determines whether when generating SQL statements, an AS keyword should be generated
 128             before a correlation name.
 129
 130             E.g., it determines whether <code>SELECT * FROM table AS correlation_name</code> or
 131             <code>SELECT * FROM table correlation_name</code> is generated.
 132         */
 133         bool generateASBeforeCorrelationName() const;
 134
 135         /** should date time be escaped like '2001-01-01' => {D '2001-01-01' }
 136         */
 137         bool shouldEscapeDateTime() const;
 138
 139         /** should named parameters (:foo, [foo]) be replaced by unnamed parameters (?)
 140         */
 141         bool shouldSubstituteParameterNames() const;
 142
 143         /** auto increment columns should be automatically used as primary key.
 144         */
 145         bool isAutoIncrementPrimaryKey() const;
 146
 147         /** determines the syntax to use for boolean comparison predicates
 148
 149             @see css::sdb::BooleanComparisonMode
 150         */
 151         sal_Int32
 152             getBooleanComparisonMode() const;
 153
 154         /** determines in relations are supported.
 155         *
 156         * \return <TRUE/> when relations are supported, otherwise <FALSE/>
 157         */
 158         bool supportsRelations() const;
 159
 160         /** determines if column alias names can be used in the order by clause.
 161         *
 162         * \return <TRUE/> when relations are supported, otherwise <FALSE/>
 163         */
 164         bool supportsColumnAliasInOrderBy() const;
 165
 166         /** determines whether user administration is supported for the database
 167
 168             User administration support is controlled by the availability of the XUsersSupplier
 169             interface, and it returning a non-NULL users container.
 170
 171             @param _rContext
 172                 the component context we operate in. Might be needed to create the
 173                 css.sdbc.DriverManager instance.
 174         */
 175         bool    supportsUserAdministration( const css::uno::Reference<css::uno::XComponentContext>& _rContext ) const;
 176
 177         /** determines whether in the application UI, empty table folders (aka catalogs/schemas) should be displayed
 178         */
 179         bool displayEmptyTableFolders() const;
 180
 181         /** determines that threads are supported.
 182         *
 183         * \return <TRUE/> when threads are supported, otherwise <FALSE/>
 184         */
 185         bool supportsThreads() const;
 186     };
 187
 188
 189 } // namespace dbtools
 190
 191
 192 #endif // INCLUDED_CONNECTIVITY_DBMETADATA_HXX
 193
 194 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */