Commit 22ee54dc authored by Matthieu Dorier's avatar Matthieu Dorier
Browse files

added comments and an execute function

parent 751a6747
......@@ -9,56 +9,151 @@ namespace sonata {
class AdminImpl;
/**
* @brief Admin interface to a Sonata service. Enables creating
* and destroying databases, and attaching and detaching them
* from a provider. If Sonata providers have set up a security
* token, operations from the Admin interface will need this
* security token.
*/
class Admin {
public:
/**
* @brief Constructor.
*
* @param engine Thallium engine.
* @param token Security token setup by providers.
*/
Admin(thallium::engine& engine, const std::string& token);
/**
* @brief Copy constructor.
*/
Admin(const Admin&);
/**
* @brief Move constructor.
*/
Admin(Admin&&);
/**
* @brief Copy-assignment operator.
*/
Admin& operator=(const Admin&);
/**
* @brief Move-assignment operator.
*/
Admin& operator=(Admin&&);
/**
* @brief Destructor.
*/
~Admin();
/**
* @brief Check if the Admin instance is valid.
*/
operator bool() const;
/**
* @brief Creates a database on the target provider.
* The config string must be a JSON object acceptable
* by the desired backend's creation function.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to create.
* @param type Type of the database to create.
* @param config JSON configuration for the database.
*/
void createDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name,
const std::string& type,
const std::string& config) const;
/**
* @brief Creates a database on the target provider.
* The config object must be a JSON object acceptable
* by the desired backend's creation function.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to create.
* @param type Type of the database to create.
* @param config JSON configuration for the database.
*/
void createDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name,
const std::string& type,
const Json::Value& config) const;
/**
* @brief Attaches an existing database to the target provider.
* The config string must be a JSON object acceptable
* by the desired backend's attach function.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to create.
* @param type Type of the database to create.
* @param config JSON configuration for the database.
*/
void attachDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name,
const std::string& type,
const std::string& config) const;
/**
* @brief Attaches an existing database to the target provider.
* The config object must be a JSON object acceptable
* by the desired backend's attach function.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to create.
* @param type Type of the database to create.
* @param config JSON configuration for the database.
*/
void attachDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name,
const std::string& type,
const Json::Value& config) const;
/**
* @brief Detach an attached database from the target provider.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to detach.
*/
void detachDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name) const;
/**
* @brief Destroys an attached database from the target provider.
*
* @param address Address of the target provider.
* @param provider_id Provider id.
* @param name Name of the database to destroy.
*/
void destroyDatabase(const std::string& address,
uint16_t provider_id,
const std::string& name) const;
/**
* @brief Shuts down the target server. The Thallium engine
* used by the server must have remote shutdown enabled.
*
* @param address Address of the server to shut down.
*/
void shutdownServer(const std::string& address) const;
private:
......
......@@ -2,74 +2,227 @@
#define __SONATA_BACKEND_HPP
#include <sonata/RequestResult.hpp>
#include <unordered_set>
#include <unordered_map>
#include <functional>
#include <json/json.h>
/**
* @brief Helper class to register backend types into the backend factory.
*/
template<typename BackendType>
class __SonataBackendRegistration;
namespace sonata {
/**
* @brief Interface for database backends. To build a new backend,
* implement a class that inherits from Backend, and put
* SONATA_REGISTER_BACKEND(mybackend, MyBackend); in a cpp file
* that includes your backend class' header file.
*
* Your backend class should also have two static functions to
* respectively create and open a backend database:
*
* std::unique_ptr<Backend> create(const Json::Value& config)
* std::unique_ptr<Backend> attach(const Json::Value& config)
*/
class Backend {
public:
/**
* @brief Constructor.
*/
Backend() = default;
/**
* @brief Move-constructor.
*/
Backend(Backend&&) = default;
/**
* @brief Copy-constructor.
*/
Backend(const Backend&) = default;
/**
* @brief Move-assignment operator.
*/
Backend& operator=(Backend&&) = default;
/**
* @brief Copy-assignment operator.
*/
Backend& operator=(const Backend&) = default;
/**
* @brief Destructor.
*/
virtual ~Backend() = default;
/**
* @brief Executes Jx9 code on the Database. The variable
* names specified in vars will then be extracted and returned.
*
* @param code Code to execute.
* @param vars Variables to return.
*
* @return a RequestResult<std::unordered_map<std::string,std::string>>
* instance.
*/
virtual RequestResult<std::unordered_map<std::string,std::string>>
execute(const std::string& code,
const std::unordered_set<std::string>& vars) = 0;
/**
* @brief Creates a new collection in the database.
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<bool> instance.
*/
virtual RequestResult<bool> createCollection(
const std::string& coll_name) = 0;
/**
* @brief Checks if a collection exists.
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<bool> instance.
*/
virtual RequestResult<bool> openCollection(
const std::string& coll_name) = 0;
/**
* @brief Destroys a collection
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<bool> instance.
*/
virtual RequestResult<bool> dropCollection(
const std::string& coll_name) = 0;
/**
* @brief Stores a record into the collection.
* The record should be a valid JSON object.
*
* @param coll_name Name of the collection.
* @param record Record to store.
*
* @return a RequestResult<uint64_t> instance
* containing the record id if successful.
*/
virtual RequestResult<uint64_t> store(
const std::string& coll_name,
const std::string& record) = 0;
/**
* @brief Fetches a particular record by its id.
*
* @param coll_name Name of the collection.
* @param record_id Record id.
*
* @return a RequestResult<std::string> instance.
* containing the content of the record if successful.
*/
virtual RequestResult<std::string> fetch(
const std::string& coll_name,
uint64_t record_id) = 0;
/**
* @brief Returns an array of records matching a give
* Jx9 filter. The filter should be expressed as a string
* containing a function. For example:
*
* "function($user) { return $user.age > 30; }"
*
* @param coll_name Name of the collection.
* @param filter_code Code of the Jx9 function.
*
* @return a RequestResult<std::vector<std::string>>
* instance containing the result of the request.
*/
virtual RequestResult<std::vector<std::string>> filter(
const std::string& coll_name,
const std::string& filter_code) = 0;
/**
* @brief Updates an existing record with the new content.
*
* @param coll_name Name of the collection.
* @param record_id Record to update.
* @param new_content New content of the record.
*
* @return a RequestResult<bool> instance indicating
* whether the update was successful.
*/
virtual RequestResult<bool> update(
const std::string& coll_name,
uint64_t record_id,
const std::string& new_content) = 0;
/**
* @brief Returns all the records in the collection.
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<std::vector<std::string>> instance
* containing all the records as strings, if successful.
*/
virtual RequestResult<std::vector<std::string>> all(
const std::string& coll_name) = 0;
/**
* @brief Returns the last record id stored in the collection.
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<uint64_t> instance containing
* the last record id, if successful.
*/
virtual RequestResult<uint64_t> lastID(
const std::string& coll_name) = 0;
/**
* @brief Returns the size of the collection.
*
* @param coll_name Name of the collection.
*
* @return a RequestResult<size_t> instance containing
* the size of the collection.
*/
virtual RequestResult<size_t> size(
const std::string& coll_name) = 0;
/**
* @brief Erases the specified record from the collection.
*
* @param coll_name Name of the collection.
* @param record_id Record to erase.
*
* @return a RequestResult<bool> instance.
*/
virtual RequestResult<bool> erase(
const std::string& coll_name,
uint64_t record_id) = 0;
/**
* @brief Destroys the underlying database resources.
*
* @return a RequestResult<bool> instance indicating
* whether the database was successfully destroyed.
*/
virtual RequestResult<bool> destroy() = 0;
};
/**
* @brief The BackendFactory contains function to create
* or attach databases.
*/
class BackendFactory {
template<typename BackendType>
......@@ -79,9 +232,27 @@ class BackendFactory {
BackendFactory() = delete;
/**
* @brief Creates a database and returns a unique_ptr to the created
* backend instance.
*
* @param backend_name Name of the backend to use.
* @param config Configuration object to pass to the backend's create function.
*
* @return a unique_ptr to the created Backend.
*/
static std::unique_ptr<Backend> createBackend(const std::string& backend_name,
const Json::Value& config);
/**
* @brief Opens an existing database and returns a unique_ptr to the
* created backend instance.
*
* @param backend_name Name of the backend to use.
* @param config Configuration object to pass to the backend's attach function.
*
* @return a unique_ptr to the created Backend.
*/
static std::unique_ptr<Backend> attachBackend(const std::string& backend_name,
const Json::Value& config);
......
......@@ -9,26 +9,63 @@ namespace sonata {
class ClientImpl;
/**
* @brief The Client object is the main object used to establish
* a connection with a Sonata service.
*/
class Client {
public:
/**
* @brief Constructor.
*
* @param engine Thallium engine.
*/
Client(thallium::engine& engine);
/**
* @brief Copy constructor.
*/
Client(const Client&);
/**
* @brief Move constructor.
*/
Client(Client&&);
/**
* @brief Copy-assignment operator.
*/
Client& operator=(const Client&);
/**
* @brief Move-assignment operator.
*/
Client& operator=(Client&&);
/**
* @brief Destructor.
*/
~Client();
/**
* @brief Opens a remote database and returns a
* Database instance to access it.
*
* @param address Address of the provider holding the database.
* @param provider_id Provider id.
* @param db_name Database name.
*
* @return a Database instance.
*/
Database open(const std::string& address,
uint16_t provider_id,
const std::string& db_name) const;
/**
* @brief Checks that the Client instance is valid.
*/
operator bool() const;
private:
......
......@@ -12,67 +12,199 @@ namespace tl = thallium;
class DatabaseImpl;
class CollectionImpl;
/**
* @brief The Collection object is a handle to a collection
* in a given remote database on a server. It offers function
* to store and search documents.
*/
class Collection {
friend class Database;
public:
/**
* @brief Copy constructor.
*/
Collection(const Collection&);
/**
* @brief Move constructor.
*/
Collection(Collection&&);
/**
* @brief Copy-assignment operator.
*/
Collection& operator=(const Collection&);
/**
* @brief Move-assignment operator.
*/
Collection& operator=(Collection&&);
/**
* @brief Destructor.
*/
~Collection();
/**
* @brief Checks if the Collection object is valid.
*/
operator bool() const;
/**
* @brief Stores a document into the collection.
*
* @param record A valid JSON-formated document.
*
* @return the record id of the stored document.
*/
uint64_t store(const std::string& record) const;
/**
* @brief Stores a document into the collection.
*
* @param record A JSON object.
*
* @return the record id of the stored document.
*/
uint64_t store(const Json::Value& record) const;
/**
* @brief Stores a document into the collection.
*
* @param record A valid JSON-formated document.
*
* @return the record id of the stored document.
*/
uint64_t store(const char* record) const {
return store(std::string(record));
}
/**
* @brief Fetches a document by its record id.
*
* @param[in] id Record id.
* @param[out] result Resulting string.
*/
void fetch(uint64_t id,
std::string* result) const;
/**
* @brief Fetches a document by its record id.
*
* @param[in] id Record id.
* @param[out] result Resulting JSON object.
*/
void fetch(uint64_t id,
Json::Value* result) const;
/**
* @brief Filters the collection and returns the
* records that match the condition. This condition should
* be expressed as a Jx9 function returning TRUE or FALSE.
* For example the following Jx9 function selects only
* the records where x < 4 :
*
* "function($record) { return $record.x < 4; }"
*
* @param filterCode A Jx9 filter code.
* @param result Resuling vector of records as strings.
*/
void filter(const std::string& filterCode,
std::vector<std::string>* result) const;
/**
* @brief Filters the collection and returns the
* records that match the condition. This condition should
* be expressed as a Jx9 function returning TRUE or FALSE.
* For example the following Jx9 function selects only
* the records where x < 4 :
*
* "function($record) { return $record.x < 4; }"
*
* @param filterCode A Jx9 filter code.
* @param result Resuling JSON object containing the array of results.
*/
void filter(const std::string& filterCode,
Json::Value* result) const;
/**
* @brief Updates the content of a document with a new content.
*
* @param id Record id of the document to update.
* @param record New document.
*/
void update(uint64_t id,
const Json::Value& record) const;
/**
* @brief Updates the content of a document with a new content.
*
* @param id Record id of the document to update.
* @param record New document.
*/
void update(uint64_t id,
const std::string& record) const;
/**
* @brief Updates the content of a document with a new content.
*
* @param id Record id of the document to update.
* @param record New document.
*/
void update(uint64_t id,
const char* record) const {
return update(id, std::string(record));
}
/**
* @brief Returns all the documents from the collection
* as a vector of strings.
*
* @param result All the documents from the collection.
*/
void all(std::vector<std::string>* result) const;
/**
* @brief Returns all the documents from the collection
* as a JSON object.
*
* @param result All the documents from the collection.
*/
void all(Json::Value* result)