net.rim.device.api.system
Class ObjectGroup

java.lang.Object
  net.rim.device.api.system.ObjectGroup

public final class ObjectGroup
extends Object

Object groups An object group is a collection of objects which all reside in the same filesystem record. Use the ObjectGroup class to consolidate persistent object handles for an object into one group and reduce the number of persistent object handles being used by the system. The number of available persistent object handles is determined by a handheld device's flash memory and an application's data structures. Consolidating persistent object handles reduces the number of used object handles. Consider a record that contains 10 string fields. This record consumes 11 persistent object handles. Using the ObjectGroup class to group the record, just one object handle is used for the record instead of 11. The persistent object handles for the String fields are consolidated under the record object handle. A grouped object is read-only. Attempting to modify a grouped object without ungrouping it throws an ObjectGroupReadOnlyException. See 'Memory Best Practices for the BlackBerry Java Development Environment' for more information.

Example

 // AddressbookEntry class.
 public class AddressbookEntry
 {
      private String _firstname;
      private String _lastname;
      // ...
 }
 
 // Some other class... 
 // Using Object Grouping for the AddressbookEntryClass:
 private static addAddressbookEntry( firstnameString, lastnameString ) 
 {
     AddressbookEntry entry = new AddressbookEntry( firstname, lastname);
     // Consumes 3 object handle.
 
     ObjectGroup.createGroup(entry);          // Consumes only 1 object handle
     Addressbook.getInstance().add( entry );  
 }
     
 
 private static editEntry( index int) 
 {
     AddressbookEntry entry = Addressbook.getInstance().get( index );
 
     if (ObjectGroup.isInGroup( entry )
     {
         entry = (AddressbookEntry)ObjectGroup.expandGroup( entry );
     }
 
     // Perform editing of object as usual...
 } 
 

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

Method Summary
	static void	createGroup(Object obj) Groups an object and everything it references to (recursively) into one orphan filesystem record.
	static void	createGroupIgnoreTooBig(Object obj) Groups an object and everything it references to (recursively) into one orphan filesystem record.
	static Object	expandGroup(Object obj) Ungroups an object.
	static boolean	isInGroup(Object obj) Indicates whether an object is grouped.

Methods inherited from class java.lang.Object

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

Method Detail

createGroup

public static void createGroup(Object obj)

Groups an object and everything it references to (recursively) into one orphan filesystem record. References between objects in a group are rewritten as relative references which do not consume an object handle. Any attempt to modify an object in a group will result in ObjectGroupReadOnlyException being thrown.

Parameters:

obj - the object to group

Throws:

ObjectGroupTooBigException - if there are too many objects to fit in 64k

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

createGroupIgnoreTooBig

public static void createGroupIgnoreTooBig(Object obj)

Groups an object and everything it references to (recursively) into one orphan filesystem record. References between objects in a group are rewritten as relative references which do not consume an object handle. Any attempt to modify an object in a group will result in ObjectGroupReadOnlyException being thrown. This version will record (in the event log) if a grouping failed.

Parameters:

obj - the object to group

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

expandGroup

public static Object expandGroup(Object obj)

Ungroups an object. You must ungroup a grouped object before modifying it.

Parameters:

obj - The object to ungroup.

Returns:

The ungrouped version of the object.

Throws:

IllegalArgumentException - if obj is not the root of an ObjectGroup.

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

isInGroup

public static boolean isInGroup(Object obj)

Indicates whether an object is grouped.

Parameters:

obj - The object to check.

Returns:

true if obj is grouped, 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 4.0.0