com.funambol.syncml.spds
Interface SyncSource

All Known Implementing Classes:
BaseSyncSource, ConfigSyncSource, FileSyncSource, TrackableSyncSource, TwoPhasesFileSyncSource

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
           
static int STATUS_CONNECTION_ERROR
          A problem with the connection to the remote server occurred
static int STATUS_RECV_ERROR
          At least one message has an error during receive
static int STATUS_SEND_ERROR
          At least one message has an error during send
static int STATUS_SERVER_ERROR
          An error occurred with the remote server.
static int STATUS_SUCCESS
          No error for this session
 
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.
 SyncItem createSyncItem(java.lang.String key, java.lang.String type, char state, java.lang.String parent, long size)
          Creates a SyncItem that the sync engine can use to store an incoming item.
 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 getClientAddNumber()
          Return the number of new items (add) that the client will send during the session.
 int getClientDeleteNumber()
          Return the number of deleted items that the client will send during the session.
 int getClientItemsNumber()
          Return the number of changes that the client will send during the session.
 int getClientReplaceNumber()
          Return the number of replaced items that the client will send during the session.
 SourceConfig getConfig()
          Returns the config of the source.
 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
 SyncListener getListener()
          Returns the current listener (or null if not set)
 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 getStatus()
          Returns the status of the sync source.
 int getSyncMode()
          Return the preferred sync mode of the source.
 java.lang.String getType()
          Returns the type of the source.
 void setConfig(SourceConfig config)
          Sets the config 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 setListener(SyncListener listener)
          Set a sync listener.
 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

STATUS_SUCCESS

static final int STATUS_SUCCESS
No error for this session

See Also:
Constant Field Values

STATUS_SEND_ERROR

static final int STATUS_SEND_ERROR
At least one message has an error during send

See Also:
Constant Field Values

STATUS_RECV_ERROR

static final int STATUS_RECV_ERROR
At least one message has an error during receive

See Also:
Constant Field Values

STATUS_SERVER_ERROR

static final int STATUS_SERVER_ERROR
An error occurred with the remote server. For instance an invalid messagev or item, but not blocking for the sync.

See Also:
Constant Field Values

STATUS_CONNECTION_ERROR

static final int STATUS_CONNECTION_ERROR
A problem with the connection to the remote server occurred

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 method returns the set of items in the source. This set can be frozen just after the beginSync is invoked or it can change as new changes are applied. The method only guarantees that it returns all the items that were in the store when beginSync got invoked. When an item is returned by this method it may be no longer in the source if it got deleted. In other words there is no guarantee an item returned is still in the source. This method acts as an iterator and is guaranteed to be initialized after beginSync.

Returns:
the current item or null if no more items
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

getClientAddNumber

int getClientAddNumber()
Return the number of new items (add) that the client will send during the session. This method, after the beginSync() call, should return the number of new 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

getClientReplaceNumber

int getClientReplaceNumber()
Return the number of replaced items that the client will send during the session. This method, after the beginSync() call, should return the number of replaced 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

getClientDeleteNumber

int getClientDeleteNumber()
Return the number of deleted items that the client will send during the session. This method, after the beginSync() call, should return the number of delted 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.

setListener

void setListener(SyncListener listener)
Set a sync listener.

Parameters:
listener - the listener or null to remove it

getListener

SyncListener getListener()
Returns the current listener (or null if not set)


getStatus

int getStatus()
Returns the status of the sync source. The status is encoded as a bit mask of the STATUS_* values


getConfig

SourceConfig getConfig()
Returns the config of the source. The client can use this method to obtain the config object and change some parameter. A setConfig() must be called to actually change the source configuration.

Returns:
the config of the source

setConfig

void setConfig(SourceConfig config)
Sets the config of the source. The client can use this method to change the config of the source configuration. This operation should not be done while the sync is in progress.


createSyncItem

SyncItem createSyncItem(java.lang.String key,
                        java.lang.String type,
                        char state,
                        java.lang.String parent,
                        long size)
                        throws SyncException
Creates a SyncItem that the sync engine can use to store an incoming item.

Parameters:
key - is the item key
type - is the item type
state - this item's state
parent - is the item's parent
size - is the item size
Throws:
SyncException


Copyright © 2001-2009 Funambol.