Declarative Objectivity (DO) Language : Attribute Structures : Collection Attributes
Collection Attributes
Collection attributes are attributes that hold groupings of elements.
Discussion 
A collection attribute may hold one of the following logical types of collection:
Collection
Description
Ordered grouping of potentially non-unique elements. Elements are maintained in the order in which they were added to the collection.
Grouping of unique elements, which may be ordered or unordered. Organization of elements is controlled by the collection.
Grouping of key-value pairs. Keys must be unique within the collection; values may be non-unique. Keys may be ordered or unordered. Organization of elements is controlled by the collection.
Every collection attribute is described by:
An element specification that specifies the element type for a list or set. A map requires both an element specification and a key specification.
A collection-implementation type that specifies the collection’s internal data structure. A collection implementation supports a particular combination of features, such as the number and type of elements; whether the elements are ordered, unordered, unique, or nonunique; whether the collection is optimized for very many or very few elements; and so on. The federated database provides several built-in implementation types for each type of collection.
In general, the element type for a list may be any data type other than a collection type.
Note: Currently, the element type of a set or map must be a reference type.
You can use a collection attribute to model a to-many relationship by setting the element type to be a reference type. An object with such an attribute can be linked to multiple objects of the referenced class. (You use a reference attribute to model a to-one relationship.)
List Attributes
       
List Values
Logical Type
Settings
Options1
Quick Look
Arrays of dataType elements
List
Element:
dataType
highVolumeDates: List {
  Element: Date
}
 
servRecs: List {
  Storage: Variable,
  Element: String {
    Encoding: Utf8,
    Storage: Variable
  }
}
 
topTenRatings: List {
  Storage: FixedSize,
  FixedStorageSize: 10,
  Element: Integer {
    Encoding: Unsigned,
    Storage: B8
  }
}
 
Storage:
Variable
FixedSize
 
FixedStorageSize:
n
To-many relationships to persistent objects
List
Element:
referenceType
categories: List {
  Storage: Variable,
  Element: Reference {
    Referenced: FleetData.VehicleCategory
  }
}
 
 
stalls: List {
  Storage: Variable,
  Element: Reference {
    Referenced: FleetData.Stall,
    Inverse: location
  }
}
 
Storage:
Variable
FixedSize
 
FixedStorageSize:
 
n
Scalable lists of references to persistent objects
List
Element:
referenceType
models: List {
  CollectionTypeName: TreeListOfReferences,
  Element: Reference {
    Referenced: FleetData.VehicleModel
  }
}
CollectionTypeName
TreeListOfReferences
1. You can omit settings for default options, which are indicated in boldface.
Discussion 
For general syntax information, see About Attribute Structures.
For examples of literal list values, see Collection Structures.
If the elements of a list are references to persistent objects of a schema class, the list models a to-many relationship.
Specifying the Attribute Type
A list attribute has following logical type.
Logical Type
Description
List
Ordered grouping of potentially non-unique elements. Elements are maintained in the order in which they were added to the collection.
Specifying Type Characteristics
A list attribute uses the following settings to specify detailed type characteristics:
Setting
Specifies
Options
Element:
The data type of the list’s elements.
dataType consisting of the logical type and settings used in an attribute structure of the chosen data type. dataType may not describe another collection type.
Storage:
The storage for lists
Variable
The number of elements may vary
FixedSize
The number of elements is fixed
FixedCapacity
(Reserved for future use.) The number of elements may vary up to a fixed maximum number
FixedStorageSize:
The size of a fixed-size list.
n
Integer number of elements in a fixed-size list.
CollectionTypeName:
The built-in implementation type for the list.
(Omit setting)
Unnamed implementation determined by the other settings.
TreeListOfReferences
Scalable list of references
The following table summarizes the built-in implementations that are currently supported for lists.
  
Built-in List Implementation
CollectionTypeName:
Element:
Storage:
Description
Variable-size array
Any data type except a collection type
Variable
Array with a variable number of elements of the specified type.
Fixed-size array
Any data type except a collection type
FixedSize
Array with a fixed number of elements of the specified type.
Scalable list of references
TreeListOfReferences
Reference type
Variable
B+ tree for a variable number (possibly millions) of elements that are references to objects of a schema class.
Set Attributes
 
Set Values
Logical Type
Settings
Options
Quick Look
Unordered sets of references to persistent objects
Set
CollectionTypeName:
 
HashSetOfReferences
 
pendingPickups: Set {
  CollectionTypeName: HashSetOfReferences,
  Element: Reference {
     Referenced: FleetData.Reservation
  }
}
 
Element:
referenceType
Ordered sets of references to persistent objects
Set
CollectionTypeName:
TreeSetOfReferences
pendingPickups: Set {
  CollectionTypeName: TreeSetOfReferences,
  Element: Reference {
     Referenced: FleetData.Reservation
  }
}
 
Element:
referenceType
Discussion 
For general syntax information, see About Attribute Structures.
For examples of literal set values, see Collection Structures.
Because the elements of a set are references to persistent objects of a schema class, you can use a set to model a to-many relationship.
Specifying the Attribute Type
A set attribute has following logical type.
Logical Type
Description
Set
Grouping of unique elements, which may be ordered or unordered. Organization of elements is controlled by the collection.
Specifying Type Characteristics
A set attribute uses the following settings to specify detailed type characteristics:
Setting
Specifies
Element:
The data type of the set’s elements. Specify a referenceType consisting of the logical type and settings used in a reference attribute structure.
CollectionTypeName:
The built-in implementation type for the set. Must be specified explicitly.
Note:A set attribute always provides storage for a variable number of elements. An error occurs if you attempt to configure a set attribute’s storage explicitly.
Note:A set attribute uses the built-in set-implementation type that you request explicitly by name. An error occurs if the requested set implementation is incompatible with the element specification.
The following table summarizes the built-in implementations that are currently supported for sets.
      
Built-in Set Implementation
CollectionTypeName:
Element:
Description
Unordered set
HashSetOfReferences
Reference type
Hashing mechanism for a variable number (possibly millions) of unsorted elements that are unique references to objects of a schema class. Hash values are computed from the identifiers of the referenced objects.
Ordered set
TreeSetOfReferences
Reference type
B+ tree for a variable number (possibly millions) of elements that are unique references to objects of a schema class. Elements are sorted in increasing order by the identifiers (OIDs) of the referenced objects.
Map Attributes
            
Map Values
Logical Type
Settings
Options
Quick Look
Name maps with string keys leading to referenced objects
Map
CollectionTypeName:
NameToReferenceMap
customers: Map {
  CollectionTypeName: NameToReferenceMap,
  Key: String {
    Encoding: Byte,
    Storage: Variable
  },
    Element: Reference {
       Referenced: FleetData.Customer
  }
}
Key:
stringType
Element:
referenceType
Unordered object maps with references to persistent objects as keys and values
Map
CollectionTypeName:
HashMapOfReferences
customers: Map {
  CollectionTypeName: HashMapOfReferences,
  Key: Reference {
     Referenced: FleetData.RentalContract
  },
  Element: Reference {
     Referenced: FleetData.Customer
  }
}
Key:
referenceType
Element:
referenceType
Ordered object maps with references to persistent objects as keys and values
Map
CollectionTypeName:
TreeMapOfReferences
customers: Map {
  CollectionTypeName: TreeMapOfReferences,
  Key: Reference {
     Referenced: FleetData.RentalContract
  },
  Element: Reference {
     Referenced: FleetData.Customer
  }
}
Key:
referenceType
Element:
referenceType
Discussion 
For general syntax information, see About Attribute Structures.
For examples of literal map values, see Collection Structures.
Because the values of a map are references to persistent objects of a schema class, you can use a map to model a to-many relationship.
Specifying the Attribute Type
A map attribute has following logical type:
Logical Type
Description
Map
Grouping of key-value pairs. Keys must be unique within the collection; values may be non-unique. Keys may be ordered or unordered. Organization of elements is controlled by the collection.
 
Specifying Type Characteristics
A map attribute uses the following settings to specify detailed type characteristics:
Setting
Specifies
Key:
The data type of the map’s keys.
For a name map, specify a stringType consisting of the logical type and settings used in a string attribute structure.
For an object map, specify a referenceType consisting of the logical type and settings used in a reference attribute structure for unidirectional references only.
Element:
The data type of the map’s values. Specify a referenceType consisting of the logical type and settings used in a reference attribute structure for either unidirectional or bidirectional references.
CollectionTypeName:
The built-in implementation type for the map. Must be specified explicitly.
Note:A map attribute always provides storage for a variable number of key-value pairs. An error occurs if you attempt to configure a map attribute’s storage explicitly.
Note:A map attribute uses the built-in map-implementation type that you request explicitly by name. An error occurs if the requested map implementation is incompatible with the key or element specification.
The following table summarizes the built-in implementations that are currently supported for maps.
 
Built-in Map Implementation
CollectionTypeName:
Key:
Element:
Description
Name map
NameToReferenceMap
String type
Reference type
Dictionary for a variable number (up to about 10,000) of unique strings, each paired with a reference to an object of a schema class. Not optimized for scalability.
Unordered object map
HashMapOfReferences
Reference type
Reference type
Hashing mechanism for a variable number (possibly millions) of unsorted keys that are unique unidirectional references to objects of a schema class. Hash values are computed from the identifiers of the referenced objects.
Ordered object map
TreeMapOfReferences
Reference type
Reference type
B+ tree for a variable number (possibly millions) of keys that are unique unidirectional references to objects of a schema class. Elements are sorted in increasing order by the identifiers (OIDs) of the referenced objects.
About To-Many Relationships
When the element type of a collection attribute is a reference type, the attribute models a to-many relationship (also called a to-many UML association). An object with such an attribute has a collection for storing references to multiple objects of the referenced class. The collection may be a list, set, or map. If the collection is a list, it may be variable or fixed-size.
You implement a to-many relationship either as a collection of unidirectional references, or a collection of bidirectional references, depending on how you specify the reference type for the collection attribute’s elements.
Collection of Unidirectional References
A collection of unidirectional references represents a one-way relationship between an object of a source class and some number of objects of a destination class.
The source class defines a collection attribute whose elements are of a unidirectional reference type. Furthermore:
The source class may be either referenceable or embeddable.
The destination class must be referenceable, and may be the same as the source class. The destination class is specified by the Referenced: setting for the reference type described by the element specification.
When a source class has an attribute for a collection of unidirectional references, you can use that attribute to link a particular object of the source class to multiple objects of the destination class. Each reference representing one of these links is stored as an element within the source object’s collection. Each stored reference encapsulates the object identifier (OID) of a destination object. Because an OID uniquely identifies an object by its location within the federated database, a DO query can use the collection of OIDs to traverse from the source object to any or all of the destination objects.
Example. The following UPDATE SCHEMA statement creates two related schema classes, RentalCompany and VehicleCategory. RentalCompany is the source class, with a list attribute called categories for unidirectionally referencing objects of VehicleCategory, the destination class:
UPDATE SCHEMA 
{
  CREATE CLASS FleetData.RentalCompany 
  {
    ...
    categories: List { 
      Storage: Variable,
      Element: Reference {
        Referenced: FleetData.VehicleCategory
      }
    },
    ...
  }
  CREATE CLASS FleetData.VehicleCategory 
  {
    ...
  }
}
The categories attribute enables you to link a particular RentalCompany object to any number of related VehicleCategory objects. Each such link is represented as a unidirectional reference to a VehicleCategory object, and added to the RentalCompany’s categories list, as shown in the following diagram:
A DO query that finds a RentalCompany object can use its categories collection to find and access the related VehicleCategory objects:
FROM RentalCompany RETURN categories.rate;
Collection of Bidirectional References
A collection of bidirectional references represents a two-way relationship between an object of a source class and multiple objects of a destination class.
The source class defines a collection attribute whose elements are of a bidirectional reference type. Furthermore:
The source class must be referenceable.
The destination class must be referenceable, and may be the same as the source class. The destination class is specified by the Referenced: setting for the reference type described by the element specification.
The destination class must have an attribute for holding one or more bidirectional references to objects of the source class. The attribute, which may be either a reference attribute or a collection attribute, is specified by the Inverse: setting for the reference type described by the element specification.
When a source class has an attribute for a collection of bidirectional references, you can use that attribute to link a particular object of the source class to multiple objects of the destination class. Each time you add a link to another destination object, you add a new reference to the source object’s collection. Because the reference is bidirectional, the destination object is automatically provided with an inverse reference pointing back to the source object.
Example. The following UPDATE SCHEMA statement creates two referenceable schema classes, Vehicle and RentalContract. The Vehicle class has a list attribute called pastRentals for holding a variable number of bidirectional references to RentalContract objects. The RentalContract class has a reference attribute called vehicle for holding a single bidirectional reference to a Vehicle object. The pastRentals and vehicle attributes are inverses of each other.
UPDATE SCHEMA 
{
  CREATE CLASS FleetData.Vehicle 
  {
    ...
    pastRentals: List { 
      Storage: Variable,
      Element: Reference {
        Referenced: FleetData.RentalContract, 
        Inverse: vehicle
      }
    },
    ...
  }
 
  CREATE CLASS FleetData.RentalContract, 
  {
    ...
    vehicle: Reference {
      Referenced: FleetData.Vehicle,
      Inverse: pastRentals
    },
    ...
  }
}
The pastRentals and vehicle attributes enable you to form bidirectional links between a particular Vehicle object and some number of related Stall objects. Adding a reference to the Vehicle’s pastRentals list automatically causes the RentalContract’s vehicle attribute to be set, as shown in the following diagram:
A DO query that finds a Vehicle object can use its pastRentals collection to find and access the related RentalContract objects:
FROM Vehicle RETURN pastRentals.number;
Conversely, a query that finds a RentalContract object can use the OID stored in the vehicle attribute to find and access the related Vehicle object.
FROM RentalContract RETURN vehicle.license;