Best practice: Conserve object handles
One of the most common errors that app developers encounter is an exhaustion of persistent object handles. The amount of application storage space on the smartphone determines the fixed number of persistent object handles that are available in the system. Depending on the data structure selection, stored records can quickly exhaust the number of persistent object handles. A persistent object consumes a persistent object handle and an object handle. A transient object consumes only an object handle.
For example, a record that contains ten String fields, which represent items such as a name, phone number, and address, consumes 11 persistent object handles, one for the record object and one for each String. If an application persists 3000 records, the application consumes 33,000 persistent object handles, which exceeds the number of persistent object handles available on a smartphone that has16 MB of flash memory.
You can use the net.rim.device.api.system.ObjectGroup class to consolidate the object handles for an object into one group. Using the example in the previous paragraph, if you group the record, the record consumes one persistent object handle instead of 11. The object handles for the String fields consolidate under the record object handle.
When you consolidate object handles into one group, the object handle is read-only. You must ungroup the object before you can change it. After you complete the changes, group the object again. If you attempt to change a grouped object without first ungrouping it, an ObjectGroupReadOnlyException is thrown.
Ungrouping an object has a performance impact. The system creates a copy of the grouped object and allocates handles to each of the objects inside that group. Therefore, objects should only be ungrouped when necessary.
It is possible for commits to the persistent store to occur during garbage collection without an explicit commit(), so grouping of objects should always occur before calls to setContents() or commit(). For more information about object grouping, see net.rim.device.api.system.ObjectGroup.