docs: add integration examples

CMakeLists.txt

@@ -101,7 +101,7 @@ endif()
 
 if(OPENGEMINI_BUILD_EXAMPLE)
     message(STATUS "Generating examples")
-    add_subdirectory(examples)
+    add_subdirectory(examples/usage)
 endif()
 
 if (OPENGEMINI_BUILD_DOCUMENTATION)

README.md

@@ -42,6 +42,9 @@ OpenGemini is a cloud-native distributed time series database, find more informa
     - [GoogleTest](https://github.com/google/googletest) (*optional*, for building unit tests)
 
 ## Integration
+
+> For a whole example project, please check out `examples/integration` directory.
+
 ### CMake FetchContent
 It is recommended to integrate with OpenGeminiCxx using CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html).
 
@@ -90,7 +93,7 @@ You may also need to link against any necessary dependencies to your program man
 ```
 
 ## Quick Start
-Below are a few examples show how to use some of the main features of the library. For more example code, please check out `examples` directory;
+> Below are a few examples show how to use some of the main features of the library. For more example code, please check out `examples/usage` directory.
 ### Query data from the server
 ```cpp
 #include <iostream>

README_CN.md

@@ -43,6 +43,9 @@ OpenGemini 是一款云原生分布式时序数据库。获取更多信息，请
 
 
 ## 与项目集成
+
+> 您可以通过`examples/integration`目录查看完整的示例工程。
+
 ### CMake FetchContent
 我们推荐使用CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) 来将OpenGeminiCxx集成到您的项目中。
 
@@ -81,7 +84,7 @@ target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
 ```
 
 ### Header-Only
-> **注意：** 尽管OpenGeminiCxx可以当作纯头文件引用，但我们仍建议使用预编译好的版本以减少构建时间。
+> **注意：** 尽管OpenGeminiCxx可以作为纯头文件引用，但我们仍建议使用预编译好的版本以减少构建时间。
 
 下载[OpenGeminiCxx](https://github.com/openGemini/opengemini-client-cpp/releases)，然后将`/path/to/opengemini-client-cpp/include`添加至工程的包含路径中。
 
@@ -91,7 +94,7 @@ target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
 ```
 
 ## 快速上手
-下列示例代码简单演示了这个库的一些主要特性，您可以通过`examples`目录查看更多的示例代码。
+> 下列示例代码简单演示了这个库的一些主要特性，您可以通过`examples/usage`目录查看更多的示例代码。
 ### 从服务端查询数据
 ```cpp
 #include <iostream>

examples/integration/fetch_content/CMakeLists.txt

@@ -0,0 +1,39 @@
+# Copyright 2024 openGemini Authors
+#
+# Licensed 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.
+
+cmake_minimum_required(VERSION 3.12)
+
+project(ExampleFetchContent)
+
+# You can set option variables here to control configurations.
+#
+# Enable TLS support:
+#    set(OPENGEMINI_ENABLE_SSL_SUPPORT ON)
+# Build OpenGeminiCxx as a shared library:
+#    set(OPENGEMINI_BUILD_SHARED_LIBS ON)
+#
+# For details about all the options, see README file.
+
+# Declare OpenGeminiCxx and make it available
+include(FetchContent)
+FetchContent_Declare(OpenGeminiCxx
+    GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
+    GIT_TAG        main
+)
+FetchContent_MakeAvailable(OpenGeminiCxx)
+
+add_executable(YourApp main.cpp)
+
+# Link OpenGeminiCxx's target against to your target.
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)

examples/integration/fetch_content/main.cpp

@@ -0,0 +1,29 @@
+// Copyright 2024 openGemini Authors
+//
+// Licensed 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.
+
+#include <iostream>
+
+#include <opengemini/Client.hpp>
+#include <opengemini/ClientConfigBuilder.hpp>
+
+int main(int argc, char** argv)
+{
+    opengemini::Client client{ opengemini::ClientConfigBuilder()
+                                   .AppendAddress({ "127.0.0.1", 8086 })
+                                   .Finalize() };
+
+    std::cout << "OpenGemini server's version: " << client.Ping(0) << std::endl;
+
+    return 0;
+}

examples/integration/find_package/CMakeLists.txt

@@ -0,0 +1,34 @@
+# Copyright 2024 openGemini Authors
+#
+# Licensed 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.
+
+cmake_minimum_required(VERSION 3.12)
+
+project(ExampleFetchContent)
+
+# If you installed OpenGeminiCxx to a custom directory,
+# you may need to tell CMake where to search the library such as:
+#    setting root variable before calling find_package():
+#        set(OpenGeminiCxx_ROOT /path/to/the/installation)
+#    or specifying the root variable while running cmake:
+#        $ cmake -DOpenGeminiCxx_ROOT=/path/to/the/installation
+#    or adding the directory to the CMAKE_PREFIX_PATH.
+#
+# For more usage about find_package() check: https://cmake.org/cmake/help/latest/command/find_package.html
+
+find_package(OpenGeminiCxx REQUIRED)
+
+add_executable(YourApp main.cpp)
+
+# Link OpenGeminiCxx's target against to your target.
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)

examples/integration/find_package/main.cpp

@@ -0,0 +1,22 @@
+// Copyright 2024 openGemini Authors
+//
+// Licensed 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.
+
+#include <opengemini/Client.hpp>
+
+int main(int argc, char** argv)
+{
+    opengemini::Client client{ {} };
+
+    return 0;
+}

include/CMakeLists.txt

@@ -44,6 +44,10 @@ else()
         opengemini/impl/ClientImpl.cpp
         opengemini/impl/ClientConfigBuilder.cpp
         opengemini/impl/ErrorCode.cpp
+        opengemini/impl/cli/database/Database.cpp
+        opengemini/impl/cli/database/Ping.cpp
+        opengemini/impl/cli/policy/RetentionPolicy.cpp
+        opengemini/impl/cli/query/Query.cpp
         opengemini/impl/comm/Context.cpp
         opengemini/impl/enc/LineProtocolEncoder.cpp
         opengemini/impl/http/IHttpClient.cpp

include/opengemini/impl/ClientImpl.cpp

@@ -79,8 +79,3 @@ ClientImpl::ConstructHttpClient(const ClientConfig& config)
 };
 
 } // namespace opengemini::impl
-
-#include "opengemini/impl/cli/Database.cpp"
-#include "opengemini/impl/cli/Ping.cpp"
-#include "opengemini/impl/cli/Query.cpp"
-#include "opengemini/impl/cli/RetentionPolicy.cpp"

include/opengemini/impl/ClientImpl.hpp

@@ -93,9 +93,6 @@ class ClientImpl {
              typename = void>
     void Spawn(FUNCTION&& func, COMPLETION_TOKEN&& token);
 
-private:
-    struct Functor;
-
 private:
     Context                            ctx_;
     std::shared_ptr<http::IHttpClient> http_;

include/opengemini/impl/ClientImpl.tpp

@@ -16,7 +16,11 @@
 
 #include <boost/exception/diagnostic_information.hpp>
 
-#include "opengemini/impl/cli/Functor.hpp"
+#include "opengemini/impl/cli/database/Database.hpp"
+#include "opengemini/impl/cli/database/Ping.hpp"
+#include "opengemini/impl/cli/policy/RetentionPolicy.hpp"
+#include "opengemini/impl/cli/query/Query.hpp"
+#include "opengemini/impl/cli/write/Write.hpp"
 #include "opengemini/impl/comm/CompletionSignature.hpp"
 #include "opengemini/impl/util/ErrorHandling.hpp"
 #include "opengemini/impl/util/TypeTraits.hpp"
@@ -33,7 +37,7 @@ auto ClientImpl::Ping(std::size_t index, COMPLETION_TOKEN&& token)
                           "Completion signature of Ping must be: "
                           "void(std::exception_ptr, std::string)");
 
-            Spawn<Signature>(Functor::RunPing{ this, index },
+            Spawn<Signature>(cli::RunPing{ { *http_, *lb_ }, index },
                              OPENGEMINI_PF(token));
         },
         token,
@@ -50,8 +54,9 @@ auto ClientImpl::Query(struct Query query, COMPLETION_TOKEN&& token)
                           "Completion signature of Query must be: "
                           "void(std::exception_ptr, QueryResult)");
 
-            Spawn<Signature>(Functor::RunQueryGet{ this, std::move(query) },
-                             OPENGEMINI_PF(token));
+            Spawn<Signature>(
+                cli::RunQueryGet{ { *http_, *lb_ }, std::move(query) },
+                OPENGEMINI_PF(token));
         },
         token,
         std::move(query));
@@ -71,9 +76,9 @@ auto ClientImpl::CreateDatabase(std::string_view        database,
                           "Completion signature of CreateDatabase must be: "
                           "void(std::exception_ptr)");
 
-            Spawn<Signature>(Functor::RunCreateDatabase{ this,
-                                                         std::move(database),
-                                                         std::move(rpConfig) },
+            Spawn<Signature>(cli::RunCreateDatabase{ { *http_, *lb_ },
+                                                     std::move(database),
+                                                     std::move(rpConfig) },
                              OPENGEMINI_PF(token));
         },
         token,
@@ -91,7 +96,7 @@ auto ClientImpl::ShowDatabase(COMPLETION_TOKEN&& token)
                           "Completion signature of ShowDatabase must be: "
                           "void(std::exception_ptr, std::vector<std::string>)");
 
-            Spawn<Signature>(Functor::RunShowDatabase{ this },
+            Spawn<Signature>(cli::RunShowDatabase{ { *http_, *lb_ } },
                              OPENGEMINI_PF(token));
         },
         token);
@@ -109,7 +114,7 @@ auto ClientImpl::DropDatabase(std::string_view   database,
                           "void(std::exception_ptr)");
 
             Spawn<Signature>(
-                Functor::RunDropDatabase{ this, std::move(database) },
+                cli::RunDropDatabase{ { *http_, *lb_ }, std::move(database) },
                 OPENGEMINI_PF(token));
         },
         token,
@@ -133,12 +138,11 @@ auto ClientImpl::CreateRetentionPolicy(std::string_view   database,
                 "Completion signature of CreateRetentionPolicy must be: "
                 "void(std::exception_ptr)");
 
-            Spawn<Signature>(
-                Functor::RunCreateRetentionPolicy{ this,
-                                                   std::move(database),
-                                                   std::move(rpConfig),
-                                                   isDefault },
-                OPENGEMINI_PF(token));
+            Spawn<Signature>(cli::RunCreateRetentionPolicy{ { *http_, *lb_ },
+                                                            std::move(database),
+                                                            std::move(rpConfig),
+                                                            isDefault },
+                             OPENGEMINI_PF(token));
         },
         token,
         std::string(database),
@@ -159,7 +163,8 @@ auto ClientImpl::ShowRetentionPolicies(std::string_view   database,
                 "void(std::exception_ptr, std::vector<RetentionPolicy>)");
 
             Spawn<Signature>(
-                Functor::RunShowRetentionPolicies{ this, std::move(database) },
+                cli::RunShowRetentionPolicies{ { *http_, *lb_ },
+                                               std::move(database) },
                 OPENGEMINI_PF(token));
         },
         token,
@@ -182,9 +187,9 @@ auto ClientImpl::DropRetentionPolicy(std::string_view   database,
                 "void(std::exception_ptr)");
 
             Spawn<Signature>(
-                Functor::RunDropRetentionPolicy{ this,
-                                                 std::move(database),
-                                                 std::move(retentionPolicy) },
+                cli::RunDropRetentionPolicy{ { *http_, *lb_ },
+                                             std::move(database),
+                                             std::move(retentionPolicy) },
                 OPENGEMINI_PF(token));
         },
         token,
@@ -209,10 +214,10 @@ auto ClientImpl::Write(std::string_view   database,
                           "void(std::exception_ptr)");
 
             Spawn<Signature>(
-                Functor::RunWrite<POINT_TYPE>{ this,
-                                               std::move(database),
-                                               std::move(retentionPolicy),
-                                               std::move(point) },
+                cli::RunWrite<POINT_TYPE>{ { *http_, *lb_ },
+                                           std::move(database),
+                                           std::move(retentionPolicy),
+                                           std::move(point) },
                 OPENGEMINI_PF(token));
         },
         token,
@@ -255,5 +260,3 @@ void ClientImpl::Spawn(FUNCTION&& func, COMPLETION_TOKEN&& token)
 }
 
 } // namespace opengemini::impl
-
-#include "opengemini/impl/cli/Write.tpp"