Line data    Source code

       1             : /******************************************************************************
       2             :  *
       3             :  * Project:  GDAL
       4             :  * Purpose:  Declaration of GDALRelationship class
       5             :  * Author:   Nyall Dawson, <nyall dot dawson at gmail dot com>
       6             :  *
       7             :  ******************************************************************************
       8             :  * Copyright (c) 2022, Nyall Dawson <nyall dot dawson at gmail dot comg>
       9             :  *
      10             :  * SPDX-License-Identifier: MIT
      11             :  ****************************************************************************/
      12             : 
      13             : #ifndef GDALRELATIONSHIP_H_INCLUDED
      14             : #define GDALRELATIONSHIP_H_INCLUDED
      15             : 
      16             : #include "cpl_port.h"
      17             : #include "gdal.h"
      18             : 
      19             : #include <string>
      20             : #include <vector>
      21             : 
      22             : /************************************************************************/
      23             : /*                            Relationships                             */
      24             : /************************************************************************/
      25             : 
      26             : /**
      27             :  * Definition of a table relationship.
      28             :  *
      29             :  * GDALRelationship describes the relationship between two tables, including
      30             :  * properties such as the cardinality of the relationship and the participating
      31             :  * tables.
      32             :  *
      33             :  * Not all relationship properties are supported by all data formats.
      34             :  *
      35             :  * @since GDAL 3.6
      36             :  */
      37             : class CPL_DLL GDALRelationship
      38             : {
      39             :   protected:
      40             :     /*! @cond Doxygen_Suppress */
      41             :     std::string m_osName{};
      42             :     std::string m_osLeftTableName{};
      43             :     std::string m_osRightTableName{};
      44             :     GDALRelationshipCardinality m_eCardinality =
      45             :         GDALRelationshipCardinality::GRC_ONE_TO_MANY;
      46             :     std::string m_osMappingTableName{};
      47             :     std::vector<std::string> m_osListLeftTableFields{};
      48             :     std::vector<std::string> m_osListRightTableFields{};
      49             :     std::vector<std::string> m_osListLeftMappingTableFields{};
      50             :     std::vector<std::string> m_osListRightMappingTableFields{};
      51             :     GDALRelationshipType m_eType = GDALRelationshipType::GRT_ASSOCIATION;
      52             :     std::string m_osForwardPathLabel{};
      53             :     std::string m_osBackwardPathLabel{};
      54             :     std::string m_osRelatedTableType{};
      55             : 
      56             :     /*! @endcond */
      57             : 
      58             :   public:
      59             :     /**
      60             :      * Constructor for a relationship between two tables.
      61             :      * @param osName relationship name
      62             :      * @param osLeftTableName left table name
      63             :      * @param osRightTableName right table name
      64             :      * @param eCardinality cardinality of relationship
      65             :      */
      66         359 :     GDALRelationship(const std::string &osName,
      67             :                      const std::string &osLeftTableName,
      68             :                      const std::string &osRightTableName,
      69             :                      GDALRelationshipCardinality eCardinality =
      70             :                          GDALRelationshipCardinality::GRC_ONE_TO_MANY)
      71         359 :         : m_osName(osName), m_osLeftTableName(osLeftTableName),
      72         359 :           m_osRightTableName(osRightTableName), m_eCardinality(eCardinality)
      73             :     {
      74         359 :     }
      75             : 
      76             :     /** Get the name of the relationship */
      77         396 :     const std::string &GetName() const
      78             :     {
      79         396 :         return m_osName;
      80             :     }
      81             : 
      82             :     /** Get the cardinality of the relationship */
      83         249 :     GDALRelationshipCardinality GetCardinality() const
      84             :     {
      85         249 :         return m_eCardinality;
      86             :     }
      87             : 
      88             :     /** Get the name of the left (or base/origin) table in the relationship.
      89             :      *
      90             :      * @see GetRightTableName()
      91             :      * @see SetLeftTableName()
      92             :      */
      93         217 :     const std::string &GetLeftTableName() const
      94             :     {
      95         217 :         return m_osLeftTableName;
      96             :     }
      97             : 
      98             :     /** Sets the name of the left (or base/origin) table in the relationship.
      99             :      *
     100             :      * @see GetLeftTableName()
     101             :      * @since 3.13
     102             :      */
     103           4 :     void SetLeftTableName(const std::string &osName)
     104             :     {
     105           4 :         m_osLeftTableName = osName;
     106           4 :     }
     107             : 
     108             :     /** Get the name of the right (or related/destination) table in the
     109             :      * relationship.
     110             :      *
     111             :      * @see GetLeftTableName()
     112             :      * @see SetRightTableName()
     113             :      */
     114         213 :     const std::string &GetRightTableName() const
     115             :     {
     116         213 :         return m_osRightTableName;
     117             :     }
     118             : 
     119             :     /** Sets the name of the right (or related/destination) table in the
     120             :      * relationship.
     121             :      *
     122             :      * @see GetRightTableName()
     123             :      * @since 3.13
     124             :      */
     125           4 :     void SetRightTableName(const std::string &osName)
     126             :     {
     127           4 :         m_osRightTableName = osName;
     128           4 :     }
     129             : 
     130             :     /** Get the name of the mapping table for many-to-many relationships.
     131             :      *
     132             :      * @see SetMappingTableName()
     133             :      */
     134         176 :     const std::string &GetMappingTableName() const
     135             :     {
     136         176 :         return m_osMappingTableName;
     137             :     }
     138             : 
     139             :     /** Sets the name of the mapping table for many-to-many relationships.
     140             :      *
     141             :      * @see GetMappingTableName()
     142             :      */
     143         122 :     void SetMappingTableName(const std::string &osName)
     144             :     {
     145         122 :         m_osMappingTableName = osName;
     146         122 :     }
     147             : 
     148             :     /** Get the names of the participating fields from the left table in the
     149             :      * relationship.
     150             :      *
     151             :      * @see GetRightTableFields()
     152             :      * @see SetLeftTableFields()
     153             :      */
     154         161 :     const std::vector<std::string> &GetLeftTableFields() const
     155             :     {
     156         161 :         return m_osListLeftTableFields;
     157             :     }
     158             : 
     159             :     /** Get the names of the participating fields from the right table in the
     160             :      * relationship.
     161             :      *
     162             :      * @see GetLeftTableFields()
     163             :      * @see SetRightTableFields()
     164             :      */
     165         155 :     const std::vector<std::string> &GetRightTableFields() const
     166             :     {
     167         155 :         return m_osListRightTableFields;
     168             :     }
     169             : 
     170             :     /** Sets the names of the participating fields from the left table in the
     171             :      * relationship.
     172             :      *
     173             :      * @see GetLeftTableFields()
     174             :      * @see SetRightTableFields()
     175             :      */
     176         369 :     void SetLeftTableFields(const std::vector<std::string> &osListFields)
     177             :     {
     178         369 :         m_osListLeftTableFields = osListFields;
     179         369 :     }
     180             : 
     181             :     /** Sets the names of the participating fields from the right table in the
     182             :      * relationship.
     183             :      *
     184             :      * @see GetRightTableFields()
     185             :      * @see SetLeftTableFields()
     186             :      */
     187         370 :     void SetRightTableFields(const std::vector<std::string> &osListFields)
     188             :     {
     189         370 :         m_osListRightTableFields = osListFields;
     190         370 :     }
     191             : 
     192             :     /** Get the names of the mapping table fields which correspond to the
     193             :      * participating fields from the left table in the relationship.
     194             :      *
     195             :      * @see GetRightMappingTableFields()
     196             :      * @see SetLeftMappingTableFields()
     197             :      */
     198          61 :     const std::vector<std::string> &GetLeftMappingTableFields() const
     199             :     {
     200          61 :         return m_osListLeftMappingTableFields;
     201             :     }
     202             : 
     203             :     /** Get the names of the mapping table fields which correspond to the
     204             :      * participating fields from the right table in the relationship.
     205             :      *
     206             :      * @see GetLeftMappingTableFields()
     207             :      * @see SetRightMappingTableFields()
     208             :      */
     209          61 :     const std::vector<std::string> &GetRightMappingTableFields() const
     210             :     {
     211          61 :         return m_osListRightMappingTableFields;
     212             :     }
     213             : 
     214             :     /** Sets the names of the mapping table fields which correspond to the
     215             :      * participating fields from the left table in the relationship.
     216             :      *
     217             :      * @see GetLeftMappingTableFields()
     218             :      * @see SetRightMappingTableFields()
     219             :      */
     220         318 :     void SetLeftMappingTableFields(const std::vector<std::string> &osListFields)
     221             :     {
     222         318 :         m_osListLeftMappingTableFields = osListFields;
     223         318 :     }
     224             : 
     225             :     /** Sets the names of the mapping table fields which correspond to the
     226             :      * participating fields from the right table in the relationship.
     227             :      *
     228             :      * @see GetRightMappingTableFields()
     229             :      * @see SetLeftMappingTableFields()
     230             :      */
     231             :     void
     232         318 :     SetRightMappingTableFields(const std::vector<std::string> &osListFields)
     233             :     {
     234         318 :         m_osListRightMappingTableFields = osListFields;
     235         318 :     }
     236             : 
     237             :     /** Get the type of the relationship.
     238             :      *
     239             :      * @see SetType()
     240             :      */
     241         111 :     GDALRelationshipType GetType() const
     242             :     {
     243         111 :         return m_eType;
     244             :     }
     245             : 
     246             :     /** Sets the type of the relationship.
     247             :      *
     248             :      * @see GetType()
     249             :      */
     250         263 :     void SetType(GDALRelationshipType eType)
     251             :     {
     252         263 :         m_eType = eType;
     253         263 :     }
     254             : 
     255             :     /** Get the label of the forward path for the relationship.
     256             :      *
     257             :      * The forward and backward path labels are free-form, user-friendly strings
     258             :      * which can be used to generate descriptions of the relationship between
     259             :      * features from the right and left tables.
     260             :      *
     261             :      * E.g. when the left table contains buildings and the right table contains
     262             :      * furniture, the forward path label could be "contains" and the backward
     263             :      * path label could be "is located within". A client could then generate a
     264             :      * user friendly description string such as "fire hose 1234 is located
     265             :      * within building 15a".
     266             :      *
     267             :      * @see SetForwardPathLabel()
     268             :      * @see GetBackwardPathLabel()
     269             :      */
     270          53 :     const std::string &GetForwardPathLabel() const
     271             :     {
     272          53 :         return m_osForwardPathLabel;
     273             :     }
     274             : 
     275             :     /** Sets the label of the forward path for the relationship.
     276             :      *
     277             :      * The forward and backward path labels are free-form, user-friendly strings
     278             :      * which can be used to generate descriptions of the relationship between
     279             :      * features from the right and left tables.
     280             :      *
     281             :      * E.g. when the left table contains buildings and the right table contains
     282             :      * furniture, the forward path label could be "contains" and the backward
     283             :      * path label could be "is located within". A client could then generate a
     284             :      * user friendly description string such as "fire hose 1234 is located
     285             :      * within building 15a".
     286             :      *
     287             :      * @see GetForwardPathLabel()
     288             :      * @see SetBackwardPathLabel()
     289             :      */
     290         260 :     void SetForwardPathLabel(const std::string &osLabel)
     291             :     {
     292         260 :         m_osForwardPathLabel = osLabel;
     293         260 :     }
     294             : 
     295             :     /** Get the label of the backward path for the relationship.
     296             :      *
     297             :      * The forward and backward path labels are free-form, user-friendly strings
     298             :      * which can be used to generate descriptions of the relationship between
     299             :      * features from the right and left tables.
     300             :      *
     301             :      * E.g. when the left table contains buildings and the right table contains
     302             :      * furniture, the forward path label could be "contains" and the backward
     303             :      * path label could be "is located within". A client could then generate a
     304             :      * user friendly description string such as "fire hose 1234 is located
     305             :      * within building 15a".
     306             :      *
     307             :      * @see SetBackwardPathLabel()
     308             :      * @see GetForwardPathLabel()
     309             :      */
     310          53 :     const std::string &GetBackwardPathLabel() const
     311             :     {
     312          53 :         return m_osBackwardPathLabel;
     313             :     }
     314             : 
     315             :     /** Sets the label of the backward path for the relationship.
     316             :      *
     317             :      * The forward and backward path labels are free-form, user-friendly strings
     318             :      * which can be used to generate descriptions of the relationship between
     319             :      * features from the right and left tables.
     320             :      *
     321             :      * E.g. when the left table contains buildings and the right table contains
     322             :      * furniture, the forward path label could be "contains" and the backward
     323             :      * path label could be "is located within". A client could then generate a
     324             :      * user friendly description string such as "fire hose 1234 is located
     325             :      * within building 15a".
     326             :      *
     327             :      * @see GetBackwardPathLabel()
     328             :      * @see SetForwardPathLabel()
     329             :      */
     330         260 :     void SetBackwardPathLabel(const std::string &osLabel)
     331             :     {
     332         260 :         m_osBackwardPathLabel = osLabel;
     333         260 :     }
     334             : 
     335             :     /** Get the type string of the related table.
     336             :      *
     337             :      * This a free-form string representing the type of related features, where
     338             :      * the exact interpretation is format dependent. For instance, table types
     339             :      * from GeoPackage relationships will directly reflect the categories from
     340             :      * the GeoPackage related tables extension (i.e. "media", "simple
     341             :      * attributes", "features", "attributes" and "tiles").
     342             :      *
     343             :      * @see SetRelatedTableType()
     344             :      */
     345         150 :     const std::string &GetRelatedTableType() const
     346             :     {
     347         150 :         return m_osRelatedTableType;
     348             :     }
     349             : 
     350             :     /** Sets the type string of the related table.
     351             :      *
     352             :      * This a free-form string representing the type of related features, where
     353             :      * the exact interpretation is format dependent. For instance, table types
     354             :      * from GeoPackage relationships will directly reflect the categories from
     355             :      * the GeoPackage related tables extension (i.e. "media", "simple
     356             :      * attributes", "features", "attributes" and "tiles").
     357             :      *
     358             :      * @see GetRelatedTableType()
     359             :      */
     360         347 :     void SetRelatedTableType(const std::string &osType)
     361             :     {
     362         347 :         m_osRelatedTableType = osType;
     363         347 :     }
     364             : 
     365             :     /** Convert a GDALRelationship* to a GDALRelationshipH.
     366             :      */
     367          97 :     static inline GDALRelationshipH ToHandle(GDALRelationship *poRelationship)
     368             :     {
     369          97 :         return static_cast<GDALRelationshipH>(poRelationship);
     370             :     }
     371             : 
     372             :     /** Convert a GDALRelationshipH to a GDALRelationship*.
     373             :      */
     374         738 :     static inline GDALRelationship *FromHandle(GDALRelationshipH hRelationship)
     375             :     {
     376         738 :         return static_cast<GDALRelationship *>(hRelationship);
     377             :     }
     378             : };
     379             : 
     380             : #endif