include/connectivity/parameters.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 #ifndef INCLUDED_CONNECTIVITY_PARAMETERS_HXX
  20 #define INCLUDED_CONNECTIVITY_PARAMETERS_HXX
  21
  22 #include <map>
  23 #include <vector>
  24
  25 #include <com/sun/star/sdb/XSingleSelectQueryComposer.hpp>
  26
  27 #include <connectivity/dbtoolsdllapi.hxx>
  28 #include <connectivity/paramwrapper.hxx>
  29 #include <unotools/sharedunocomponent.hxx>
  30 #include <comphelper/interfacecontainer2.hxx>
  31
  32 namespace com::sun::star::beans { class XPropertySet; }
  33 namespace com::sun::star::container { class XIndexAccess; }
  34 namespace com::sun::star::form { class XDatabaseParameterListener; }
  35 namespace com::sun::star::io { class XInputStream; }
  36 namespace com::sun::star::sdbc { class XArray; }
  37 namespace com::sun::star::sdbc { class XBlob; }
  38 namespace com::sun::star::sdbc { class XClob; }
  39 namespace com::sun::star::sdbc { class XConnection; }
  40 namespace com::sun::star::sdbc { class XDatabaseMetaData; }
  41 namespace com::sun::star::sdbc { class XParameters; }
  42 namespace com::sun::star::sdbc { class XRef; }
  43 namespace com::sun::star::task { class XInteractionHandler; }
  44 namespace com::sun::star::uno { class XAggregation; }
  45 namespace com::sun::star::uno { class XComponentContext; }
  46
  47 namespace dbtools
  48 {
  49
  50
  51     typedef ::utl::SharedUNOComponent< css::sdb::XSingleSelectQueryComposer, ::utl::DisposableComponent >
  52             SharedQueryComposer;
  53
  54
  55     //= ParameterManager
  56
  57     class FilterManager;
  58     class OOO_DLLPUBLIC_DBTOOLS ParameterManager
  59     {
  60     public:
  61         /// classifies the origin of the data to fill a parameter
  62         enum class ParameterClassification
  63         {
  64             /** parameters which are filled from the master-detail relationship, where the detail
  65                 name is an explicit parameter name
  66             */
  67             LinkedByParamName,
  68             /** parameters which are filled from the master-detail relationship, where the detail
  69                 name is a column name, so an implicit parameter had to be generated for it
  70             */
  71             LinkedByColumnName,
  72             /** parameters which are filled externally (i.e. by XParameters::setXXX, or by the parameter listeners)
  73             */
  74             FilledExternally
  75         };
  76         /** meta data about an inner parameter
  77         */
  78     private:
  79         struct ParameterMetaData
  80         {
  81             /// the type of the parameter
  82             ParameterClassification     eType;
  83             /// the column object for this parameter, as returned by the query composer
  84             css::uno::Reference< css::beans::XPropertySet >
  85                                         xComposerColumn;
  86             /// the indices of inner parameters which need to be filled when this concrete parameter is set
  87             ::std::vector< sal_Int32 >  aInnerIndexes;
  88
  89             /// ctor with composer column
  90             ParameterMetaData( const css::uno::Reference< css::beans::XPropertySet >& _rxColumn )
  91                 :eType           ( ParameterClassification::FilledExternally )
  92                 ,xComposerColumn ( _rxColumn         )
  93             {
  94             }
  95         };
  96
  97         typedef ::std::map< OUString, ParameterMetaData >    ParameterInformation;
  98
  99     private:
 100         ::osl::Mutex&                       m_rMutex;
 101         ::comphelper::OInterfaceContainerHelper2  m_aParameterListeners;
 102
 103         css::uno::Reference< css::uno::XComponentContext >
 104                                             m_xContext;
 105
 106         css::uno::WeakReference< css::beans::XPropertySet >
 107                                             m_xComponent;                // the database component whose parameters we're handling
 108         css::uno::Reference< css::uno::XAggregation >
 109                                             m_xAggregatedRowSet;    // the aggregated row set - necessary for unwrapped access to some interfaces
 110         css::uno::Reference< css::sdbc::XParameters >
 111                                             m_xInnerParamUpdate;    // write access to the inner parameters
 112         SharedQueryComposer                 m_xComposer;            // query composer wrapping the statement which the *aggregate* is based on
 113         SharedQueryComposer                 m_xParentComposer;      // query composer wrapping the statement of our parent database component
 114         css::uno::Reference< css::container::XIndexAccess >
 115                                             m_xInnerParamColumns;   // index access to the parameter columns, as got from the query composer
 116
 117         ::dbtools::param::ParametersContainerRef
 118                                             m_pOuterParameters;     // the container of parameters which still need to be filled in by
 119                                                                     // external instances
 120         sal_Int32                           m_nInnerCount;          // overall number of parameters as required by the database component's aggregate
 121
 122         ParameterInformation                m_aParameterInformation;
 123
 124         std::vector< OUString >             m_aMasterFields;
 125         std::vector< OUString >             m_aDetailFields;
 126
 127         OUString                            m_sIdentifierQuoteString;
 128         OUString                            m_sSpecialCharacters;
 129         css::uno::Reference< css::sdbc::XDatabaseMetaData > m_xConnectionMetadata;
 130
 131         ::std::vector< bool >               m_aParametersVisited;
 132
 133         bool                                m_bUpToDate;
 134
 135     public:
 136         /** ctor
 137         */
 138         explicit ParameterManager(
 139             ::osl::Mutex& _rMutex,
 140             const css::uno::Reference< css::uno::XComponentContext >& _rxContext
 141         );
 142
 143         /// late ctor
 144         void    initialize(
 145                     const css::uno::Reference< css::beans::XPropertySet >& _rxComponent,
 146                     const css::uno::Reference< css::uno::XAggregation >& _rxComponentAggregate
 147                 );
 148
 149         /// makes the object forgetting the references to the database component
 150         void    dispose( );
 151
 152         /// clears the instance data
 153                 void    clearAllParameterInformation();
 154
 155         /// checks whether the parameter information is up-to-date
 156         bool    isUpToDate() const { return m_bUpToDate; }
 157
 158         /** updates all parameter information represented by the instance
 159         */
 160         void    updateParameterInfo( FilterManager& _rFilterManager );
 161
 162         /** fills parameter values, as extensive as possible
 163
 164             <p>In particular, all values which can be filled from the master-detail relationship of
 165             between our database component and its parent are filled in.</p>
 166
 167             @param _rxCompletionHandler
 168                 an interaction handler which should be used to fill all parameters which
 169                 cannot be filled by other means. May be <NULL/>
 170             @param _rClearForNotifies
 171                 the mutex guard to be (temporarily) cleared for notifications
 172
 173             @precond
 174                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 175
 176             @return
 177                 <TRUE/> if and only if the parameter filling has <em>not</em> been cancelled by the user
 178         */
 179         bool    fillParameterValues(
 180                     const css::uno::Reference< css::task::XInteractionHandler >& _rxCompletionHandler,
 181                     ::osl::ResettableMutexGuard& _rClearForNotifies
 182                 );
 183
 184         /** sets all parameter values to null (via <member>XParameters::setNull</member>)
 185
 186             @precond
 187                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 188         */
 189         void    setAllParametersNull();
 190
 191         /** resets all detail columns which are, via a parameter, linked to a master column, to
 192             the value of this master column.
 193
 194             For instance, if the database component is bound to a statement <code>SELECT * from invoice where inv_id = :cid</code>,
 195             and there is <em>one</em> master-detail link from
 196
 197             @precond
 198                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 199         */
 200         void    resetParameterValues();
 201
 202         /** adds the given listener to the list of parameter listeners
 203         */
 204         void    addParameterListener(
 205                     const css::uno::Reference< css::form::XDatabaseParameterListener >& _rxListener
 206                 );
 207
 208         /** removes the given listener from the list of parameter listeners
 209         */
 210         void    removeParameterListener(
 211                     const css::uno::Reference< css::form::XDatabaseParameterListener >& _rxListener
 212                 );
 213
 214         // XParameters equivalents
 215         void setNull            ( sal_Int32 _nIndex, sal_Int32 sqlType);
 216         void setObjectNull      ( sal_Int32 _nIndex, sal_Int32 sqlType, const OUString& typeName);
 217         void setBoolean         ( sal_Int32 _nIndex, bool x);
 218         void setByte            ( sal_Int32 _nIndex, sal_Int8 x);
 219         void setShort           ( sal_Int32 _nIndex, sal_Int16 x);
 220         void setInt             ( sal_Int32 _nIndex, sal_Int32 x);
 221         void setLong            ( sal_Int32 _nIndex, sal_Int64 x);
 222         void setFloat           ( sal_Int32 _nIndex, float x);
 223         void setDouble          ( sal_Int32 _nIndex, double x);
 224         void setString          ( sal_Int32 _nIndex, const OUString& x);
 225         void setBytes           ( sal_Int32 _nIndex, const css::uno::Sequence< sal_Int8 >& x);
 226         void setDate            ( sal_Int32 _nIndex, const css::util::Date& x);
 227         void setTime            ( sal_Int32 _nIndex, const css::util::Time& x);
 228         void setTimestamp       ( sal_Int32 _nIndex, const css::util::DateTime& x);
 229         void setBinaryStream    ( sal_Int32 _nIndex, const css::uno::Reference< css::io::XInputStream>& x, sal_Int32 length);
 230         void setCharacterStream ( sal_Int32 _nIndex, const css::uno::Reference< css::io::XInputStream>& x, sal_Int32 length);
 231         void setObject          ( sal_Int32 _nIndex, const css::uno::Any& x);
 232         void setObjectWithInfo  ( sal_Int32 _nIndex, const css::uno::Any& x, sal_Int32 targetSqlType, sal_Int32 scale);
 233         void setRef             ( sal_Int32 _nIndex, const css::uno::Reference< css::sdbc::XRef>& x);
 234         void setBlob            ( sal_Int32 _nIndex, const css::uno::Reference< css::sdbc::XBlob>& x);
 235         void setClob            ( sal_Int32 _nIndex, const css::uno::Reference< css::sdbc::XClob>& x);
 236         void setArray           ( sal_Int32 _nIndex, const css::uno::Reference< css::sdbc::XArray>& x);
 237         void clearParameters();
 238
 239     private:
 240         /// checks whether the object is already initialized, and not yet disposed
 241         bool    isAlive() const { return m_xComponent.get().is() && m_xInnerParamUpdate.is(); }
 242
 243         /** creates a filter expression from a master-detail link where the detail denotes a column name
 244         */
 245         OUString
 246                 createFilterConditionFromColumnLink(
 247                     const OUString& /* [in]  */ _rMasterColumn,
 248                     const css::uno::Reference< css::beans::XPropertySet >& /* [in]  */ xDetailColumn,
 249                           OUString& /* [out] */ _rNewParamName
 250                 );
 251
 252         /** initializes our query composer, and the collection of inner parameter columns
 253
 254             @param _rxComponent
 255                 the database component to initialize from. Must not be <NULL/>
 256             @return
 257                 <TRUE/> if and only if the initialization was successful
 258
 259             @postcond
 260                 if and only if <TRUE/> is returned, then <member>m_xInnerParamColumns</member> contains the collection of
 261                 inner parameters
 262         */
 263         bool    initializeComposerByComponent(
 264                     const css::uno::Reference< css::beans::XPropertySet >& _rxComponent
 265                 );
 266
 267         /** collects initial meta information about inner parameters (i.e. it initially fills
 268             <member>m_aParameterInformation</member>).
 269
 270             @param _bSecondRun
 271                 if <TRUE/>, this is the second run, because we ourself previously extended the filter of
 272                 the RowSet
 273
 274             @precond
 275                 <member>m_xInnerParamColumns</member> is not <NULL/>
 276         */
 277         void    collectInnerParameters( bool _bSecondRun );
 278
 279         /** analyzes the master-detail links for our database component, and initializes m_aMasterFields and m_aDetailFields
 280
 281             @param _rFilterManager
 282                 the filter manager of the database component
 283             @param _rColumnsInLinkDetails
 284                 will be set to <TRUE/> if and only if there were link pairs where the detail field denoted
 285                 a column name of our database component
 286
 287             @precond
 288                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 289         */
 290         void    analyzeFieldLinks( FilterManager& _rFilterManager, bool& /* [out] */ _rColumnsInLinkDetails );
 291
 292         /** classifies the link pairs
 293
 294             @param  _rxParentColumns
 295                 the columns of the parent database component
 296
 297             @param  _rxColumns
 298                 the columns of our own database component
 299
 300             @param  _out_rAdditionalFilterComponents
 301                 the additional filter components which are required for master-detail relationships where
 302                 the detail part denotes a column name. In such a case, an additional filter needs to be created,
 303                 containing a new parameter.
 304
 305             @param  _out_rAdditionalHavingComponents
 306                 the additional having clause components which are required for master-detail relationships where
 307                 the detail part denotes a column name. In such a case, an additional filter needs to be created,
 308                 containing a new parameter.
 309
 310             @precond
 311                 <member>m_aMasterFields</member> and <member>m_aDetailFields</member> have the same length
 312         */
 313         void    classifyLinks(
 314                     const css::uno::Reference< css::container::XNameAccess >& _rxParentColumns,
 315                     const css::uno::Reference< css::container::XNameAccess >& _rxColumns,
 316                     ::std::vector< OUString >& _out_rAdditionalFilterComponents,
 317                     ::std::vector< OUString >& _out_rAdditionalHavingComponents
 318                 );
 319
 320         /** finalizes our <member>m_pOuterParameters</member> so that it can be used for
 321             external parameter listeners
 322
 323             @precond
 324                 <member>m_pOuterParameters</member> is <NULL/>
 325             @precond
 326                 <member>m_xInnerParamUpdate</member> is not <NULL/>
 327         */
 328         void    createOuterParameters();
 329
 330         /** fills in the parameters values which result from the master-detail relationship
 331             between the database component and its parent
 332
 333             @param _rxParentColumns
 334                 the columns of the parameter database component. Must not be <NULL/>
 335             @precond
 336                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 337         */
 338         void    fillLinkedParameters(
 339                     const css::uno::Reference< css::container::XNameAccess >& _rxParentColumns
 340                 );
 341
 342         /** completes all missing parameters via an interaction handler
 343
 344             @precond
 345                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 346
 347             @return
 348                 <TRUE/> if and only if the parameter filling has <em>not</em> been cancelled by the user
 349         */
 350         bool    completeParameters(
 351                     const css::uno::Reference< css::task::XInteractionHandler >& _rxCompletionHandler,
 352                     const css::uno::Reference< css::sdbc::XConnection >& _rxConnection
 353                 );
 354
 355         /** asks the parameter listeners to fill in final values
 356
 357             @precond
 358                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 359
 360             @return
 361                 <TRUE/> if and only if the parameter filling has <em>not</em> been cancelled by the user
 362         */
 363         bool    consultParameterListeners( ::osl::ResettableMutexGuard& _rClearForNotifies );
 364
 365         /** mark an externally filled parameter as visited
 366         */
 367         void    externalParameterVisited( sal_Int32 _nIndex );
 368
 369     private:
 370         /** retrieves the columns of the parent database component
 371
 372             @precond
 373                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 374             @return
 375                 <TRUE/> if and only if the columns could be successfully retrieved
 376         */
 377         bool    getParentColumns(
 378                     css::uno::Reference< css::container::XNameAccess >& /* [out] */ _out_rxParentColumns,
 379                     bool _bFromComposer
 380                 );
 381
 382         /** retrieves the columns of our database component
 383
 384             @param _bFromComposer
 385                 if <TRUE/>, the columns are obtained from the composer, else from the living database component itself
 386             @return
 387                 <TRUE/> if and only if the columns could be successfully retrieved
 388         */
 389         bool    getColumns(
 390                     css::uno::Reference< css::container::XNameAccess >& /* [out] */ _rxColumns,
 391                     bool _bFromComposer
 392                 );
 393
 394         /** retrieves the active connection of the database component
 395         */
 396         void    getConnection(
 397                     css::uno::Reference< css::sdbc::XConnection >& /* [out] */ _rxConnection
 398                 );
 399
 400         /** caches some info about the connection of our database component
 401         */
 402         void    cacheConnectionInfo();
 403
 404     private:
 405         ParameterManager( const ParameterManager& ) = delete;
 406         ParameterManager& operator=( const ParameterManager& ) = delete;
 407     };
 408
 409
 410 } // namespacefrm
 411
 412
 413 #endif // INCLUDED_CONNECTIVITY_PARAMETERS_HXX
 414
 415 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */