net.rim.device.api.synchronization
Class SyncItem

java.lang.Object
  net.rim.device.api.synchronization.SyncItem

All Implemented Interfaces:

SyncCollection, SyncConverter, SyncObject

Direct Known Subclasses:

OTASyncCapableSyncItem

public abstract class SyncItem
extends Object
implements SyncObject, SyncCollection, SyncConverter

Provides an implementation of SyncCollection to provide small objects with easy access to the Synchronization API. This class is used to provide backup/restore functionality to small bits of information, typically configuration options.

Implementers should extend this object and implement the abstract functions:

• SyncItem.getSyncName()
• SyncItem.getSyncName(Locale locale)
• SyncItem.getSyncVersion()
• SyncItem.getSyncData(DataBuffer buffer, int version)
• SyncItem.setSyncData(DataBuffer buffer, int version)

See Also:

SyncCollection, SyncManager.enableSynchronization(net.rim.device.api.synchronization.SyncCollection), SyncConverter, 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

Constructor Summary
	protected	SyncItem()

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.
	boolean	convert(SyncObject object, DataBuffer buffer, int version) Converts a SyncObject into synchronization data.
	SyncObject	convert(DataBuffer data, int version, int uid) Extracts a SyncObject from the synchronization data.
	void	endTransaction() End a synchronization transaction involving this collection.
	SyncConverter	getSyncConverter() Retrieve the sync message converter for this collection.
	abstract boolean	getSyncData(DataBuffer buffer, int version) Gets the data of this object for use in synchronization.
	abstract String	getSyncName() Retrieve this collection's sync name.
	abstract String	getSyncName(Locale locale)
	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.
	abstract int	getSyncVersion() Retrieve the unique identifier used by the sync framework to identify the synchronization version of this collection.
	int	getUID() Returns the unique ID stored in this SyncObject.
	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.
	abstract boolean	setSyncData(DataBuffer buffer, int version) Sets the data of this object from the data received through synchronization.
	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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.rim.device.api.synchronization.SyncCollection

getSyncName

Constructor Detail

SyncItem

protected SyncItem()

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 Detail

setSyncData

public abstract boolean setSyncData(DataBuffer buffer,
                                    int version)

Sets the data of this object from the data received through synchronization.

Parameters:

buffer - The data received through synchronization.

version - The version number specified with the data.

Returns:

true if the operation was successful; false otherwise.

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

getSyncData

public abstract boolean getSyncData(DataBuffer buffer,
                                    int version)

Gets the data of this object for use in synchronization.

Parameters:

buffer - The DataBuffer into which the data should be placed.

version - The version of the information to be provided.

Returns:

true if the operation was successful; false otherwise.

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

getUID

public int getUID()

Description copied from interface: SyncObject

Returns the unique ID stored in this SyncObject.

Specified by:

getUID in interface SyncObject

Returns:

The unique ID of this object.

See Also:

SyncObject.getUID()

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

convert

public boolean convert(SyncObject object,
                       DataBuffer buffer,
                       int version)

Description copied from interface: SyncConverter

Converts a SyncObject into synchronization data.

Specified by:

convert in interface SyncConverter

Parameters:

object - The SyncObject to be converted.

buffer - The buffer into which the data will be placed. This buffer should not be rewound as it may already contain other data.

version - The version number specified with the data.

Returns:

true if the object was converted successfully; false otherwise.

See Also:

SyncConverter.convert( SyncObject, DataBuffer, int )

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

convert

public SyncObject convert(DataBuffer data,
                          int version,
                          int uid)

Description copied from interface: SyncConverter

Extracts a SyncObject from the synchronization data.

Specified by:

convert in interface SyncConverter

Parameters:

data - The DataBuffer containing only the synchronization data. This buffer may be rewound as it will contain only the data associated with the SyncObject in question.

version - The version number specified with the data.

Returns:

A SyncObject obtained from the synchronization data, or null if this conversion was unsuccessful.

See Also:

SyncConverter.convert( DataBuffer, int, int )

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

public abstract int getSyncVersion()

Description copied from interface: SyncCollection

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.

Specified by:

getSyncVersion in interface SyncCollection

Returns:

The sync version value for this collection.

See Also:

SyncCollection.getSyncVersion()

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

public abstract String getSyncName()

Description copied from interface: SyncCollection

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.

Specified by:

getSyncName in interface SyncCollection

Returns:

Sync name for this collection.

See Also:

SyncCollection.getSyncName()

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

public abstract String getSyncName(Locale locale)

See Also:

SyncCollection.getSyncName()

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

addSyncObject

public boolean addSyncObject(SyncObject object)

Description copied from interface: SyncCollection

Add a sync object to this collection.

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

Specified by:

addSyncObject in interface SyncCollection

Parameters:

object - The sync object to add to this collection.

Returns:

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

See Also:

SyncCollection.addSyncObject(net.rim.device.api.synchronization.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

updateSyncObject

public boolean updateSyncObject(SyncObject oldObject,
                                SyncObject newObject)

Description copied from interface: SyncCollection

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

Specified by:

updateSyncObject in interface SyncCollection

Parameters:

oldObject - Sync object to replace; may be null.

Returns:

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

See Also:

SyncCollection.updateSyncObject(net.rim.device.api.synchronization.SyncObject, net.rim.device.api.synchronization.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

removeSyncObject

public boolean removeSyncObject(SyncObject object)

Description copied from interface: SyncCollection

Remove a sync object from this collection.

Specified by:

removeSyncObject in interface SyncCollection

Parameters:

object - Sync object to remove.

Returns:

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

See Also:

SyncCollection.removeSyncObject(net.rim.device.api.synchronization.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

removeAllSyncObjects

public boolean removeAllSyncObjects()

Description copied from interface: SyncCollection

Flush all sync objects out of this collection.

Specified by:

removeAllSyncObjects in interface SyncCollection

Returns:

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

See Also:

SyncCollection.removeAllSyncObjects()

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

public SyncObject[] getSyncObjects()

Description copied from interface: SyncCollection

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.

Specified by:

getSyncObjects in interface SyncCollection

Returns:

All the sync objects in tihs collection.

See Also:

SyncCollection.getSyncObjects()

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

public SyncObject getSyncObject(int uid)

Description copied from interface: SyncCollection

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

Specified by:

getSyncObject in interface SyncCollection

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.

See Also:

SyncCollection.getSyncObject(int)

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

public boolean isSyncObjectDirty(SyncObject object)

Description copied from interface: SyncCollection

Determine if the provided sync object has recently been modified.

Specified by:

isSyncObjectDirty in interface SyncCollection

Parameters:

object - Object to check.

Returns:

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

See Also:

SyncCollection.isSyncObjectDirty(net.rim.device.api.synchronization.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

setSyncObjectDirty

public void setSyncObjectDirty(SyncObject object)

Description copied from interface: SyncCollection

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.

Specified by:

setSyncObjectDirty in interface SyncCollection

Parameters:

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

See Also:

SyncCollection.setSyncObjectDirty(net.rim.device.api.synchronization.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

public void clearSyncObjectDirty(SyncObject object)

Description copied from interface: SyncCollection

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.

Specified by:

clearSyncObjectDirty in interface SyncCollection

Parameters:

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

See Also:

SyncCollection.clearSyncObjectDirty(net.rim.device.api.synchronization.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

public int getSyncObjectCount()

Description copied from interface: SyncCollection

Retrieve the number of sync objects in this collection.

Specified by:

getSyncObjectCount in interface SyncCollection

Returns:

Number of sync objects contained in this collection.

See Also:

SyncCollection.getSyncObjectCount()

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

getSyncConverter

public SyncConverter getSyncConverter()

Description copied from interface: SyncCollection

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.

Specified by:

getSyncConverter in interface SyncCollection

Returns:

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

See Also:

SyncCollection.getSyncConverter()

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

public void beginTransaction()

Description copied from interface: SyncCollection

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.

Specified by:

beginTransaction in interface SyncCollection

See Also:

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

endTransaction

public void endTransaction()

Description copied from interface: SyncCollection

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()).

Specified by:

endTransaction in interface SyncCollection

See Also:

SyncCollection.endTransaction()

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