include/connectivity/dbtools.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_DBTOOLS_HXX
  21 #define INCLUDED_CONNECTIVITY_DBTOOLS_HXX
  22
  23 #include <connectivity/dbexception.hxx>
  24 #include <comphelper/types.hxx>
  25 #include <com/sun/star/sdbc/DataType.hpp>
  26 #include <comphelper/stl_types.hxx>
  27 #include <unotools/sharedunocomponent.hxx>
  28 #include <connectivity/dbtoolsdllapi.hxx>
  29 #include <connectivity/FValue.hxx>
  30
  31 namespace com { namespace sun { namespace star {
  32
  33 namespace sdb {
  34     class XSingleSelectQueryComposer;
  35     class SQLContext;
  36 }
  37 namespace sdbcx {
  38     class XTablesSupplier;
  39 }
  40 namespace sdbc {
  41     class XConnection;
  42     class XDatabaseMetaData;
  43     class XRowSet;
  44     class XDataSource;
  45     class SQLException;
  46     class XParameters;
  47     class XRowUpdate;
  48 }
  49 namespace beans {
  50     class XPropertySet;
  51 }
  52 namespace awt {
  53     class XWindow;
  54 }
  55 namespace lang {
  56     struct Locale;
  57     class XMultiServiceFactory;
  58     class WrappedTargetException;
  59 }
  60 namespace container {
  61     class XNameAccess;
  62 }
  63 namespace uno {
  64     class XComponentContext;
  65 }
  66 namespace util {
  67     class XNumberFormatTypes;
  68     class XNumberFormatsSupplier;
  69 }
  70 namespace task {
  71     class XInteractionHandler;
  72 }
  73
  74 } } }
  75
  76
  77 //.........................................................................
  78 namespace dbtools
  79 {
  80     class ISQLStatementHelper;
  81     typedef ::utl::SharedUNOComponent< ::com::sun::star::sdbc::XConnection > SharedConnection;
  82
  83     enum EComposeRule
  84     {
  85         eInTableDefinitions,
  86         eInIndexDefinitions,
  87         eInDataManipulation,
  88         eInProcedureCalls,
  89         eInPrivilegeDefinitions,
  90         eComplete
  91     };
  92 //=========================================================================
  93     // date conversion
  94
  95     // calculates the default numberformat for a given datatype and a give language
  96     OOO_DLLPUBLIC_DBTOOLS
  97     sal_Int32 getDefaultNumberFormat(const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _xColumn,
  98                                      const ::com::sun::star::uno::Reference< ::com::sun::star::util::XNumberFormatTypes >& _xTypes,
  99                                      const ::com::sun::star::lang::Locale& _rLocale);
 100
 101     // calculates the default numberformat for a given datatype and a give language
 102     // @param  _nDataType @see com.sun.star.sdbc.DataType
 103     // @param _nScale       can be zero
 104     OOO_DLLPUBLIC_DBTOOLS
 105     sal_Int32 getDefaultNumberFormat(sal_Int32 _nDataType,
 106                                      sal_Int32 _nScale,
 107                                      sal_Bool _bIsCurrency,
 108                                      const ::com::sun::star::uno::Reference< ::com::sun::star::util::XNumberFormatTypes >& _xTypes,
 109                                      const ::com::sun::star::lang::Locale& _rLocale);
 110
 111 //=========================================================================
 112
 113     /** creates a connection which can be used for the rowset given
 114
 115         The function tries to obtain a connection for the row set with the following
 116         steps (in this order):
 117         <nl>
 118             <li>If the rowset already has an ActiveConnection (means a non-<NULL/> value vor this property),
 119                 this one is used.</li>
 120             <li>If row set is part of a database form document (see ->isEmbeddedInDatabase),
 121                 a connection for the respective database is used.</li>
 122             <li>If in the parent hierarchy of the row set, there is an object supporting
 123                 the XConnection interface, this one is returned.</li>
 124             <li>If the DataSourceName property of the row set is not empty, a connection for this
 125                 data source is retrieved.</li>
 126             <li>If the URL property of the row set is not empty, an connection for this URL is
 127                 retrieved from the driver manager.
 128         </nl>
 129
 130         @param _rxRowSet
 131             the row set
 132
 133         @param _rxFactory
 134             a service factory, which can be used to create data sources, interaction handler etc (the usual stuff)
 135
 136         @param _bSetAsActiveConnection
 137             If <TRUE/>, the calculated connection is set as ActiveConnection property on the rowset.
 138
 139             If the connection was newly created by the method, and this parameter is <TRUE/>, then
 140             the ownership of the connection is delivered to a temporary object, which observes the
 141             row set: As soon as a connection-relevant property of the row set changes, or as soon
 142             as somebody else sets another ActiveConnection at the row set, the original
 143             connection (the one which this function calculated) is disposed and discarded. At this
 144             very moment, also the temporary observer object dies. This way, it is ensured that
 145             there's no resource leak from an un-owned connection object.
 146     */
 147     OOO_DLLPUBLIC_DBTOOLS
 148     ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection> connectRowset(
 149         const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet>& _rxRowSet,
 150         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext,
 151         sal_Bool _bSetAsActiveConnection
 152     )   SAL_THROW ( ( ::com::sun::star::sdbc::SQLException
 153                     , ::com::sun::star::lang::WrappedTargetException
 154                     , ::com::sun::star::uno::RuntimeException ) );
 155
 156     /** ensures that a row set has a valid ActiveConnection, if possible
 157
 158         This function does nearly the same as ->connectRowset. In fact, it is to be preferred over
 159         ->connectRowset, if possible.
 160
 161         There are a few differences:
 162         <ul><li>If a connection could be determined for the given RowSet, it is always
 163                 set as ActiveConnection.</li>
 164             <li>Definition of the ownership of the created connection allows for more scenarios:
 165                 <ul><li>If the connection was not newly created, the returned ->SharedConnection
 166                         instance will not have the ownership, since in this case it's assumed
 167                         that there already is an instance which has the ownership.</li>
 168                     <li>If the connection was newly created, and ->_bUseAutoConnectionDisposer
 169                         is <TRUE/>, then the returned SharedConnection instance will <em>not</em>
 170                         be the owner of the connection. Instead, the ownership will be delivered
 171                         to a temporary object as described for connectRowset.</li>
 172                     <li>If the connection was newly created, and ->_bUseAutoConnectionDisposer
 173                         is <FALSE/>, then the returned SharedConnection instance will have the
 174                         ownership of the XConnection.</li>
 175                 </ul>
 176             </li>
 177         </ul>
 178     */
 179     OOO_DLLPUBLIC_DBTOOLS SharedConnection    ensureRowSetConnection(
 180         const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet>& _rxRowSet,
 181         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext,
 182         bool _bUseAutoConnectionDisposer
 183     )   SAL_THROW ( ( ::com::sun::star::sdbc::SQLException
 184                     , ::com::sun::star::lang::WrappedTargetException
 185                     , ::com::sun::star::uno::RuntimeException ) );
 186
 187     /** returns the connection the RowSet is currently working with (which is the ActiveConnection property)
 188     */
 189     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection> getConnection(const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet>& _rxRowSet) throw (::com::sun::star::uno::RuntimeException);
 190     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection> getConnection_withFeedback(
 191             const OUString& _rDataSourceName,
 192             const OUString& _rUser,
 193             const OUString& _rPwd,
 194             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext)
 195         SAL_THROW ( (::com::sun::star::sdbc::SQLException) );
 196
 197
 198     /** determines whether the given component is part of a document which is an embedded database
 199         document (such as a form)
 200     */
 201     OOO_DLLPUBLIC_DBTOOLS bool    isEmbeddedInDatabase(
 202                 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
 203                 ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxActualConnection
 204             );
 205
 206     /** returns the columns of the named table of the given connection
 207     */
 208     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess> getTableFields(
 209         const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _rxConn,
 210         const OUString& _rName
 211     );
 212
 213     /** returns the primary key columns of the table
 214     */
 215     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess> getPrimaryKeyColumns_throw(
 216         const ::com::sun::star::uno::Any& i_aTable
 217     );
 218     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess> getPrimaryKeyColumns_throw(
 219         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& i_xTable
 220     );
 221
 222     /** get fields for a result set given by a "command descriptor"
 223
 224         <p>A command descriptor here means:
 225         <ul><li>a SDB-level connection (com.sun.star.sdb::Connection</li>
 226             <li>a string specifying the name of an object relative to the connection</li>
 227             <li>a com.sun.star.sdb::CommandType value specifying the type
 228                 of the object</type></li>
 229         </ul>
 230         </p>
 231
 232         @param _rxConnection
 233             the connection relative to which the to-be-examined object exists
 234
 235         @param _nCommandType
 236             the type of the object
 237
 238         @param _rCommand
 239             the object. This may be a table name, a query name, or an SQL statement, depending on the value
 240             of <arg>_nCommandType</arg>
 241
 242         @param _rxCollectionOner
 243             If (and only if) <arg>CommandType</arg> is CommandType.COMMAND, the fields collection which is returned
 244             by this function here is a temporary object. It is kept alive by another object, which is to be
 245             created temporarily, too. To ensure that the fields you get are valid as long as you need them,
 246             the owner which controls their life time is transfered to this parameter upon return.<br/>
 247
 248             Your fields live as long as this component lives.<br/>
 249
 250             Additionally, you are encouraged to dispose this component as soon as you don't need the fields anymore.
 251             It depends on the connection's implementation if this is necessary, but the is no guarantee, so to
 252             be on the safe side with respect to resource leaks, you should dispose the component.
 253
 254         @param _pErrorInfo
 255             If not <NULL/>, then upon return from the function the instance pointed to by this argument will
 256             contain any available error information in case something went wrong.
 257
 258         @return
 259             the container of the columns (aka fields) of the object
 260     */
 261     OOO_DLLPUBLIC_DBTOOLS
 262     ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
 263         getFieldsByCommandDescriptor(
 264             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection,
 265             const sal_Int32 _nCommandType,
 266             const OUString& _rCommand,
 267             ::com::sun::star::uno::Reference< ::com::sun::star::lang::XComponent >& _rxKeepFieldsAlive,
 268             SQLExceptionInfo* _pErrorInfo = NULL
 269         )   SAL_THROW( ( ) );
 270
 271
 272     /** get fields for a result set given by a "command descriptor"
 273
 274         <p>A command descriptor here means:
 275         <ul><li>a SDB-level connection (com.sun.star.sdb::Connection</li>
 276             <li>a string specifying the name of an object relative to the connection</li>
 277             <li>a com.sun.star.sdb::CommandType value specifying the type
 278                 of the object</type></li>
 279         </ul>
 280         </p>
 281
 282         @param _rxConnection
 283             the connection relative to which the to-be-examined object exists
 284
 285         @param _nCommandType
 286             the type of the object
 287
 288         @param _rCommand
 289             the object. This may be a table name, a query name, or an SQL statement, depending on the value
 290             of <arg>_nCommandType</arg>
 291
 292         @param _pErrorInfo
 293             If not <NULL/>, then upon return from the function the instance pointed to by this argument will
 294             contain any available error information in case something went wrong.
 295
 296         @return
 297             an array of strings containing the names of the columns (aka fields) of the object
 298     */
 299     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Sequence< OUString >
 300         getFieldNamesByCommandDescriptor(
 301             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection,
 302             const sal_Int32 _nCommandType,
 303             const OUString& _rCommand,
 304             SQLExceptionInfo* _pErrorInfo = NULL
 305         )   SAL_THROW( ( ) );
 306
 307
 308     /** create a new ::com::sun::star::sdbc::SQLContext, fill it with the given descriptions and the given source,
 309         and <i>append</i> _rException (i.e. put it into the NextException member of the SQLContext).
 310     */
 311     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::sdb::SQLContext prependContextInfo(const ::com::sun::star::sdbc::SQLException& _rException, const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, const OUString& _rContextDescription, const OUString& _rContextDetails );
 312
 313     OOO_DLLPUBLIC_DBTOOLS
 314     ::com::sun::star::sdbc::SQLException prependErrorInfo(
 315         const ::com::sun::star::sdbc::SQLException& _rChainedException,
 316         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 317         const OUString& _rAdditionalError,
 318         const StandardSQLState _eSQLState = SQL_ERROR_UNSPECIFIED,
 319         const sal_Int32 _nErrorCode = 0);
 320
 321     /** search the parent hierachy for a data source.
 322     */
 323     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDataSource> findDataSource(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _xParent);
 324
 325     /** determines the value of a booolean data source setting, given by ASCII name
 326
 327         @param _rxConnection
 328             the connection belonging to the data source whose setting is to be retrieved
 329         @param _pAsciiSettingName
 330             the ASCII name of the setting
 331     */
 332     OOO_DLLPUBLIC_DBTOOLS bool getBooleanDataSourceSetting(
 333             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection,
 334             const sal_Char* _pAsciiSettingName
 335         );
 336
 337     /** check if a specific property is enabled in the info sequence
 338         @deprecated
 339             Use getBooleanDataSourceSetting instead, which cares for the default of the property itself,
 340             instead of spreading this knowledge through all callers.
 341     */
 342     OOO_DLLPUBLIC_DBTOOLS
 343     sal_Bool isDataSourcePropertyEnabled(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface>& _xProp
 344                                         ,const OUString& _sProperty,
 345                                         sal_Bool _bDefault = sal_False);
 346
 347     /** retrieves a particular indirect data source setting
 348
 349         @param _rxDataSource
 350             a data source component
 351         @param _pAsciiSettingsName
 352             the ASCII name of the setting to obtain
 353         @param _rSettingsValue
 354             the value of the setting, upon successful return
 355
 356         @return
 357             <FALSE/> if the setting is not present in the <member scope="com::sun::star::sdb">DataSource::Info</member>
 358             member of the data source
 359             <TRUE/> otherwise
 360     */
 361     OOO_DLLPUBLIC_DBTOOLS
 362     bool    getDataSourceSetting(
 363         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxDataSource,
 364         const sal_Char* _pAsciiSettingsName,
 365         ::com::sun::star::uno::Any& /* [out] */ _rSettingsValue
 366     );
 367     OOO_DLLPUBLIC_DBTOOLS
 368     bool    getDataSourceSetting(
 369         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxDataSource,
 370         const OUString& _sSettingsName,
 371         ::com::sun::star::uno::Any& /* [out] */ _rSettingsValue
 372     );
 373
 374     OOO_DLLPUBLIC_DBTOOLS OUString getDefaultReportEngineServiceName(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxFactory);
 375
 376     /** quote the given name with the given quote string.
 377     */
 378     OOO_DLLPUBLIC_DBTOOLS OUString quoteName(const OUString& _rQuote, const OUString& _rName);
 379
 380     /** quote the given table name (which may contain a catalog and a schema) according to the rules provided by the meta data
 381     */
 382     OOO_DLLPUBLIC_DBTOOLS
 383     OUString quoteTableName(const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDatabaseMetaData>& _rxMeta
 384                                     , const OUString& _rName
 385                                     ,EComposeRule _eComposeRule);
 386
 387     /** split a fully qualified table name (including catalog and schema, if appliable) into it's component parts.
 388         @param  _rxConnMetaData     meta data describing the connection where you got the table name from
 389         @param  _rQualifiedName     fully qualified table name
 390         @param  _rCatalog           (out parameter) upon return, contains the catalog name
 391         @param  _rSchema            (out parameter) upon return, contains the schema name
 392         @param  _rName              (out parameter) upon return, contains the table name
 393         @param  _eComposeRule       where do you need the name for
 394     */
 395     OOO_DLLPUBLIC_DBTOOLS void qualifiedNameComponents(const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDatabaseMetaData >& _rxConnMetaData,
 396         const OUString& _rQualifiedName, OUString& _rCatalog, OUString& _rSchema, OUString& _rName,EComposeRule _eComposeRule);
 397
 398     /** calculate a NumberFormatsSupplier for use with an given connection
 399         @param      _rxConn         the connection for which the formatter is requested
 400         @param      _bAllowDefault  if the connection (and related components, such as it's parent) cannot supply
 401                                     a formatter, we can ask the DatabaseEnvironment for a default one. This parameter
 402                                     states if this is allowed.
 403         @param      _rxFactory      required (only of _bAllowDefault is sal_True) for creating the DatabaseEnvironment.
 404         @return     the formatter all object related to the given connection should work with.
 405     */
 406     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::util::XNumberFormatsSupplier> getNumberFormats(
 407         const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _rxConn,
 408         sal_Bool _bAllowDefault = sal_False,
 409         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext = ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>()
 410     );
 411
 412     /** create an com::sun::star::sdb::XSingleSelectQueryComposer which represents
 413         the current settings (Command/CommandType/Filter/Order) of the given rowset.
 414
 415         As such an instance can be obtained from a com::sun::star::sdb::Connection
 416         only the function searches for the connection the RowSet is using via connectRowset.
 417         This implies that a connection will be set on the RowSet if needed.
 418         (need to changes this sometimes ...)
 419     */
 420     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdb::XSingleSelectQueryComposer > getCurrentSettingsComposer(
 421         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxRowSetProps,
 422         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext
 423     );
 424
 425     /** transfer and translate properties between two FormComponents
 426         @param      _rxOld      the source property set
 427         @param      _rxNew      the destination property set
 428         @param      _rLocale    the locale for converting number related properties
 429     */
 430     OOO_DLLPUBLIC_DBTOOLS void TransferFormComponentProperties(
 431         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxOld,
 432         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxNew,
 433         const ::com::sun::star::lang::Locale& _rLocale
 434         );
 435
 436     /** check if the property "Privileges" supports ::com::sun::star::sdbcx::Privilege::INSERT
 437         @param      _rxCursorSet    the property set
 438     */
 439     OOO_DLLPUBLIC_DBTOOLS sal_Bool canInsert(const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxCursorSet);
 440     /** check if the property "Privileges" supports ::com::sun::star::sdbcx::Privilege::UPDATE
 441         @param      _rxCursorSet    the property set
 442     */
 443     OOO_DLLPUBLIC_DBTOOLS sal_Bool canUpdate(const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxCursorSet);
 444     /** check if the property "Privileges" supports ::com::sun::star::sdbcx::Privilege::DELETE
 445         @param      _rxCursorSet    the property set
 446     */
 447     OOO_DLLPUBLIC_DBTOOLS sal_Bool canDelete(const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _rxCursorSet);
 448
 449     //----------------------------------------------------------------------------------
 450     /** compose a complete table name from it's up to three parts, regarding to the database meta data composing rules
 451     */
 452     OOO_DLLPUBLIC_DBTOOLS OUString composeTableName( const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDatabaseMetaData >& _rxMetaData,
 453                             const OUString& _rCatalog,
 454                             const OUString& _rSchema,
 455                             const OUString& _rName,
 456                             sal_Bool _bQuote,
 457                             EComposeRule _eComposeRule);
 458
 459     /** composes a table name for usage in a SELECT statement
 460
 461         This includes quoting of the table as indicated by the connection's meta data, plus respecting
 462         the settings "UseCatalogInSelect" and "UseSchemaInSelect", which might be present
 463         in the data source which the connection belongs to.
 464     */
 465     OOO_DLLPUBLIC_DBTOOLS OUString composeTableNameForSelect(
 466                             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection,
 467                             const OUString& _rCatalog,
 468                             const OUString& _rSchema,
 469                             const OUString& _rName );
 470
 471     /** composes a table name for usage in a SELECT statement
 472
 473         This includes quoting of the table as indicated by the connection's meta data, plus respecting
 474         the settings "UseCatalogInSelect" and "UseSchemaInSelect", which might be present
 475         in the data source which the connection belongs to.
 476     */
 477     OOO_DLLPUBLIC_DBTOOLS OUString composeTableNameForSelect(
 478                             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection,
 479                             const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _xTable );
 480     //----------------------------------------------------------------------------------
 481     /** compose the table name out of the property set which must support the properties from the service <member scope= "com::sun::star::sdbcx">table</member>
 482         @param  _xMetaData
 483             The metadata from the connection.
 484         @param  _xTable
 485             The table.
 486     */
 487     OOO_DLLPUBLIC_DBTOOLS OUString composeTableName(
 488         const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDatabaseMetaData>& _xMetaData,
 489         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _xTable,
 490         EComposeRule _eComposeRule,
 491         bool _bSuppressCatalogName,
 492         bool _bSuppressSchemaName,
 493         bool _bQuote);
 494
 495     //----------------------------------------------------------------------------------
 496     OOO_DLLPUBLIC_DBTOOLS sal_Int32 getSearchColumnFlag( const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _rxConn,
 497                                     sal_Int32 _nDataType);
 498     // return the datasource for the given datasource name
 499     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDataSource> getDataSource(const OUString& _rsDataSourceName,
 500                         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext);
 501
 502     /** search for a name that is NOT in the NameAcces
 503         @param  _rxContainer
 504             the NameAccess container to search in
 505         @param  _rBaseName
 506             the base name that should be used to create the new name
 507         @param  _bStartWithNumber
 508             When <TRUE/> the name ends with number even when the name itself doesn't occur in the collection.
 509         @return
 510             A name which doesn't exist in the collection.
 511     */
 512     OOO_DLLPUBLIC_DBTOOLS
 513     OUString createUniqueName(const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess>& _rxContainer,
 514                                      const OUString& _rBaseName,
 515                                      sal_Bool _bStartWithNumber = sal_True);
 516
 517     /** creates a unique name which is not already used in the given name array
 518     */
 519     OOO_DLLPUBLIC_DBTOOLS OUString createUniqueName(
 520         const ::com::sun::star::uno::Sequence< OUString >& _rNames,
 521         const OUString& _rBaseName,
 522         sal_Bool _bStartWithNumber = sal_True
 523     );
 524
 525     /** create a name which is a valid SQL 92 identifier name
 526         @param      _rName          the string which should be converted
 527         @param      _rSpecials      @see com.sun.star.sdbc.XDatabaseMetaData.getExtraNameCharacters
 528
 529         @see isValidSQLName
 530     */
 531     OOO_DLLPUBLIC_DBTOOLS OUString convertName2SQLName(const OUString& _rName,const OUString& _rSpecials);
 532
 533     /** checks whether the given name is a valid SQL name
 534
 535         @param      _rName          the string which should be converted
 536         @param      _rSpecials      @see com.sun.star.sdbc.XDatabaseMetaData.getExtraNameCharacters
 537
 538         @see convertName2SQLName
 539     */
 540     OOO_DLLPUBLIC_DBTOOLS sal_Bool isValidSQLName( const OUString& _rName, const OUString& _rSpecials );
 541
 542     OOO_DLLPUBLIC_DBTOOLS
 543     void showError( const SQLExceptionInfo& _rInfo,
 544                     const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow>& _pParent,
 545                     const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext);
 546
 547     /** implements <method scope="com.sun.star.sdb">XRowUpdate::updateObject</method>
 548         <p>The object which is to be set is analyzed, and in case it is a simlpe scalar type for which there
 549         is another updateXXX method, this other method is used.</p>
 550         @param _rxUpdatedObject
 551             the interface to forward all updateXXX calls to (except updateObject)
 552         @param _nColumnIndex
 553             the column index to update
 554         @param _rValue
 555             the value to update
 556         @return
 557             <TRUE/> if the update request was successfully re-routed to one of the other updateXXX methods
 558     */
 559     OOO_DLLPUBLIC_DBTOOLS
 560     sal_Bool implUpdateObject(  const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowUpdate >& _rxUpdatedObject,
 561                                 const sal_Int32 _nColumnIndex,
 562                                 const ::com::sun::star::uno::Any& _rValue)  SAL_THROW   (   (   ::com::sun::star::sdbc::SQLException,   ::com::sun::star::uno::RuntimeException)    );
 563
 564
 565
 566     /** ask the user for parameters if the prepared statement needs some and sets them in the prepared statement
 567         @param _xConnection     the connection must be able to create com::sun::star::sdb::SingleSelectQueryComposers
 568         @param _xPreparedStmt   the prepared statement where the parameters could be set when needed
 569         @param _aParametersSet  contains which parameters have to asked for and which already have set.
 570     */
 571     OOO_DLLPUBLIC_DBTOOLS
 572     void askForParameters(  const ::com::sun::star::uno::Reference< ::com::sun::star::sdb::XSingleSelectQueryComposer >& _xComposer,
 573                             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XParameters>& _xParameters,
 574                             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection,
 575                             const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionHandler >& _rxHandler,
 576                             const ::std::vector<bool, std::allocator<bool> >& _aParametersSet = ::std::vector<bool, std::allocator<bool> >());
 577
 578     /** call the appropriate set method for the specific sql type @see com::sun::star::sdbc::DataType
 579         @param  _xParams        the parameters where to set the value
 580         @param  parameterIndex  the index of the parameter, 1 based
 581         @param  x               the value to set
 582         @param  sqlType         the corresponding sql type @see com::sun::star::sdbc::DataType
 583         @param  scale           the scale of the sql type can be 0
 584     */
 585     OOO_DLLPUBLIC_DBTOOLS
 586     void setObjectWithInfo( const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XParameters>& _xParameters,
 587                             sal_Int32 parameterIndex,
 588                             const ::com::sun::star::uno::Any& x,
 589                             sal_Int32 sqlType,
 590                             sal_Int32 scale=0) throw(::com::sun::star::sdbc::SQLException, ::com::sun::star::uno::RuntimeException);
 591
 592     /** call the appropriate set method for the specific sql type @see com::sun::star::sdbc::DataType
 593         @param  _xParams        the parameters where to set the value
 594         @param  parameterIndex  the index of the parameter, 1 based
 595         @param  x               the value to set
 596         @param  sqlType         the corresponding sql type @see com::sun::star::sdbc::DataType
 597         @param  scale           the scale of the sql type can be 0
 598     */
 599     OOO_DLLPUBLIC_DBTOOLS
 600     void setObjectWithInfo( const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XParameters>& _xParameters,
 601                             sal_Int32 parameterIndex,
 602                             const ::connectivity::ORowSetValue& x,
 603                             sal_Int32 sqlType,
 604                             sal_Int32 scale=0) throw(::com::sun::star::sdbc::SQLException, ::com::sun::star::uno::RuntimeException);
 605
 606
 607     /** implements <method scope="com.sun.star.sdb">XParameters::setObject</method>
 608         <p>The object which is to be set is analyzed, and in case it is a simlpe scalar type for which there
 609         is another setXXX method, this other method is used.</p>
 610         @param _rxParameters
 611             the interface to forward all setXXX calls to (except setObject)
 612         @param _nColumnIndex
 613             the column index to update
 614         @param _rValue
 615             the value to update
 616         @return
 617             <TRUE/> if the update request was successfully re-routed to one of the other updateXXX methods
 618     */
 619     OOO_DLLPUBLIC_DBTOOLS
 620     sal_Bool implSetObject( const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XParameters>& _rxParameters,
 621                             const sal_Int32 _nColumnIndex,
 622                             const ::com::sun::star::uno::Any& _rValue) SAL_THROW ( ( ::com::sun::star::sdbc::SQLException, ::com::sun::star::uno::RuntimeException ) );
 623
 624     /** creates the standard sql create table statement without the key part.
 625         @param  descriptor
 626             The descriptor of the new table.
 627         @param  _xConnection
 628             The connection.
 629         @param  _bAddScale
 630             The scale will also be added when the value is 0.
 631     */
 632     OOO_DLLPUBLIC_DBTOOLS
 633     OUString createStandardCreateStatement(  const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& descriptor,
 634                                                     const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection,
 635                                                     ISQLStatementHelper* _pHelper,
 636                                                     const OUString& _sCreatePattern = OUString());
 637
 638     /** creates the standard sql statement for the key part of a create table statement.
 639         @param  descriptor
 640             The descriptor of the new table.
 641         @param  _xConnection
 642             The connection.
 643     */
 644     OOO_DLLPUBLIC_DBTOOLS
 645     OUString createStandardKeyStatement( const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& descriptor,
 646                                                 const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection);
 647
 648     /** creates the standard sql statement for the type part of a create or alter table statement.
 649         @param  _pHelper
 650             Allow to add special SQL constructs.
 651         @param  descriptor
 652             The descriptor of the column.
 653         @param  _xConnection
 654             The connection.
 655     */
 656     OOO_DLLPUBLIC_DBTOOLS
 657     OUString createStandardTypePart(     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& descriptor
 658                                                 ,const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection
 659                                                 ,const OUString& _sCreatePattern = OUString());
 660
 661     /** creates the standard sql statement for the column part of a create table statement.
 662         @param  _pHelper
 663             Allow to add special SQL constructs.
 664         @param  descriptor
 665             The descriptor of the column.
 666         @param  _xConnection
 667             The connection.
 668         @param  _pHelper
 669             Allow to add special SQL constructs.
 670     */
 671     OOO_DLLPUBLIC_DBTOOLS
 672     OUString createStandardColumnPart(   const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& descriptor
 673                                                 ,const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection
 674                                                 ,ISQLStatementHelper* _pHelper = NULL
 675                                                 ,const OUString& _sCreatePattern = OUString());
 676
 677     /** creates a SQL CREATE TABLE statement
 678
 679         @param  descriptor
 680             The descriptor of the new table.
 681         @param  _xConnection
 682             The connection.
 683         @param  _pHelper
 684             Allow to add special SQL constructs.
 685         @param  _sCreatePattern
 686
 687         @return
 688             The CREATE TABLE statement.
 689     */
 690     OOO_DLLPUBLIC_DBTOOLS
 691     OUString createSqlCreateTableStatement(  const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& descriptor
 692                                                     ,const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection
 693                                                     ,ISQLStatementHelper* _pHelper = NULL
 694                                                     ,const OUString& _sCreatePattern = OUString());
 695
 696     /** creates a SDBC column with the help of getColumns.
 697         @param  _xTable
 698             The table.
 699         @param  _rName
 700             The name of the column.
 701         @param  _bCase
 702             Is the column case sensitive.
 703         @param  _bQueryForInfo
 704             If <TRUE/> the autoincrement and currency field will be read from the meta data, otherwise the following parameters will be used instead
 705         @param  _bIsAutoIncrement
 706             <TRUE/> if the column is an autoincrement.
 707         @param  _bIsCurrency
 708             <TRUE/> if the column is a currency field.
 709         @param  _nDataType
 710             The data type of the column.
 711     */
 712     OOO_DLLPUBLIC_DBTOOLS
 713     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>
 714             createSDBCXColumn(  const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>& _xTable,
 715                                 const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection,
 716                                 const OUString& _rName,
 717                                 sal_Bool _bCase,
 718                                 sal_Bool _bQueryForInfo = sal_True,
 719                                 sal_Bool _bIsAutoIncrement = sal_False,
 720                                 sal_Bool _bIsCurrency = sal_False,
 721                                 sal_Int32 _nDataType = com::sun::star::sdbc::DataType::OTHER);
 722
 723     /** tries to locate the corresponding DataDefinitionSupplier for the given url and connection
 724         @param  _rsUrl
 725             The URL used to connect to the database.
 726         @param  _xConnection
 727             The connection used to find the correct driver.
 728         @param  _rxContext
 729             Used to create the drivermanager.
 730         @return
 731             The datadefintion object.
 732     */
 733     OOO_DLLPUBLIC_DBTOOLS ::com::sun::star::uno::Reference< ::com::sun::star::sdbcx::XTablesSupplier> getDataDefinitionByURLAndConnection(
 734             const OUString& _rsUrl,
 735             const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection,
 736             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext>& _rxContext);
 737
 738     /** returns the table privileges to the given parameters
 739         @param  _xMetaData
 740             The meta data.
 741         @param  _sCatalog
 742             contains the catalog name
 743         @param  _sSchema
 744             contains the schema name
 745         @param  _sTable
 746             contains the table name
 747     */
 748     OOO_DLLPUBLIC_DBTOOLS
 749     sal_Int32 getTablePrivileges(const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XDatabaseMetaData>& _xMetaData,
 750                                  const OUString& _sCatalog,
 751                                  const OUString& _sSchema,
 752                                  const OUString& _sTable);
 753
 754     typedef ::std::pair<sal_Bool,sal_Bool> TBoolPair;
 755     typedef ::std::pair< TBoolPair,sal_Int32 > ColumnInformation;
 756     typedef ::std::multimap< OUString, ColumnInformation, ::comphelper::UStringMixLess> ColumnInformationMap;
 757     /** collects the information about auto increment, currency and data type for the given column name.
 758         The column must be quoted, * is also valid.
 759         @param  _xConnection
 760             The connection.
 761         @param  _sComposedTableName
 762             The quoted table name. ccc.sss.ttt
 763         @param  _sName
 764             The name of the column, or *
 765         @param  _rInfo
 766             The information about the column(s).
 767     */
 768     OOO_DLLPUBLIC_DBTOOLS
 769     void collectColumnInformation(  const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection>& _xConnection,
 770                                     const OUString& _sComposedTableName,
 771                                     const OUString& _rName,
 772                                     ColumnInformationMap& _rInfo);
 773
 774
 775     /** adds a boolean comparison clause to the given SQL predicate
 776
 777         @param _rExpression
 778             the expression which is to be compared with a boolean value
 779         @param _bValue
 780             the boolean value which the expression is to be compared with
 781         @param _nBooleanComparisonMode
 782             the boolean comparison mode to be used. Usually obtained from
 783             a css.sdb.DataSource's Settings member.
 784         @param _out_rSQLPredicate
 785             the buffer to which the comparison predicate will be appended
 786     */
 787     OOO_DLLPUBLIC_DBTOOLS void getBoleanComparisonPredicate(
 788             const OUString& _rExpression,
 789             const sal_Bool  _bValue,
 790             const sal_Int32 _nBooleanComparisonMode,
 791             OUStringBuffer& _out_rSQLPredicate
 792         );
 793
 794 //.........................................................................
 795 }   // namespace dbtools
 796 //.........................................................................
 797
 798 #endif // INCLUDED_CONNECTIVITY_DBTOOLS_HXX
 799
 800 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */