This article applies to BlackBerry® wireless devices based on Java™.
An exhaustion of object handles is a common memory-related error that application developers encounter. The BlackBerry device operating system defines the two following types of object handles:
Transitive object handles (more commonly referred to as object handles) are consumed for each object in the system.
Persistent object handles, on the other hand, are consumed only when an object is persisted. That is, a persisted object consumes both a transitive and persistent object handle.
There is a fixed number of object handles in the system (for more information, see the Memory best practices for the BlackBerry Java Development Environment document), where the number of persistent object handles is roughly half the number of transitive object handles. It is important to conserve object handles as often as possible, especially when persisting objects to the limited number. Depending on the data structure selection, it does not take too many stored records to exhaust the number of object handles.
Consider a record that contains 10 String fields representing items such as name, phone number, address, and so on. This record consumes 11 persistent object handles (one for the record object and one for each string). If 3000 records are persisted, the record consumes 33,000 persistent object handles, exceeding the current number of persistent object handles on a 16 MB device.
In BlackBerry Device Software 4.0, an exposed application programming interface (API) provides the capability of Object Grouping. Using the net.rim.device.api.system.ObjectGroup class, you can consolidate the object handles for an object into one group. If you group the record, only one object handle is used for the record instead of 11. The object handles for the String fields will be consolidated under the record object handle.
However, use of the ObjectGroup API has two disadvantages:
When an object is grouped it is considered read-only; you must ungroup the object before making any changes to it. Once the changes are complete, you can group the objects again by using the standard group method. If you try to modify a grouped object without first ungrouping it, an ObjectGroupReadOnlyException will be thrown.
A performance penalty is applied when an object is ungrouped. The system creates a copy of the grouped object and allocate handles to each of the objects inside the group. Therefore, ungroup objects only when necessary. This is why many applications on the device have separate View and Edit menu items. The View menu item does not ungroup the entry, while the Edit menu item does ungroup the item.
The sample code associated with this article shows how an application can take advantage of object grouping for data storage on the device with the common address book implementation. It also shows how easy it is to modify a grouped object that the system does not permit.