dbmanagercontainer.hpp

/*
This file is part of libdbmanager
(see the file COPYING in the root of the sources for a link to the
homepage of libdbmanager)

libdbmanager is a C++ library providing methods for reading/modifying a
database using only C++ methods & objects and no SQL
Copyright (C) 2016 Legrand SA

libdbmanager is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License version 3
(dated 29 June 2007) as published by the Free Software Foundation.

libdbmanager 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with libdbmanager (in the source code, it is enclosed in
the file named "lgpl-3.0.txt" in the root of the sources).
If not, see <http://www.gnu.org/licenses/>.
*/
/**
 *
 * \file dbmanagercontainer.hpp
 *
 * \brief Container to manipulate instances of DBManager
 */

#ifndef _DBMANAGERCONTAINER_HPP_
#define _DBMANAGERCONTAINER_HPP_

//STL includes
#include <string>
#include <exception>

#include "dbmanagerapi.hpp"	// For LIBDBMANAGER_API

//Library includes
#include "dbmanager.hpp"

/**
 * \class DBManagerContainer
 *
 * \brief Class to encapsulate a DBManager object (generated by class DBManagerFactory)
 * It will ensure the object is created (if not already existing), and the reference count is kepts up to date during the life cycle of DBManagerContainer
 * (DBManagerFactory::getInstance().freeDBManager() will be called when this DBManagerContainer is destructed)
 */
class LIBDBMANAGER_API DBManagerContainer {

	/**
	 * \brief swap function to allow implementing of copy-and-swap idiom on members of type DBManagerContainer
	 *
	 * This function will swap all attributes of \p first and \p second
	 * See http://stackoverflow.com/questions/3279543/what-is-the-copy-and-swap-idiom
	 *
	 * \param first The first object
	 * \param second The second object
	 */
	friend void swap(DBManagerContainer& first, DBManagerContainer& second);

public:
	/**
	 * \brief Class constructor
	 *
	 * Arguments are the same as DBManagerFactory::getDBManager()
	 *
	 * \param dbLocation The location, in a URL address, of the database to manage.
	 * \param configurationDescriptionFile The path to the configuration file to use for this database, or the configuration content directly provided as a std::string (no carriage return allowed in this case)
	 * \param exclusive When true, ensures that encapsulated DBManager is not shared by any other container, or raise an exception otherwise
	 */
	DBManagerContainer(std::string dbLocation, std::string configurationDescriptionFile="", bool exclusive=false);

	/**
	 * \brief Copy constructor
	 *
	 * \param other The object to copy from
	 */
	DBManagerContainer(const DBManagerContainer& other);

	/**
	 * \brief Class destructor
	 *
	 * Will ensure the underlying DBManager object reference count is decremented (and destructed by factory if reference count reaches 0)
	 */
	~DBManagerContainer();

	/**
	 * \brief Assignment operator
	 * 
	 * Private... we don't accept assignment, just instanciate a new object instead or use references
	 */
	DBManagerContainer& operator=(const DBManagerContainer& other) = delete;
	
	/**
	 * \brief Attribute getter
	 *
	 * Get a reference to the encapsulated DBManager object
	 *
	 * \return A reference to the encapsulated DBManager object
	 */
	inline DBManager& getDBManager() const {
		return this->dbm;
	}

private:
	std::string dbLocation;	/*!< The location URL of the database handled by the DBManager object encapsulated in this container */
	std::string configurationDescriptionFile;	/*!< The path to the configuration file to use for the encapsulated DBManager object in this container, or the configuration content directly provided as a std::string (no carriage return allowed in this case) */
	bool exclusive;	/*!< If true, it will be forbidden to share the encapsulated DBManager with any other container. This means copy construction and assignment will fail with an excpetion */

	DBManager& dbm;	/*!< The DBManager object encapsulated in this container. Use DBManagerContainer::getDBManager() method to get access to this attribute */
};

#endif //_DBMANAGERCONTAINER_HPP_