From f5b875bac59c9039a8f461345086dcd83436c583 Mon Sep 17 00:00:00 2001 From: Rebekah Davis Date: Thu, 14 Nov 2024 10:59:26 -0500 Subject: [PATCH] Deprecate tiledb_filestore_* APIs. --- doc/policy/api_changes.md | 8 ++ tiledb/sm/c_api/tiledb_deprecated.h | 154 ++++++++++++++++++++++++- tiledb/sm/c_api/tiledb_experimental.h | 156 +------------------------- tiledb/sm/c_api/tiledb_filestore.cc | 2 + tiledb/sm/enums/mime_type.h | 4 +- 5 files changed, 167 insertions(+), 157 deletions(-) diff --git a/doc/policy/api_changes.md b/doc/policy/api_changes.md index 9c91c880009..31bd0c97903 100644 --- a/doc/policy/api_changes.md +++ b/doc/policy/api_changes.md @@ -81,7 +81,15 @@ 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` +- `tiledb_mime_type_to_str` +- `tiledb_mime_type_from_str` ## Deprecation History Generation diff --git a/tiledb/sm/c_api/tiledb_deprecated.h b/tiledb/sm/c_api/tiledb_deprecated.h index d3bc83291b0..a2947e51629 100644 --- a/tiledb/sm/c_api/tiledb_deprecated.h +++ b/tiledb/sm/c_api/tiledb_deprecated.h @@ -42,7 +42,159 @@ 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; + +/** + * 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_DEPRECATED_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_DEPRECATED_EXPORT int32_t tiledb_mime_type_from_str( + const char* str, tiledb_mime_type_t* mime_type) TILEDB_NOEXCEPT; #ifdef __cplusplus } diff --git a/tiledb/sm/c_api/tiledb_experimental.h b/tiledb/sm/c_api/tiledb_experimental.h index f74b938cb5c..5f1b09f3499 100644 --- a/tiledb/sm/c_api/tiledb_experimental.h +++ b/tiledb/sm/c_api/tiledb_experimental.h @@ -540,163 +540,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. * diff --git a/tiledb/sm/c_api/tiledb_filestore.cc b/tiledb/sm/c_api/tiledb_filestore.cc index c6be1d3b0e4..f265f87965b 100644 --- a/tiledb/sm/c_api/tiledb_filestore.cc +++ b/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" diff --git a/tiledb/sm/enums/mime_type.h b/tiledb/sm/enums/mime_type.h index ad8fd425291..5cdd2ed496a 100644 --- a/tiledb/sm/enums/mime_type.h +++ b/tiledb/sm/enums/mime_type.h @@ -5,7 +5,7 @@ * * The MIT License * - * @copyright Copyright (c) 2017-2022 TileDB, Inc. + * @copyright Copyright (c) 2017-2024 TileDB, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -29,6 +29,8 @@ * * This defines the TileDB MimeType enum that maps to tiledb_mime_type_t * C-API enum. + * + * Note: This enum is deprecated and will be removed in the next release. */ #ifndef TILEDB_MIME_TYPE_H