Deprecate tiledb_filestore_* APIs.

doc/policy/api_changes.md

@@ -81,6 +81,12 @@ Function removal shall be announced one release cycle before removal, following
 
 ### 2.27.0..2.28.0
 
+- `tiledb_filestore_schema_create`
+- `tiledb_filestore_uri_import`
+- `tiledb_filestore_uri_export`
+- `tiledb_filestore_buffer_import`
+- `tiledb_filestore_buffer_export`
+- `tiledb_filestore_size`
 - `tiledb_group_dump_str`
 
 ## Deprecation History Generation

tiledb/sm/c_api/tiledb_deprecated.h

@@ -42,7 +42,139 @@
 extern "C" {
 #endif
 
-// No deprecated APIs are declared at the moment.
+/**
+ * Creates an array schema based on the properties of the provided URI
+ * or a default schema if no URI is provided
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_array_schema_t* schema;
+ * tiledb_filestore_schema_create(ctx, "/path/file.pdf", &schema);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param uri The file URI.
+ * @param array_schema The TileDB array schema to be created
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_schema_create(
+    tiledb_ctx_t* ctx,
+    const char* uri,
+    tiledb_array_schema_t** array_schema) TILEDB_NOEXCEPT;
+
+/**
+ * Imports a file into a TileDB filestore array
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_array_schema_t* schema;
+ * tiledb_filestore_schema_create(ctx, path_to_file, &schema);
+ * tiledb_array_create(ctx, path_to_array, schema);
+ * tiledb_filestore_uri_import(ctx, path_to_array, path_to_file,
+ * TILEDB_MIME_AUTODETECT);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param filestore_array_uri The array URI.
+ * @param file_uri The file URI.
+ * @param mime_type The mime type of the file
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_uri_import(
+    tiledb_ctx_t* ctx,
+    const char* filestore_array_uri,
+    const char* file_uri,
+    tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT;
+
+/**
+ * Exports a filestore array into a bare file
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_filestore_uri_export(ctx, path_to_file, path_to_array);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param file_uri The file URI.
+ * @param filestore_array_uri The array URI.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_uri_export(
+    tiledb_ctx_t* ctx,
+    const char* file_uri,
+    const char* filestore_array_uri) TILEDB_NOEXCEPT;
+
+/**
+ * Writes size bytes starting at address buf into filestore array
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_array_schema_t* schema;
+ * tiledb_filestore_schema_create(ctx, NULL, &schema);
+ * tiledb_array_create(ctx, path_to_array, schema);
+ * tiledb_filestore_buffer_import(ctx, path_to_array, buf, size,
+ * TILEDB_MIME_AUTODETECT);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param filestore_array_uri The array URI.
+ * @param buf The input buffer
+ * @param size Number of bytes to be imported
+ * @param mime_type The mime type of the data
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_buffer_import(
+    tiledb_ctx_t* ctx,
+    const char* filestore_array_uri,
+    void* buf,
+    size_t size,
+    tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT;
+
+/**
+ * Dump the content of a filestore array into a buffer
+ * **Example:**
+ *
+ * @code{.c}
+ * size_t size = 1024;
+ * void *buf = malloc(size);
+ * tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param filestore_array_uri The array URI.
+ * @param offset The offset at which we should start exporting from the array
+ * @param buf The buffer that will contain the filestore array content
+ * @param size The number of bytes to be exported into the buffer
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_buffer_export(
+    tiledb_ctx_t* ctx,
+    const char* filestore_array_uri,
+    size_t offset,
+    void* buf,
+    size_t size) TILEDB_NOEXCEPT;
+
+/**
+ * Get the uncompressed size of a filestore array
+ * **Example:**
+ *
+ * @code{.c}
+ * size_t size;
+ * tiledb_filestore_size(ctx, path_to_array, &size);
+ * void *buf = malloc(size);
+ * tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);
+ * free(buf);
+ * @endcode
+ *
+ * @param[in] ctx The TileDB context.
+ * @param[in] filestore_array_uri The array URI.
+ * @param[in] size The returned uncompressed size of the filestore array
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_size(
+    tiledb_ctx_t* ctx,
+    const char* filestore_array_uri,
+    size_t* size) TILEDB_NOEXCEPT;
 
 #ifdef __cplusplus
 }

tiledb/sm/c_api/tiledb_experimental.h

@@ -63,6 +63,30 @@
 extern "C" {
 #endif
 
+/* ****************************** */
+/*       ENUMS TO/FROM STR        */
+/* ****************************** */
+
+/**
+ * Get the string representation of a mime type enum
+ *
+ * @param mime_type The mime enum
+ * @param str The resulted string representation
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT int32_t tiledb_mime_type_to_str(
+    tiledb_mime_type_t mime_type, const char** str) TILEDB_NOEXCEPT;
+
+/**
+ * Turn a string mime type into a TileDB enum
+ *
+ * @param str The mime type string
+ * @param mime_type The resulted mime enum
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT int32_t tiledb_mime_type_from_str(
+    const char* str, tiledb_mime_type_t* mime_type) TILEDB_NOEXCEPT;
+
 /* ********************************* */
 /*             LOGGING               */
 /* ********************************* */
@@ -540,163 +564,9 @@ TILEDB_EXPORT capi_return_t tiledb_array_consolidate_fragments(
     tiledb_config_t* config) TILEDB_NOEXCEPT;
 
 /* ********************************* */
-/*             FILESTORE             */
+/*         CONSOLIDATION PLAN        */
 /* ********************************* */
 
-/**
- * Creates an array schema based on the properties of the provided URI
- * or a default schema if no URI is provided
- * **Example:**
- *
- * @code{.c}
- * tiledb_array_schema_t* schema;
- * tiledb_filestore_schema_create(ctx, "/path/file.pdf", &schema);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param uri The file URI.
- * @param array_schema The TileDB array schema to be created
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_schema_create(
-    tiledb_ctx_t* ctx,
-    const char* uri,
-    tiledb_array_schema_t** array_schema) TILEDB_NOEXCEPT;
-
-/**
- * Imports a file into a TileDB filestore array
- * **Example:**
- *
- * @code{.c}
- * tiledb_array_schema_t* schema;
- * tiledb_filestore_schema_create(ctx, path_to_file, &schema);
- * tiledb_array_create(ctx, path_to_array, schema);
- * tiledb_filestore_uri_import(ctx, path_to_array, path_to_file,
- * TILEDB_MIME_AUTODETECT);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param filestore_array_uri The array URI.
- * @param file_uri The file URI.
- * @param mime_type The mime type of the file
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_uri_import(
-    tiledb_ctx_t* ctx,
-    const char* filestore_array_uri,
-    const char* file_uri,
-    tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT;
-
-/**
- * Exports a filestore array into a bare file
- * **Example:**
- *
- * @code{.c}
- * tiledb_filestore_uri_export(ctx, path_to_file, path_to_array);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param file_uri The file URI.
- * @param filestore_array_uri The array URI.
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_uri_export(
-    tiledb_ctx_t* ctx,
-    const char* file_uri,
-    const char* filestore_array_uri) TILEDB_NOEXCEPT;
-
-/**
- * Writes size bytes starting at address buf into filestore array
- * **Example:**
- *
- * @code{.c}
- * tiledb_array_schema_t* schema;
- * tiledb_filestore_schema_create(ctx, NULL, &schema);
- * tiledb_array_create(ctx, path_to_array, schema);
- * tiledb_filestore_buffer_import(ctx, path_to_array, buf, size,
- * TILEDB_MIME_AUTODETECT);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param filestore_array_uri The array URI.
- * @param buf The input buffer
- * @param size Number of bytes to be imported
- * @param mime_type The mime type of the data
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_buffer_import(
-    tiledb_ctx_t* ctx,
-    const char* filestore_array_uri,
-    void* buf,
-    size_t size,
-    tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT;
-
-/**
- * Dump the content of a filestore array into a buffer
- * **Example:**
- *
- * @code{.c}
- * size_t size = 1024;
- * void *buf = malloc(size);
- * tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param filestore_array_uri The array URI.
- * @param offset The offset at which we should start exporting from the array
- * @param buf The buffer that will contain the filestore array content
- * @param size The number of bytes to be exported into the buffer
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_buffer_export(
-    tiledb_ctx_t* ctx,
-    const char* filestore_array_uri,
-    size_t offset,
-    void* buf,
-    size_t size) TILEDB_NOEXCEPT;
-
-/**
- * Get the uncompressed size of a filestore array
- * **Example:**
- *
- * @code{.c}
- * size_t size;
- * tiledb_filestore_size(ctx, path_to_array, &size);
- * void *buf = malloc(size);
- * tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);
- * free(buf);
- * @endcode
- *
- * @param[in] ctx The TileDB context.
- * @param[in] filestore_array_uri The array URI.
- * @param[in] size The returned uncompressed size of the filestore array
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_filestore_size(
-    tiledb_ctx_t* ctx,
-    const char* filestore_array_uri,
-    size_t* size) TILEDB_NOEXCEPT;
-
-/**
- * Get the string representation of a mime type enum
- *
- * @param mime_type The mime enum
- * @param str The resulted string representation
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_mime_type_to_str(
-    tiledb_mime_type_t mime_type, const char** str) TILEDB_NOEXCEPT;
-
-/**
- * Turn a string mime type into a TileDB enum
- *
- * @param str The mime type string
- * @param mime_type The resulted mime enum
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_mime_type_from_str(
-    const char* str, tiledb_mime_type_t* mime_type) TILEDB_NOEXCEPT;
-
 /**
  * Creates a consolidation plan object.
  *

tiledb/sm/c_api/tiledb_filestore.cc

@@ -29,6 +29,8 @@
  * @section DESCRIPTION
  *
  * This file defines the C API of TileDB for filestore.
+ *
+ * Note: These APIs are deprecated and will be removed in the next release.
  **/
 
 #include "tiledb/api/c_api/array_schema/array_schema_api_internal.h"