net.rim.device.api.synchronization
Interface SyncCollection

All Known Implementing Classes:

OTASyncCapableSyncItem, SyncItem

public interface SyncCollection

Defines functionality required for a collection of SyncObject instances, used for backup, restore, and synchronization of persisted data with a back-end synchronization service.

Implementation constraints
Naming your collection: Every collection has a name that uniquely identifies the collection within the sync system. Your collection's sync name is equivalent to a database name for your ID, and get used as a unique key within the system. When the device gets connected to a Desktop Manager, the sync name appears to the user as the database name for your collection. During enterprise activation, the sync name appears in the activation list as collection name.

Note that once code with your sync collection's name has interacted with a backup/restore service, you may not change the name without breaking backwards compatibility.

Sync collection names should not, therefore, be localized or dynamic.

Additionally, your sync collection's name must consist of no less than 1 and no more than 32 characters.

Finally, some back-end services treat your sync collection's name with case-sensitivity and some do not; therefore, you should ensure that your collection's name does not rely solely on differences of case to be unique, as this will work with some services, but not with others.

See Also:

SyncItem, SyncManager.enableSynchronization(net.rim.device.api.synchronization.SyncCollection), StateInfoListener

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Method Summary
	boolean	addSyncObject(SyncObject object) Add a sync object to this collection.
	void	beginTransaction() Start a synchronization transaction involving this collection.
	void	clearSyncObjectDirty(SyncObject object) Mark a provided sync object as not having been recently modified.
	void	endTransaction() End a synchronization transaction involving this collection.
	SyncConverter	getSyncConverter() Retrieve the sync message converter for this collection.
	String	getSyncName() Retrieve this collection's sync name.
	String	getSyncName(Locale locale) Retrieve a localized name for this collection.
	SyncObject	getSyncObject(int uid) Retrieve the sync object associated with provided ID from this collection.
	int	getSyncObjectCount() Retrieve the number of sync objects in this collection.
	SyncObject[]	getSyncObjects() Retrieve all the sync objects from this collection.
	int	getSyncVersion() Retrieve the unique identifier used by the sync framework to identify the synchronization version of this collection.
	boolean	isSyncObjectDirty(SyncObject object) Determine if the provided sync object has recently been modified.
	boolean	removeAllSyncObjects() Flush all sync objects out of this collection.
	boolean	removeSyncObject(SyncObject object) Remove a sync object from this collection.
	void	setSyncObjectDirty(SyncObject object) Mark a provided sync object as having been recently modified.
	boolean	updateSyncObject(SyncObject oldObject, SyncObject newObject) Replace an existing sync object in this collection with a new one.

Method Detail

addSyncObject

boolean addSyncObject(SyncObject object)

Add a sync object to this collection.

Implementations should, by default, set the sync object's dirty bit to clean.

Parameters:

object - The sync object to add to this collection.

Returns:

True if the sync object is successfully added to this collection; otherwise false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

updateSyncObject

boolean updateSyncObject(SyncObject oldObject,
                         SyncObject newObject)

Replace an existing sync object in this collection with a new one.

Implementations should find the provided old sync object in this collection, and then replace it with the provided new sync object. After the replacement, your implementation should mark the new sync object as clean.

Implementations should cope with a null reference to an old object by simply adding the new object to this collection (however, consumers should in general rely upon SyncCollection.addSyncObject(SyncObject) to add new objects).

Parameters:

oldObject - Sync object to replace; may be null.

newobject - New sync object to replace the old one; must not be null, or the same object as provided for the old sync object.

Returns:

True if the old sync object was successfully replaced by the provided new one; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

removeSyncObject

boolean removeSyncObject(SyncObject object)

Remove a sync object from this collection.

Parameters:

object - Sync object to remove.

Returns:

True if the provided sync object gets removed from this collection; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

removeAllSyncObjects

boolean removeAllSyncObjects()

Flush all sync objects out of this collection.

Returns:

True if all the sync objects got removed from this collection; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncObjects

SyncObject[] getSyncObjects()

Retrieve all the sync objects from this collection.

Your implementation must allow for the fact that the synchronization manager will freely manipulate the returned array as it requires.

Returns:

All the sync objects in tihs collection.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncObject

SyncObject getSyncObject(int uid)

Retrieve the sync object associated with provided ID from this collection.

Parameters:

uid - Unique identifier for the sync object to retrieve.

Returns:

Sync object associated with the provided unique ID, or null, if this collection contains no such object.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

isSyncObjectDirty

boolean isSyncObjectDirty(SyncObject object)

Determine if the provided sync object has recently been modified.

Parameters:

object - Object to check.

Returns:

True if the provided object has been modified since the last time it was marked clean; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

setSyncObjectDirty

void setSyncObjectDirty(SyncObject object)

Mark a provided sync object as having been recently modified.

If the device modifies a sync object, then this method should be invoked in order to mark the object as recently changed.

Parameters:

object - Sync object to mark as having been recently modified.

See Also:

SyncCollection.clearSyncObjectDirty(SyncObject)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

clearSyncObjectDirty

void clearSyncObjectDirty(SyncObject object)

Mark a provided sync object as not having been recently modified.

If the device successfully accounts for recent modifications to a sync object, then this method should be invoked in order to remove the "recently modified" mark from the object.

Parameters:

object - Sync object from which to remove the "recently modified" mark.

See Also:

SyncCollection.setSyncObjectDirty(SyncObject)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncObjectCount

int getSyncObjectCount()

Retrieve the number of sync objects in this collection.

Returns:

Number of sync objects contained in this collection.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncVersion

int getSyncVersion()

Retrieve the unique identifier used by the sync framework to identify the synchronization version of this collection.

The back-end synchronization framework supports incremental changes to this collection's data only as long as the sync version for this collection remains unchanged.

When the sync version value for this collection changes on the device, the back-end service assumes that data tagged with the previous version value cannot be reliably synchronized to the device, and will purge all data not tagged with this current sync version value.

Returns:

The sync version value for this collection.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncName

String getSyncName()

Retrieve this collection's sync name.

Implementors must ensure that this method returns a sync name within the naming constraints outlined in this interface's description.

Returns:

Sync name for this collection.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSyncName

String getSyncName(Locale locale)

Retrieve a localized name for this collection.

Implementors may wish to provide a localized name for collection implementations; however, this localized name should get used for display purposes only: the underlying sync name used with the rest of the sync system must be canonical and retrieved by SyncCollection.getSyncName().

The system will use the value retrieved from SyncCollection.getSyncName() for its display purposes if this method returns null.

Parameters:

locale - Display locale of interest.

Returns:

Display name for this collection within the provided locale.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.2

getSyncConverter

SyncConverter getSyncConverter()

Retrieve the sync message converter for this collection.

The sync system depends upon a sync message converter to serialize the sync objects contained within this collection, and to create new SyncObject instances from their serialized forms.

Returns:

Sync message converter for this collection; this may not be null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

beginTransaction

void beginTransaction()

Start a synchronization transaction involving this collection.

The sync system uses transactions to perform synchronizations that involve a large number of data records (because all the affected data records must be handled in a series of packets with the back-end service). The sync manager invokes this method before serially adding, modifying, or deleting a data record.

When the synchronization transaction is complete, the sync manager will terminate it by invoking SyncCollection.endTransaction().

Notice that the OTA Sync framework provides a similar function through the OTASyncListener transaction listener interface.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

endTransaction

void endTransaction()

End a synchronization transaction involving this collection.

The sync manager invokes this method when terminating a synchronization involving this collection (that it opened by invoking SyncCollection.beginTransaction()).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0