ENH: Adding missing methods in OGRVersionProxy, and adding documentation of the class as well

Modules/Adapters/GdalAdapters/include/otbOGRVersionProxy.h

@@ -19,6 +19,7 @@
 #define __otbOGRVersionProxy_h
 
 #include <string>
+#include <vector>
 #include "otbConfigure.h"
 
 #ifdef OTB_USE_GDAL_20
@@ -31,6 +32,22 @@ class OGRSFDriver;
 
 namespace otb
 {
+/** 
+ * \brief This class serves as a proxy hiding interface changes in gdal 2.0 
+ *
+ * This static class serves as a proxy hiding interface changes in OGR
+ * dataset between gdal 1.x (x>10) and gdal 2.x. It defines a common
+ * interface that should be used in place of calling directly the
+ * wrapped gdal methods.
+ * 
+ * Whenever GDALDataset and GDALDriver have to be used to open a
+ * vector dataset (or OGRDataSource an OGRSFDriver for gdal 1.x), one
+ * should use OGRVersionProxy type members GDALDatasetType and
+ * GDALDriverType.
+ * 
+ * See static method documentation for details.
+ */
+
 class OGRVersionProxy
 {
 public:
@@ -41,29 +58,145 @@ public:
   typedef OGRDataSource GDALDatasetType;
   typedef OGRSFDriver   GDALDriverType;
 #endif
-  
+
+  /** 
+   * This method opens a file, possibly in read-only mode, and returns
+   * a dataset.
+   *
+   * Calls OGRSFDriverRegistrar::Open for gdal 1.x implementation and GDALopenEx for
+   * gdal 2.x implementation.
+
+   * \param filename Filename of the file to open
+   * \param readOnly: If true, dataset is open in read-only mode.
+   * \return NULL if file could not be open.
+   */ 
   static GDALDatasetType * Open(const char * filename, bool readOnly = true);
-  
+
+  /**
+   * This method closes a dataset.
+   *
+   * Calls OGRDataSource::DestroyDataSource for gdal 1.x
+   * implementation and GDALClose for gdal 2.x implementation.
+   *
+   * \param dataset Pointer to the dataset to close. Will not be
+   * checked for null pointer.
+   */
   static void Close(GDALDatasetType * dataset);
-  
+
+  /**
+   * This method creates a new dataset.
+   *
+   * Calls OGRSFDriver::CreateDataSource for gdal 1.x implementation
+   * and GDALDriver::Create with (0,0) raster size for gdal 2.x
+   * implementation
+   * 
+   * \param driver Pointer to the driver used for creation. Will not
+   * be checked for null pointer.
+   *
+   * \param name Name of the dataset to create.
+   * 
+   * \return NULL if dataset could not be created.
+   */
   static GDALDatasetType * Create(GDALDriverType * driver, const char * name);
 
+
+  /**
+   * This method physically deletes an existing dataset.
+   * 
+   * Calls OGRDataSource::DeleteDataSource for gdal 1.x implementation
+   * and GDALDriver::Delete for gdal 2.x implementation.
+   *
+   * \param driver Pointer to the driver used for creation. Will not
+   * be checked for null pointer.
+   *
+   * \param name Name of the dataset to destroy.
+   */ 
   static bool Delete(GDALDriverType * driver, const char * name);
 
+  /**
+   * This method returns a pointer to the driver from its name.
+   * 
+   * Calls OGRSFDriverRegistrar::GetRegistrar()->GetDriverByName() for
+   * gdal 1.x implementation and
+   * GetGDALDriverManager()->GetDriverByName() for gdal 2.x
+   * implementation.
+   * 
+   * \param name Name of the driver to retrieve
+   * 
+   * \return NULL if no driver could be retrieved.
+   */
   static GDALDriverType *  GetDriverByName(const char * name);
 
+  /**
+   * Test driver and dataset for a given capability.
+   *
+   * Calls OGRSFDriver::TestCapability for gdal 1.x implementation and
+   * GDALDataset::TestCapability for gdal 2.x implementation.
+   *
+   * \param driver Pointer to the driver to test. Will not
+   * be checked for null pointer.
+   *
+   * \param dataset Pointer to the dataset to test. Will not be
+   * checked for null pointer.
+   *
+   * \param capability Name of the capability to test.
+   *
+   * \return True if the capability is supported.
+   */
   static bool TestCapability(const GDALDriverType * driver, const GDALDatasetType * dataset, const char * capability);
 
+  /**
+   * Sync dataset to disk.
+   *
+   * Calls OGRDataSource::SyncToDisk() for gdal 1.x implementation and
+   * GDALDataset::FlushCache() for gdal 2.x  implementation.
+   *
+   * \param dataset Pointer to the dataset to sync. Will not be
+   * checked for null pointer.
+   *
+   * \return True if sync went on without any error.
+   */
   static bool SyncToDisk(GDALDatasetType * dataset);
 
+  /**
+   * \return The name of the dataset class behind the implementation
+   * (OGRDataSource for gdal 1.x and GdalDataset for gdal 2.x)
+   */
   static std::string GetDatasetClassName();
 
+  /**
+   * \return The name of the driver class behind the implementation
+   * (OGRSFDriver for gdal 1.x and GDALDriver for gdal 2.x)
+   */
   static std::string GetDriverClassName();
 
-  static std::string GetDatasetDescription(GDALDatasetType * dataset);
+  /**
+   * Return the list of files composing the dataset.
+   * 
+   * Calls OGRDataSource::GetName() and wrap in string vector for gdal
+   * 1.x implementation, and GDALDataset::GetFileList and wrap in
+   * string vector for gdal 2.x implementation.
+   *  
+   * \param dataset Pointer to the dataset to get the file list from. Will not be
+   * checked for null pointer.
+   * 
+   * \return A vector of string containing the list of files.
+   */
+  static std::vector<std::string> GetFileListAsStringVector(GDALDatasetType * dataset);
+
+  /** 
+   * Return the list of available drivers.
+   *
+   * Calls OGRSFDriverRegistrar::GetRegistrar() for gdal 1.x
+   * implementation and GetGDALDriverManager() for gdal 2.x
+   * implementation.
+   *
+   * \return A vector of string containing the list of available drivers.
+   */  
+  static std::vector<std::string> GetAvailableDriversAsStringVector();
 
 private:
-  OGRVersionProxy(); // purposely not implemeted
+  OGRVersionProxy(); // purposely not implemented
   OGRVersionProxy(const OGRVersionProxy&); // purposely not implemented
   void operator=(const OGRVersionProxy&); // purposely not implemented
 };

Modules/Adapters/GdalAdapters/src/otbOGRVersionProxy1x.cxx

@@ -17,7 +17,14 @@
 =========================================================================*/
 #include "otbOGRVersionProxy.h"
 
+#ifdef __GNUC__
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wshadow"
 #include "ogrsf_frmts.h"
+#pragma GCC diagnostic pop
+#else
+#include "ogrsf_frmts.h"
+#endif
 
 namespace otb
 {
@@ -66,9 +73,13 @@ std::string OGRVersionProxy::GetDriverClassName()
   return std::string("OGRSFDriver");
 }
 
-std::string OGRVersionProxy::GetDatasetDescription(GDALDatasetType * dataset)
+std::vector<std::string> OGRVersionProxy::GetFileListAsStringVector(GDALDatasetType * dataset)
 {
-  return std::string(dataset->GetName());
+  std::vector<std::string> ret;
+
+  ret.push_back(std::string(dataset->GetName()));
+  
+  return ret;
 }
 
 bool OGRVersionProxy::SyncToDisk(GDALDatasetType * dataset)
@@ -78,4 +89,18 @@ bool OGRVersionProxy::SyncToDisk(GDALDatasetType * dataset)
   return (res == OGRERR_NONE);
 }
 
+std::vector<std::string> OGRVersionProxy::GetAvailableDriversAsStringVector()
+{
+  std::vector<std::string> ret;
+  
+  int nbDrivers = OGRSFDriverRegistrar::GetRegistrar()->GetDriverCount();
+  
+  for(int i = 0; i < nbDrivers;++i)
+    {
+    ret.push_back(OGRSFDriverRegistrar::GetRegistrar()->GetDriver(i)->GetName());
+    }
+
+  return ret;
+}
+
 } // end namespace

Modules/Adapters/GdalAdapters/src/otbOGRVersionProxy2x.cxx

@@ -17,7 +17,14 @@
 =========================================================================*/
 #include "otbOGRVersionProxy.h"
 
+#ifdef __GNUC__
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wshadow"
 #include "gdal_priv.h"
+#pragma GCC diagnostic pop
+#else
+#include "gdal_priv.h"
+#endif
 
 namespace otb
 {
@@ -66,8 +73,10 @@ std::string OGRVersionProxy::GetDriverClassName()
   return std::string("GDALDriver");
 }
 
-std::string OGRVersionProxy::GetDatasetDescription(GDALDatasetType * dataset)
+std::vector<std::string> OGRVersionProxy::GetFileListAsStringVector(GDALDatasetType * dataset)
 {
+  std::vector<std::string> ret;
+  
   char ** files = dataset->GetFileList();
 
   std::string files_str="";
@@ -77,12 +86,13 @@ std::string OGRVersionProxy::GetDatasetDescription(GDALDatasetType * dataset)
     unsigned int i = 0;
     while(files[i]!=NULL)
       {
-      files_str+=std::string(files[i])+" ";
+      ret.push_back(std::string(files[i]));
       ++i;
       }
     CSLDestroy(files);
     }
-  return files_str;
+
+  return ret;
 }
 
 bool OGRVersionProxy::SyncToDisk(GDALDatasetType * dataset)
@@ -92,4 +102,18 @@ bool OGRVersionProxy::SyncToDisk(GDALDatasetType * dataset)
   return true;
 }
 
+std::vector<std::string> OGRVersionProxy::GetAvailableDriversAsStringVector()
+{
+  std::vector<std::string> ret;
+  
+  int nbDrivers = GetGDALDriverManager()->GetDriverCount();
+  
+  for(int i = 0; i < nbDrivers;++i)
+    {
+    ret.push_back(GDALGetDriverShortName(GetGDALDriverManager()->GetDriver(i)));
+    }
+
+  return ret;
+}
+
 } // end namespace