CacheSyncSource Class Reference
[Sync Client]

This class class implements the SyncSource interface, adding a method to detect the changes in the local store since the last sync based on cache files to make easier the implementation of new sync sources. More...

#include <CacheSyncSource.h>

Inheritance diagram for CacheSyncSource:

Inheritance graph
[legend]
Collaboration diagram for CacheSyncSource:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 CacheSyncSource (const WCHAR *name, AbstractSyncSourceConfig *sc, KeyValueStore *cache=NULL)
 Constructor: create a CacheSyncSource with the specified name.
void setItemStatus (const WCHAR *key, int status, const char *command)
 called by the sync engine with the status returned by the server for a certain item that the client sent to the server.
SyncItem * getFirstItemKey ()
 Return the key of the first SyncItem of all.
SyncItem * getNextItemKey ()
 Return the key of the next SyncItem of all.
SyncItem * getFirstItem ()
 Return the first SyncItem of all.
SyncItem * getNextItem ()
 Return the next SyncItem of all.
SyncItem * getFirstNewItem ()
 Return the first SyncItem of new one.
SyncItem * getNextNewItem ()
 Return the next SyncItem of new one.
SyncItem * getFirstUpdatedItem ()
 Return the first SyncItem of updated one.
SyncItem * getNextUpdatedItem ()
 Return the next SyncItem of updated one.
SyncItem * getFirstDeletedItem ()
 Return the first SyncItem of updated one.
SyncItem * getNextDeletedItem ()
 Return the next SyncItem of updated one.
void serverStatusPackageEnded ()
 Indicates that all the server status of the current package of the client items has been processed by the engine.
void clientStatusPackageEnded ()
 Indicates that all the client status of the current package of the server items that has been processed by the client and are going to be sent to the server.
virtual int beginSync ()
 Check that the cache store is available before starting the sync.
virtual int endSync ()
 In the first implementatation, in which serverStatusPackageEnded and clientStatusPackageEnded are not yet impelemented, the end sync will udpate the whole cache status persistently.
virtual StringBuffer getItemSignature (StringBuffer &key)
 Get the signature of an item given the key.
virtual void * getItemContent (StringBuffer &key, size_t *size)=0
 Get the content of an item given the key.
virtual EnumerationgetAllItemList ()=0
 Returns an Enumeration containing the StringBuffer keys of all items.
virtual int insertItem (SyncItem &item)=0
 Called by the sync engine to add an item that the server has sent.
virtual int modifyItem (SyncItem &item)=0
 Called by the sync engine to update an item that the source already should have.
virtual int removeItem (SyncItem &item)=0
 Called by the sync engine to update an item that the source already should have.

Protected Member Functions

int saveCache ()
 Save the current cache into the persistent store.
int addItem (SyncItem &item)
 Implementation of the SyncSource method addItem, it's called by the SyncManager to add an item that the server has sent.
int updateItem (SyncItem &item)
 Called by the sync engine to update an item that the source already should have.
int deleteItem (SyncItem &item)
 Called by the sync engine to update an item that the source already should have.
int updateInCache (KeyValuePair &k, const char *action=REPLACE)
 Used to update the cache adding, replacing or deleting.
int insertInCache (KeyValuePair &k)
 To insert in the cache.
int removeFromCache (KeyValuePair &k)
 To remove from cache.
int clearCache ()
 Clear the cache using the removeAllProperties method.

Detailed Description

This class class implements the SyncSource interface, adding a method to detect the changes in the local store since the last sync based on cache files to make easier the implementation of new sync sources.

It requires an instance of a class implementing the KeyValueStore interface to store the sync cache, made by pairs of LUID (the local id of the item) and a fingerprint (default method is CRC of the content, but can be a timestamp or any other way to detect a change on the item). By default, CacheSyncSource is able to obtain a PropertyFile (which implements KeyValueStore as a file), but if a more efficient way to store it is available for the platform, the developer can create anoher store and pass it in the CacheSyncSource constructor (see also the SQLKeyValueStore abstract class).

The mandatory methods to implement are: getAllItemList: returns a list of StringBuffer with all the keys of the items in the data store insertItem: adds a new item into the data store modifyItem: modifies an item in the data store removeItem: removes an item from the data store removeAllItems: removes all the items from the data store getItemContent: get the content of an item given the key

The optional methods, that can be overloaded to change the behavior of the user sync source, are: getItemSignature: get a fingerprint of the item, which is any string which allows to detech changes in the item


Constructor & Destructor Documentation

CacheSyncSource::CacheSyncSource ( const WCHAR *  name,
AbstractSyncSourceConfig sc,
KeyValueStore cache = NULL 
)

Constructor: create a CacheSyncSource with the specified name.

Parameters:
name the name of the SyncSource
sc configuration for the sync source: the instance must remain valid throughout the lifetime of the sync source because it keeps a reference to it and uses it as its own. A NULL pointer is allowed for unit testing outside of the sync framework; the sync source then references a global config instance to avoid crashes, but modifying that config will not make much sense. The pointer may also be set directly after creating the SyncSource, which is useful when a derived class creates the config in its own constructor.
cache the store for the cache. Released by the CacheSyncSource


Member Function Documentation

int CacheSyncSource::saveCache (  )  [protected]

Save the current cache into the persistent store.

Which store depends on the KeyValueStore passed in the constructor (a file by default).

int CacheSyncSource::addItem ( SyncItem &  item  )  [protected, virtual]

Implementation of the SyncSource method addItem, it's called by the SyncManager to add an item that the server has sent.

It calls the insertItem() method that must be implemented by the user. Also used to update the item

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implements SyncSource.

int CacheSyncSource::updateItem ( SyncItem &  item  )  [protected, virtual]

Called by the sync engine to update an item that the source already should have.

The item's key is the local key of that item.

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implements SyncSource.

int CacheSyncSource::deleteItem ( SyncItem &  item  )  [protected, virtual]

Called by the sync engine to update an item that the source already should have.

The item's key is the local key of that item, no data is provided.

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implements SyncSource.

int CacheSyncSource::updateInCache ( KeyValuePair &  k,
const char *  action = REPLACE 
) [protected]

Used to update the cache adding, replacing or deleting.

The KeyValuePair contains the pair UID/signature. It is provided by the proper method who calls this. It udpates the cache that is in memory. The action by default is Replace.

void CacheSyncSource::setItemStatus ( const WCHAR *  key,
int  status,
const char *  command 
) [virtual]

called by the sync engine with the status returned by the server for a certain item that the client sent to the server.

It contains also the proper command associated to the item. It is used to update the current array of cache.

Parameters:
key - the local key of the item
status - the SyncML status returned by the server
command - the SyncML command associated to the item

Reimplemented from SyncSource.

SyncItem* CacheSyncSource::getFirstItemKey (  )  [inline]

Return the key of the first SyncItem of all.

It is used in case of refresh sync and retrieve all the keys of the data source.

Deprecated:
no more used. use removeAllItems instead.

SyncItem* CacheSyncSource::getNextItemKey (  )  [inline]

Return the key of the next SyncItem of all.

It is used in case of refresh sync and retrieve all the keys of the data source.

Deprecated:
no more used. use removeAllItems instead.

SyncItem* CacheSyncSource::getFirstItem (  )  [virtual]

Return the first SyncItem of all.

It is used in case of slow sync and retrieve the entire data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getNextItem (  )  [virtual]

Return the next SyncItem of all.

It is used in case of slow sync and retrieve the entire data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getFirstNewItem (  )  [virtual]

Return the first SyncItem of new one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getNextNewItem (  )  [virtual]

Return the next SyncItem of new one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getFirstUpdatedItem (  )  [virtual]

Return the first SyncItem of updated one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getNextUpdatedItem (  )  [virtual]

Return the next SyncItem of updated one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getFirstDeletedItem (  )  [virtual]

Return the first SyncItem of updated one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

SyncItem* CacheSyncSource::getNextDeletedItem (  )  [virtual]

Return the next SyncItem of updated one.

It is used in case of fast sync and retrieve the new data source content.

Implements SyncSource.

void CacheSyncSource::serverStatusPackageEnded (  )  [inline, virtual]

Indicates that all the server status of the current package of the client items has been processed by the engine.

This signal can be useful to update the modification arrays NOT USED at the moment

Reimplemented from SyncSource.

void CacheSyncSource::clientStatusPackageEnded (  )  [inline, virtual]

Indicates that all the client status of the current package of the server items that has been processed by the client and are going to be sent to the server.

This signal can be useful to update the modification arrays NOT USED at the moment

Reimplemented from SyncSource.

virtual StringBuffer CacheSyncSource::getItemSignature ( StringBuffer &  key  )  [virtual]

Get the signature of an item given the key.

The signature could be a crc computation or a timestamp or whatever can identify uniquely the content of an item. The default implementation uses a crc computation of the value. Overriding implementation could provide something different like the timestamp or other...

Parameters:
key the key of the item.
Returns:
the signature of the selected item

virtual void* CacheSyncSource::getItemContent ( StringBuffer &  key,
size_t *  size 
) [pure virtual]

Get the content of an item given the key.

It is used to populate the SyncItem before the engine uses it in the usual flow of the sync.

Parameters:
key the local key of the item
size OUT: the size of the content

Implemented in FileSyncSource.

virtual Enumeration* CacheSyncSource::getAllItemList (  )  [pure virtual]

Returns an Enumeration containing the StringBuffer keys of all items.

It is used both for the full sync, where all items are sent to the server, and for the fast sync to calculate the modification since the last successful sync.

Returns:
a newly allocated Enumeration that is free'd by the CacheSyncSource CacheSyncSource. Return NULL in case of error, an empty Enumeration if there are no items.

Implemented in FileSyncSource.

virtual int CacheSyncSource::insertItem ( SyncItem &  item  )  [pure virtual]

Called by the sync engine to add an item that the server has sent.

The sync source is expected to add it to its database, then set the key to the local key assigned to the new item. Alternatively the sync source can match the new item against one of the existing items and return that key.

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implemented in FileSyncSource.

virtual int CacheSyncSource::modifyItem ( SyncItem &  item  )  [pure virtual]

Called by the sync engine to update an item that the source already should have.

The item's key is the local key of that item.

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implemented in FileSyncSource.

virtual int CacheSyncSource::removeItem ( SyncItem &  item  )  [pure virtual]

Called by the sync engine to update an item that the source already should have.

The item's key is the local key of that item, no data is provided.

Parameters:
item the item as sent by the server
Returns:
SyncML status code

Implemented in FileSyncSource.


The documentation for this class was generated from the following file:
Generated on Wed Jan 14 17:15:44 2009 for Funambol C++ Client Library by  doxygen 1.5.2