4. Client API

4.1 Definitions

• Event: Event is the smallest data unit in ChronoLog. All data pieces are stored as Events.
• Story: Story is the structure organizing Events together with the ordering guarantee across them.
• Chronicle: Chronicle is the structure collecting Stories together for easier data management.

4.2 ConfigurationManager class

The class used to manage all the configurations in ChronoLog. A JSON file is required to set up all the configurations such as ChronoVisor’s IP and port.

ConfigurationManager::ConfigurationManager(const std::string &conf_file_path)

• The constructor reads configurations from the given configuration file and configure the ChronoLog Client Library accordingly
• Exit if fatal error is found

4.3 Client class

The class used to manage the metadata interaction with ChronoLog through the ChronoLog Client Library

Client::Client(ChronoLog::ConfigurationManager const &confManager)

• The constructor requires an object of ConfigurationManager to initialize the client object

int Client::Connect()

• Connect to a ChronoLog deployment
• Return CL_SUCCESS on success, error code otherwise

int Client::Disconnect()

• Disconnect from a ChronoLog deployment
• Return CL_SUCCESS on success, error code otherwise

int Client::CreateChronicle(std::string const &chronicle_name, std::map <std::string, std::string> const &attrs, int &flags)

• Create a Chronicle named chronicle_name
• Return CL_SUCCESS on success, error code otherwise
• attrs is used to fine tune the property of the Chronicle such as the tiering policy
• flags is used to enable or disable configuration flags during the creation
• If there is no existing Chronicle with the same name, Chronicle chronicle_name will be created. Otherwise, an error code CL_ERR_CHRONICLE_EXISTS will be returned

int Client::DestroyChronicle(std::string const &chronicle_name)

• Destroy the Chronicle named chronicle_name
• Return CL_SUCCESS on success, error code otherwise
• If the Chronicle has no Story being acquired, it will be destroyed. Otherwise, an error code CL_ERR_ACQUIRED will be returned

std::pair <int, StoryHandle*> Client::AcquireStory(std::string const &chronicle_name, std::string const &story_name, const std::map <std::string, std::string> &attrs, int &flags)

• Acquire the Story with the name story_name under the Chronicle named chronicle_name to get ready for data access
• A pair<int, StoryHandle *> will be returned on success. The first variable is the return value which should be CL_SUCCESS on success. The second one is a pointer to a StoryHandle object which manages access to the acquired Story.
• If the Chronicle or the Story does not exist, an error code CL_ERR_NOT_EXIST will be returned

int Client::ReleaseStory(std::string const &chronicle_name, std::string const &story_name)

• Release the Story with the name story_name under the Chronicle named chronicle_name
• Return CL_SUCCESS on success, error code otherwise

int Client::DestroyStory(std::string const &chronicle_name, std::string const &story_name)

• Destroy the Story with the name of story_name under the Chronicle named chronicle_name
• Return CL_SUCCESS on success, error code otherwise
• If the Story is being acquired, an error code CL_ERR_ACQUIRED will be returned

4.4 StoryHandle class

The class used to manage all Story-specific data access ChronoLog APIs such as recording.

int StoryHandle::log_event(std::string const &event_record)

• Record Events to ChronoLog
• Return CL_SUCCESS on success, error code otherwise