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/uno/XAggregation.hpp>
  26 #include <com/sun/star/uno/XComponentContext.hpp>
  27 #include <com/sun/star/form/XDatabaseParameterListener.hpp>
  28 #include <com/sun/star/sdbc/XConnection.hpp>
  29 #include <com/sun/star/task/XInteractionHandler.hpp>
  30 #include <com/sun/star/sdbc/XParameters.hpp>
  31 #include <com/sun/star/container/XIndexAccess.hpp>
  32 #include <com/sun/star/beans/XPropertySet.hpp>
  33 #include <com/sun/star/sdb/XSingleSelectQueryComposer.hpp>
  34
  35 #include <connectivity/dbtoolsdllapi.hxx>
  36 #include <connectivity/paramwrapper.hxx>
  37 #include <unotools/sharedunocomponent.hxx>
  38 #include <cppuhelper/interfacecontainer.hxx>
  39
  40
  41 namespace dbtools
  42 {
  43
  44
  45     typedef ::utl::SharedUNOComponent< ::com::sun::star::sdb::XSingleSelectQueryComposer, ::utl::DisposableComponent >
  46             SharedQueryComposer;
  47
  48
  49     //= ParameterManager
  50
  51     class FilterManager;
  52     class OOO_DLLPUBLIC_DBTOOLS ParameterManager
  53     {
  54     public:
  55         /// classifies the origin of the data to fill a parameter
  56         enum ParameterClassification
  57         {
  58             /** parameters which are filled from the master-detail relationship, where the detail
  59                 name is an explicit parameter name
  60             */
  61             eLinkedByParamName,
  62             /** parameters which are filled from the master-detail relationship, where the detail
  63                 name is a column name, so an implicit parameter had to be generated for it
  64             */
  65             eLinkedByColumnName,
  66             /** parameters which are filled externally (i.e. by XParameters::setXXX, or by the parameter listeners)
  67             */
  68             eFilledExternally
  69         };
  70         /** meta data about an inner parameter
  71         */
  72     private:
  73         struct ParameterMetaData
  74         {
  75             /// the type of the parameter
  76             ParameterClassification     eType;
  77             /// the column object for this parameter, as returned by the query composer
  78             ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
  79                                         xComposerColumn;
  80             /// the indices of inner parameters which need to be filled when this concrete parameter is set
  81             ::std::vector< sal_Int32 >  aInnerIndexes;
  82
  83             /// default ctor
  84             ParameterMetaData()
  85                 :eType( eFilledExternally )
  86             {
  87             }
  88
  89             /// ctor with composer column
  90             ParameterMetaData( const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxColumn )
  91                 :eType           ( eFilledExternally )
  92                 ,xComposerColumn ( _rxColumn         )
  93             {
  94             }
  95         };
  96
  97         typedef ::std::map< OUString, ParameterMetaData >    ParameterInformation;
  98
  99     private:
 100         ::osl::Mutex&                       m_rMutex;
 101         ::cppu::OInterfaceContainerHelper   m_aParameterListeners;
 102
 103         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >
 104                                             m_xContext;
 105
 106         ::com::sun::star::uno::WeakReference< ::com::sun::star::beans::XPropertySet >
 107                                             m_xComponent;                // the database component whose parameters we're handling
 108         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XAggregation >
 109                                             m_xAggregatedRowSet;    // the aggregated row set - necessary for unwrapped access to some interfaces
 110         ::com::sun::star::uno::Reference< ::com::sun::star::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         ::com::sun::star::uno::Reference< ::com::sun::star::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         ::com::sun::star::uno::Sequence< OUString >  m_aMasterFields;
 125         ::com::sun::star::uno::Sequence< OUString >  m_aDetailFields;
 126
 127         OUString                     m_sIdentifierQuoteString;
 128         OUString                     m_sSpecialCharacters;
 129         ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _rxContext
 141         );
 142
 143         /// late ctor
 144         void    initialize(
 145                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxComponent,
 146                     const ::com::sun::star::uno::Reference< ::com::sun::star::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 are up-to-date
 156         inline  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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::form::XDatabaseParameterListener >& _rxListener
 206                 );
 207
 208         /** removes the given listener from the list of parameter listeners
 209         */
 210         void    removeParameterListener(
 211                     const ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Sequence< sal_Int8 >& x);
 226         void setDate            ( sal_Int32 _nIndex, const ::com::sun::star::util::Date& x);
 227         void setTime            ( sal_Int32 _nIndex, const ::com::sun::star::util::Time& x);
 228         void setTimestamp       ( sal_Int32 _nIndex, const ::com::sun::star::util::DateTime& x);
 229         void setBinaryStream    ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStream>& x, sal_Int32 length);
 230         void setCharacterStream ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStream>& x, sal_Int32 length);
 231         void setObject          ( sal_Int32 _nIndex, const ::com::sun::star::uno::Any& x);
 232         void setObjectWithInfo  ( sal_Int32 _nIndex, const ::com::sun::star::uno::Any& x, sal_Int32 targetSqlType, sal_Int32 scale);
 233         void setRef             ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRef>& x);
 234         void setBlob            ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XBlob>& x);
 235         void setClob            ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XClob>& x);
 236         void setArray           ( sal_Int32 _nIndex, const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XArray>& x);
 237         void clearParameters();
 238
 239     private:
 240         /// checkes whether the object is already initialized, and not yet disposed
 241         inline  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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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             @precond
 306                 <member>m_aMasterFields</member> and <member>m_aDetailFields</member> have the same length
 307         */
 308         void    classifyLinks(
 309                     const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxParentColumns,
 310                     const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxColumns,
 311                     ::std::vector< OUString >& _out_rAdditionalFilterComponents
 312                 );
 313
 314         /** finalizes our <member>m_pOuterParameters</member> so that it can be used for
 315             external parameter listeners
 316
 317             @precond
 318                 <member>m_pOuterParameters</member> is <NULL/>
 319             @precond
 320                 <member>m_xInnerParamUpdate</member> is not <NULL/>
 321         */
 322         void    createOuterParameters();
 323
 324         /** fills in the parameters values which result from the master-detail relationship
 325             between the database component and its parent
 326
 327             @param _rxParentColumns
 328                 the columns of the parameter database component. Must not be <NULL/>
 329             @precond
 330                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 331         */
 332         void    fillLinkedParameters(
 333                     const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxParentColumns
 334                 );
 335
 336         /** completes all missing parameters via an interaction handler
 337
 338             @precond
 339                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 340
 341             @return
 342                 <TRUE/> if and only if the parameter filling has <em>not</em> been cancelled by the user
 343         */
 344         bool    completeParameters(
 345                     const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionHandler >& _rxCompletionHandler,
 346                     const ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& _rxConnection
 347                 );
 348
 349         /** asks the parameter listeners to fill in final values
 350
 351             @precond
 352                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 353
 354             @return
 355                 <TRUE/> if and only if the parameter filling has <em>not</em> been cancelled by the user
 356         */
 357         bool    consultParameterListeners( ::osl::ResettableMutexGuard& _rClearForNotifies );
 358
 359         /** mark an externally filled parameter asvisited
 360         */
 361         void    externalParameterVisited( sal_Int32 _nIndex );
 362
 363     private:
 364         /** retrieves the columns of the parent database component
 365
 366             @precond
 367                 the instance is alive, i.e. <member>isAlive</member> returns <TRUE/>
 368             @return
 369                 <TRUE/> if and only if the columns could be successfully retrieved
 370         */
 371         bool    getParentColumns(
 372                     ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& /* [out] */ _out_rxParentColumns,
 373                     bool _bFromComposer
 374                 );
 375
 376         /** retrieves the columns of our database component
 377
 378             @param _bFromComposer
 379                 if <TRUE/>, the columns are obtained from the composer, else from the living database component itself
 380             @return
 381                 <TRUE/> if and only if the columns could be successfully retrieved
 382         */
 383         bool    getColumns(
 384                     ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& /* [out] */ _rxColumns,
 385                     bool _bFromComposer
 386                 );
 387
 388         /** retrieves the active connection of the database component
 389         */
 390         bool    getConnection(
 391                     ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XConnection >& /* [out] */ _rxConnection
 392                 );
 393
 394         /** caches some info about the connection of our database component
 395         */
 396         void    cacheConnectionInfo();
 397
 398     private:
 399         ParameterManager( const ParameterManager& ) SAL_DELETED_FUNCTION;
 400         ParameterManager& operator=( const ParameterManager& ) SAL_DELETED_FUNCTION;
 401     };
 402
 403
 404 } // namespacefrm
 405
 406
 407 #endif // INCLUDED_CONNECTIVITY_PARAMETERS_HXX
 408
 409 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */