Collection Class

Collections are the basic structures used to store multiple object references or primitive type values. The Collection class is the abstract superclass of all collection classes that defines the common protocol for all of its subclasses. The Collection class provides the protocol to:

When membership of a collection is a class, instances of that class and all of its subclasses can be included in the collection. When a Collection object is cloned (by using the reimplemented cloneSelf method of the Object class), the entries in the collection are copied to the new collection instance.

The add, remove, and includes methods are defined at the Collection class level to provide closure and are inherited by all subclasses of collection. However, use of these Collection class methods with external key dictionaries is not recommended because none of the method signatures allow for the specification of external keys.

Transient objects, including exclusive collections, that are automatically created by JADE cannot be shared. However, all exclusive collections of a shared transient object are created as shared transient objects by JADE. (For details about specifying the creation of transient objects that can be shared across threads, see "create Instruction", in Chapter 1 of the JADE Developer’s Reference.)

The structure of the Collection class hierarchy is shown in the following diagram.

Use bracket symbols ([]) to access random entries in a dictionary or array.

An exclusive collection is created when it is updated for the first time. Whenever an exclusive collection is created, regardless of whether it has an inverse reference, the edition of the owner object is updated. An exclusive collection is also created if the instantiate method is called before the collection is updated the first time. For details about the behavior of and tuning collections, see Chapter 4 of the JADE Developer’s Reference.

When the type of a property is a Collection subclass, the access mode setting applies to the reference to the collection rather than its members; that is, a setting of read‑only does not prevent collection members being added, deleted, or updated.

For Collection classes that are internal pseudo arrays (that is, arrays of GUI‑related information only in the JADE run time module), the only Collection class methods that are implemented are size and size64.

For details about specifying dictionary membership and keys at run time, see "DynaDictionary Class", later in this chapter. For details about the methods defined in the Collection class, see "Collection Methods", in the following subsection. (For details about the lockReceiver method option, which indicates that an exclusive lock of transaction duration is to be placed on the receiver collection before calling the method, see "lockReceiver Option", in Chapter 1 of the JADE Developer’s Reference.)