create or replace PACKAGE CT_MRDS.DATA_EXPORTER
AUTHID CURRENT_USER
AS
   /**
      * Data Export Package: Provides comprehensive data export capabilities to various formats (CSV, Parquet) 
      * with support for cloud storage integration via Oracle Cloud Infrastructure (OCI).
      * The structure of comment is used by GET_PACKAGE_DOCUMENTATION function 
      * which returns documentation text for confluence page (to Copy-Paste it).
   **/

   -- Package Version Information
   PACKAGE_VERSION     CONSTANT VARCHAR2(10) := '2.1.0';
   PACKAGE_BUILD_DATE  CONSTANT VARCHAR2(19) := '2025-10-22 15:00:00';
   PACKAGE_AUTHOR      CONSTANT VARCHAR2(50) := 'MRDS Development Team';

   -- Version History (last 3-5 changes)
   VERSION_HISTORY     CONSTANT VARCHAR2(4000) := 
       'v2.1.0 (2025-10-22): Added version tracking and PARTITION_YEAR/PARTITION_MONTH support' || CHR(10) ||
       'v2.0.0 (2025-10-01): Separated export functionality from FILE_MANAGER package' || CHR(10) ||
       'v1.0.0 (2025-09-15): Initial implementation within FILE_MANAGER package' || CHR(10);

   cgBL       CONSTANT  VARCHAR2(2)   := CHR(13)||CHR(10);
   vgMsgTmp             VARCHAR2(32000);

   ---------------------------------------------------------------------------------------------------------------------------
   ---------------------------------------------------------------------------------------------------------------------------

   /**
      * @name     EXPORT_TABLE_DATA
      * @desc     Wrapper procedure for DBMS_CLOUD.EXPORT_DATA.
      *           Exports data into CSV file on OCI infrustructure.
      *           pBucketArea parameter accepts: 'INBOX', 'ODS', 'DATA', 'ARCHIVE'
      * @example  
      *   begin
      *      DATA_EXPORTER.EXPORT_TABLE_DATA(
      *          pSchemaName     => 'CT_MRDS',
      *          pTableName      => 'MY_TABLE',
      *          pKeyColumnName  => 'A_WORKFLOW_HISTORY_KEY',
      *          pBucketArea     => 'DATA',
      *          pFolderName     => 'csv_exports'
      *      );
      *   end;
   **/
   PROCEDURE EXPORT_TABLE_DATA (
     pSchemaName      IN VARCHAR2,
     pTableName       IN VARCHAR2,
     pKeyColumnName   IN VARCHAR2,
     pBucketArea      IN VARCHAR2,
     pFolderName      IN VARCHAR2,
     pCredentialName  IN VARCHAR2 default ENV_MANAGER.gvCredentialName
   );



   /**
      * @name     EXPORT_TABLE_DATA_BY_DATE
      * @desc     Wrapper procedure for DBMS_CLOUD.EXPORT_DATA.
      *           Exports data into PARQUET files on OCI infrustructure.
      *           Each YEAR_MONTH pair goes to seperate file (implicit partitioning).
      *           Allows specifying custom column list or uses T.* if pColumnList is NULL.
      *           Validates that all columns in pColumnList exist in the target table.
      *           Automatically adds 'T.' prefix to column names in pColumnList.
      *           pBucketArea parameter accepts: 'INBOX', 'ODS', 'DATA', 'ARCHIVE'
      * @example  
      *   begin
      *      DATA_EXPORTER.EXPORT_TABLE_DATA_BY_DATE(
      *          pSchemaName     => 'CT_MRDS',
      *          pTableName      => 'MY_TABLE',
      *          pKeyColumnName  => 'A_WORKFLOW_HISTORY_KEY',
      *          pBucketArea     => 'DATA',
      *          pFolderName     => 'parquet_exports',
      *          pColumnList     => 'COLUMN1, COLUMN2, COLUMN3',  -- Optional
      *          pMinDate        => DATE '2024-01-01',
      *          pMaxDate        => SYSDATE
      *      );
      *   end;
   **/
   PROCEDURE EXPORT_TABLE_DATA_BY_DATE (
     pSchemaName      IN VARCHAR2,
     pTableName       IN VARCHAR2,
     pKeyColumnName   IN VARCHAR2,
     pBucketArea      IN VARCHAR2,
     pFolderName      IN VARCHAR2,
     pColumnList      IN VARCHAR2 default NULL,
     pMinDate         IN DATE     default DATE '1900-01-01',
     pMaxDate         IN DATE     default SYSDATE,
     pCredentialName  IN VARCHAR2 default ENV_MANAGER.gvCredentialName
   );



   /**
      * @name     EXPORT_TABLE_DATA_TO_CSV_BY_DATE
      * @desc     Exports data to separate CSV files partitioned by year and month.
      *           Creates one CSV file for each year/month combination found in the data.
      *           Uses the same date filtering mechanism with CT_ODS.A_LOAD_HISTORY as EXPORT_TABLE_DATA_BY_DATE,
      *           but exports to CSV format instead of Parquet.
      *           File naming pattern: {pFileName}_YYYYMM.csv or {TABLENAME}_YYYYMM.csv (if pFileName is NULL)
      * @example  
      *   begin
      *      -- With custom filename
      *      DATA_EXPORTER.EXPORT_TABLE_DATA_TO_CSV_BY_DATE(
      *          pSchemaName     => 'CT_MRDS',
      *          pTableName      => 'MY_TABLE',
      *          pKeyColumnName  => 'A_WORKFLOW_HISTORY_KEY',
      *          pBucketArea     => 'DATA',
      *          pFolderName     => 'exports',
      *          pFileName       => 'my_export.csv',
      *          pMinDate        => DATE '2024-01-01',
      *          pMaxDate        => SYSDATE
      *      );
      *      
      *      -- With auto-generated filename (based on table name only)
      *      DATA_EXPORTER.EXPORT_TABLE_DATA_TO_CSV_BY_DATE(
      *          pSchemaName     => 'OU_TOP',
      *          pTableName      => 'AGGREGATED_ALLOTMENT',
      *          pKeyColumnName  => 'A_WORKFLOW_HISTORY_KEY',
      *          pBucketArea     => 'ARCHIVE',
      *          pFolderName     => 'exports',
      *          pMinDate        => DATE '2025-09-01',
      *          pMaxDate        => DATE '2025-09-17'
      *      );
      *      -- This will create files like: AGGREGATED_ALLOTMENT_202509.csv, etc.
      *      pBucketArea parameter accepts: 'INBOX', 'ODS', 'DATA', 'ARCHIVE'
      *   end;
   **/
   PROCEDURE EXPORT_TABLE_DATA_TO_CSV_BY_DATE (
      pSchemaName      IN VARCHAR2,
      pTableName       IN VARCHAR2,
      pKeyColumnName   IN VARCHAR2,
      pBucketArea      IN VARCHAR2,
      pFolderName      IN VARCHAR2,
      pFileName        IN VARCHAR2 DEFAULT NULL,
      pColumnList      IN VARCHAR2 default NULL,
      pMinDate         IN DATE     default DATE '1900-01-01',
      pMaxDate         IN DATE     default SYSDATE,
      pCredentialName  IN VARCHAR2 default ENV_MANAGER.gvCredentialName
   );

   ---------------------------------------------------------------------------------------------------------------------------
   -- VERSION MANAGEMENT FUNCTIONS
   ---------------------------------------------------------------------------------------------------------------------------

   /**
      * Returns the current package version number
      * return: Version string in format X.Y.Z (e.g., '2.1.0')
   **/
   FUNCTION GET_VERSION RETURN VARCHAR2;

   /**
      * Returns comprehensive build information including version, date, and author
      * return: Formatted string with complete build details
   **/
   FUNCTION GET_BUILD_INFO RETURN VARCHAR2;

   /**
      * Returns the version history with recent changes
      * return: Multi-line string with version history
   **/
   FUNCTION GET_VERSION_HISTORY RETURN VARCHAR2;

END;
