Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :     qgsvectorlayerjoininfo.h
       3                 :            :     ---------------------
       4                 :            :     begin                : January 2017
       5                 :            :     copyright            : (C) 2017 by Martin Dobias
       6                 :            :     email                : wonder dot sk at gmail dot com
       7                 :            :  ***************************************************************************
       8                 :            :  *                                                                         *
       9                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      10                 :            :  *   it under the terms of the GNU General Public License as published by  *
      11                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      12                 :            :  *   (at your option) any later version.                                   *
      13                 :            :  *                                                                         *
      14                 :            :  ***************************************************************************/
      15                 :            : #ifndef QGSVECTORLAYERJOININFO_H
      16                 :            : #define QGSVECTORLAYERJOININFO_H
      17                 :            : 
      18                 :            : #include <QHash>
      19                 :            : #include <QString>
      20                 :            : #include <QStringList>
      21                 :            : 
      22                 :            : #include "qgsfeature.h"
      23                 :            : 
      24                 :            : #include "qgsvectorlayerref.h"
      25                 :            : 
      26                 :            : /**
      27                 :            :  * \ingroup core
      28                 :            :  * \brief Defines left outer join from our vector layer to some other vector layer.
      29                 :            :  * The join is done based on [our layer].targetField = [join layer].joinField
      30                 :            :  *
      31                 :            :  * \since QGIS 3.0
      32                 :            :  */
      33                 :          0 : class CORE_EXPORT QgsVectorLayerJoinInfo
      34                 :            : {
      35                 :            :   public:
      36                 :            : 
      37                 :            :     /**
      38                 :            :      * Constructor for QgsVectorLayerJoinInfo.
      39                 :            :      */
      40                 :          0 :     QgsVectorLayerJoinInfo() = default;
      41                 :            : 
      42                 :            :     //! Sets weak reference to the joined layer
      43                 :          0 :     void setJoinLayer( QgsVectorLayer *layer ) { mJoinLayerRef = QgsVectorLayerRef( layer ); }
      44                 :            :     //! Returns joined layer (may be NULLPTR if the reference was set by layer ID and not resolved yet)
      45                 :          0 :     QgsVectorLayer *joinLayer() const { return mJoinLayerRef.get(); }
      46                 :            : 
      47                 :            :     //! Sets ID of the joined layer. It will need to be overwritten by setJoinLayer() to a reference to real layer
      48                 :          0 :     void setJoinLayerId( const QString &layerId ) { mJoinLayerRef = QgsVectorLayerRef( layerId ); }
      49                 :            :     //! ID of the joined layer - may be used to resolve reference to the joined layer
      50                 :          0 :     QString joinLayerId() const { return mJoinLayerRef.layerId; }
      51                 :            : 
      52                 :            :     //! Sets name of the field of our layer that will be used for join
      53                 :          0 :     void setTargetFieldName( const QString &fieldName ) { mTargetFieldName = fieldName; }
      54                 :            :     //! Returns name of the field of our layer that will be used for join
      55                 :          0 :     QString targetFieldName() const { return mTargetFieldName; }
      56                 :            : 
      57                 :            :     //! Sets name of the field of joined layer that will be used for join
      58                 :          0 :     void setJoinFieldName( const QString &fieldName ) { mJoinFieldName = fieldName; }
      59                 :            :     //! Returns name of the field of joined layer that will be used for join
      60                 :          0 :     QString joinFieldName() const { return mJoinFieldName; }
      61                 :            : 
      62                 :            :     //! Sets prefix of fields from the joined layer. If NULLPTR, joined layer's name will be used.
      63                 :          0 :     void setPrefix( const QString &prefix ) { mPrefix = prefix; }
      64                 :            :     //! Returns prefix of fields from the joined layer. If NULLPTR, joined layer's name will be used.
      65                 :          0 :     QString prefix() const { return mPrefix; }
      66                 :            : 
      67                 :            :     //! Sets whether values from the joined layer should be cached in memory to speed up lookups
      68                 :            :     void setUsingMemoryCache( bool enabled );
      69                 :            : 
      70                 :            :     /**
      71                 :            :      * Returns whether values from the joined layer should be cached in memory to speed up lookups.
      72                 :            :      * Will return FALSE if upsertOnEdit is enabled.
      73                 :            :      */
      74                 :            :     bool isUsingMemoryCache() const;
      75                 :            : 
      76                 :            :     /**
      77                 :            :      * Returns whether the form has to be dynamically updated with joined fields
      78                 :            :      *  when  a feature is being created in the target layer.
      79                 :            :      * \since QGIS 3.0
      80                 :            :      */
      81                 :          0 :     bool isDynamicFormEnabled() const { return mDynamicForm; }
      82                 :            : 
      83                 :            :     /**
      84                 :            :      * Sets whether the form has to be dynamically updated with joined fields
      85                 :            :      *  when a feature is being created in the target layer.
      86                 :            :      * \since QGIS 3.0
      87                 :            :      */
      88                 :          0 :     void setDynamicFormEnabled( bool enabled ) { mDynamicForm = enabled; }
      89                 :            : 
      90                 :            :     /**
      91                 :            :      * Returns whether joined fields may be edited through the form of
      92                 :            :      *  the target layer.
      93                 :            :      * \since QGIS 3.0
      94                 :            :      */
      95                 :          0 :     bool isEditable() const { return mEditable; }
      96                 :            : 
      97                 :            :     /**
      98                 :            :      * Sets whether the form of the target layer allows editing joined fields.
      99                 :            :      * \since QGIS 3.0
     100                 :            :      */
     101                 :            :     void setEditable( bool enabled );
     102                 :            : 
     103                 :            :     /**
     104                 :            :      * Returns whether a feature created on the target layer has to impact
     105                 :            :      *  the joined layer by creating a new feature if necessary.
     106                 :            :      * \since QGIS 3.0
     107                 :            :      */
     108                 :          0 :     bool hasUpsertOnEdit() const { return mUpsertOnEdit; }
     109                 :            : 
     110                 :            :     /**
     111                 :            :      * Sets whether a feature created on the target layer has to impact
     112                 :            :      *  the joined layer by creating a new feature if necessary.
     113                 :            :      * \since QGIS 3.0
     114                 :            :      */
     115                 :          0 :     void setUpsertOnEdit( bool enabled ) { mUpsertOnEdit = enabled; }
     116                 :            : 
     117                 :            :     /**
     118                 :            :      * Returns whether a feature deleted on the target layer has to impact the
     119                 :            :      *  joined layer by deleting the corresponding joined feature.
     120                 :            :      * \since QGIS 3.0
     121                 :            :      */
     122                 :          0 :     bool hasCascadedDelete() const { return mCascadedDelete; }
     123                 :            : 
     124                 :            :     /**
     125                 :            :      * Sets whether a feature deleted on the target layer has to impact the
     126                 :            :      *  joined layer by deleting the corresponding joined feature.
     127                 :            :      * \since QGIS 3.0
     128                 :            :      */
     129                 :          0 :     void setCascadedDelete( bool enabled ) { mCascadedDelete = enabled; }
     130                 :            : 
     131                 :            :     /**
     132                 :            :      * Returns the prefixed name of the field.
     133                 :            :      * \param field the field
     134                 :            :      * \returns the prefixed name of the field
     135                 :            :      * \since QGIS 3.0
     136                 :            :      */
     137                 :            :     QString prefixedFieldName( const QgsField &field ) const;
     138                 :            : 
     139                 :            :     /**
     140                 :            :      * Extract the join feature from the target feature for the current
     141                 :            :      *  join layer information.
     142                 :            :      * \param feature A feature from the target layer
     143                 :            :      * \returns the corresponding joined feature
     144                 :            :      * \since QGIS 3.0
     145                 :            :      */
     146                 :            :     QgsFeature extractJoinedFeature( const QgsFeature &feature ) const;
     147                 :            : 
     148                 :            :     /**
     149                 :            :      * Sets a list of fields to ignore whatever happens.
     150                 :            :      *
     151                 :            :      * \deprecated use setJoinFieldNamesBlockList() instead
     152                 :            :      */
     153                 :            :     Q_DECL_DEPRECATED void setJoinFieldNamesBlackList( const QStringList &blackList ) SIP_DEPRECATED { mBlockList = blackList; }
     154                 :            : 
     155                 :            :     /**
     156                 :            :      * Returns the list of fields to ignore.
     157                 :            :      *
     158                 :            :      * \deprecated use joinFieldNamesBlockList() instead
     159                 :            :      */
     160                 :            :     Q_DECL_DEPRECATED QStringList joinFieldNamesBlackList() const SIP_DEPRECATED { return mBlockList; }
     161                 :            : 
     162                 :            :     /**
     163                 :            :      * Sets a \a list of fields to ignore whatever happens.
     164                 :            :      *
     165                 :            :      * \see joinFieldNamesBlockList()
     166                 :            :      * \since QGIS 3.14
     167                 :            :      */
     168                 :          0 :     void setJoinFieldNamesBlockList( const QStringList &list ) { mBlockList = list; }
     169                 :            : 
     170                 :            :     /**
     171                 :            :      * Returns the list of fields to ignore.
     172                 :            :      *
     173                 :            :      * \see setJoinFieldNamesBlockList()
     174                 :            :      * \since QGIS 3.14
     175                 :            :      */
     176                 :          0 :     QStringList joinFieldNamesBlockList() const { return mBlockList; }
     177                 :            : 
     178                 :            :     /**
     179                 :            :      * Returns TRUE if blocklisted fields is not empty or if a subset of names
     180                 :            :      * has been set.
     181                 :            :      *
     182                 :            :      * \since QGIS 3.0
     183                 :            :      */
     184                 :            :     bool hasSubset( bool blocklisted = true ) const;
     185                 :            : 
     186                 :            :     /**
     187                 :            :      * Returns the list of field names to use for joining considering
     188                 :            :      * blocklisted fields and subset.
     189                 :            :      *
     190                 :            :      * \since QGIS 3.0
     191                 :            :      */
     192                 :            :     static QStringList joinFieldNamesSubset( const QgsVectorLayerJoinInfo &info, bool blocklisted = true );
     193                 :            : 
     194                 :          0 :     bool operator==( const QgsVectorLayerJoinInfo &other ) const
     195                 :            :     {
     196                 :          0 :       return mTargetFieldName == other.mTargetFieldName &&
     197                 :          0 :              mJoinLayerRef.layerId == other.mJoinLayerRef.layerId &&
     198                 :          0 :              mJoinFieldName == other.mJoinFieldName &&
     199                 :          0 :              mJoinFieldsSubset == other.mJoinFieldsSubset &&
     200                 :          0 :              mMemoryCache == other.mMemoryCache &&
     201                 :          0 :              mPrefix == other.mPrefix;
     202                 :            :     }
     203                 :            : 
     204                 :            :     /**
     205                 :            :      * Sets the subset of fields to be used from joined layer.
     206                 :            :      *
     207                 :            :      * Ownership of \a fileNamesSubset is transferred. A \a fieldNameSubset of NULLPTR indicates that all fields should be used.
     208                 :            :      *
     209                 :            :      * \see joinFieldNamesSubset()
     210                 :            :      * \since QGIS 2.6
     211                 :            :     */
     212                 :          0 :     void setJoinFieldNamesSubset( QStringList *fieldNamesSubset SIP_TRANSFER ) { mJoinFieldsSubset = std::shared_ptr<QStringList>( fieldNamesSubset ); }
     213                 :            : 
     214                 :            :     /**
     215                 :            :      * Returns the subset of fields to be used from joined layer.
     216                 :            :      *
     217                 :            :      * All fields will be used if NULLPTR is returned.
     218                 :            :      *
     219                 :            :      * \see setJoinFieldNamesSubset()
     220                 :            :      *
     221                 :            :      * \since QGIS 2.6
     222                 :            :     */
     223                 :          0 :     QStringList *joinFieldNamesSubset() const { return mJoinFieldsSubset.get(); }
     224                 :            : 
     225                 :            :   protected:
     226                 :            :     //! Join field in the target layer
     227                 :            :     QString mTargetFieldName;
     228                 :            :     //! Weak reference to the joined layer
     229                 :            :     QgsVectorLayerRef mJoinLayerRef;
     230                 :            :     //! Join field in the source layer
     231                 :            :     QString mJoinFieldName;
     232                 :            : 
     233                 :            :     /**
     234                 :            :      * An optional prefix. If it is a Null string "{layername}_" will be used
     235                 :            :      * \since QGIS 2.8
     236                 :            :      */
     237                 :            :     QString mPrefix;
     238                 :            : 
     239                 :            :     //! True if the join is cached in virtual memory
     240                 :          0 :     bool mMemoryCache = false;
     241                 :            : 
     242                 :            :     //! Subset of fields to use from joined layer. NULLPTR = use all fields
     243                 :            :     std::shared_ptr<QStringList> mJoinFieldsSubset;
     244                 :            : 
     245                 :            :     // caching support
     246                 :            : 
     247                 :            :     friend class QgsVectorLayerJoinBuffer;
     248                 :            :     friend class QgsVectorLayerFeatureIterator;
     249                 :            : 
     250                 :            :     //! True if the cached join attributes need to be updated
     251                 :          0 :     bool cacheDirty = true;
     252                 :            : 
     253                 :          0 :     bool mDynamicForm = false;
     254                 :            : 
     255                 :          0 :     bool mEditable = false;
     256                 :            : 
     257                 :          0 :     bool mUpsertOnEdit = false;
     258                 :            : 
     259                 :          0 :     bool mCascadedDelete = false;
     260                 :            : 
     261                 :            :     QStringList mBlockList;
     262                 :            : 
     263                 :            :     //! Cache for joined attributes to provide fast lookup (size is 0 if no memory caching)
     264                 :            :     QHash< QString, QgsAttributes> cachedAttributes;
     265                 :            : 
     266                 :            : };
     267                 :            : 
     268                 :            : 
     269                 :            : #endif // QGSVECTORLAYERJOININFO_H