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         349 :     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         349 :         : m_osName(osName), m_osLeftTableName(osLeftTableName),
      72         349 :           m_osRightTableName(osRightTableName), m_eCardinality(eCardinality)
      73             :     {
      74         349 :     }
      75             : 
      76             :     /** Get the name of the relationship */
      77         393 :     const std::string &GetName() const
      78             :     {
      79         393 :         return m_osName;
      80             :     }
      81             : 
      82             :     /** Get the cardinality of the relationship */
      83         247 :     GDALRelationshipCardinality GetCardinality() const
      84             :     {
      85         247 :         return m_eCardinality;
      86             :     }
      87             : 
      88             :     /** Get the name of the left (or base/origin) table in the relationship.
      89             :      *
      90             :      * @see GetRightTableName()
      91             :      */
      92         202 :     const std::string &GetLeftTableName() const
      93             :     {
      94         202 :         return m_osLeftTableName;
      95             :     }
      96             : 
      97             :     /** Get the name of the right (or related/destination) table in the
      98             :      * relationship */
      99         197 :     const std::string &GetRightTableName() const
     100             :     {
     101         197 :         return m_osRightTableName;
     102             :     }
     103             : 
     104             :     /** Get the name of the mapping table for many-to-many relationships.
     105             :      *
     106             :      * @see SetMappingTableName()
     107             :      */
     108         160 :     const std::string &GetMappingTableName() const
     109             :     {
     110         160 :         return m_osMappingTableName;
     111             :     }
     112             : 
     113             :     /** Sets the name of the mapping table for many-to-many relationships.
     114             :      *
     115             :      * @see GetMappingTableName()
     116             :      */
     117         113 :     void SetMappingTableName(const std::string &osName)
     118             :     {
     119         113 :         m_osMappingTableName = osName;
     120         113 :     }
     121             : 
     122             :     /** Get the names of the participating fields from the left table in the
     123             :      * relationship.
     124             :      *
     125             :      * @see GetRightTableFields()
     126             :      * @see SetLeftTableFields()
     127             :      */
     128         157 :     const std::vector<std::string> &GetLeftTableFields() const
     129             :     {
     130         157 :         return m_osListLeftTableFields;
     131             :     }
     132             : 
     133             :     /** Get the names of the participating fields from the right table in the
     134             :      * relationship.
     135             :      *
     136             :      * @see GetLeftTableFields()
     137             :      * @see SetRightTableFields()
     138             :      */
     139         151 :     const std::vector<std::string> &GetRightTableFields() const
     140             :     {
     141         151 :         return m_osListRightTableFields;
     142             :     }
     143             : 
     144             :     /** Sets the names of the participating fields from the left table in the
     145             :      * relationship.
     146             :      *
     147             :      * @see GetLeftTableFields()
     148             :      * @see SetRightTableFields()
     149             :      */
     150         362 :     void SetLeftTableFields(const std::vector<std::string> &osListFields)
     151             :     {
     152         362 :         m_osListLeftTableFields = osListFields;
     153         362 :     }
     154             : 
     155             :     /** Sets the names of the participating fields from the right table in the
     156             :      * relationship.
     157             :      *
     158             :      * @see GetRightTableFields()
     159             :      * @see SetLeftTableFields()
     160             :      */
     161         363 :     void SetRightTableFields(const std::vector<std::string> &osListFields)
     162             :     {
     163         363 :         m_osListRightTableFields = osListFields;
     164         363 :     }
     165             : 
     166             :     /** Get the names of the mapping table fields which correspond to the
     167             :      * participating fields from the left table in the relationship.
     168             :      *
     169             :      * @see GetRightMappingTableFields()
     170             :      * @see SetLeftMappingTableFields()
     171             :      */
     172          61 :     const std::vector<std::string> &GetLeftMappingTableFields() const
     173             :     {
     174          61 :         return m_osListLeftMappingTableFields;
     175             :     }
     176             : 
     177             :     /** Get the names of the mapping table fields which correspond to the
     178             :      * participating fields from the right table in the relationship.
     179             :      *
     180             :      * @see GetLeftMappingTableFields()
     181             :      * @see SetRightMappingTableFields()
     182             :      */
     183          61 :     const std::vector<std::string> &GetRightMappingTableFields() const
     184             :     {
     185          61 :         return m_osListRightMappingTableFields;
     186             :     }
     187             : 
     188             :     /** Sets the names of the mapping table fields which correspond to the
     189             :      * participating fields from the left table in the relationship.
     190             :      *
     191             :      * @see GetLeftMappingTableFields()
     192             :      * @see SetRightMappingTableFields()
     193             :      */
     194         313 :     void SetLeftMappingTableFields(const std::vector<std::string> &osListFields)
     195             :     {
     196         313 :         m_osListLeftMappingTableFields = osListFields;
     197         313 :     }
     198             : 
     199             :     /** Sets the names of the mapping table fields which correspond to the
     200             :      * participating fields from the right table in the relationship.
     201             :      *
     202             :      * @see GetRightMappingTableFields()
     203             :      * @see SetLeftMappingTableFields()
     204             :      */
     205             :     void
     206         313 :     SetRightMappingTableFields(const std::vector<std::string> &osListFields)
     207             :     {
     208         313 :         m_osListRightMappingTableFields = osListFields;
     209         313 :     }
     210             : 
     211             :     /** Get the type of the relationship.
     212             :      *
     213             :      * @see SetType()
     214             :      */
     215         111 :     GDALRelationshipType GetType() const
     216             :     {
     217         111 :         return m_eType;
     218             :     }
     219             : 
     220             :     /** Sets the type of the relationship.
     221             :      *
     222             :      * @see GetType()
     223             :      */
     224         263 :     void SetType(GDALRelationshipType eType)
     225             :     {
     226         263 :         m_eType = eType;
     227         263 :     }
     228             : 
     229             :     /** Get the label of the forward path for the relationship.
     230             :      *
     231             :      * The forward and backward path labels are free-form, user-friendly strings
     232             :      * which can be used to generate descriptions of the relationship between
     233             :      * features from the right and left tables.
     234             :      *
     235             :      * E.g. when the left table contains buildings and the right table contains
     236             :      * furniture, the forward path label could be "contains" and the backward
     237             :      * path label could be "is located within". A client could then generate a
     238             :      * user friendly description string such as "fire hose 1234 is located
     239             :      * within building 15a".
     240             :      *
     241             :      * @see SetForwardPathLabel()
     242             :      * @see GetBackwardPathLabel()
     243             :      */
     244          53 :     const std::string &GetForwardPathLabel() const
     245             :     {
     246          53 :         return m_osForwardPathLabel;
     247             :     }
     248             : 
     249             :     /** Sets the label of the forward path for the relationship.
     250             :      *
     251             :      * The forward and backward path labels are free-form, user-friendly strings
     252             :      * which can be used to generate descriptions of the relationship between
     253             :      * features from the right and left tables.
     254             :      *
     255             :      * E.g. when the left table contains buildings and the right table contains
     256             :      * furniture, the forward path label could be "contains" and the backward
     257             :      * path label could be "is located within". A client could then generate a
     258             :      * user friendly description string such as "fire hose 1234 is located
     259             :      * within building 15a".
     260             :      *
     261             :      * @see GetForwardPathLabel()
     262             :      * @see SetBackwardPathLabel()
     263             :      */
     264         260 :     void SetForwardPathLabel(const std::string &osLabel)
     265             :     {
     266         260 :         m_osForwardPathLabel = osLabel;
     267         260 :     }
     268             : 
     269             :     /** Get the label of the backward path for the relationship.
     270             :      *
     271             :      * The forward and backward path labels are free-form, user-friendly strings
     272             :      * which can be used to generate descriptions of the relationship between
     273             :      * features from the right and left tables.
     274             :      *
     275             :      * E.g. when the left table contains buildings and the right table contains
     276             :      * furniture, the forward path label could be "contains" and the backward
     277             :      * path label could be "is located within". A client could then generate a
     278             :      * user friendly description string such as "fire hose 1234 is located
     279             :      * within building 15a".
     280             :      *
     281             :      * @see SetBackwardPathLabel()
     282             :      * @see GetForwardPathLabel()
     283             :      */
     284          53 :     const std::string &GetBackwardPathLabel() const
     285             :     {
     286          53 :         return m_osBackwardPathLabel;
     287             :     }
     288             : 
     289             :     /** Sets the label of the backward path for the relationship.
     290             :      *
     291             :      * The forward and backward path labels are free-form, user-friendly strings
     292             :      * which can be used to generate descriptions of the relationship between
     293             :      * features from the right and left tables.
     294             :      *
     295             :      * E.g. when the left table contains buildings and the right table contains
     296             :      * furniture, the forward path label could be "contains" and the backward
     297             :      * path label could be "is located within". A client could then generate a
     298             :      * user friendly description string such as "fire hose 1234 is located
     299             :      * within building 15a".
     300             :      *
     301             :      * @see GetBackwardPathLabel()
     302             :      * @see SetForwardPathLabel()
     303             :      */
     304         260 :     void SetBackwardPathLabel(const std::string &osLabel)
     305             :     {
     306         260 :         m_osBackwardPathLabel = osLabel;
     307         260 :     }
     308             : 
     309             :     /** Get the type string of the related table.
     310             :      *
     311             :      * This a free-form string representing the type of related features, where
     312             :      * the exact interpretation is format dependent. For instance, table types
     313             :      * from GeoPackage relationships will directly reflect the categories from
     314             :      * the GeoPackage related tables extension (i.e. "media", "simple
     315             :      * attributes", "features", "attributes" and "tiles").
     316             :      *
     317             :      * @see SetRelatedTableType()
     318             :      */
     319         144 :     const std::string &GetRelatedTableType() const
     320             :     {
     321         144 :         return m_osRelatedTableType;
     322             :     }
     323             : 
     324             :     /** Sets the type string of the related table.
     325             :      *
     326             :      * This a free-form string representing the type of related features, where
     327             :      * the exact interpretation is format dependent. For instance, table types
     328             :      * from GeoPackage relationships will directly reflect the categories from
     329             :      * the GeoPackage related tables extension (i.e. "media", "simple
     330             :      * attributes", "features", "attributes" and "tiles").
     331             :      *
     332             :      * @see GetRelatedTableType()
     333             :      */
     334         340 :     void SetRelatedTableType(const std::string &osType)
     335             :     {
     336         340 :         m_osRelatedTableType = osType;
     337         340 :     }
     338             : 
     339             :     /** Convert a GDALRelationship* to a GDALRelationshipH.
     340             :      */
     341          81 :     static inline GDALRelationshipH ToHandle(GDALRelationship *poRelationship)
     342             :     {
     343          81 :         return static_cast<GDALRelationshipH>(poRelationship);
     344             :     }
     345             : 
     346             :     /** Convert a GDALRelationshipH to a GDALRelationship*.
     347             :      */
     348         706 :     static inline GDALRelationship *FromHandle(GDALRelationshipH hRelationship)
     349             :     {
     350         706 :         return static_cast<GDALRelationship *>(hRelationship);
     351             :     }
     352             : };
     353             : 
     354             : #endif