Chapter 17: Collection Frameworks

This chapter introduces the frameworks used by the Object COBOL collection classes. Collection frameworks are mainly concerned with the communication between collections and the elements they store.

17.1 Overview

The Object COBOL collection classes assume that their elements are objects. A collection sends messages to its elements to get information such as the element's size and content. Even when you store intrinsic data (as opposed to objects), the collection uses the methods implemented in the intrinsic classes and uses the INVOKE ...AS verb to send messages to the data.

The elements stored in a collection need to include in their interface the methods to respond to those messages. Default versions of most of these are provided in the Base class, but you may want to override these to provide different or more efficient behavior for particular types of object.

You will also need to provide methods which conform to a particular interface for the collection class sort and iterator methods.

17.2 Comparison Between Elements

Collections carry out two types of comparison on elements:

Equality
One element greater than another

17.2.1 Equality

A collection compares two elements by sending the "equal" message to one element, giving it the other element as a parameter. The default "equal" method in Base simply compares the object references of the two objects (that is, they are equal only if they are the same object).

For many applications you will want to compare part or all of the element's instance data to determine equality. Implement the interface to "equal" as follows:

 method-id. "equal".
 linkage section.
 01 lnkElement                object reference. 
 01 lnkEqualityResult         pic x comp-5.
  88 isEqual                  value 1. 
  88 isNotEqual               value 0. 
 procedure division using lnkElement returning lnkEqualityResult.
* Code to compare lnkElement to self and return 
* lnkEqualityResult.
    exit method.
 end method "equal".

17.2.2 Relative Value of Objects

The default sort method of a SortedCollection instance sends the "lessThanOrEqual" (if it is a collection "ofReferences") or the "lessThanOrEqualByLengthValue" (if it is a collection "ofValues") message to all the elements in the collection. There is no default method for this in Base, although it is implemented by the Intrinsic classes and by CharacterArray.

You may need to implement this method so that two objects can compare themselves using part of their instance data. Use the following interface to implement the "lessThanOrEqual" method:

 method-id. "lessThanOrEqual".
 ...
 linkage section.
 01 lnkString             object reference.
 01 lnkResult             pic x comp-5.
  88 isEqual              value 1.
  88 isNotEqual           value 0.

 procedure division using lnkString returning lnkResult.
* Code to compare lnkElement to self and return a result
     exit method.
 end method "lessThanOrEqual".

Use the following interface to implement the "lessThanOrEqualbyLengthValue" method:

 method-id. "lessThanOrEqualbyLengthValue".
 linkage section.
 01 lnkElement                  object reference. 
 01 lnkSize                     pic x(4) comp-5.
 01 lnkResult                   pic x comp-5.
  88 isLessThanOrEqual          value 1. 
  88 isNotLessThanorEqual       value 0. 
 procedure division using lnkElement lnkSize 
                returning lnkResult. 
* Code to compare lsElement to self and return 
* isNotLessThanOrEqual if lsElement is greater than
* self. The lsSize parameter is the value returned
* by element in response to the "size" message.
    exit method.
 end method "lessThanOrEqualbyLengthValue".

17.3 Hashing Elements

The dictionary and set classes use hash values to store and retrieve elements. The default "hash" mechanism in base returns the object reference to the object.

You will often need to override the default with a hash mechanism which creates a hash value using the object's instance data. There are two reasons for this:

Dictionaries and sets will otherwise allow you to add elements or keys with duplicate instance data, because the hash values returned from the default method are different.
Retrieval of data is more efficient. With the default method, the hash value returned to search for an element or key will not relate to the data of the element or key, and the set or dictionary will have to search until it finds the correct object.

Implement the interface to "hash" as follows:

 method-id. "hash".
 linkage section.
 01 lnkHashValue                pic s9(9) comp-5.
 procedure division returning lnkHashValue. 
* Code to return a hashvalue based on object's attributes.
    exit method.
 end method "hash".

Separate objects which have the same value must always return identical results from "hash". Hash values do not have to be unique for each element, but the more duplicate hash values a dictionary contains, the less efficient its storage and retrieval of elements. Hash values should always be positive numbers.

17.4 Display Mechanisms

There are two mechanisms you can use to display the contents of a collection. You can send the message "display" to the collection or you can display the collection on a Listbox.

17.4.1 Using "display"

If you send the "display" message to a collection, it displays on the console all the elements of the collection between parentheses "()". To do this, it sends the message "display" to every element in the collection. The default "display" method in Base displays a description of the object. For example, if sent to one of the CheckAccount objects used in the tutorials, the default "display" method would show:

an instance of the class checkaccount

CharacterArray and the COBOL intrinsic classes implement their own "display" methods which display their contents. You can implement "display" in your own objects using the following interface:

 method-id. "display".
 ...
 procedure division.
* Code to display self on the console. 
    exit method.
 end method "display".

17.4.2 Display on a Listbox

You can display a collection of CharacterArrays or intrinsic data by passing it to a Listbox with the "setContents" message. The Listbox displays each element of the collection as a string on a separate line.

17.5 Collection Sort Methods

Instances of SortedCollection sort elements into order as they are added. The default sorting mechanism provided sends the message "lessThanOrEqual" (if a collection "ofReferences") or "lessThanOrEqualbyLengthValue" (if a collection "ofValues") to elements to compare their relative values (see the section Relative Value of Objects).

You can set your own sort method for an instance of SortedCollection. The method you provide must compare two elements and return a value indicating which element should appear before the other.

To override the default sort method you must create a Callback for your method and pass the Callback to the SortedCollection.

Implement the interface to your sort method as follows:

 method-id. "sortMethod".
 linkage section.
 01 lnkElement1              object reference. 
 01 lnkElement2              object reference. 
 01 lnkResult                pic x comp-5.
  88 element1first           value 1. 
  88 element2first           value 0. 
 procedure division using lsElement1 lsElement2  
                returning lnkResult. 
* Code to compare lsElement1 to lsElement2 and set 
* lnkResult to determine which element should precede 
* the other. 
    exit method.
 end method "sortMethod".

17.6 Iterator Methods

The collection classes implement four iterator methods which enable you to access all the elements of your collection by sending a single message to the collection. To use any of the iterator methods you need to provide a Callback object. The Callback is passed each element of the collection as a parameter in turn.

This section shows you the interface the method in the Callback must have to work with the iterator methods. The iterator methods provided are:

"do"	Passes every element in the collection to a callback.
"select"	Passes every element in the collection to a callback. Any elements for which the callback returns "true" (by setting a PIC X COMP-5 to value 1) are stored in a new subcollection.
"reject"	Passes every element in the collection to a callback. Any elements for which the callback returns "false" (by setting a PIC X COMP-5 to value 0) are stored in a new subcollection.
"collect"	Passes every element in the collection to a callback. The Callback returns an object (which can be the same or different to the original element). All the objects returned are collected into a new collection of the same type as the original collection.

Implement the interface for a callback method for "do" as follows:

 method-id. "doMethod".
 linkage section.
 01  lnkElement               object reference. 
 procedure division using lnkElement. 
* Any code to process the element. 
    exit program.
 end method "doMethod".

Implement the interface for a callback method for "select" as follows:

 method-id. "selectMethod".
 linkage section.
 01 lnkElement               object reference. 
 01 lnkselectResult          pic x comp-5.
  88  selectThisElement      value 1. 
  88  dontSelectElement      value 0. 
 procedure division using lnkElement returning lnkSelectResult. 
* Code to determine whether lnkElement should be included in the
* new subcollection. 
    exit method.
 end method "selectMethod".

Implement the interface for a callback method for "reject" as follows:

 method-id. "rejectMethod".
 linkage section.
 01 lnkElement               object reference. 
 01 lnkRejectResult          pic x comp-5.
  88 rejectThisElement       value 1. 
  88 dontRejectElement       value 0. 
 procedure division using lnkElement returning lnkRejectResult. 
* Code to determine whether lnkElement should be included in the
* new subcollection. 
    exit method.
 end method "rejectMethod".

Implement the interface for a callback method for "collect" as follows:

 method-id. "collectMethod".
 linkage section.
 01 lnkElement               object reference. 
 01 lnkReturnElement         object reference. 

 procedure division using lnkElement returning lnkReturnElement.
* Code to return an element for the new collection.
    exit method.
 end method "collectMethod".

Introduction to the Class Library

Intrinsic Data