com.funambol.syncml.spds
Interface SyncSource

All Known Implementing Classes:
BaseSyncSource

public interface SyncSource

A SyncSource is responsible for storing and retrieving SyncItem objects from/to an external data source. Note that the SyncSource interface makes no assumptions about the underlying data source or about how data are formatted: each concrete implementation will use its specific storage and format.

A SyncSource is not used directly by the host application, instead its methods are called by the synchronization engine during modifications analysis.

The SyncSource methods are designed to perform an efficient synchronization process, letting the source selecting the changed items instead of doing more complex field by field comparison. It is responsibility of the source developer to make sure that the getNextNew/Updated/DeletedItem() methods return the correct values.

The configuration information required to set up a SyncSource is stored in the class SourceConfig , used by the BaseSyncSource class.


Field Summary
static java.lang.String ENCODING_B64
           
static java.lang.String ENCODING_NONE
           
 
Method Summary
 int addItem(SyncItem item)
          Add a new SyncItem to this source backend.
 void beginSync(int syncMode)
          Called after SyncManager preparation and initialization just before start the synchronization of the SyncSource.
 void dataReceived(java.lang.String date, int size)
          Called by the engine when new data has been received by the server, before processing it.
 int deleteItem(java.lang.String key)
          Delete a SyncItem stored in the source backend.
 void endSync()
          Called just before committing the synchronization process by the SyncManager.
 int getClientItemsNumber()
          Return the number of changes that the client will send during the session.
 java.lang.String getEncoding()
          Returns the encoding of the source.
 SyncFilter getFilter()
          Return the current filter for this SyncSource
 long getLastAnchor()
          Return the Last Anchor for this source
 java.lang.String getName()
          Returns the name of the source
 long getNextAnchor()
          Return the Next Anchor for this source
 SyncItem getNextDeletedItem()
          Returns a SyncItem containing the key of the first/next deleted item of the store (locally removed after the last sync, but not yet deleted on server)
 SyncItem getNextItem()
          Returns the next item of the store (for slow sync).
 SyncItem getNextNewItem()
          Returns the first/next new item of the store.
 SyncItem getNextUpdatedItem()
          Returns the first/next updated item of the store (changed from the last sync)
 int getServerItemsNumber()
          Retiurn the number of changes that the server will send during the session.
 java.lang.String getSourceUri()
          Returns the source URI
 int getSyncMode()
          Return the preferred sync mode of the source.
 java.lang.String getType()
          Returns the type of the source.
 void setFilter(SyncFilter filter)
          Set a new filter for this SyncSource
 void setItemStatus(java.lang.String key, int status)
          Tell the SyncSource the status returned by the server for an Item previously sent.
 void setLastAnchor(long time)
          Set the value of the Last Anchor for this source
 void setNextAnchor(long time)
          Set the value of the Next Anchor for this source
 void setServerItemsNumber(int number)
          Set the number of changes that the server will send during the session.
 int updateItem(SyncItem item)
          Update a given SyncItem stored in the source backend.
 

Field Detail

ENCODING_NONE

static final java.lang.String ENCODING_NONE
See Also:
Constant Field Values

ENCODING_B64

static final java.lang.String ENCODING_B64
See Also:
Constant Field Values
Method Detail

getName

java.lang.String getName()
Returns the name of the source

Returns:
the name of the source

getSourceUri

java.lang.String getSourceUri()
Returns the source URI

Returns:
the absolute URI of the source

getType

java.lang.String getType()
Returns the type of the source. The types are defined as mime-types, for instance * text/x-vcard).

Returns:
the type of the source

getEncoding

java.lang.String getEncoding()
Returns the encoding of the source. The encoding can be 'b64' or 'none' only. The standard defines also 'des' and '3des' but they are not implemented in this version of the APIs.

Returns:
the encoding of the source

getSyncMode

int getSyncMode()
Return the preferred sync mode of the source. The preferred sync mode is the one that the SyncManager sends to the server in the initialization phase. The server can respond with a different alert code, to force, for instance, a slow.

Returns:
the preferred sync mode for this source

getFilter

SyncFilter getFilter()
Return the current filter for this SyncSource


setFilter

void setFilter(SyncFilter filter)
Set a new filter for this SyncSource


addItem

int addItem(SyncItem item)
            throws SyncException
Add a new SyncItem to this source backend. The item key after a successful add must contain the local UID, that is used by the engine to send the mappings to the server. The source must then change the item key accordingly before return.

Parameters:
item - the SyncItem to add, with the GUID sent by the server. The source is resposible to set it to the LUID before returning a successful status code.
Returns:
the status code of the operation. It will be returned to the server in the response for this item.
Throws:
SyncException - if an unrecoverable error occur, to stop the sync

updateItem

int updateItem(SyncItem item)
               throws SyncException
Update a given SyncItem stored in the source backend.

Parameters:
item - the SyncItem to update. The key of the item is already the LUID.
Returns:
the status code of the operation. It will be returned to the server in the response for this item.
Throws:
SyncException - if an unrecoverable error occur, to stop the sync

deleteItem

int deleteItem(java.lang.String key)
               throws SyncException
Delete a SyncItem stored in the source backend.

Parameters:
key - The key of the item to delete.
Returns:
the status code of the operation. It will be returned to the server in the response for this item.
Throws:
SyncException - if an unrecoverable error occur, to stop the sync

getNextItem

SyncItem getNextItem()
                     throws SyncException
Returns the next item of the store (for slow sync).

The implementation of this method must iterate on all the items of the source, starting from the first after a beginSync() call and returning null when no more items are available.

Throws:
SyncException

getNextNewItem

SyncItem getNextNewItem()
                        throws SyncException
Returns the first/next new item of the store.

The implementation of this method must iterate on the items of the source not yet sent to the server, starting from the first one after a beginSync() call and returning null when no more items are available.

Returns:
the first new item, in a SyncItem object, or null if no new items are present.
Throws:
SyncException

getNextUpdatedItem

SyncItem getNextUpdatedItem()
                            throws SyncException
Returns the first/next updated item of the store (changed from the last sync)

Returns:
the first updated item, in a SyncItem object, or null if no updated items are present.
Throws:
SyncException

getNextDeletedItem

SyncItem getNextDeletedItem()
                            throws SyncException
Returns a SyncItem containing the key of the first/next deleted item of the store (locally removed after the last sync, but not yet deleted on server)

Returns:
the first deleted item, in a SyncItem object, or null if no deleted items are present.
Throws:
SyncException

setItemStatus

void setItemStatus(java.lang.String key,
                   int status)
                   throws SyncException
Tell the SyncSource the status returned by the server for an Item previously sent.

Parameters:
key - the key of the item
status - the status code received for that item
Throws:
SyncException - if the SyncSource wants to stop the sync

dataReceived

void dataReceived(java.lang.String date,
                  int size)
Called by the engine when new data has been received by the server, before processing it. The date is in the format received in the HTTP headers, if available. This enable clients running on devices without timezone support to detect the time and location of the server, and thus the timezone of the client. The size is the total size of the received message, in bytes.


getClientItemsNumber

int getClientItemsNumber()
Return the number of changes that the client will send during the session. This method, after the beginSync() call, should return the number of items to be sent to the server. This is a read-only value for the Syncmanager.

Returns:
number of items to sent, or -1 if unknown

getServerItemsNumber

int getServerItemsNumber()
Retiurn the number of changes that the server will send during the session. The value is set by the engine after the Sync tag is sent by the server, with the value of the NumberOfchanges tag or -1 if not present.

Returns:
number of changes from the server, or -1 if not announced.

setServerItemsNumber

void setServerItemsNumber(int number)
Set the number of changes that the server will send during the session. This method is called by the engine to notify the Source of the number of changes announced by the server. If the server does not announce the number of changes, the engine will call this method with parameter -1.

Parameters:
number - of changes from the server, or -1 if not announced.

getLastAnchor

long getLastAnchor()
Return the Last Anchor for this source


setLastAnchor

void setLastAnchor(long time)
Set the value of the Last Anchor for this source


getNextAnchor

long getNextAnchor()
Return the Next Anchor for this source


setNextAnchor

void setNextAnchor(long time)
Set the value of the Next Anchor for this source


beginSync

void beginSync(int syncMode)
               throws SyncException
Called after SyncManager preparation and initialization just before start the synchronization of the SyncSource. The implementation must reset the all/new/upd/del item lists when this method is called by the sync engine.

Parameters:
syncMode - the synchronization type: one of the values in sync4j.framework.core.AlertCode
Throws:
SyncException - in case of error. This will stop the sync process

endSync

void endSync()
             throws SyncException
Called just before committing the synchronization process by the SyncManager. The SyncSource can stop the commit phase raising an exception here.

Throws:
SyncException - in case of error, to stop the commit.


Copyright © 2006 Funambol.