From Harmoni

Often one needs to store a collection of ids so that the can be grouped together and maybe ordered. Sets provide a global service for creating, accessing, and modifying persistant, ordered, groups of ids.

Contents 1 Classes 1.1 Set 1.2 OrderedSet 1.3 SetManager 2 Usage 2.1 Accessing Sets 2.2 Persistent Sets

Classes

Set

The most basic of sets, the Set provides the following methods:

• hasNext() - True if there are more items in the Set.
• next() - Returns the next Item in the Set.
• reset() - Resets the internal pointer in the Set to the first Item.
• addItem($id) - Add an Id object to the Set.
• removeItem($id) - Remove the specified Id from the Set.
• remvoeAllItems() - Remove all Items from the Set.
• isInSet($id) - Returns TRUE if the specified Id is in the Set.
• count() - Return the number of items in the Set.

A Set is an iterator which can have items added and removed from it.

OrderedSet

In addition to the methods of the Set class, the OrderedSet provides the following methods:

• moveUp($id) - Move the specified Id toward the begining of the Set.
• moveDown($id) - Move the specified Id toward the end of the Set.
• moveToPosition($id, $position) - Move the specified Id to the specified position. (The first item is at position "0".)
• getPostion($id) - Get the position of the specified Id (The first item is at position "0".)

These allow the a persistent order to be maintained. When addItem() is called, the new Id is added to the end of the Set.

SetManager

The SetManager service provides a global way to access Sets as well as a place to cache created Set objects so that references can be passed out to each instead of re-instatiating them. As well, the SetManager stores the database index for the database in which the Sets are stored, so that this configuration does not need to be maintained by the application.

Usage

Accessing Sets

Sets can be thought of as always existing. They are not created and destroyed, but rather accessed when needed. Sets can either be "temporary", lasting for a given session; or they can be persistent, lasting across sessions.

All sets have an id. To access a set, request it from the SetManager:

$idManager = Services::getService("Id");
$myId = $idManager->getId('12345');

$setManager = Services::getService("Sets");
$mySet = $setManager->getTemporarySet($myId);

echo $mySet->count();

Persistent Sets

Persistent sets are accessed in the same way, but with the getPersistentSet($id) method:

$mySet = $setManager->getTemporarySet($myId);

A persistent Set requires no additional actions above a temporary Set; as items are added, removed, or reordered, those changes are stored by the implementation.

A temporary set can be re-cast as a persistent set by using the SetManager->persist($set) method. If A persistent Set of the same Id already exists, the new one will replace it.

$idManager = Services::getService("Id");
$myId = $idManager->getId('12345');

$setManager = Services::getService("Sets");
$myTempSet = $setManager->getTemporarySet($myId);

echo $myTempSet->count();
// 0;

$myPersistentSet = $setManager->persist($myTempSet);

echo $myPersistentSet->count();
// 0;

$myPersistentSet->addItem($idManager->getId('5432'));

echo $myTempSet->count();
// 0;
echo $myPersistentSet->count();
// 1;