/*

Copyright (c) 2002-2005, Yauheni Akhotnikau
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

- The name of the author may not be used to endorse or promote products derived
from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.

*/

/*
	ObjESSty-1
*/

/*!
	\file
	\brief Интерфейс объекта, управляющего базами данных на локальной
	машине.
*/

#if !defined( _OESS_1__DB__SITE__LOCALHOST_HPP_ )
#define _OESS_1__DB__SITE__LOCALHOST_HPP_

#include <oess_1/db/h/declspec.hpp>

#include <string>

#include <oess_1/defs/h/types.hpp>

#include <oess_1/db/storage/h/config.hpp>

#include <oess_1/db/site/h/abstract_connector.hpp>

namespace oess_1 {

namespace db {

namespace site {

namespace impl {

class	request_t;
class	response_t;

} /* namespace impl */

//
// localhost_t
//

/*!
	\brief Интерфейс объекта, управляющего базами данных на локальной
	машине.

	Фактически, часть сервера баз данных, отвечающая
	только за взаимодействие базой данных.
*/
class	OESS_1__DB__TYPE	localhost_t
{
	public :
		virtual ~localhost_t();

		//! Параметры создания БД.
		enum
		{
			//! Не пересоздавать уже существующую БД.
			no_overwrite = 1
		};

		//! Физически создать базу данных.
		/*! \since v.1.1.0

			Создается база с пустой схемой данных.

			Созданная база данных не становится автоматически
			доступной для использования. После успешного
			создания база должна быть описана последующим
			обращением к db_describe(). */
		virtual void
		db_create(
			//! Физическое имя БД (имя файла без расширения).
			const std::string & physic_name,
			//! Битовая маска флагов, определяющих
			//! режим создания БД. Если установлен флаг
			//! no_overwrite, то существующая БД не пересоздается.
			//! В противном случае старое содержимое БД будет
			//! потеряно.
			oess_1::uint_t creation_mode ) = 0;

		//! Физически создать базу данных.
		/*! \since v.1.4.0

			Использование этого метода предпочтительнее, т.к. он предоставляет
			возможность задать конфигурацию новой БД.

			Созданная база данных не становится автоматически
			доступной для использования. После успешного
			создания база должна быть описана последующим
			обращением к db_describe(). */
		virtual void
		db_create(
			//! Физическое имя БД (имя файла без расширения).
			const std::string & physic_name,
			//! Конфигурация новой БД.
			const oess_1::db::storage::config_t & config,
			//! Битовая маска флагов, определяющих
			//! режим создания БД. Если установлен флаг
			//! no_overwrite, то существующая БД не пересоздается.
			//! В противном случае старое содержимое БД будет
			//! потеряно.
			oess_1::uint_t creation_mode ) = 0;

		//! Описать доступную для использования базу.
		virtual void
		db_describe(
			//! Логическое имя БД (т.е. имя, через которое
			//! база будет доступна клиентам).
			const std::string & logic_name,
			//! Физическое имя БД (фактически, имя файла БД
			//! без расширения).
			const std::string & physic_name,
			//! Размер кэша для этой базы (количество страниц
			//! хранилища, одновременно удерживаемых в ОП).
			//! \deprecated Начиная с версии v.1.4. игнорируется.
			oess_1::uint_t cache_size,
			//! true, если БД нужно открыть в режиме read-only.
			bool is_read_only,
			//! true, если разрешается автоматическое
			//! восстановление БД после сбоев.
			bool is_auto_repair_enabled ) = 0;

		//! Описать доступную для использования базу.
		/*!
			\since v.1.4.0

			Использование этого метода предпочтительнее, т.к. он предоставляет
			возможность задать конфигурацию новой БД.
		*/
		virtual void
		db_describe(
			//! Логическое имя БД (т.е. имя, через которое
			//! база будет доступна клиентам).
			const std::string & logic_name,
			//! Физическое имя БД (фактически, имя файла БД
			//! без расширения).
			const std::string & physic_name,
			//! Конфигурация для использования БД.
			const oess_1::db::storage::config_t & config,
			//! true, если БД нужно открыть в режиме read-only.
			bool is_read_only,
			//! true, если разрешается автоматическое
			//! восстановление БД после сбоев.
			bool is_auto_repair_enabled ) = 0;

		//! Сбросить содержимое кэша открытых БД на диск.
		/*!
			\deprecated Начиная с версии v.1.4. флуширование БД
				осуществляется автоматически при завершении транзакции.
		*/
		virtual void
		db_flush_all() = 0;

		//! Установить/отменить режим автоматического
		//! флуширования после выполнения каждой операции,
		//! изменяющей указанную БД.
		/*!
			\deprecated Начиная с версии v.1.4. флуширование БД
				осуществляется автоматически при завершении транзакции.

			Включение режима автоматического флуширования
			не сбрасывает на диск страницы, которые в данный
			момент находятся в кэше.

			\return Предыдущее значение режима
			автоматического флуширования.
		*/
		virtual bool
		db_set_auto_flush(
			/*! Логическое имя БД, на которую осуществляется
				воздействие. */
			const std::string & logic_name,
			/*! Если true, то после завершения каждой
				операции, изменяющей БД, будет просходить
				сброс всех "грязных" страниц кэша на диск. */
			bool is_on ) = 0;

		//! Обработать запрос и отдать результат.
		/*! Возвращается указатель на динамически-созданный
			объект response, который должен быть удален
			посредством delete. */
		virtual impl::response_t *
		process(
			const impl::request_t & req ) = 0;

};

//
// create_std_localhost
//

/*!
	Создание стандартной реализации интерфейса localhost_t.
	Возвращается указатель на динамически созданный объект,
	который должен быть уничтожен посредством оператора
	delete.
*/
OESS_1__DB__FUNC(localhost_t *)
create_std_localhost();

//
// create_std_localhost_connector
//

/*!
	Создание стандартной реализации интерфейса
	abstract_connector_t, предназначенной для
	работы с объектом localhost_t.
	Возвращается указатель на динамически созданный объект,
	который должен быть уничтожен посредством оператора
	delete.
*/
OESS_1__DB__FUNC(abstract_connector_t *)
create_std_localhost_connector(
	localhost_t & );

} /* namespace site */

} /* namespace db */

} /* namespace oess_1 */

#endif
