EBackend.Cache¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`sqlite_stmt_free` (stmt)
	`change_revision` ()
	`clear_offline_changes` (cancellable)
	`contains` (uid, deleted_flag)
	`copy_missing_to_column_values` (column_names, column_values, other_columns)
	`dup_key` (key)
	`dup_revision` ()
	`erase` ()
	`foreach` (deleted_flag, where_clause, func, user_data, cancellable)
	`foreach_update` (deleted_flag, where_clause, func, user_data, cancellable)
	`freeze_revision_change` ()
	`get` (uid, cancellable)
	`get_count` (deleted_flag, cancellable)
	`get_filename` ()
	`get_key_int` (key)
	`get_object_include_deleted` (uid, cancellable)
	`get_objects` (deleted_flag, cancellable)
	`get_offline_changes` (cancellable)
	`get_offline_state` (uid, cancellable)
	`get_sqlitedb` ()
	`get_uids` (deleted_flag, cancellable)
	`get_version` ()
	`initialize_sync` (filename, other_columns, cancellable)
	`is_revision_change_frozen` ()
	`lock` (lock_type)
	`put` (uid, revision, object, other_columns, offline_flag, cancellable)
	`remove` (uid, offline_flag, cancellable)
	`remove_all` (cancellable)
	`set_key` (key, value)
	`set_key_int` (key, value)
	`set_offline_state` (uid, state, cancellable)
	`set_revision` (revision)
	`set_version` (version)
	`sqlite_exec` (sql_stmt, cancellable)
	`sqlite_maybe_vacuum` (cancellable)
	`sqlite_select` (sql_stmt, func, user_data, cancellable)
	`thaw_revision_change` ()
	`unlock` (action)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_before_put` (uid, revision, object, other_columns, is_replace, cancellable)
	`do_before_remove` (uid, cancellable)
	`do_clear_offline_changes_locked` (cancellable)
	`do_erase` ()
	`do_put_locked` (uid, revision, object, other_columns, offline_state, is_replace, cancellable)
	`do_remove_locked` (uid, cancellable)
	`do_revision_changed` ()

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`before-put`
`before-remove`
`revision-changed`

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class EBackend.Cache(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: EBackend.CacheClass

Contains only private data that should be read and manipulated using the functions below.

New in version 3.26.

classmethod error_quark()¶

Return type:: int

classmethod sqlite_stmt_free(stmt)¶

Parameters:: stmt (str) – a statement to free

Frees a statement previously constructed with e_cache_sqlite_stmt_printf().

New in version 3.26.

change_revision()¶: Instructs the self to change its revision. In case the revision change is frozen with EBackend.Cache.freeze_revision_change() it notes to change the revision once the revision change is fully thaw.

New in version 3.26.

clear_offline_changes(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: Whether succeeded.
Return type:: bool

Marks all objects as being fully synchronized with the server and removes those which are marked as locally deleted.

New in version 3.26.

contains(uid, deleted_flag)¶

Parameters:

uid (str) – a unique identifier of an object
deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum

Returns:

Whether the object had been found.

Return type:

bool

Checkes whether the self contains an object with the given uid.

New in version 3.26.

copy_missing_to_column_values(column_names, column_values, other_columns)¶

Parameters:

column_names ([str]) – column names
column_values ([str]) – column values
other_columns (EBackend.CacheColumnValues) – an EBackend.CacheColumnValues to fill

Returns:

an EBackend.CacheColumnValues to fill

Return type:

other_columns: EBackend.CacheColumnValues

Adds every column value which is not Camel.part of the other_columns to it, except of EBackend.CACHE_COLUMN_UID, EBackend.CACHE_COLUMN_REVISION, EBackend.CACHE_COLUMN_OBJECT and EBackend.CACHE_COLUMN_STATE columns.

This can be used within the callback of EBackend.Cache.foreach_update().

New in version 3.32.

dup_key(key)¶

Parameters:: key (str) – a key name
Raises:: GLib.Error
Returns:: a value of the key. Free the returned string with GLib.free(), when no longer needed.
Return type:: str

New in version 3.26.

dup_revision()¶

Returns:: A revision of the whole self. This is meant to be used by the descendants. Free the returned pointer with GLib.free(), when no longer needed.
Return type:: str

New in version 3.26.

erase()¶: Erases the cache and all of its content from the disk. The only valid operation after this is to free the self.

New in version 3.26.

foreach(deleted_flag, where_clause, func, user_data, cancellable)¶

Parameters:

deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum
where_clause (str or None) – an optional SQLite WHERE clause Camel.part, or None
func (EBackend.CacheForeachFunc) – an EBackend.CacheForeachFunc function to call for each object
user_data (object or None) – user data for the func
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Calls func for each found object, which satisfies the criteria for both deleted_flag and where_clause.

Note the func should not call any SQLite commands, because it’s invoked within a SELECT statement execution.

New in version 3.26.

foreach_update(deleted_flag, where_clause, func, user_data, cancellable)¶

Parameters:

deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum
where_clause (str or None) – an optional SQLite WHERE clause Camel.part, or None
func (EBackend.CacheUpdateFunc) – an EBackend.CacheUpdateFunc function to call for each object
user_data (object or None) – user data for the func
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Calls func for each found object, which satisfies the criteria for both deleted_flag and where_clause, letting the caller update values where necessary. The return value of func is used to determine whether the call was successful, not whether there are any changes to be saved. If anything fails during the call then the all changes are reverted.

When there are requested any changes by the func, this function also calls EBackend.Cache.copy_missing_to_column_values() to ensure no descendant column data is lost.

New in version 3.26.

freeze_revision_change()¶: Freezes automatic revision change for the self. The function can be called multiple times, but each such call requires its pair function EBackend.Cache.thaw_revision_change() call. See also EBackend.Cache.change_revision().

New in version 3.26.

get(uid, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

An object with the given uid. Free it with GLib.free(), when no longer needed. Returns None on error, like when the object could not be found.

out_revision:: an out variable for a revision of the object, or None to ignore
out_other_columns:: an out variable for EBackend.CacheColumnValues other columns, as defined when creating the self, or None to ignore

Return type:

(str or None, out_revision: str or None, out_other_columns: EBackend.CacheColumnValues or None)

Returns an object with the given uid. This function does not consider locally deleted objects. The out_revision is set to the object revision, if not None. Free it with GLib.free() when no longer needed. Similarly the out_other_columns contains a column name to column value strings for additional columns which had been requested when calling EBackend.Cache.initialize_sync(), if not None. Free the returned EBackend.CacheColumnValues with EBackend.CacheColumnValues.free(), when no longer needed.

New in version 3.26.

get_count(deleted_flag, cancellable)¶

Parameters:

deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Count of objects stored in the self.

Return type:

int

New in version 3.26.

get_filename()¶

Returns:: a filename of the self, with which it had been initialized.
Return type:: str

New in version 3.26.

get_key_int(key)¶

Parameters:: key (str) – a key name
Raises:: GLib.Error
Returns:: The user key value or -1 on error.
Return type:: int

Reads the user key value as an integer.

New in version 3.26.

get_object_include_deleted(uid, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

An object with the given uid. Free it with GLib.free(), when no longer needed. Returns None on error, like when the object could not be found.

out_revision:: an out variable for a revision of the object, or None to ignore
out_other_columns:: an out variable for EBackend.CacheColumnValues other columns, as defined when creating the self, or None to ignore

Return type:

(str or None, out_revision: str or None, out_other_columns: EBackend.CacheColumnValues or None)

The same as EBackend.Cache.get(), only considers also locally deleted objects.

New in version 3.30.

get_objects(deleted_flag, cancellable)¶

Parameters:

deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded. It doesn’t necessarily mean that there was any object stored in the self.

out_objects:: a pointer to GLib.SList to store the found objects to
out_revisions:: a pointer to GLib.SList to store the found revisions to, or None

Return type:

(bool, out_objects: [str], out_revisions: [str])

Gets a list of objects stored in the self, optionally together with their revisions. The uids are not returned in any particular order, but the position between out_objects and out_revisions matches the same object.

Both out_objects and out_revisions contain newly allocated GLib.SList, which should be freed with g_slist_free_full (slist, GLib.free); when no longer needed.

New in version 3.26.

get_offline_changes(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: A newly allocated list of all offline changes. Free it with g_slist_free_full (slist, EBackend.CacheOfflineChange.free); when no longer needed.
Return type:: [EBackend.CacheOfflineChange]

Gathers the list of all offline changes being done so far. The returned GLib.SList contains EBackend.CacheOfflineChange structure. Use EBackend.Cache.clear_offline_changes() to clear all offline changes at once.

New in version 3.26.

get_offline_state(uid, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Current offline state EBackend.OfflineState for the given object. It returns EBackend.OfflineState.UNKNOWN when the object could not be found or other error happened.

Return type:

EBackend.OfflineState

New in version 3.26.

get_sqlitedb()¶

Returns:: An SQLite3 database pointer. It is owned by the self.
Return type:: object or None

New in version 3.26.

get_uids(deleted_flag, cancellable)¶

Parameters:

deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded. It doesn’t necessarily mean that there was any object stored in the self.

out_uids:: a pointer to GLib.SList to store the found uid to
out_revisions:: a pointer to GLib.SList to store the found revisions to, or None

Return type:

(bool, out_uids: [str], out_revisions: [str])

Gets a list of unique object identifiers stored in the self, optionally together with their revisions. The uids are not returned in any particular order, but the position between out_uids and out_revisions matches the same object.

Both out_uids and out_revisions contain newly allocated GLib.SList, which should be freed with g_slist_free_full (slist, GLib.free); when no longer needed.

New in version 3.26.

get_version()¶

Returns:: A cache data version. This is meant to be used by the descendants.
Return type:: int

New in version 3.26.

initialize_sync(filename, other_columns, cancellable)¶

Parameters:

filename (str) – a filename of an SQLite database to use
other_columns ([EBackend.CacheColumnInfo] or None) – an optional GLib.SList with additional columns to add to the objects table
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Initializes the self and opens the filename database. This should be called by the descendant.

The other_columns are added to the objects table (EBackend.CACHE_TABLE_OBJECTS). Values for these columns are returned by EBackend.Cache.get() and can be stored with EBackend.Cache.put().

New in version 3.26.

is_revision_change_frozen()¶

Returns:: Whether automatic revision change for the self is currently frozen.
Return type:: bool

New in version 3.26.

lock(lock_type)¶

Parameters:: lock_type (EBackend.CacheLockType) – an EBackend.CacheLockType

Locks the self thus other threads cannot use it. This can be called recursively within one thread. Each call should have its pair EBackend.Cache.unlock().

New in version 3.26.

put(uid, revision, object, other_columns, offline_flag, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
revision (str or None) – a revision of the object
object (str) – the object itself
other_columns (EBackend.CacheColumnValues or None) – an EBackend.CacheColumnValues with other columns to set; can be None
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether putting this object in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Stores an object into the cache. Depending on offline_flag, this update the object’s offline state accordingly. When the offline_flag is set to EBackend.CacheOfflineFlag.IS_ONLINE, then it’s set to EBackend.OfflineState.SYNCED, like to be fully synchronized with the server, regardless of its previous offline state. Overwriting locally deleted object behaves like an addition of a completely new object.

New in version 3.26.

remove(uid, offline_flag, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether removing the object in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Removes the object with the given uid from the self. Based on the offline_flag, it can remove also any information about locally made offline changes. Removing the object with EBackend.CacheOfflineFlag.IS_OFFLINE will still remember it for later use with EBackend.Cache.get_offline_changes().

New in version 3.26.

remove_all(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: Whether succeeded.
Return type:: bool

Removes all objects from the self in one call.

New in version 3.26.

set_key(key, value)¶

Parameters:

key (str) – a key name
value (str or None) – a value to set, or None to delete the key

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets a value of the user key, or deletes it, if the value is None.

New in version 3.26.

set_key_int(key, value)¶

Parameters:

key (str) – a key name
value (int) – an integer value to set

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets an integer value for the user key.

New in version 3.26.

set_offline_state(uid, state, cancellable)¶

Parameters:

uid (str) – a unique identifier of an object
state (EBackend.OfflineState) – an EBackend.OfflineState to set
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets an offline state for the object identified by uid.

New in version 3.26.

set_revision(revision)¶

Parameters:: revision (str or None) – a revision to set; use None to unset it

Sets the revision of the whole self. This is not meant to be used by the descendants, because the revision is updated automatically when needed. The descendants can listen to “revision-changed” signal.

New in version 3.26.

set_version(version)¶

Parameters:: version (int) – a cache data version to set

Sets a cache data version. This is meant to be used by the descendants. The version should be greater than zero.

New in version 3.26.

sqlite_exec(sql_stmt, cancellable)¶

Parameters:

sql_stmt (str) – an SQLite statement to execute
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Executes an SQLite statement. Use EBackend.Cache.sqlite_select() for SELECT statements.

New in version 3.26.

sqlite_maybe_vacuum(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: Whether succeeded. It doesn’t mean that the vacuum had been run, only that no error happened during the call.
Return type:: bool

Runs vacuum (compacts the database file), if needed.

New in version 3.26.

sqlite_select(sql_stmt, func, user_data, cancellable)¶

Parameters:

sql_stmt (str) – an SQLite SELECT statement to execute
func (EBackend.CacheSelectFunc) – an EBackend.CacheSelectFunc function to call for each row
user_data (object or None) – user data for func
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Executes a SELECT statement sql_stmt and calls func for each row of the result. Use EBackend.Cache.sqlite_exec() for statements which do not return row sets.

New in version 3.26.

thaw_revision_change()¶: Thaws automatic revision change for the self. It’s the pair function of EBackend.Cache.freeze_revision_change().

New in version 3.26.

unlock(action)¶

Parameters:: action (EBackend.CacheUnlockAction) – an EBackend.CacheUnlockAction

Unlocks the cache which was previouly locked with EBackend.Cache.lock(). The cache locked with EBackend.CacheLockType.WRITE should use either action EBackend.CacheUnlockAction.COMMIT or EBackend.CacheUnlockAction.ROLLBACK, while the EBackend.CacheLockType.READ should use EBackend.CacheUnlockAction.NONE action.

New in version 3.26.

do_before_put(uid, revision, object, other_columns, is_replace, cancellable) virtual¶

Parameters:

uid (str) –
revision (str) –
object (str) –
other_columns (EBackend.CacheColumnValues) –
is_replace (bool) –
cancellable (Gio.Cancellable or None) –

Return type:

bool

do_before_remove(uid, cancellable) virtual¶

Parameters:

uid (str) –
cancellable (Gio.Cancellable or None) –

Return type:

bool

do_clear_offline_changes_locked(cancellable) virtual¶

Parameters:: cancellable (Gio.Cancellable or None) –
Return type:: bool

do_erase() virtual¶: Erases the cache and all of its content from the disk. The only valid operation after this is to free the cache.

New in version 3.26.

do_put_locked(uid, revision, object, other_columns, offline_state, is_replace, cancellable) virtual¶