Notes on RAAPI

Iterators

Iterators must always be freed after use. Every repository implementing RAAPI must ensure that iterators are thread-safe: when the repository is modified, the iterator still contains the original list of references. This can be implemented either by always creating a new list for iterable elements or by utilizing the copy-on-write pattern.

Example of using iterators

Iterator it = getIteratorFor...(...);
Reference r = resolveIteratorFirst(it);
while (r != 0) {
    // Process here reference r
    freeReference(r); // not required unless the underlying repository requires this
    r = resolveIteratorNext(it);
}
freeIterator(it);

Advanced associations

We use the term advanced association for n-ary associations, association-classes, and n-ary association-classes. All such associations are created via RAAPI function
createAdvancedAssociation(String name, boolean nAry, boolean associationClass)

An advanced association behaves likes a class (although it might not be a class internally) with n bidirectional associations attached to it. To specify all n association ends, call createAssociation n times, where a reference to the n-ary association has to be passed instead of one of the class references. N-ary association links can be created by means of createObject, and n-ary link ends can be created by calling createLink n times and passing a reference to the n-ary link instead of one of the object references.

Encoding values