/*!
  @file           Converter_IManager.hpp
  @author         TorstenS
  @author         AlexanderK
  @ingroup        Converter
  @brief          abstract interface class to the converter
                  containing general functions to manage the converter
*/

/*
    ========== licence begin  GPL
    Copyright (c) 2001-2005 SAP AG

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
    ========== licence end

*/



#ifndef CONVERTER_IMANAGER_HPP
#define CONVERTER_IMANAGER_HPP


/*===========================================================================*
 *  INCLUDES                                                                 *
 **/

#include "gsp00.h"   // PASCAL: SP_basic_constants_and_types

#include "Converter/Converter_Version.hpp"
#include "DataAccess/Data_Types.hpp"
#include "IOManager/IOMan_BlockAddress.hpp"

class Kernel_DateTime;

/*!
  @interface      Converter_IManager
  @brief          abstract interface class to the converter
                  containing general functions to manage the converter
 */
class Converter_IManager
{
public:

    /*!
       @brief   returns the manager interface of the converter
       @return  (Converter_IManager) instance of the converter

       - This static function returns the interface of the converter which
         allows access to all methods defined in this interface class
     */
    static  Converter_IManager & Instance();

    /*!
       @brief   Creates converter for restarting an existing database
       @param   TaskId                      [in] own TaskId
       @param   ConverterVersion            [in] converter version from restart record
       @param   packedRootBlockAddr         [in] i/o address of converter root page
       @param   snapShotVersion             [in] converter version which identifies a frozen
                                                 snapshot of the converter
       @param   packedSnapShotRootBlockAddr [in] i/o address of the root of the frozen
                                                 converter snapshot
       @param   snapShotCreationTimeStamp   [in] creation 'timestamp' of the snapshot
       @param   bIncConverterVersion        [in] indicates whether version must be
                                                 incremented after the restart
       @param   bLastSaveDataSuccessful     [in] indicates whether the last save data
                                                 finished successfully
       @param   MaxDynamicPageNo            [in] maximun used dynamic page number of the
                                                 restarted database
       @param   MaxStaticPageNo             [in] maximun used static page number of the
                                                 restarted database
       @param   NumAllPages                 [in] maximum number of pages which can be stored
                                                 in the data base. this corresponds to the sum
                                                 of size of all devices
       @return  none


       - The internal structures of the converter are created.
       - Converter pages are read from devices. The converter root
         page can be found at address 'rootaddr'.
       - The parameters 'MaxDynamicPageNo', 'MaxStaticPageNo' and  'NumAllPages'
         are used to determine the initial size of the  converter.
       - 'ConverterVersion' is the converter version of the database to be
         recovered. If 'bIncConverterVersion' is true, the converter version
         is incremented after a successful restart.
     */
    virtual void Restart (
        const tsp00_TaskId              TaskId,
        const Converter_Version         &ConverterVersion,
        const IOMan_PackedBlockAddress  &packedRootBlockAddr,
        const Converter_Version         &snapShotVersion,
        const IOMan_PackedBlockAddress  &packedSnapShotRootBlockAddr,
        const Kernel_DateTime           &snapShotCreationTimeStamp,
        const SAPDB_Bool                bIncConverterVersion,
        const SAPDB_Bool                bLastSaveDataSuccessful,
        const Data_PageNo               MaxDynamicPageNo,
        const Data_PageNo               MaxStaticPageNo,
        const SAPDB_UInt                NumAllPages ) = 0;

    /*!
       @brief   Restart the converter for restore pages.
       @param   TaskId                      [in] own Task ID
       @param   ConverterVersion            [in] converter version from restart record
       @param   packedRootBlockAddr         [in] i/o address of converter root page
       @param   snapShotVersion             [in] converter version which identifies a frozen
                                                 snapshot of the converter
       @param   packedSnapShotRootBlockAddr [in] i/o address of the root of the frozen
                                                 converter snapshot
       @param   snapShotCreationTimeStamp   [in] creation 'timestamp' of the snapshot
       @param   bLastSaveDataSuccessful     [in] indicates whether the last save data
                                                 finished successfully
       @param   MaxDynamicPageNo            [in] maximun used dynamic page number of the
                                                 restarted database
       @param   MaxStaticPageNo             [in] maximun used static page number of the
                                                 restarted database
       @param   NumAllPages                 [in] maximum number of pages which can be stored
                                                 in the data base. this corresponds to the sum
                                                 of size of all devices
       @return  none


       - The internal structures of the converter are restarted
       - Converter pages are read from devices. The converter root
         page can be found at address 'rootaddr'.
       - The parameters 'MaxDynamicPageNo', 'MaxStaticPageNo' and
         'NumAllPages' are used to determine the initial size of
         the converter.
       - 'ConverterVersion' is the converter version of the database
         to be recovered. If 'bIncConverterVersion' is true, the converter
         version is incremented after a successful restart.
     */
    virtual void RestartForRestore (
        const tsp00_TaskId              TaskId,
        const Converter_Version         &ConverterVersion,
        const IOMan_PackedBlockAddress  &packedRootBlockAddr,
        const Converter_Version         &snapShotVersion,
        const IOMan_PackedBlockAddress  &packedSnapShotRootBlockAddr,
        const Kernel_DateTime           &snapShotCreationTimeStamp,
        const SAPDB_Bool                bLastSaveDataSuccessful,
        const Data_PageNo               MaxDynamicPageNo,
        const Data_PageNo               MaxStaticPageNo,
        const SAPDB_UInt                NumAllPages ) = 0;

    /*!
       @brief   Creates an empty converter for a new data base (needed for activate serverdb)
       @param   taskId      [in] taskId
       @param   numAllPages [in] maximum number of pages which can be stored in the data base.
                                 this corresponds to the sum of size of all devices
       @return  none

       - The internal structures of the converter are created.
       - The parameter 'NumAllPages' is used to determine the initial size of the  converter.
     */

    virtual void Create(
        const tsp00_TaskId taskId,
        const SAPDB_UInt   numAllPages ) = 0;

    /*!
       @brief   Creates an empty converter for restoring existing database
       @param   taskId                  [in] taskId
       @param   converterVersion        [in] converter version from restart record
       @param   bLastSaveDataSuccessful [in] indicates whether the last save data finished successfully
       @param   maxDynamicPageNo        [in] maximun used dynamic page number of the restarted database
       @param   maxStaticPageNo         [in] maximun used static page number of the restarted database
       @param   numAllPages             [in] maximum number of pages which can be stored in the data base.
                                             this corresponds to the sum of size of all data volumes
       @return  none

       - The internal structures of the converter are created and initialized.
       - The parameters 'MaxDynamicPageNo', 'MaxStaticPageNo' and 'NumAllPages'
         are used to determine the initial size of the  converter.
       - ConverterVersion' is the converter version of the database to be recovered.
     */

    virtual void  CreateForRestore(
        const tsp00_TaskId      taskId,
        const Converter_Version &converterVersion,
        const SAPDB_Bool        bLastSaveDataSuccessful,
        const Data_PageNo       maxDynamicPageNo,
        const Data_PageNo       maxStaticPageNo,
        const SAPDB_UInt        numAllPages ) = 0;

    /*!
       @brief   Shuts the converter down
       @param   taskId [in,out] task id
       @return  none

       - All resources held by the converter are released and all
         member data are reseted to their initial values
       - All tasks waiting for the converter are resumed.
     */

    virtual void Shutdown( const tsp00_TaskId taskId ) = 0;


    /*!
       @brief   Saves converter to data volumes (sequential writing)
       @param   taskId               [in] current task id
       @param   ConverterVersion    [out] new valid converter version
       @param   MaxDynamicPageNo    [out] maximun used dynamic page number. This
                                          number has to be stored in the restart page
                                          in order the calculate the right size of the
                                          converter (dynamic map) after a restart.
       @param   MaxStaticPageNo     [out] maximun used static page number. This number
                                          has to be stored in the restart page in order
                                          the calculate the right size of the converter
                                          (static map) after a restart.
                                          (see Converter_IManager::Restart)
       @param   packedRootBlockAddr [out] Block address of the converter
                                          root page (to be stored in the restart record)
       @return         SAPDB_Bool


       - All converter pages which have been changed since the last
         savepoint and which refer to permanent data pages are
         written out to data devspaces.
       - The routine returns several parameters describing the actual
         state of the converter.
       - If the flush is triggered by a SAVEPOINT the returned parameters are not
         needed since they were already inserted into the restart record by
         the Converter_ISavePoint::EndSavePoint method.
         If the converter is not active the return value is false;
     */
    virtual SAPDB_Bool FlushSerial (
        const tsp00_TaskId          taskId,
        Converter_Version           &ConverterVersion,
        Data_PageNo                 &MaxStaticPageNo,
        Data_PageNo                 &MaxDynamicPageNo,
        IOMan_PackedBlockAddress    &packedRootBlockAddr ) = 0;

    /*!
       @brief   Saves converter to data volumes (sequential writing)
       @param   taskId               [in] current task id
       @param   packedRootBlockAddr [out] Block address of the converter root
                                          page (to be stored in the restart record
       @return  SAPDB_Bool


       - All converter pages which have been changed since the last
         savepoint and which refer to permanent data pages are
         written out to data volumes in a sequential way.
         If the converter is not active the return value is false;
     */
    virtual SAPDB_Bool FlushSerialForColdSave (
        const tsp00_TaskId        taskId,
        IOMan_PackedBlockAddress  &packedRootBlockAddr ) = 0;

    /*!
       @brief   Expands the converter
       @param   TaskId        [in] current task id
       @param   DevNo         [in] logical identifier for the added data devspace
       @param   DevSize       [in] size of the added data devspace in pages.
       @param   VolMode       [in] access mode of volume
       @param   NumPagesAdded [in] number of pages added and usable by the data base (by assigning a new device)
       @return  none

       - Expands the converter to to manage NumPagesAdded more data pages
       - The routine is applicable with database in both cold and
         warm state.
       - The internal structures of the converter are adapted.
     */
    virtual SAPDB_Bool Expand (
        const tsp00_TaskId          TaskId,
        const IOMan_DeviceNo        &DevNo,
        const SAPDB_UInt            DevSize,
        const RTE_VolumeAccessMode  VolMode,
        const SAPDB_UInt            NumPagesAdded) = 0;
};

#endif  /* CONVERTER_IMANAGER_HPP */
