create or replace PACKAGE ODS.FILE_MANAGER_ODS
AUTHID DEFINER
AS
   /**
    * FILE_MANAGER_ODS - Wrapper package for CT_MRDS.FILE_MANAGER
    * 
    * This package serves as a wrapper for CT_MRDS.FILE_MANAGER procedures.
    * The key difference is that this package uses AUTHID DEFINER instead of 
    * AUTHID CURRENT_USER, which means all objects will be created in the ODS 
    * schema regardless of which user executes the procedures.
    * 
    * This solves the execution context issue where users need to connect as 
    * ODS user to use CT_MRDS.FILE_MANAGER procedures.
    * 
    * MARS-1049: Added pEncoding parameter support for CSV character set specification
    */

   -- Package Version Information (Semantic Versioning: MAJOR.MINOR.PATCH)
   PACKAGE_VERSION     CONSTANT VARCHAR2(10) := '2.1.0';
   PACKAGE_BUILD_DATE  CONSTANT VARCHAR2(20) := '2025-11-24 11:50:00';
   PACKAGE_AUTHOR      CONSTANT VARCHAR2(100) := 'Grzegorz Michalski';

   -- Version History (Latest changes first)
   VERSION_HISTORY     CONSTANT VARCHAR2(4000) := 
      '2.1.0 (2025-11-24): MARS-1049 - Added pEncoding parameter support for CSV character set specification' || CHR(13)||CHR(10) ||
      '2.0.0 (2025-10-22): Added package versioning system using centralized ENV_MANAGER functions' || CHR(13)||CHR(10) ||
      '1.5.0 (2025-10-12): Enhanced external table creation with official path patterns support' || CHR(13)||CHR(10) ||
      '1.0.0 (2025-09-20): Initial release with AUTHID DEFINER wrapper for external table creation';

   /**
    * @name     CREATE_EXTERNAL_TABLE
    * @desc     Creates external tables that can read data from Oracle Cloud Storage.
    *           This is a wrapper for CT_MRDS.FILE_MANAGER.CREATE_EXTERNAL_TABLE
    *           but uses DEFINER rights to ensure objects are created in ODS schema.
    *           
    *           MARS-1049: Added support for CSV character set encoding specification
    * @param    pTableName - Name of the external table to create
    * @param    pTemplateTableName - Template table defining the structure
    * @param    pPrefix - Storage path prefix in Oracle Cloud Storage
    * @param    pBucketUri - URI of the target bucket (default: ENV_MANAGER.gvInboxBucketUri)
    * @param    pFileName - Specific file name (optional)
    * @param    pDelimiter - Field delimiter (default: ',')
    * @param    pEncoding - Character set encoding for CSV files (e.g., 'UTF-8', 'WE8MSWIN1252', 'EE8ISO8859P2')
    *                       If NULL, no CHARACTERSET clause is added to external table definition
    * @example  EXEC ODS.FILE_MANAGER_ODS.CREATE_EXTERNAL_TABLE(
    *               'C2D_A_UC_DISSEM_METADATA_LOADS_INBOX',
    *               'CT_ET_TEMPLATES.C2D_A_UC_DISSEM_METADATA_LOADS',
    *               'INBOX/C2D/UC_DISSEM/A_UC_DISSEM_METADATA_LOADS',
    *               CT_MRDS.ENV_MANAGER.gvInboxBucketUri,
    *               NULL, ',', 'UTF-8'
    *           );
    */
   PROCEDURE CREATE_EXTERNAL_TABLE (
      pTableName          IN VARCHAR2,
      pTemplateTableName  IN VARCHAR2,
      pPrefix             IN VARCHAR2,
      pBucketUri          IN VARCHAR2 DEFAULT CT_MRDS.ENV_MANAGER.gvInboxBucketUri,
      pFileName           IN VARCHAR2 DEFAULT NULL,
      pDelimiter          IN VARCHAR2 DEFAULT ',',
      pEncoding           IN VARCHAR2 DEFAULT NULL
   );

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

   /**
      * @name     GET_VERSION
      * @desc     Returns the current version number of the FILE_MANAGER_ODS package.
      *           Uses semantic versioning format (MAJOR.MINOR.PATCH).
      * @example  SELECT FILE_MANAGER_ODS.GET_VERSION() FROM DUAL;
      * @ex_rslt  2.1.0
   **/
   FUNCTION GET_VERSION RETURN VARCHAR2;

   /**
      * @name     GET_BUILD_DATE
      * @desc     Returns the build date of the FILE_MANAGER_ODS package.
      * @return   VARCHAR2 - Build date in format 'YYYY-MM-DD HH24:MI:SS'
      * @example  SELECT ODS.FILE_MANAGER_ODS.GET_BUILD_DATE() FROM DUAL;
      */
   FUNCTION GET_BUILD_DATE RETURN VARCHAR2;

   /**
      * @name     GET_AUTHOR
      * @desc     Returns the author of the FILE_MANAGER_ODS package.
      * @return   VARCHAR2 - Package author name
      * @example  SELECT ODS.FILE_MANAGER_ODS.GET_AUTHOR() FROM DUAL;
      */
   FUNCTION GET_AUTHOR RETURN VARCHAR2;

   /**
      * @name     GET_BUILD_INFO
      * @desc     Returns comprehensive build information including version, build date, and author.
      *           Uses centralized ENV_MANAGER.GET_PACKAGE_VERSION_INFO function.
      * @example  SELECT FILE_MANAGER_ODS.GET_BUILD_INFO() FROM DUAL;
      * @ex_rslt  Package: FILE_MANAGER_ODS
      *           Version: 2.1.0
      *           Build Date: 2025-11-24 11:50:00
      *           Author: Grzegorz Michalski
   **/
   FUNCTION GET_BUILD_INFO RETURN VARCHAR2;

   /**
      * @name     GET_VERSION_HISTORY
      * @desc     Returns complete version history with all releases and changes.
      *           Uses centralized ENV_MANAGER.FORMAT_VERSION_HISTORY function.
      * @example  SELECT FILE_MANAGER_ODS.GET_VERSION_HISTORY() FROM DUAL;
      * @ex_rslt  FILE_MANAGER_ODS Version History:
      *           2.0.0 (2025-10-22): Added package versioning system...
   **/
   FUNCTION GET_VERSION_HISTORY RETURN VARCHAR2;

END FILE_MANAGER_ODS;

/