05. Client API

5.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.

5.2 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

5.3 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

int StoryHandle::playback_story(uint64_t start, uint64_t end, std::vector<Event> &playback_events)

• Retrieve all Events in the Story within the timestamp range [start, end].
• The Events are stored in playback_events.
• Returns CL_SUCCESS on success, an error code otherwise.
• If start or end timestamps are out of range, an error code CL_ERR_OUT_OF_RANGE will be returned.

5.4 Event Class

The Event class represents the smallest data unit in ChronoLog. Each Event contains a timestamp, client ID, an index, and a log record.

Constructor

Event::Event(chrono_time event_time = 0, ClientId client_id = 0, chrono_index index = 0, std::string const &record = std::string())

• Creates an Event object.
• event_time: The timestamp of the event.
• client_id: The client ID that generated the event.
• index: The event index for ordering.
• record: The actual data record of the event.

Getters

uint64_t Event::time() const

• Returns the timestamp of the Event.

ClientId const &Event::client_id() const

• Returns the client ID of the Event.

uint32_t Event::index() const

• Returns the index of the Event.

std::string const &Event::log_record() const

• Returns the log record of the Event.

Operators

bool Event::operator==(const Event &other) const

• Checks if two Events are equal based on event_time, client_id, and eventIndex.

bool Event::operator!=(const Event &other) const

• Checks if two Events are different.

bool Event::operator<(const Event &other) const

• Compares Events based on event_time, then client_id, and finally eventIndex.

std::string Event::toString() const

• Returns a string representation of the Event in the format: {Event:<eventTime>:<clientId>:<eventIndex>:<logRecord>}