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) Adds a SyncObject to this SyncCollection.
	void	beginTransaction() Starts a transaction.
	void	clearSyncObjectDirty(SyncObject object) Marks the specified SyncObject as not dirty.
	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() Ends a transaction.
	SyncConverter	getSyncConverter() Returns the synchronization message converter (SyncConverter) for this SyncCollection.
	abstract boolean	getSyncData(DataBuffer buffer, int version) Gets the data of this object for use in synchronization.
	abstract String	getSyncName() Returns the name of this SyncCollection.
	abstract String	getSyncName(Locale locale)
	SyncObject	getSyncObject(int uid) Return the SyncObject in this SyncCollection with the given UID.
	int	getSyncObjectCount() Returns a the number of SyncObjects in this SyncCollection.
	SyncObject[]	getSyncObjects() Returns an array of SyncObjects representing all SyncObjects in this SyncCollection.
	abstract int	getSyncVersion() Returns the current version number of this SyncCollection.
	int	getUID() Returns the unique ID stored in this SyncObject.
	boolean	isSyncObjectDirty(SyncObject object) Determines whether a specified SyncObject is dirty.
	boolean	removeAllSyncObjects() Called to remove all SyncObjects from the SyncCollection.
	boolean	removeSyncObject(SyncObject object) Removes a SyncObject from this SyncCollection.
	abstract boolean	setSyncData(DataBuffer buffer, int version) Sets the data of this object from the data received through synchronization.
	void	setSyncObjectDirty(SyncObject object) Marks the specified SyncObject as dirty.
	boolean	updateSyncObject(SyncObject oldObject, SyncObject newObject) Updates a SyncObject in this SyncCollection.

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

Returns the current version number of this SyncCollection.

Specified by:

getSyncVersion in interface SyncCollection

Returns:

The current version number of this SyncCollection.

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

Returns the name of this SyncCollection. NOTE: The name that is returned must be unique across all SyncCollections and should never be localized.

Specified by:

getSyncName in interface SyncCollection

Returns:

The name of this SyncCollection.

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

Adds a SyncObject to this SyncCollection.

The SyncObject's dirty bit is set to clean by default.

Specified by:

addSyncObject in interface SyncCollection

Parameters:

object - The SyncObject to be added to the collection.

Returns:

true if the operation was successful; false otherwise.

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

Updates a SyncObject in this SyncCollection.

The method accepts the old object to be replaced as well as the new object that will replace it in the collection. The SyncObject should subsequently be marked clean.

Specified by:

updateSyncObject in interface SyncCollection

Parameters:

oldObject - The object to be updated.

Returns:

true if the operation was successful; false otherwise.

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

Removes a SyncObject from this SyncCollection.

Specified by:

removeSyncObject in interface SyncCollection

Parameters:

object - The object to be removed.

Returns:

true if the operation was successful; false otherwise.

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

Called to remove all SyncObjects from the SyncCollection.

Specified by:

removeAllSyncObjects in interface SyncCollection

Returns:

true if the update succeeded; false otherwise.

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

Returns an array of SyncObjects representing all SyncObjects in this SyncCollection.

The synchronization manager assumes that it is free to manipulate this array as it requires.

Specified by:

getSyncObjects in interface SyncCollection

Returns:

An array of SyncObjects in this SyncCollection.

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

Return the SyncObject in this SyncCollection with the given UID.

Specified by:

getSyncObject in interface SyncCollection

Parameters:

uid - The UID of the SyncObject to retrieve.

Returns:

The SyncObject with the given ID or null if no such SyncObject exists.

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

Determines whether a specified SyncObject is dirty.

"Dirty" refers to whether or not the object has been modified on the handheld.

Specified by:

isSyncObjectDirty in interface SyncCollection

Parameters:

object - The object in question.

Returns:

true if the SyncObject is dirty; false otherwise.

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

Marks the specified SyncObject as dirty.

"Dirty" refers to whether or not the object has been modified on the handheld.

Specified by:

setSyncObjectDirty in interface SyncCollection

Parameters:

object - The SyncObject in question.

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

Marks the specified SyncObject as not dirty.

"Dirty" refers to whether or not the object has been modified on the handheld.

Specified by:

clearSyncObjectDirty in interface SyncCollection

Parameters:

object - The SyncObject in question.

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

Returns a the number of SyncObjects in this SyncCollection.

Specified by:

getSyncObjectCount in interface SyncCollection

Returns:

The number of SyncObjects in this SyncCollection.

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

Returns the synchronization message converter (SyncConverter) for this SyncCollection.

A SyncConverter serializes SyncObjects and processes serialized data to create SyncObjects.

Specified by:

getSyncConverter in interface SyncCollection

Returns:

The synchronization message converter for this SyncCollection.

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

Starts a transaction.

Transactions are required to execute synchronizations that involve a large number of data records. The beginTransaction method is invoked by the SyncManager before adding, modifying or deleting a data record serially.

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

Ends a transaction.

Transactions are required to execute synchronizations that involve a large number of data records. The endTransaction method is invoked to signal the end of the transaction.

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