com.funambol.syncclient.spds.engine
Interface SyncSource

All Known Implementing Classes:
AbstractRecovery, AssetSyncSource, DummySyncSource, FileSystemSyncSource, SIFFileSystemSyncSource, SIFSyncSource

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

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 getNew/Updated/DeletedSyncItems() methods return the correct values.

The configuration information required to set up a SyncSource is stored in the device management store under the context ./syncml/sources with the structure below:

    .../{source name}
        + class
        + uri
        + type
        + ... other properties ...
 
Where other properties are implementation specific and are set by the engine when the source is instantiated.

Version:
$Id: SyncSource.java,v 1.3 2007-12-22 18:09:18 nichele Exp $

Method Summary
 void beginSync(int syncMode)
          Called after SyncManager preparation and initialization just before start the synchronization of the SyncSource.
 void commitSync()
          Called just before committing the synchronization process by the SyncManager.
 SyncItem[] getAllSyncItems(java.security.Principal principal)
          Returns all items in the data store belonging to the given principal.
 SyncItem[] getDeletedSyncItems(java.security.Principal principal, java.util.Date since)
          Returns all deleted items belonging to the given principal and deleted after the given point in time.
 java.lang.String getName()
          Returns the name of the source
 SyncItem[] getNewSyncItems(java.security.Principal principal, java.util.Date since)
          Returns all new items belonging to the given principal and created after the given point in time.
 java.lang.String getSourceURI()
          Returns the source URI
 java.lang.String getType()
          Returns the type of the source.
 SyncItem[] getUpdatedSyncItems(java.security.Principal principal, java.util.Date since)
          Returns all updated items belonging to the given principal and modified after the given point in time.
 void removeSyncItem(java.security.Principal principal, SyncItem syncItem)
          Removes a SyncItem given its key.
 SyncItem setSyncItem(java.security.Principal principal, SyncItem syncItem)
          Replaces an existing SyncItem or adds a new SyncItem if it does not exist.
 

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

getAllSyncItems

SyncItem[] getAllSyncItems(java.security.Principal principal)
                           throws SyncException
Returns all items in the data store belonging to the given principal.

Parameters:
principal - not used, always null
Returns:
an array of all SyncItems stored in this source. If there are no items an empty array is returned.
Throws:
SyncException - in case of error (for instance if the underlying data store runs into problems)

getDeletedSyncItems

SyncItem[] getDeletedSyncItems(java.security.Principal principal,
                               java.util.Date since)
                               throws SyncException
Returns all deleted items belonging to the given principal and deleted after the given point in time.

Parameters:
principal - the principal for which the data has to be considered Null means all principals
since - consider the changes since this point in time. Null means all items regardless when they were changed.
Returns:
an array of keys containing the SyncItem's key of the deleted items after the last synchronizazion. If there are no deleted items an empty array is returned.
Throws:
SyncException - in case of error (for instance if the underlying data store runs into problems)

getNewSyncItems

SyncItem[] getNewSyncItems(java.security.Principal principal,
                           java.util.Date since)
                           throws SyncException
Returns all new items belonging to the given principal and created after the given point in time.

Parameters:
principal - not used, always null
since - consider the changes since this point in . Null means all items regardless when they were changed.
Returns:
an array of items containing representing the newly created items. If there are no new items an empty array MUST BE returned.
Throws:
SyncException - in case of error (for instance if the underlying data store runs into problems)

getUpdatedSyncItems

SyncItem[] getUpdatedSyncItems(java.security.Principal principal,
                               java.util.Date since)
                               throws SyncException
Returns all updated items belonging to the given principal and modified after the given point in time.

Parameters:
principal - not used, always null
since - consider the changes since this point in time. Null means all items regardless when they were changed.
Returns:
an array of keys containing the SyncItem's key of the updated items after the last synchronizazion. It MUST NOT return null for no keys, but instad an empty array.
Throws:
SyncException

removeSyncItem

void removeSyncItem(java.security.Principal principal,
                    SyncItem syncItem)
                    throws SyncException
Removes a SyncItem given its key.

Parameters:
principal - not used, always null
syncItem - the item to remove
Throws:
SyncException - in case of error (for instance if the underlying data store runs into problems)

setSyncItem

SyncItem setSyncItem(java.security.Principal principal,
                     SyncItem syncItem)
                     throws SyncException
Replaces an existing SyncItem or adds a new SyncItem if it does not exist. The item is also returned giving the opportunity to the source to modify its content and return the updated item (i.e. updating the id to the GUID).

Parameters:
principal - not used, always null
syncItem - the item to replace/add
Returns:
the inserted/updated item
Throws:
SyncException - in case of error (for instance if the underlying data store runs into problems)

beginSync

void beginSync(int syncMode)
               throws SyncException
Called after SyncManager preparation and initialization just before start the synchronization of the SyncSource.

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

commitSync

void commitSync()
                throws SyncException
Called just before committing the synchronization process by the SyncManager. If an error is detected and

Throws:
SyncException


Copyright © 2010 Funambol. All Rights Reserved.