SHOW Signed
 

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:
JDE 4.0.0

Method Summary
 Category: Signed static void createGroup(Object obj)
          Groups an object and everything it references to (recursively) into one orphan filesystem record.
 Category: Signed static void createGroupIgnoreTooBig(Object obj)
          Groups an object and everything it references to (recursively) into one orphan filesystem record.
 Category: Signed static Object expandGroup(Object obj)
          Return a new object which is a read-write clone of an object group
 Category: Signed static boolean isInGroup(Object obj)
           
 
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
Since:
JDE 4.0.0
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.

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
Since:
JDE 4.0.0
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.

expandGroup

public static Object expandGroup(Object obj)
Return a new object which is a read-write clone of an object group
Parameters:
obj - the object to ungroup
Throws:
IllegalArgumentException - if obj is not the root of the ObjectGroup.
Since:
JDE 4.0.0
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.

isInGroup

public static boolean isInGroup(Object obj)
Since:
JDE 4.0.0
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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.