TEXT
package xpp_internal
is
/**
 * Project:         Project (<a href="http://en.1stsw.com/products/extreme-parallel-processing/"> XPP 1. SOFTWAROV┴ s.r.o.</a>)
 * Description:     Internal Package for eXtreme Parallel Processing
 * <p> 
 * @author          Petr Jezek
 * @version         1.0.1, 2013-03-10
 * @since           1.0 
 * @headcom
 */
 
    
/**
 * The function is returning name of current schema
 * 
 * @return The name of schema where is XPP installed in varchar2
 * @throws c_err_get_curr_schema_name  The name of schema where is XPP installed is not possible to retrive. 
 */
  function get_current_schema_name
  return varchar2;

/**
 * The function is translating required p_queue_name to real queue name.
 * The goal of this translation it to secure creation/modify/delete of internal XPP queues.  
 * 
 * @param p_queue_name The requested name of queue.  
 * @return name of real queue in varchar2 
 * @throws c_err_get_curr_schema_name  The name of schema where is XPP installed is not possible to retrive.   
 */  
  function get_queue_name(
    p_queue_name     in varchar2
   ,p_with_schema    in boolean default true
  ) return varchar2;
  
/**
 * The function is translating required p_queue_name to real recipient name.
 * The goal of this translation it to secure creation/modify/delete of internal XPP recipients.  
 * 
 * @param p_queue_name The requested name of queue.  
 * @return name of real recipient in varchar2  
 */ 
  function get_queue_recipient_def_name(
    p_queue_name     in varchar2
  ) return varchar2;

/**
 * The function is returning name exception when queue is empty.
 * 
 * @param p_queue_name The name of queue.  
 * @return The message name of empty queue in varchar2  
 */  
  function get_msg_name_empty_queue(
    p_queue_name     in varchar2
  ) return varchar2;


---------------------------------------- types --------------------------------
/**
 * The procedure defines user type for queue p_queue_name acording definition in parameter p_queue_type_body.
 * Name of required type is based on p_queue_name.
 * Finally is the new type granted for actual executor. 
 * Note: it can raise the same exception like is raising CREATE TYPE command and GRANT EXEUTE commnad.   
 *  
 * @param p_queue_name         The name of queue associate to the the requested type.
 * @param p_queue_type_body    The definition of new type. (It is according defintion part in the brackets while definion of new type.)  
 * @param p_queue_type_name    The name of newly created type 
 * @throws c_err_queue_name The queue name is forbidden. 
 */ 
  procedure define_type(
    p_queue_name        in varchar2
   ,p_queue_type_body   in varchar2
   ,p_queue_type_name  out varchar2
  );

/**
 * The procedure drops user type for queue p_queue_name.
 * Name of required type is based on p_queue_name.
 * Note: it can raise the same exception like is raising DROP TYPE commnad.   
 *  
 * @param p_queue_name         The name of queue associate to the the requested type.
 * @throws c_err_queue_name The queue name is forbidden. 
 */ 
  procedure destroy_type(
    p_queue_name        in varchar2
  );

----------------------------------------- sequences ---------------------------

/**
 * The procedure defines user sequence for queue p_queue_name.
 * Name of sequence is based on p_queue_name.
 *  
 * @param p_queue_name         The name of queue associate to the the requested sequence.
 * @throws c_err_queue_name The queue name is forbidden. 
 */ 
  procedure define_sequence(
    p_queue_name        in varchar2
  );

/**
 * The procedure drops user sequence for queue p_queue_name.
 *  
 * @param p_queue_name         The name of queue associate to the the requested sequence.
 * @throws c_err_queue_name The queue name is forbidden. 
 */ 
  procedure destroy_sequence(
    p_queue_name        in varchar2
  );

---------------------------------------- tables -------------------------------

/**
 * The procedure defines table for queue p_queue_name.
 * Name of table is based on p_queue_name.
 * Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM. 
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 * @param p_storage_clause       The storage clause for reation of queue table.  
 * @throws c_err_queue_name           The queue name is forbidden.
 * @throws c_err_creation_queue_table The table is not created or is not created in expected time.
 */ 
  procedure define_table(
     p_queue_name        in varchar2
    ,p_storage_clause    in varchar2
  );

/**
 * The procedure drops table for queue p_queue_name.
 *  
 * @param p_queue_name                   The name of table associate to the the requested sequence.
 * @throws c_err_queue_name           The queue name is forbidden.  
 * @throws c_err_deletion_queue_table The table is not dropped or is not dropped in expected time.
 */ 
   procedure destroy_table(
      p_queue_name        in varchar2
   );

---------------------------------------- queue --------------------------------

/**
 * The procedure defines queue p_queue_name.
 * Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM. 
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 * @throws c_err_queue_name           The queue name is forbidden.
 * @throws c_err_creation_queue       The queue is not created or is not created in expected time.
 */ 
  procedure define_queue(
     p_queue_name     in varchar2
    ,p_queue_comments in varchar2 := null
    ,p_user_to_grant  in varchar2 := null
  );


/**
 * The procedure drops queue queue p_queue_name.
 *  
 * @param p_queue_name                   The name of table associate to the the requested sequence.
 * @throws c_err_queue_name           The queue name is forbidden.  
 * @throws c_err_deletion_queue_table The queue is not dropped or is not dropped in expected time.
 */ 
  procedure destroy_queue(
   p_queue_name        in varchar2
  );


---------------------------------------- package ------------------------------

/**
 * The procedure defines interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
 * Name of packages is based on p_queue_name.
 * Note: it can raise the same exception like is raising CREATE OR REPLACE PACKAGE command and GRANT EXEUTE commnad.   
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 * @throws c_err_queue_name           The queue name is forbidden.
 */ 
  procedure define_processing_package(
      p_queue_name         in varchar2
  );

/**
 * The procedure drops interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
 * Note: it can raise the same exception like is raising DROP PACKAGE command.   
 *  
 * @param p_queue_name                   The name of table associate to the the requested sequence.
 * @throws c_err_queue_name           The queue name is forbidden.  
 */ 
  procedure destroy_processing_package(
      p_queue_name         in varchar2
  );

---------------------------------------- subscribers --------------------------

/**
 * The procedure defines subscriber for queue p_queue_name.
 * Name of subscriber and recepient is based on p_queue_name.
 * Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM. 
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 * @param p_recipient_name               The name of recepient of queue associate to the the requested table.
 * @throws c_err_queue_name           The queue name is forbidden.
 * @throws c_err_creation_subscriber  The subscriber is not created or is not created in expected time.
 */
  procedure add_subscriber(
      p_queue_name         in varchar2
     ,p_recipient_name     in varchar2
  );
  
/**
 * The procedure drops subscriber for queue p_queue_name.
 * Note: The expected time of dropping is defined by value of MAX_DURATION in table XPP_CONF_PARAM. 
 *  
 * @param p_queue_name                   The name of table associate to the the requested sequence.
 * @throws c_err_queue_name           The queue name is forbidden.  
 * @throws c_err_deletion_subscriber  The subscriber is not dropped or is not dropped in expected time.
 */
  procedure del_subscriber(
     p_queue_name         in varchar2
    ,p_recipient_name     in varchar2
  );

-------------------------------- queue configuration ---------------------------

/**
 * The procedure defines subscriber for queue p_queue_name.
 * Name of subscriber configuration is based on p_queue_name.
 *  
 * @param p_queue_name                     The name of table associate to the the requested sequence.
 * @throws c_err_queue_name             The queue name is forbidden.
 * @throws c_err_number_of_executors    The number of requested parallel tasks is forbidden.
 * @throws c_err_queue_is_not_defined       The queue is not defined. (Prior the XPP.EVENT_OPEN should be called XPP.EVENT_INIT)
 * @throws c_err_subscr_conf_exists The subscriber configuration of queue already exists.
 *   
 */ 
   procedure add_subscription_conf(
      p_queue_name           in varchar2
     ,p_general_procedure    in varchar2
     ,p_number_of_executors  in number
     ,p_procedure_to_run     in varchar2
     ,p_procedure_on_success in varchar2 default null
     ,p_procedure_on_error   in varchar2 default null
     ,p_param_on_error_input in number   default 1
     ,p_step                 in number   default 0
   );
   
/**
 * The procedure drops subscriber for queue p_queue_name.
 *  
 * @param p_queue_name                   The name of table associate to the the requested sequence.
 * @throws c_err_queue_name           The queue name is forbidden.  
 * @throws c_err_deletion_queue_table The table is not dropped or is not dropped in expected time.
 */ 
   procedure delete_all_subscription_conf(
      p_queue_name       in varchar2
   );
   
-------------------------------- requests -------------------------------------

/**
 * The procedure add requests into queue p_queue_name.
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 * @param p_record                       The record to insert into queue is long row type.
 * @param p_message_id                   The message id.
 */ 
  procedure add_request(
       p_queue_name       in  varchar2
      ,p_record           in  long raw
      ,p_message_id       out raw
  );
  
/**
 * The procedure remove all requests from queue p_queue_name.
 *  
 * @param p_queue_name                   The name of queue associate to the the requested table.
 */ 
  procedure delete_all_request(
       p_queue_name       in varchar2
  );

---------------------------------------- processing ---------------------------

/**
 * The procedure is waiting for message.
 * When value of input value p_unlimited_time is true, then waiting will be limited by maxiaml possible time defiend by database.
 * Otherwise the expected time of waiting is defined by value of MAX_DURATION in table XPP_CONF_PARAM.  
 * 
 * @param p_alert          The name of message (or alert).  
 * @param p_msg            The content of message.  
 * @param p_stat           Status of message. Possible values is 0, 1, 2. See definition of dbms_alert.waitone. 
 * @param p_unlimited_time The boolean value is setting waiting time to maximum configured in DB or based on XPP configuration.  
 */ 
  procedure wait_my_alert(
    p_alert in varchar2
   ,p_msg   out varchar2
   ,p_stat  out number
   ,p_unlimited_time in boolean default false
  );



/**
 * The procedure is initiate definition task, register catching of message when queue will be processed and execute the processing of the task. 
 * 
 * @param p_task_name                        The name of task.  
 * @param p_queue_name                       The requested name of queue.  
 * @param p_comment                          The comment of task.  
 * @param p_sql_stmt                         The sql statement to be executed in parallel.  
 * @param p_parallel_level                   The level of requested parallel execution of queue.
 * @throws c_err_end_of_evaluation_period The evaluation period is over.   
 */ 
  procedure initiate (
      p_task_name      in varchar2
     ,p_queue_name     in varchar2
     ,p_comment        in varchar2
     ,p_sql_stmt       in clob
     ,p_parallel_level in number
  );

/**
 * The procedure is cleaning configuration of task 
 * Note: All exceptions while cleaning are disabled.
 *   
 * @param p_task_name                        The name of task.  
 */ 
  procedure clean_task (
    p_task_name in varchar2
  );

/**
 * The procedure is sending message indentify by p_name parameter with context in parameter p_message. 
 * Note: When the length of context of message is longer then 1900 bytes then is cut to 1900  
 *   
 * @param p_name             The name of message.  
 * @param p_message          The content of the message.  
 */   
  procedure send_message(
     p_name    in varchar2
    ,p_message in varchar2
  );

/**
 * The function is returning of processing of task in varchar2.
 *  List of possible statuses
 *  NOT_EXISTS 
 *  CREATED
 *  CHUNKING
 *  CHUNKING_FAILED
 *  CHUNKED
 *  PROCESSING
 *  FINISHED
 *  FINISHED_WITH_ERROR
 *  CRASHED
 * <p> 
 * @return The status of tasks in varchar2.  
 */
  function get_processing_status(p_task_name in varchar2)
  return varchar2;
    
/**
 * The function is returning true task is running or configured an ready to running, otherwise it return false.
 * 
 * @param p_task_name The name of task.  
 * @return It returns true when task is running, otherwise it returns false.
 */ 
  function is_task_running (
    p_task_name in varchar2
  ) return boolean;

/**
 * The function is returning true task is successfuly finished, otherwise it return false.
 * 
 * @param p_task_name The name of task.  
 * @return It returns true when task is successfuly finished, otherwise it returns false.
 */   
  function is_task_finished_successfuly (
    p_task_name in varchar2
  ) return boolean;

/**
 * The function returns varchar2 with list of error raised while fatal error of task execution.
 * 
 * @param p_task_name The name of task.  
 * @return It returns varchar2 with list of error raised while fatal error of task execution.
 */    
  function collect_and_raise_task_errors(
    p_task_name in varchar2
  ) return varchar2;

/**
 * The procedure is chceking if the instance is running. 
 * When is not running the it runs the parallel task.
 * Each task will try in concurency mode dequeue and process messages from the queue. 
 * 
 * @param p_queue_name The requested name of queue. 
 * @throws c_err_error_while_run_parallel The creation of parallel task fail.  
 */ 
  procedure run_subscriber_processing(
     p_queue_name      in varchar2
  );

/**
 * The procedure is stopping running instance of task.
 * It will raise exception when parameter p_raise_exeception is set to true and task is not running. 
 * 
 * @param p_queue_name              The requested name of queue. 
 * @throws c_err_task_not_exists The task to stop not exists.  
 */   
    procedure task_stop(
      p_task_name        in varchar2
     ,p_raise_exeception in boolean default true
    );
    
/**
 * The procedure is returning identification of official buyer of the XPP.
 *   
 * @param p_company_name    The name of company.  
 * @param p_invoice_id      The identification of invoice.  
 * @param p_paymenent_type  The payment information.  
 * @param p_paymenent_date  The date of payment.  
 */   
  procedure licence_id (
    p_company_name   out varchar2
   ,p_invoice_id     out varchar2
   ,p_paymenent_type out varchar2
   ,p_paymenent_date out varchar2
  );


end xpp_internal;