feat: add pure virtual classes for Catalog, Table, etc. (#47)

# What are done in this PR
- Added pure virtual classes of `Catalog`, `Table`, `TableOperations`,
`Transaction` and `LocationProvider` with limited features like
`AppendFiles` and `TableScan`.
- Added basic definitions of `Namespace` and `TableIdentifier`.
- Defined initial `Error` enum.

# What are undecided
- How to define an IO-less `FileIO`.
- How to define `StructLike`.

Author: wgtmac

example/demo_example.cc

@@ -21,11 +21,11 @@
 
 #include "iceberg/arrow/demo_arrow.h"
 #include "iceberg/avro/demo_avro.h"
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 #include "iceberg/puffin/demo_puffin.h"
 
 int main() {
-  std::cout << iceberg::DemoTable().print() << std::endl;
+  std::cout << iceberg::Demo().print() << std::endl;
   std::cout << iceberg::puffin::DemoPuffin().print() << std::endl;
   std::cout << iceberg::arrow::DemoArrow().print() << std::endl;
   std::cout << iceberg::avro::DemoAvro().print() << std::endl;

src/iceberg/CMakeLists.txt

@@ -19,7 +19,7 @@ set(ICEBERG_INCLUDES "$<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/src>"
                      "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>")
 set(ICEBERG_SOURCES
     arrow_c_data_internal.cc
-    demo_table.cc
+    demo.cc
     schema.cc
     schema_field.cc
     type.cc)

src/iceberg/arrow/demo_arrow.cc

@@ -21,13 +21,12 @@
 
 #include <arrow/config.h>
 
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::arrow {
 
 std::string DemoArrow::print() const {
-  return DemoTable().print() +
-         ", Arrow version: " + ::arrow::GetBuildInfo().version_string;
+  return Demo().print() + ", Arrow version: " + ::arrow::GetBuildInfo().version_string;
 }
 
 }  // namespace iceberg::arrow

src/iceberg/arrow/demo_arrow.h

@@ -22,11 +22,11 @@
 #include <string>
 
 #include "iceberg/arrow/iceberg_arrow_export.h"
-#include "iceberg/table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::arrow {
 
-class ICEBERG_ARROW_EXPORT DemoArrow : public Table {
+class ICEBERG_ARROW_EXPORT DemoArrow : public Demo {
  public:
   DemoArrow() = default;
   ~DemoArrow() override = default;

src/iceberg/avro/demo_avro.cc

@@ -23,7 +23,7 @@
 
 #include "avro/Compiler.hh"
 #include "avro/ValidSchema.hh"
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::avro {
 

src/iceberg/catalog.h

@@ -0,0 +1,194 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+#include <map>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "iceberg/error.h"
+#include "iceberg/expected.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief A Catalog API for table create, drop, and load operations.
+///
+/// Note that these functions are named after the corresponding operationId
+/// specified by the Iceberg Rest Catalog API.
+class ICEBERG_EXPORT Catalog {
+ public:
+  virtual ~Catalog() = default;
+
+  /// \brief Return the name for this catalog
+  virtual std::string_view name() const = 0;
+
+  /// \brief Return all the identifiers under this namespace
+  ///
+  /// \param ns a namespace
+  /// \return a list of identifiers for tables or ErrorKind::kNoSuchNamespace
+  /// if the namespace does not exist
+  virtual expected<std::vector<TableIdentifier>, Error> ListTables(
+      const Namespace& ns) const = 0;
+
+  /// \brief Create a table
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \param spec a partition spec
+  /// \param location a location for the table; leave empty if unspecified
+  /// \param properties a string map of table properties
+  /// \return a Table instance or ErrorKind::kAlreadyExists if the table already exists
+  virtual expected<std::unique_ptr<Table>, Error> CreateTable(
+      const TableIdentifier& identifier, const Schema& schema, const PartitionSpec& spec,
+      const std::string& location,
+      const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Update a table
+  ///
+  /// \param identifier a table identifier
+  /// \param requirements a list of table requirements
+  /// \param updates a list of table updates
+  /// \return a Table instance or ErrorKind::kAlreadyExists if the table already exists
+  virtual expected<std::unique_ptr<Table>, Error> UpdateTable(
+      const TableIdentifier& identifier,
+      const std::vector<std::unique_ptr<UpdateRequirement>>& requirements,
+      const std::vector<std::unique_ptr<MetadataUpdate>>& updates) = 0;
+
+  /// \brief Start a transaction to create a table
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \param spec a partition spec
+  /// \param location a location for the table; leave empty if unspecified
+  /// \param properties a string map of table properties
+  /// \return a Transaction to create the table or ErrorKind::kAlreadyExists if the table
+  /// already exists
+  virtual expected<std::shared_ptr<Transaction>, Error> StageCreateTable(
+      const TableIdentifier& identifier, const Schema& schema, const PartitionSpec& spec,
+      const std::string& location,
+      const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Check whether table exists
+  ///
+  /// \param identifier a table identifier
+  /// \return true if the table exists, false otherwise
+  virtual bool TableExists(const TableIdentifier& identifier) const = 0;
+
+  /// \brief Drop a table; optionally delete data and metadata files
+  ///
+  /// If purge is set to true the implementation should delete all data and metadata
+  /// files.
+  ///
+  /// \param identifier a table identifier
+  /// \param purge if true, delete all data and metadata files in the table
+  /// \return true if the table was dropped, false if the table did not exist
+  virtual bool DropTable(const TableIdentifier& identifier, bool purge) = 0;
+
+  /// \brief Load a table
+  ///
+  /// \param identifier a table identifier
+  /// \return instance of Table implementation referred to by identifier or
+  /// ErrorKind::kNoSuchTable if the table does not exist
+  virtual expected<std::shared_ptr<Table>, Error> LoadTable(
+      const TableIdentifier& identifier) const = 0;
+
+  /// \brief Register a table with the catalog if it does not exist
+  ///
+  /// \param identifier a table identifier
+  /// \param metadata_file_location the location of a metadata file
+  /// \return a Table instance or ErrorKind::kAlreadyExists if the table already exists
+  virtual expected<std::shared_ptr<Table>, Error> RegisterTable(
+      const TableIdentifier& identifier, const std::string& metadata_file_location) = 0;
+
+  /// \brief Initialize a catalog given a custom name and a map of catalog properties
+  ///
+  /// A custom Catalog implementation must have a default constructor. A compute engine
+  /// will first initialize the catalog without any arguments, and then call this method
+  /// to complete catalog initialization with properties passed into the engine.
+  ///
+  /// \param name a custom name for the catalog
+  /// \param properties catalog properties
+  virtual void Initialize(const std::string& name,
+                          const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Instantiate a builder to either create a table or start a create/replace
+  /// transaction
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \return the builder to create a table or start a create/replace transaction
+  virtual std::unique_ptr<class TableBuilder> BuildTable(
+      const TableIdentifier& identifier, const Schema& schema) const = 0;
+
+  /// \brief A builder used to create valid tables or start create/replace transactions
+  class TableBuilder {
+   public:
+    virtual ~TableBuilder() = default;
+
+    /// \brief Sets a partition spec for the table
+    ///
+    /// \param spec a partition spec
+    /// \return this for method chaining
+    virtual TableBuilder& WithPartitionSpec(const PartitionSpec& spec) = 0;
+
+    /// \brief Sets a sort order for the table
+    ///
+    /// \param sort_order a sort order
+    /// \return this for method chaining
+    virtual TableBuilder& WithSortOrder(const SortOrder& sort_order) = 0;
+
+    /// \brief Sets a location for the table
+    ///
+    /// \param location a location
+    /// \return this for method chaining
+    virtual TableBuilder& WithLocation(const std::string& location) = 0;
+
+    /// \brief Adds key/value properties to the table
+    ///
+    /// \param properties key/value properties
+    /// \return this for method chaining
+    virtual TableBuilder& WithProperties(
+        const std::map<std::string, std::string>& properties) = 0;
+
+    /// \brief Adds a key/value property to the table
+    ///
+    /// \param key a key
+    /// \param value a value
+    /// \return this for method chaining
+    virtual TableBuilder& WithProperty(const std::string& key,
+                                       const std::string& value) = 0;
+
+    /// \brief Creates the table
+    ///
+    /// \return the created table
+    virtual std::unique_ptr<Table> Create() = 0;
+
+    /// \brief Starts a transaction to create the table
+    ///
+    /// \return the Transaction to create the table
+    virtual std::unique_ptr<Transaction> StageCreate() = 0;
+  };
+};
+
+}  // namespace iceberg

src/iceberg/demo_table.cc renamed to src/iceberg/demo.cc

@@ -17,13 +17,17 @@
  * under the License.
  */
 
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 #include "iceberg/avro.h"  // include to export symbols
+#include "iceberg/catalog.h"
+#include "iceberg/location_provider.h"
 #include "iceberg/puffin.h"
+#include "iceberg/table.h"
+#include "iceberg/transaction.h"
 
 namespace iceberg {
 
-std::string DemoTable::print() const { return "DemoTable"; }
+std::string Demo::print() const { return "Demo"; }
 
 }  // namespace iceberg

src/iceberg/demo_table.h renamed to src/iceberg/demo.h

@@ -19,16 +19,18 @@
 
 #pragma once
 
-#include "iceberg/table.h"
+#include <string>
+
+#include "iceberg/iceberg_export.h"
 
 namespace iceberg {
 
-class ICEBERG_EXPORT DemoTable : public Table {
+class ICEBERG_EXPORT Demo {
  public:
-  DemoTable() = default;
-  ~DemoTable() override = default;
+  Demo() = default;
+  virtual ~Demo() = default;
 
-  std::string print() const override;
+  virtual std::string print() const;
 };
 
 }  // namespace iceberg

src/iceberg/error.h

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+#include <string>
+
+#include "iceberg/iceberg_export.h"
+
+namespace iceberg {
+
+/// \brief Error types for iceberg.
+/// TODO: add more and sort them based on some rules.
+enum class ErrorKind {
+  kNoSuchNamespace,
+  kAlreadyExists,
+  kNoSuchTable,
+  kCommitStateUnknown,
+};
+
+/// \brief Error with a kind and a message.
+struct ICEBERG_EXPORT [[nodiscard]] Error {
+  ErrorKind kind;
+  std::string message;
+};
+
+}  // namespace iceberg