• AS3Commons Collections Version 1.0.0
• Dpdk open source Revision 272
• Polygonal datastructures Version 1.04
  The ActionScript version of the polygonal data structures is not further developed and has been ported to the haXe language with the claim to be faster. However, some of the haXe structures did not support primitive values (Heap, BST), so I test here the last ActionScript version.

Note to the performance tests in this article

This article contains a number of performance test results. The tests have been executed using a small testing harness which can be found at the sibirjak google code page. The column header of the tables showing those results use the following abbreviations. The measured time is displayed in milliseconds.

Linked list

The performance of the A3Commons and Dpdk lists is nearly equal. Adding to the polygonal list takes twice the time than to the others.

AS3Commons LinkedList tests source code
Dpdk LinkedList tests source code
Polygonal DLinkedList tests source code

Map

The AS3Commons and polygonal maps use an internal Dictionary. The dpdk map instead implements a custom hash table (which is of course slower). The dpdk map only allows literal keys. The AS3Commons map consideres mixed typed primitive keys (1 != “1″) which the polygonal map treats as equal. The polygonal map stores its items additionally in a linked list to create an iterator in constant time. The other maps populate an array and return then an iterator over that array (linear time).

The Dictionary key type issue is described in the Dictionary discussion.

AS3Commons Map tests source code
Dpdk HashMap tests source code
Polygonal HashMap tests source code

Set

All sets are backed by a Dictionary instance. In difference to the others, the AS3Commons set distinguishes between numeric and literal keys of the same value (1 != “1″) wich makes it slightly slower.

The Dictionary key type issue is described in the Dictionary discussion.

AS3Commons Set tests source code
Dpdk Set tests source code
Polygonal Set tests source code

Binary search tree

The polygonal tree did throw errors when trying to remove items. The performance of removals could therefore not be tested.

The AS3Commons Treap is a randomised tree with a weak addiction to degenerate. Both other trees are neither randomised nor balanced. Adding already sorted data causes here the tree to make up a sequence where each node has only one child.

AS3Commons Treap tests source code
Dpdk BST tests source code
Polygonal BST tests source code

Priority queue

A priority queue provides fast access to the lowest (or highest) item. Dpdk and polygonal contain a arrayed heap implementation. A heap is probably the fastest way to solve the problem. Using an arrayed heap has to consider the time to shift all succeeding array elements when removing the first. The AS3Commons Treap is expensive in adding items but fast in removing (and has a better cumulative performance).

AS3Commons Treap tests source code
Dpdk PriorityQueue tests source code
Polygonal Heap tests source code

Sorted list

Both tested lists use an array with a binary search algorithm. However, the dpdk list applies a full sort after each insertion operation which is exeptional slow.

AS3Commons SortedList tests source code
Dpdk OrderedList tests source code

Table of contents

• Note to the performance tests in this article
• Definitions and overview
• Aspects of using data containers
• Array and Dictionary – features and weaknesses
• Common collections and their implementation
  • ArrayList, SortedList
  • Map, OrderedMap, SortedMap
  • Set, OrderedSet, SortedSet
  • LinkedList, Tree
• Summary

Note to the performance tests in this article

This article contains a number of performance test results. The tests have been executed using a small testing harness which can be found at the sibirjak google code page. The column header of the tables showing those results use the following abbreviations. The measured time is displayed in milliseconds.

Definitions and overview

Definitions

First of all a small definition of the term collection used in this article. A data container is meant any data structure that holds a number of distinctive objects in order to return at a later time. The built-in data containers in Flash are Array, Vector, Object and Dictionary. A collection is then furthermore a data container …

• with a generalised API that fully abstracts from the actual implementation
• and a high degree of reusablility (not narrowed to a special operation purpose).

Collections do not try to replace the built-in containers but aim to extend those with functionality and common algorithms. Many programming languages carry a collections framework in its core libraries. In ActionScript we unfortunately need to implement collections individually. This situation has brought us already a lot of approaches to establish an ActionScript collections framework.

Common reasons to use collections

Besides the availability of a convenient API, collections are preferred to add specific functionality, to gain reliability or to increase the performance of certain operations. Especially the latter might be confusing at the first glance. Indeed, all built-in containers have their specific implementation and therefore distinctive benefits and disadvantages.

This article shows how the choice of an appropiate collection may improve the runtime performance of ActionScript applications by providing interesting examples and performance test results. The article starts with a description of situations where we typically use containers to collect data and what the different requirements to such containers are. The second part examines the built-in Array and Dictionary and how they can fit the indentified requirements. The third (and last) part discusses several collections and common approaches to implement them.

Aspects of using data containers

Software applications may need to collect data for various reasons. Each of those reasons implies a preferred way how elements are stored, retrieved or removed from the data container. Different problem situations may be solved best using an adequate container or vice versa, there is no multipurpose container that fits all kinds of requirements. This chapter shows a random list of situations where we typically use data containers.

Embedded inventory

The most obvious use case of collecting data is to make up a (hard coded) inventory which serves as a data base in the class or even in the entire application. The data in the inventory should have a stable order and provide at least fast sequential access (from the first to the last item).

1
2
3
4
5
6
7
8

var users : Array = [
    new User("Mike", "Donner"),
    new User("Susi", "Sonnenschein")
];
 
for each (var user : User in users) {
    // do something
}

Proxy

A proxy is an internal representation (or a cache) of data stored elsewhere, e.g. on a remote server. The proxy should use the same ordering as the orginal repository. Since data between client and server is exchanged and identified using an object ID, we like to address (find, add, remove) items in the proxy by using IDs.

1
2
3
4
5
6
7

var users : Array = UserService.getUsers();
var user : User;
 
for each (var id : String in users) {
    user = UserService.getUser(id);
    // do something
}

Relations between objects

One-to-many relations can be expressed using a link table. The table do not need to have an order but should allow fast look up a relation by a given object.

1
2
3
4
5
6

var friends : Dictionary = new Dictionary();
...
friends[user1] = [user2, user4];
friends[user2] = [user1, user3];
...
var friends : Array = friends[user3];

Wrapper

Encapsulated components often store data in its own fashion by adding specific information to the given data objects using composition. To enable the user to operate the component with the orginal data, the component hosts an internal look-up table which maps objects to its wrappers.

1
2
3
4

loader.add("data.xml");
...
// decide not to load the data
loader.remove("data.xml");

Grouping objects

To return a group of objects from a method (or to pass to) we use a container. In the most of the cases the order of items returned is important.

1
2
3
4
5
6

function getVisits(session : String) : uint {
    var session : Session = AuthService.getSession(session);
    var user : User = UserService.getUser(session.userId);
    ...
    return [user.name, session.visitCount];
}

Temporary containers

Often we set up local containers temporarily to find duplicates, to count instances, to store items matching a certain criterion or to prepare a data structure before further processing it. Sometimes a plain array does the work, sometimes a look-up container such as Object or Dictionary. In a number of cases we need a combination of both to preserve the original order while achieving fast look-up.

1
2
3
4
5
6
7
8
9
10
11
12

var array : Array = [1, 3, 2, 1, 3, 1, 1, 4];
var map : Object = new Object();
var unique : Array = new Array();
 
for (var i : uint = 0; i < array.length; i++) {
    if (map[array[i]] === undefined) {
        unique.push(array[i]);
        map[array[i]] = true;
    }
}
 
trace (unique); // 1,3,2,4

More specific software problems

A queue is an ordered container where we want to add at end and to remove at start. In a stack we add and remove always “at end”. A searchable index maintains a sort order, and items shall be addressed instantly by instance. And so on.

1
2
3
4
5
6
7
8
9

queue.add("users.xml");
queue.add("products.xml");
queue.add("prices.xml");
...
var url : String = queue.poll(); // users.xml
// load
...
url = queue.poll(); // products.xml
// load

Binding data to user interfaces

Data driven user interface controls (List, SelectBox, DataGrid) often shall be updated automatically if the assigned data source changed. The data container then needs to dispatch change notifications.

Summary

The illustrated situations above show different and often mutually exclusive requirements to the desired data structure solution:

• The kind of order of the items (no order necessary, order by insertion, sort order).
• Sequential (for-loop, iterator) or random access (index, key, item by instance) to the items.
• High performance of adding and removing in front (or in between or at end) of a sequence of items.
• High performance of finding an element.
• Fast access to the lowest or highest element in a collection.
• Permission of multiple instances of an element (or not).
• Mapping of items by preserving a particular order of the entries.
• Enabling data binding by dispatching change notifications.

In the most of the situations we especially count only on a specific feature of a data container. This leads to the question if there are containers that fit the particular requirements better than others. The next chapter discusses how the Flash built-in data containers Array, Object and Dictionary might be used (or not) to solve common data handling problems.

Array and Dictionary – Features and Weaknesses

The Array

The Array is apparently the fastest possibility of storing elements sequentially. However, adding to (or removing from) an array requires the array to internally shift the position of all succeeding items by the number of elements added. This shifting is the more expensive the more the insertion occurred in front of the array and the longer the array is. Michael Baczynski (polygonal.de) has visulalised this behaviour in its linked list example.

Another consideration (and common trap) is the time required to find (or remove) an element within an array. Since the array is not a look-up container, the array needs to test each item for equality which is the more expensive the more longer the array is.

The table below shows the runtime of adding or removing at start or at end as well as the performance of the look-up operations has and remove.

Array tests source code

Keeping an array sorted

In many cases a container that maintains a sort order is desired. Such a container stores and returns its items always based on a sort critlerion. Applications could be a phone book, a high score list, a performant searchable index or a priority queue. A simple implementation would be to sort an array after each insertion operation. However, this approach does not scale as the following table shows.

Array tests source code

Another consideration regarding the sorted array. The built-in sort method does not preserve the formerly order of equal items. If it is important to sort equal items in the order they were inserted, the Array.sort() method cannot be used.

1
2
3
4
5

var array : Array = [1, 2, 3, 4, 5, 6, 7, 8, 9];
array.sort(function(item1 : *, item2 : *) : int {
    return 0; // all items are equal
});
trace (array); // 5,2,3,4,1,6,7,8,9

The Dictionary

The Dictionary is a look-up container where elements can be accessed instantly using a unique key. The Dictionary maintains no order of items and does not provide information about the number of elements contained. Operations based on keys perform in nearly constant time. Finding (or removing) of items is significantly slower than done with an array.

Dictionary tests source code

Another consideration of the Dictionary is its missing type safety. While everything is going well with complex keys, a primitive key is stored by its string representation rather than its original value as the following code example shows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

var dict : Dictionary = new Dictionary();
dict[1] = "one_int";
dict["1"] = "one_string";
dict[true] = "true_boolean";
 
trace (dict[1] !== undefined); // true
trace (dict["1"] !== undefined); // true
trace (dict[true] !== undefined); // true
trace (dict["true"] !== undefined); // true (!)
 
trace (getSize()); // 3 (!)
 
delete dict[1];
 
trace (dict[1] !== undefined); // false
trace (dict["1"] !== undefined); // false (!)
trace (dict[true] !== undefined); // true
trace (dict["true"] !== undefined); // true (!)
 
trace (getSize()); // 1 (!)
 
function getSize() : uint {
    var size : uint;
    for (var key : * in dict) {
        size++;
    }
    return size;
}

The missing type safety may cause serious errors or at least confusion. For example the algorithm to test if two arrays contain the same elements would not work reliably with an unmodified Dictionary. This algorithm populates a map with the number of occurrences of each element contained by both given arrays.

Dictionary used as a set

As shown, Array and Dictionary are basically slow in finding or removing items. Nevertheless, it is possible to assign the actual item (which we want to access instantly) in the key property of a Dictionary entry. All items then have to be unique.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var dict : Dictionary = new Dictionary();
dict[1] = true;
dict["1"] = true;
dict[2] = true;
 
trace (dict[1] !== undefined); // true
trace (dict["1"] !== undefined); // true
trace (dict[2] !== undefined); // true
trace (dict["2"] !== undefined); // true (!)
 
delete dict[1];
 
trace (dict[1] !== undefined); // false
trace (dict["1"] !== undefined); // false (!)

The features of such a set are the same as of the Dictionary: No order, no size information, no type safety … but a striking performance in locating objects :-).

Summary

The Flash containers are sufficiently for the most operations. Nevertheless, there are certain situations where performance, functionality and reliability leave something to be desired.

Performance

Adding or removing items in front of an array is a comparatively slow process. Thus, using an array as a queue is not the optimal solution, and a linked list performs much better (as we will see later in this article).

Finding items in an array or in a Dictionary instance requires linear time (the more elements the more time). As shown in the snippets above, we often want to find an item instantly. Fast item look-up can be achieved by using a Dictionary as a set.

Keeping an Array instance sorted calling its built-in sort after each insertion operation is a serious performance leak.

Functionality

The Dictionary does not reveal how many items it contains. Calculating such a size value can be done only with a loop over the entire contents which requires linear time.

The Dictionary does not provide any order of items. Fast key or item look-up (when used as a set) while maintaining a particular order is natively not possible. To anyhow obtain an ordered or sorted map (or set) we need to combine the Dictionary with an additional container that stores the item order.

Neither Array nor Dictionary support data binding. It is possible to wrap both containers to control all insertion or removal operations and dispatch reliable change notifications.

Reliability

The Array sort method is not stable which may cause confusion or even problems.

The Dictionary stores a primitive key always in its string representation. Different keys that have the same string representation are considered as identical (1 = “1″, true = “true”). Algorithms that rely on the Dictionary may fail if not considered.

Common collections and their implementation

Array wrapper (ArrayList)

An array wrapper is the most often encountered collection implementation. The most famous array wrapper is the Flex ArrayCollection. There are many reasons to create an ArrayList.

One goal is to control the way how items are added or removed. For example, it is possible to only permit inseration and removal at the end of an array which results then in a stack realisation.
Another goal is the simplification of the Array interface. For example arrayList.addAt(10, item) is fare more intuitive than array.splice(10, 0, item). By the way, who knows the difference between slice and splice without have an eye at the docs?
Often the array wrapper offers additional methods that easify the array handling (count, removeAll, lastIndexOf). The ArrayList might implement a stable sort that is used instead of the not stable built-in array sort.

1
2
3
4
5
6

var arrayList : ArrayListRaw = new ArrayListRaw();
arrayList.array = [1, 2, 3, 4, 5, 6, 7, 8, 9];
arrayList.sort(function(item1 : *, item2 : *) : int {
    return 0; // all items are equal
});
trace (arrayList.array); // 1,2,3,4,5,6,7,8,9

Basic array wrapper implementation in ActionScript
AS3Commons ArrayList usage example

Performance

The basic array wrapper has nearly the same runtime as an unwrapped array.

Basic array wrapper tests source code
Array tests source code

Linked list

A linked list is the most important alternative to an array to achieve a succession of elements. The list is made up of mutually linking nodes where a single node is a plain data object holding a reference to its successor, predecessor and the actual data added.

Adding or removing of items costs always the same (constant) time because only the links between two or three nodes have to be updated. However, the linked list does not support index access (addAt, getAt, removeAt). Finding elements in a linked list is as expensive as in an array (has, remove).

A linked list is the preferred solution to realise a queue interface. Several data structures utilise a linked list (rather than an array) to maintain element succession.

Basic linked list implementation in ActionScript
AS3Commons LinkedList usage example
Linked list at Wikipedia

Performance

As the table shows, the average performance of insertion or removal operations of a linked list is significantly better than of an array.

Basic linked list tests source code
Array tests source code

Map

The (basic) map is an unordered container enabling fast key look-ups. A typical map implementation uses an array to host the values and a hashing function to calculate from a given key the index position where the value should be added (or can be found). This is actually not trivial, and fortunately we have in ActionScript the Dictionary that hides all the implementation details and can be used to create a map collection.

The map extends the Dictionary to add an instant size information and to fix the problem of type unsafety (shown in the Dictionary example above). String typed keys are separately stored in an Object instance which lets decide if a given primitive key really exists.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var map : MapRaw = new MapRaw();
map.add(1, "one_int");
map.add("1", "one_string");
map.add(true, "true_boolean");
 
trace (map.hasKey(1)); // true
trace (map.hasKey("1")); // true
trace (map.hasKey(true)); // true
trace (map.hasKey("true")); // false (!)
 
trace (map.size); // 3 (!)
 
map.removeKey(1);
 
trace (map.hasKey(1)); // false
trace (map.hasKey("1")); // true (!)
trace (map.hasKey(true)); // true
trace (map.hasKey("true")); // false (!)
 
trace (map.size); // 2 (!)

Basic map implementation in ActionScript
AS3Commons Map usage example

Performance

The performance of the basic map is comparable to that of the Dictionary.

Basic map tests source code
Dictionary tests source code

Set

The set is in fact a map where only the keys are from interest. The set implementatin follows the same principles as the of the map: An Object is used to store the string typed keys, an instant size informatin is available.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var theSet : SetRaw = new SetRaw();
theSet.add(1);
theSet.add("1");
theSet.add(true);
 
trace (theSet.has(1)); // true
trace (theSet.has("1")); // true
trace (theSet.has(true)); // true
trace (theSet.has("true")); // false
 
trace (theSet.size); // 3
 
theSet.remove(1);
 
trace (theSet.has(1)); // false
trace (theSet.has("1")); // true
trace (theSet.has(true)); // true
trace (theSet.has("true")); // false
 
trace (theSet.size); // 2

Basic set implementation in ActionScript
AS3Commons Set usage example

Performance

The look-up operations has and remove operate in nearly constant time.

Basic set tests source code
Array tests source code

Sorted array

To get an array to keep a certain sort order it is the most performant solution to add items using the binary search algorithm. The search returns the index position where a given item should be added. Finding an element within the sorted array also uses a binary search.

AS3Commons SortedList implementation
AS3Commons SortedList usage example
Binary search algorithm at Wikipedia

Performance

The AS3Commons SortedList is an application of a sorted array and used here in the performance tests. Adding items to an array using the binary search algorithm (as the SortedList does) is significantly faster than adding items combined with a subsequent sort.

Adding items to a sorted array is slower than appending items to an unsorted array. Finding or removing elements is faster done with a sorted array.

AS3Commons SortedList tests source code
Array tests source code

Binary search tree

A binary search tree is the composite counterpart to a sorted array. The tree is made up of nodes where a single node is a plain data object holding a reference to its parent node, its left and right child and the actual data added. The value of the left child is always lesser, the value of the right child always greater than the value of a parent node.

Finding an element in a tree starts with the root node and continues with the left child node if the given value is lesser and with the right node if the given value is greater than the value of the parent node.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

function findNode(item : *) : Node {
    var node : Node = _root;
 
    while (node) {
        if (item < node.item) {
            node = node.left;
        } else if (item > node.item) {
            node = node.right;
        } else {
            return node;
        }
    }
 
    return null;
}

A binary search tree is used (like a sorted array) to achieve a persistant sort order in that finding of elements is comparable fast. The tree might be used as a priority queue where items are stored and returned depending on a given priority. The tree also may be used in combination with other structures to realise a sorted collection such as a sorted map or a sorted set.

The weakness of a binary search tree is its addiction to degenerate. In the worst case the tree consists of only left nodes or only right nodes. Finding elements in a degenerated tree may cost linear time since each node has to be compared. There are several tree implementations that deal with the problem. A treap is one of them.

AS3Commons Treap implementation
AS3Commons Treap usage example
Binary search tree at Wikipedia

Performance

The performance test uses the AS3Commons Treap and SortedList collections. It reveals, the binary search tree is not actually faster than a sorted array. However the sorted array suffers from the bad performance of (adding and) removing items in front of an array in general where the tree operations take the same time at all positions.

AS3Commons Treap tests source code
AS3Commons SortedList tests source code

Ordered map

A basic map does not have any succession order but this order may be realised by combining a map with a linked list where the map internally links a given key with a linked list node.

Basic ordered map implementation in ActionScript
AS3Commons LinkedMap usage example

Performance

For order related operations, the ordered map requires about the addition of time of a basic map and a linked list. For example removing at start takes 39ms which is the time needed to remove at start from a linked list (2ms) plus the time needed to remove a key from the map (37ms).

Basic ordered map tests source code
Basic map tests source code
Basic linked list tests source code

Ordered set

A basic set does not have any succession order but this order may be realised by combining a set with a linked list where the set internally links a given item with a linked list node.

Basic ordered set implementation in ActionScript
AS3Commons LinkedSet usage example

Performance

For order related operations, the ordered set requires about the addition of time of a basic set and a linked list. For example removing at start takes 39ms which is the time needed to remove at start from a linked list (1ms) plus the time needed to remove an item from the set (37ms).

While the Array slows down, finding or removing of items is done as fast it can be with an ordered set.

Basic ordered set tests source code
Basic set tests source code
Basic linked list tests source code
Array tests source code

Sorted map

A basic map does not have any succession order. A sort order may be realised by combining a map with a binary search tree where the map internally links a given key with a tree node.

AS3Commons SortedMap implementation
AS3Commons SortedMap usage example

Performance

The performance test uses the AS3Commons SortedMap, Map and Treap implementations. For order related operations, the sorted map requires about the addition of time of a basic map and a treap.

AS3Commons SortedMap tests source code
AS3Commons Map tests source code
AS3Commons Treap tests source code

Sorted set

A basic set does not have any succession order. A sort order may be realised by combining a set with a binary search tree where the set internally links a given item with a tree node.

The difference between a sorted set and a binary search tree is the performance of item based operations. While the tree needs to find a related node within its structure, the sorted set uses an internal Dictionary to instantly access this node.

AS3Commons SortedSet implementation
AS3Commons SortedSet usage example

Performance

The performance test uses the AS3Commons SortedSet, Set, Treap and SortedList implementations. For item based operations the set is significantly faster than the treap. For all other operations, the sorted set requires about the addition of time of a basic set and a treap.

Item based look-up operations (has, remove) are faster in a sorted set than in a sorted array. Removing of items from the sorted array has to take in account the time to shift the internal array indices. Here the sorted set has a far better average performance.

AS3Commons SortedSet tests source code
AS3Commons Set tests source code
AS3Commons Treap tests source code
AS3Commons SortedList tests source code

Summary

There is more than just arrays

Array and Dictionary are not the only possibilities to realise data containers in ActionScript. Choosing an alternative to Array and Dictionary is often valuable for the reasons of performance, functionality and reliability.

This article has shown several examples where the the built-in containers do not suffice and what implementations can better solve specific problems. An array wrapper might be used to control the array access and to add functionality, the linked list has a better performance of insertion and removal operations than an array, sorted list or binary search tree are very fast containers to maintain a persistent sort order, a custom map can fix an unsatisfying behaviour of the Dictionary and add introspection, the different set implementations provide fast access by instance, the ordered map saves the insertion order while elements containted by a sorted map are kept in a sort order.

Decide reasonable

All introduced collections have specific benefits and disadvantages. It depends on the special software problem what data container fits the best. Usually we need only a small and specific subset of the entire functionality of a data container. It is worthy to spend some time to analyse the problem and depending on that to choose an appropriate container. The following list suggest a few questions that may be asked.

• Is any succession of elements required?
  • Could a sorted structure be more performant?
• Is random access required (index, key, item by instance)?
  • Yes: What access type could be the best?
  • No: Are there lot of reads and writes in between a sequential container?
• Are duplicates permitted?

AS3Commons collaboration project

While in other languages the use of collections is highly popular, it isn’t in ActionScript. The reason might be a missing standard library. However, the algorithms used to implement collections are general, and the different ActionScript solutions we can find in the web are pretty similiar. Leads to the question, why we still do not have a unified collections framework in ActionScript :-)

The AS3Commons project is a (yes, again another!) community approach to create a repository of reusable ActionScript components. I have contributed to the collections library there. If you have any feedback, you are welcome. Thank you.

AS3Commons collaboration project
AS3Commons Collections homepage

Table of contents

• Quick overview
• Examples
• Differences to the Lite Collections Fx
• Getting started
• Resources

Quick Overview

The framework currently contains 10 collections of wich 8 are available as well in a bindable (event dispatching) version. A bindable collection broadcasts change notifications after any modification of its content (add, remove, reorder, empty).

The collections can be classified by their access type (list = index, set = instance, map = key), by their order (unorderd, insertion order, sort order), by their permission of multiple entries of a single instance or by their realisation.

Each collection is equipped with a feature rich iterator that enables bidirectional navigation and insertion, replacement or removal within the iteration loop. The library further includes 5 special iterators:

• ArrayIterator
• CollectionFilterIterator
• FilterIterator
• RecursiveIterator
• RecursiveFilterIterator

Note, all collections, iterators and interfaces are detailed described in the APIDoc.

Examples

The APIDoc consists of a large number of examples of all collections (bindable or not bindable). All those examples are also committed to the SVN repository and can be found here: Browse examples.

SortedList example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

package {
    import org.as3commons.collections.SortedList;
    import org.as3commons.collections.framework.ICollectionIterator;
    import org.as3commons.collections.framework.IIterator;
    import org.as3commons.collections.framework.IListIterator;
    import org.as3commons.collections.utils.StringComparator;
    import flash.display.Sprite;
 
    public class SortedListExample extends Sprite {
 
        public function SortedListExample() {
            var list : SortedList = new SortedList(new StringComparator());
 
            // Add
 
            list.add("d");
            list.add("a");
            list.add("a");
            list.add("f");
            list.add("c");
            list.add("b");
            list.add("a");
            list.add("c");
            trace (list.toArray()); // a,a,a,b,c,c,d,f
 
            list.array = ["d", "a", "a", "f", "c", "b", "a", "c"];
            trace (list.toArray()); // a,a,a,b,c,c,d,f
 
            // Inspection
 
            trace (list.first); // a
            trace (list.last); // f
 
            trace (list.hasEqual("a")); // true
            trace (list.hasEqual("e")); // false
            trace (list.equalIndices("a")); // 0,1,2
 
            trace (list.lesserIndex("a")); // -1
            trace (list.lesserIndex("c")); // 3
 
            trace (list.higherIndex("c")); // 6
            trace (list.higherIndex("f")); // -1
            trace (list.higherIndex("x")); // -1
 
            // Iterator
 
            var iterator : IIterator = list.iterator();
            trace (iterator is IIterator); // true
            trace (iterator is ICollectionIterator); // true
            trace (iterator is IListIterator); // true
 
            while (iterator.hasNext()) {
                trace (iterator.next()); // a,a,a,b,c,c,d,f
            }
        }
    }
}

Filter iterator example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

package {
    import org.as3commons.collections.ArrayList;
    import org.as3commons.collections.framework.IIterator;
    import org.as3commons.collections.iterators.FilterIterator;
    import flash.display.Sprite;
 
    public class FilterIteratorExample extends Sprite {
 
        public function FilterIteratorExample() {
            var list : ArrayList = new ArrayList();
            var iterator : IIterator;
 
            list.array = [1, 2, 3, 4, 5, 6];
            iterator = new FilterIterator(list, evenFilter);
            while (iterator.hasNext()) {
                trace (iterator.next()); // 2, 4, 6
            }
        }
 
        private function evenFilter(item : *) : Boolean {
            // lets pass only even numbers
            return item % 2 == 0;
        }
    }
}

Bindable LinkedSet example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

package {
    import org.as3commons.collections.framework.ISetIterator;
    import org.as3commons.collections.fx.LinkedSetFx;
    import org.as3commons.collections.fx.events.CollectionEvent;
    import org.as3commons.collections.fx.events.SetEvent;
    import org.as3commons.collections.utils.NumericComparator;
    import flash.display.Sprite;
 
    public class LinkedSetFxExample extends Sprite {
 
        public function LinkedSetFxExample() {
            var theSet : LinkedSetFx = new LinkedSetFx();
            theSet.addEventListener(CollectionEvent.COLLECTION_CHANGED, changedHandler);
 
            theSet.add(1);
            theSet.add(3);
            theSet.add(2);
            theSet.add(2); // no event (2 already contained)
 
            theSet.addFirst(4);
            theSet.addLast(5);
 
            theSet.addBefore(2, 6);
            theSet.addAfter(2, 7);
 
            theSet.replace(3, 8);
            theSet.replace(1, 9);
 
            theSet.removeFirst();
            theSet.removeLast();
            theSet.remove(8);
            theSet.remove(6);
            theSet.remove(10); // no event (10 not contained)
 
            theSet.reverse();
            theSet.sort(new NumericComparator());
 
            theSet.clear();
 
            // [1] added                         [1]
            // [3] added after 1                 [1 3]
            // [2] added after 3                 [1 3 2]
            // [4] added before 1                [4 1 3 2]
            // [5] added after 2                 [4 1 3 2 5]
            // [6] added after 3 before 2        [4 1 3 6 2 5]
            // [7] added after 2 before 5        [4 1 3 6 2 7 5]
            // [8] replaced after 1 before 6     [4 1 8 6 2 7 5]
            // [9] replaced after 4 before 8     [4 9 8 6 2 7 5]
            // [4] removed before 9              [9 8 6 2 7 5]
            // [5] removed after 7               [9 8 6 2 7]
            // [8] removed after 9 before 6      [9 6 2 7]
            // [6] removed after 9 before 2      [9 2 7]
            // Reset                             [7 2 9]
            // Reset                             [2 7 9]
            // Reset                             []
        }
 
        private function changedHandler(e : SetEvent) : void {
            var info : String = "";
            var iterator : ISetIterator;
 
            switch (e.kind) {
                case CollectionEvent.ITEM_ADDED:
                    info += "[" + e.item + "] added";
 
                    iterator = e.iterator() as ISetIterator;
                    if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
                    iterator.next();
                    if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
                    break;
 
                case CollectionEvent.ITEM_REMOVED:
                    info += "[" + e.item + "] removed";
 
                    iterator = e.iterator() as ISetIterator;
                    if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
                    if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
                    break;
 
                case CollectionEvent.ITEM_REPLACED:
                    info += "[" + e.item + "] replaced";
 
                    iterator = e.iterator() as ISetIterator;
                    if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
                    iterator.next();
                    if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
                    break;
 
                case CollectionEvent.RESET:
                    info += ("Reset");
                    break;
            }
 
            for (var i : uint = info.length; i < 34; i++) info += " ";
            info += "[" + e.set.toArray().join(" ") + "]";
            trace (info);
        }
    }
}

Differences to the Lite Collections Fx

Architectural changes

A list is now considered as a collection that provides (constant time) index access to its items. Therefore the LinkedList does not implement the IList interface any longer.

List, sets and maps are now considered as “random access collections” – providing a unique accessor to their items (index, item by instance, key). Therefore all lists, sets and maps have now a bindable version.

Performance increasement

The performance has been increased by a factor of 2 to 4 (partially even up to 20). A performance testing harness and all testing results will be released in the next time.

Iterator concept improvements

The iterators now have the ability to add or remove items during the iteration. The pointers (special iterators for linked collections) of the Lite Collections have been removed.

More concisely method names

All xxxItem() methods have lost their “item”. getItemAt() is now itemAt(), getFirstItem() is now simply first and so on.

Documentation

The APIDoc has been largely extended and contains all information that is necessary to work with the collections.

Getting started

There is not much to get the collections running.

1. Download SWC, ZIP or checkout the SVN branch.
2. Link or copy the sources into your project.
3. Import the collection classes and write code.
4. Examples.

Resources

• Project homepage
• Examples
• APIDoc
• Download and SVN repository
• Bug tracker

• TreeView demo application
• Setting up the data
• Creating a label function
• Using the public interface
• Styling the TreeView
• Setting custom icons

TreeView demo application

Click the image below for an interactive interface demo of the TreeView control. The demo lets you change data, styles and functionality of the component and provides information about the events dispatched and styles set.

If the popup does not do well, click here.

Setting up the data

The TreeView can work with any kind of hierachical data. There is no restriction in the type of the particular data source items. Its also possible to mix different types in one data source. The TreeView only needs to know for each item, how many children it contains (numItems) and how to get a child item at a specific index (getItemAt). There are three ways to provide this information.

1. Using a supported data source type without any preperation.
2. Implementing the IDataProvider interface in all item classes, if you are free in designing the data source.
3. Setting up a data source adapter, if you want to use a given (closed) object as the data source of the tree.

Using a supported data source

The TreeView already comes with support for a few types, from that it automatically extracts the numItems and getItemAt information.

• XML
• Array
• All maps, sets and the ArrayList from the AS3Commons Collections package

Look at the DataSourceAdapterFactory.as and see, how the TreeView handles the different item types. The example below shows an XML acting as the data source of the TreeView.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
 
    public class TreeViewExample extends Example {
        public function TreeViewExample() {
            var treeView : TreeView = new TreeView();
 
            treeView.dataSource = new XML(
                <item name="Root">
                    <item name="Node_1">
                        <item name="Node_1_1" />
                        <item name="Node_1_2" />
                    </item>
                    <item name="Node_2" />
                </item>
            );
 
            addChild(treeView);
        }
    }
}

Implementing the data provider interface

The two requirements above are modelled in a very small IDataProvider interface.

1
2
3
4
5
6

package com.sibirjak.asdpc.core.dataprovider {
    public interface IDataProvider {
        function getItemAt(index : uint) : *;
        function get numItems() : uint;
    }
}

Building a complex data source by implementing this interface is easy and may look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
 
    public class SimpleDataProviderExample extends Example {
        public function SimpleDataProviderExample() {
            var dataSource : Node = new Node("Root");
 
            var node_1 : Node = new Node("Node_1");
            node_1.addNode(new Node("Node_1_1"));
            node_1.addNode(new Node("Node_1_2"));
            dataSource.addNode(node_1);
 
            dataSource.addNode(new Node("Node_2"));
 
            var treeView : TreeView = new TreeView();
            treeView.dataSource = dataSource;
            addChild(treeView);
        }
    }
}
 
import com.sibirjak.asdpc.core.dataprovider.IDataProvider;
 
internal class Node implements IDataProvider {
    private var _name : String;
    private var _childNodes : Array = new Array();
 
    public function Node(name : String) {
        _name = name;
    }
 
    public function addNode(node : Node) : void {
        _childNodes.push(node);
    }
 
    public function getItemAt(index : uint) : * {
        return _childNodes[index];
    }
 
    public function get numItems() : uint {
        return _childNodes.length;
    }
 
    public function get name() : String {
        return _name;
    }
}

Creating a data source adapter

If the data source cannot implement the IDataProvider interace, it is necessary to write a custom data source adapter by implementing the IDataSourceAdapter interface. The adapter accepts an item from the original data source and knows how to retrieve numItems and getItemAt information from this item.

1
2
3
4
5
6

package com.sibirjak.asdpc.core.dataprovider {
    public interface IDataSourceAdapter extends IDataProvider {
        function get dataSource() : *;
        function cleanUp() : void;
    }
}

Creating a custom data source adapter is a two-step procedure.

1. Creating the adapter
2. Creating a data source adapter factory function

Creating an adapter is as simple as it could be. Let’s assume our data source item is a Node object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

internal class Node {
    private var _name : String;
    private var _childNodes : Array = new Array();
 
    public function Node(name : String) {
        _name = name;
    }
 
    public function addNode(node : Node) : void {
        _childNodes.push(node);
    }
 
    public function get name() : String {
        return _name;
    }
 
    public function get childNodes() : Array {
        return _childNodes;
    }
}

The data source adapter then will look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import com.sibirjak.asdpc.core.dataprovider.IDataSourceAdapter;
 
internal class NodeAdapter implements IDataSourceAdapter {
    private var _node : Node;
 
    public function NodeAdapter(node : Node) {
        _node = node;
    }
 
    public function get dataSource() : * {
        return _node;
    }
 
    public function getItemAt(index : uint) : * {
        return _node.childNodes[index];
    }
 
    public function get numItems() : uint {
        return _node.childNodes.length;
    }
 
    public function cleanUp() : void {
        // empty
    }
}

We now have to tell the TreeView that it should use the NodeAdapter if it encounters a Node object. To do so, we write da data source adapter function.

1
2
3
4

private function getAdapter(item : *) : IDataProvider {
    if (item is Node) return new NodeAdapter(item);
    return null;
}

Finally, we assign this function to the appropriate TreeView property.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.core.dataprovider.IDataProvider;
 
    public class SimpleDataSourceAdapterExample extends Example {
        public function SimpleDataSourceAdapterExample() {
            var dataSource : Node = new Node("Root");
 
            var node_1 : Node = new Node("Node_1");
            node_1.addNode(new Node("Node_1_1"));
            node_1.addNode(new Node("Node_1_2"));
            dataSource.addNode(node_1);
 
            dataSource.addNode(new Node("Node_2"));
 
            var treeView : TreeView = new TreeView();
            treeView.dataSource = dataSource;
            treeView.dataSourceAdapterFunction = getAdapter;
            addChild(treeView);
        }
 
        private function getAdapter(item : *) : IDataProvider {
            if (item is Node) return new NodeAdapter(item);
            return null;
        }
    }
}

Example: Visualising the display List

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.core.dataprovider.IDataProvider;
    import flash.display.DisplayObjectContainer;
 
    public class DisplayListExample extends Example {
        public function DisplayListExample() {
            var treeView : TreeView = new TreeView();
            treeView.setSize(440, 360);
            treeView.dataSource = stage;
            treeView.dataSourceAdapterFunction = getAdapter;
            treeView.expandNodeAt(0);
            addChild(treeView);
        }
 
        private function getAdapter(item : *) : IDataProvider {
             if (item is DisplayObjectContainer) {
                 return new DOCAdapter(item);
             }
             return null;
        }
    }
}
 
import com.sibirjak.asdpc.core.dataprovider.IDataSourceAdapter;
import flash.display.DisplayObjectContainer;
 
internal class DOCAdapter implements IDataSourceAdapter {
    private var _view : DisplayObjectContainer;
 
    public function DOCAdapter(view : DisplayObjectContainer) {
        _view = view;
    }
 
    public function get dataSource() : * {
        return _view;
    }
 
    public function getItemAt(index : uint) : * {
        return _view.getChildAt(index);
    }
 
    public function get numItems() : uint {
        return _view.numChildren;
    }
 
    public function cleanUp() : void {
        // empty
    }
}

Creating a label function

By default, the TreeView looks for the public properties “label” or “name” to extract a suitable label text, that can be displayed. Look at the genericToStringFunction.as and see, how the TreeView extracts the label text from an item. However, in some cases such a property does not exist or a different than the default value should be displayed. Here it is possible to assign a label function, wich is used instead of the generic toString function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.listview.renderer.ListItemContent;
 
    public class LabelFunctionExample extends Example {
        public function LabelFunctionExample() {
 
            var dataSource : Node = new Node("Root");
 
            var node_1 : Node = new Node("Node_1");
            node_1.addNode(new Node("Node_1_1"));
            node_1.addNode(new Node("Node_1_2"));
            dataSource.addNode(node_1);
 
            dataSource.addNode(new Node("Node_2"));
 
            var treeView : TreeView = new TreeView();
            treeView.dataSource = dataSource;
            treeView.setStyle(
                ListItemContent.style.labelFunction, labelFunction
            );
            addChild(treeView);
        }
 
        private function labelFunction(data : TreeNodeData) : String {
            return Node(data.item).key;
        }
    }
}
 
import com.sibirjak.asdpc.core.dataprovider.IDataProvider;
 
internal class Node implements IDataProvider{
    public var key : String;
    public var childNodes : Array = new Array();
 
    public function Node(theKey : String) {
        key = theKey;
    }
 
    public function addNode(node : Node) : void {
        childNodes.push(node);
    }
 
    public function getItemAt(index : uint) : *{
        return childNodes[index];
    }
 
    public function get numItems() : uint{
        return childNodes.length;
    }
}

The label function is set as a style with the constant “ListItemContent.style.labelFunction” used as the property name. All styles properties within the ASDPC have their particular constant. This can be useful, if your IDE supports property completion. The style “labelFunction” is defined for the class ListItemContent, which finally renders the item. More to this in the Styling the TreeView section.

Using the public interface

The public interface of the TreeView control extends the ListView control interface and offers expand/collapse, selection and scroll operations beside the possibilities to set and retrieve data information. Visit the APIdoc for a comprehensive description of the TreeView interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
 
    public class PublicInterfaceExample extends Example {
        public function PublicInterfaceExample() {
 
            // Fully expanded
 
            var treeView : TreeView = new TreeView();
            treeView.setSize(200, 200);
            treeView.dataSource = getDataSource();
            treeView.expandNodeAt(0, true);
            addChild(treeView);
 
            // Expanded and selected
 
            treeView = new TreeView();
            treeView.setSize(200, 80);
            treeView.dataSource = getDataSource();
            treeView.expandNodeAt(0);
            treeView.selectItemAt(1);
            treeView.moveTo(210, 0);
            addChild(treeView);
 
            // Fully expanded and scrolled
 
            treeView = new TreeView();
            treeView.setSize(200, 100);
            treeView.dataSource = getDataSource();
            treeView.expandNodeAt(0, true);
            treeView.scrollToItemAt(2);
            treeView.moveTo(210, 100);
            addChild(treeView);
        }
 
        private function getDataSource() : * {
            return new XML(
                <item name="Root">
                    <item name="Node_1">
                        <item name="Node_1_1" />
                        <item name="Node_1_2">
                            <item name="Node_1_2_1" />
                            <item name="Node_1_2_2" />
                        </item>
                        <item name="Node_1_3" />
                    </item>
                    <item name="Node_2">
                        <item name="Node_2_1" />
                        <item name="Node_2_2" />
                    </item>
                </item>
            );
        }
    }
}

Styling the TreeView

The TreeView (as with all ASDPC controls) can be extensively customised in functionality and appearance using styles. Most of the styles can be set or reset at runtime, wich means after the control has been added to the stage the first time.

Style management

The ASDPC style management is pretty easy to understand. Styles can be set directly to an object that defines that styles:

treeView.setSyle(TreeView.style.showRoot, false);
scrollBar.setSyle(ScrollBar.style.scrollButtonVisibility, false);

In composite structures (such as all controls are) you may set a sub component style also to the containing object:

treeView.setSyle(ScrollBar.style.scrollButtonVisibility, false);
treeView.setSyle(TreeNodeRenderer.style.indent, 24);

To work with styles it is then necessary to know:

• The structure of the control that should by styled
• The style properties of the control and of all its sub components

TreeView structure

The structure of a TreeView and all available styles are visualised in the info window of the demo application. Here again a short list of all sub components of a TreeView. Please refer to the APIDoc and to the source code to get informed about the particular styling possibilies of each sub component.

TreeView
    TreeNodeRenderer
        ListItemBackgroundSkin
        ConnectorContainer
            Connector
                DottedConnectorSkin
        ListItemContent
            Label
        DirectoryIcon
        DisclosureButton
 
    ScrollBar
        Button
            ButtonSkin
            ScrollButtonIconSkin
        Track
            ScrollTrackSkin
        Thumb
            ButtonSkin
            ScrollThumbIconSkin

Style property definitions

Styles in the ASDPC library are always defined in the class, that use the style. The label font size is defined by the Label class. The button background color is defined by the ButtonSkin class, and the color of the scroll button triangle icon is defined by the ScrollButtonIconSkin class.

By convention, a style property name includes the name of the class, which it defines. E.g. the style property name for the visibility of the root node of the TreeView is “treeView_showRoot”. You do not know those constant values, since all style properties are available as ActionScript constants. The constant for the root node visibility is simply TreeView.style.showRoot. Style property constants are either defined in a separate style object or directly to the class, that use the style. Examples:

• Label color: Label.style.color
• List item height: ListView.style.itemSize
• Scroll button visibility: ScrollBar.style.scrollButtonVisibility
• Button background colors: ButtonSkin.style_backgroundColors
• Tooltip border color: ToolTipSkin.style_borderColor

Styling example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.core.constants.Visibility;
    import com.sibirjak.asdpc.scrollbar.ScrollBar;
    import com.sibirjak.asdpc.treeview.renderer.ConnectorContainer;
    import com.sibirjak.asdpc.treeview.renderer.DisclosureButton;
    import com.sibirjak.asdpc.treeview.renderer.TreeNodeRenderer;
    import com.sibirjak.asdpc.treeview.renderer.skins.DisclosureButtonBoxIconSkin;
 
    /**
     * @author jes 04.02.2010
     */
    public class StylingExample extends Example {
        public function StylingExample() {
            var treeView : TreeView = new TreeView();
            treeView.setSize(260, 125);
            treeView.expandNodeAt(0);
 
            treeView.dataSource = new XML(
                <item name="Root">
                    <item name="Node_1">
                        <item name="Node_1_1" />
                        <item name="Node_1_2" />
                        <item name="Node_1_3" />
                    </item>
                    <item name="Node_2" />
                </item>
            );
 
            treeView.setStyles([
                // item size
                TreeView.style.itemSize, 25,
 
                // scrollbar and button visibility
                TreeView.style.scrollBarVisibility, Visibility.VISIBLE,
                ScrollBar.style.scrollButtonVisibility, Visibility.VISIBLE,
 
                // box shaped disclosure button
                DisclosureButton.style_expandedIconSkin, DisclosureButtonBoxIconSkin,
                DisclosureButton.style_collapsedIconSkin, DisclosureButtonBoxIconSkin,
                DisclosureButton.style_size, 9,
                DisclosureButtonBoxIconSkin.style_fillColor, 0x000000,
                DisclosureButtonBoxIconSkin.style_iconColor, 0xFFFFFF,
 
                // connectors below button and icon
                ConnectorContainer.style_connectorAtButton, true,
                ConnectorContainer.style_connectorAtIcon, true,
 
                // list item indent
                TreeNodeRenderer.style.indent, 26,
 
                // list item colors
                TreeNodeRenderer.style.separator, true,
                TreeNodeRenderer.style.separatorColor, 0xDDDDDD,
                TreeNodeRenderer.style.evenIndexBackgroundColors, [0xFFFFFF, 0xEEEEEE],
                TreeNodeRenderer.style.oddIndexBackgroundColors, [0xFFFFFF, 0xEEEEEE],
                TreeNodeRenderer.style.overBackgroundColors, [0xDDDDDD, 0xBBBBBB],
                TreeNodeRenderer.style.selectedBackgroundColors, [0x666666, 0x999999],
            ]); 
 
            addChild(treeView);
        }
    }
}

Setting custom icons

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

package com.sibirjak.asdpc.treeview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.treeview.renderer.DirectoryIcon;
    import com.sibirjak.asdpc.treeview.renderer.DisclosureButton;
 
    public class DynamicIconExample extends Example {
 
        [Embed(source="assets/plus.png")]
        private var _plus : Class;
        [Embed(source="assets/minus.png")]
        private var _minus : Class;
 
        [Embed(source="assets/document.png")]
        private var _document : Class;
        [Embed(source="assets/folder.png")]
        private var _folder : Class;
        [Embed(source="assets/folder_open.png")]
        private var _folder_open : Class;
 
        [Embed(source="assets/as.png")]
        private var _as : Class;
        [Embed(source="assets/html.png")]
        private var _html : Class;
        [Embed(source="assets/php.png")]
        private var _php : Class;
        [Embed(source="assets/pdf.png")]
        private var _pdf : Class;
        [Embed(source="assets/htdocs.png")]
        private var _htdocs : Class;
        [Embed(source="assets/htdocs_open.png")]
        private var _htdocs_open : Class;
 
        public function DynamicIconExample() {
 
            var treeView : TreeView = new TreeView();
 
            treeView.dataSource = new XML(
                <folder name="C:\\">
                    <folder name="documents">
                        <file name="serialz.txt" />
                        <file name="asdoc.pdf" />
                        <file name="images.zip" />
                    </folder>
                    <folder name="htdocs">
                        <file name="index.php" />
                        <file name="contact.html" />
                        <file name="popup.html" />
                    </folder>
                    <file name="manual.pdf" />
                    <file name="asdpc.exe" />
                </folder>
            );
 
            // disclosure buttons
 
            treeView.setStyles([
                DisclosureButton.style_collapsedIconSkin, _plus,
                DisclosureButton.style_expandedIconSkin, _minus,
                DisclosureButton.style_size, 16]);
 
            // default icons
 
            treeView.setStyles([
                DirectoryIcon.style.branchClosedIconSkin, _folder,
                DirectoryIcon.style.branchOpenIconSkin, _folder_open,
                DirectoryIcon.style.leafIconSkin, _document
            ]);
 
            // dynamic icons
 
            var iconFunction : Function = function (data : TreeNodeData) : Class {
                var label : String = XML(data.item).attribute("name");
 
                if (label.indexOf(".as") > -1) return _as;
                else if (label.indexOf(".php") > -1) return _php;
                else if (label.indexOf(".pdf") > -1) return _pdf;
                else if (label.indexOf(".html") > -1) return _html;
                else if (label.indexOf("htdocs") > -1) {
                    if (data.isExpanded) return _htdocs_open;
                    return _htdocs;
                }
                return null; // else use default icon
            };
 
            treeView.setStyle(DirectoryIcon.style.iconSkinFunction, iconFunction);
            treeView.expandNodeAt(0);
            addChild(treeView);
        }
    }
}

I started the development of the libray a few months ago with a TreeView component, I wanted to make fully customizable. Soon it turned out, that the tree required additional elements (list, scrollbar, button, label), which I created with similiar perfection. Primarily for the use in my examples, I later added a couple of nifty general purpose components such as a color picker, a combo box or a popup window. Now I am in possession of a sophisticated UI framework, that I am going to share here.

Note, this blog article is supposed to be updated, complemented or corrected in the future.

Table of contents

• Definition and Placement
• Examples
• Objectives
• Quick overview
• Getting started
• Resources

Definition and placement

The ASDPC library consists of a set of standard user interface controls applicable to any project without any architectural requirement. The library is targeted to simplify the development of control and from based ActionScript applications.

Using the ASDPCs does not require special knowledge or technical preparation. The controls can be used in both commercial or non-commercial projects. Hence, the software is placed under an open source software licence. There is a google code account containing the most recent sources and encouraging your contribution.

Examples

In a nutshell

Button example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package com.sibirjak.asdpc.overview {
    import com.sibirjak.asdpc.button.Button;
    import com.sibirjak.asdpc.button.ButtonEvent;
    import com.sibirjak.asdpc.common.Example;
 
    public class ButtonExample extends Example {
        private var _count : uint;
 
        public function ButtonExample() {
            var button : Button = new Button();
            button.setSize(80, 24);
            button.label = "Click: " + _count;
            button.addEventListener(ButtonEvent.CLICK, buttonClickHandler);
            addChild(button);
        }
 
        private function buttonClickHandler(event : ButtonEvent) : void {
            Button(event.target).label = "Click: " + ++_count;
        }
    }
}

ListView example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

package com.sibirjak.asdpc.overview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.listview.ListItemEvent;
    import com.sibirjak.asdpc.listview.ListView;
    import com.sibirjak.asdpc.textfield.Label;
 
    public class ListViewExample extends Example {
        private var _label : Label;
 
        public function ListViewExample() {
            var listView : ListView = new ListView();
            listView.setSize(160, 120);
            listView.dataSource = [
                "Item1", "Item2", "Item3", "Item4",
                "Item5", "Item6", "Item7", "Item8",
                "Item9", "Item10"
            ];
            listView.addEventListener(ListItemEvent.SELECTION_CHANGED, selectHandler);
            addChild(listView);
 
            _label = new Label();
            _label.text = "No item selected";
            _label.moveTo(0, 130);
            addChild(_label);
        }
 
        private function selectHandler(event : ListItemEvent) : void {
            if (event.selected) {
                _label.text = event.item + " selected";
            } else {
                _label.text = "No item selected";
            }
        }
    }
}

Objectives

No framework obligation

All controls can be used natively without any requirement to the particular application type (Flex, ActionScript or Flash).

Extensive customization capabilities

All controls can be almost entirely customized in functionality and appearance. However, default renderers and skins are applied, if not specified else. Even those default renderers and skins are highly customizable.

Performance

The controls have been developed, tested and improved for an optimal performance.

Quick overview

Life cycle architecture

The core of the library is a general base class called View. This class provides a life cycle, which is inherited to each particular control. The life cycle maintains the construction and update process of a component by invoking methods in a well defined order.

The View also offers a property change cache to avoid redundant computing. All subsequent property updates are collected and executes them cumulatively at only one single point (in the next frame). This is often called deferred rendering.

Styling and skinning

Each control defines its own particular style properties. Styles can be set to a control directly or to any display ancestor of that control. Most of the styles can also be set at runtime, which means after a control has been added to the stage the first time.

The styling possibilities:

• Setting styles to controls or default renderers and default skins
• Creating own skins for controls and default renderers
• Creating own renderers
• Creating own controls :-)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

package com.sibirjak.asdpc.overview {
    import com.sibirjak.asdpc.button.Button;
    import com.sibirjak.asdpc.button.skins.ButtonSkin;
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.textfield.Label;
 
    public class StyleExample extends Example {
        public function StyleExample() {
 
            // button 1
 
            var button : Button = new Button();
            button.setSize(60, 30);
            button.toggle = true;
            button.label = "Off";
            button.selectedLabel = "On";
 
            button.setStyle(ButtonSkin.style_backgroundColors, [0xAAAAAA, 0x333333]);
            button.setStyle(ButtonSkin.style_overBackgroundColors, [0xBBBBBB, 0x444444]);
            button.setStyle(ButtonSkin.style_borderColors, [0x999999, 0x000000]);
 
            button.setStyle(Button.style.labelStyles, [
                Label.style.color, 0xEEEEEE,
                Label.style.underline, false,
                Label.style.size, 12
            ]);
            button.setStyle(Button.style.overLabelStyles, [
                Label.style.color, 0xEEEEEE,
                Label.style.underline, true,
                Label.style.size, 12
            ]);
            button.setStyle(Button.style.selectedLabelStyles, [
                Label.style.color, 0xEEEEEE,
                Label.style.underline, false,
                Label.style.size, 12
            ]);
 
            addChild(button);
 
            // button 2
 
            button = new Button();
            button.setSize(60, 30);
            button.moveTo(80, 0);
            button.toggle = true;
            button.label = "Off";
            button.selectedLabel = "On";
 
            button.setStyles([
                ButtonSkin.style_backgroundColors, [0xFF0000, 0xAA0000],
                ButtonSkin.style_overBackgroundColors, [0xFF0000, 0xDD0000],
                ButtonSkin.style_borderColors, [0xFF0000, 0x990000],
                ButtonSkin.style_cornerRadius, 0,
 
                Button.style.labelStyles, [
                    Label.style.color, 0xFFFFFF,
                    Label.style.size, 12
                ],
                Button.style.overLabelStyles, [
                    Label.style.color, 0xFFFFFF,
                    Label.style.size, 12
                ],
                Button.style.selectedLabelStyles, [
                    Label.style.color, 0xFFFFFF,
                    Label.style.size, 12
                ]
            ]);
 
            addChild(button);
        }
    }
}

Data integration

The list controls (ListView, TreeView, SelectBox) visualise data of an external data source. Here is no restriction in the type of the data source. The ASDPC library has a built-in support for the native types Array and XML and for the AS3Commons collections. All other types can be used by creating custom data source adapter (which is easy and makes fun).

If a data source dispatchs change notifications (items added, removed), all list controls reflect those changes and update automatically.

Property binding

Most of the controls are equipped with binding capabilities. Whenever a bindable property changes, a registered binding listener receives notification. Note, the binding here is something different than the Flex binding.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package com.sibirjak.asdpc.overview {
    import com.sibirjak.asdpc.common.Example;
    import com.sibirjak.asdpc.textfield.Label;
    import com.sibirjak.asdpcbeta.checkbox.CheckBox;
 
    public class BindingExample extends Example {
        public function BindingExample() {
            var checkBox : CheckBox = new CheckBox();
            checkBox.label = "Hidden";
            checkBox.selectedLabel = "Visible";
            checkBox.moveTo(0, 1);
            addChild(checkBox);
 
            var label : Label = new Label();
            label.text = "I am visible";
            label.moveTo(80, 0);
            addChild(label);
 
            checkBox.bindProperty("selected", label, "visible");
        }
    }
}

Getting started

There is not much to get the controls running.

1. Download the SWC and copy it into your project.
2. Import the controls of your desire into your class and write code.

Resources

• Project homepage
• APIDoc
• Download and SVN repository
• Bug tracker

Table of contents

• Introduction to collections
  From built-in containers …
  … to collections
  Classification of collections
• 10 reasons for a collection framework
• Requirements to a collection framework
  Software requirements
  Acceptance criteria
• Existing solutions

Introduction to collections

Unlike scripting for server environments, where we usually synchronously access the underlying data base and process those data more or less consecutively in response to preceding HTTP calls, in client applications we need to more seriously take care about how we manage storage and retrieval that data during the entire application lifecycle. A common pattern is to load a bunch of resources from the network and keep it in stock until the appliction gets terminated. This is often called proxying, since the data we are working on are copies of the orginal data living in the remote data base. A second important difference to server side data handling comes up with the needs to collect user generated data to fulfill what the application is made for.

Built-in data containers

Array

Each programming language consists of several native containers to file and access data sets. The best known is the Array, wich stores its elements in an ordered fashion and provides convenient (random) access over its indexes or, by using a for loop, sequential access. The same item can be contained multiple times. Arrays are exceptional fast and can hardly be beaten. There is also a typed array called vector, which promises to be even faster. However, keeping elements sorted, adding elements mostly at the begin or finding elements is not really Array’s business.

public function ArrayTest() {
 
    // adding at end
    var a : Array = new Array();
    var i : int;
    var start : Number = new Date().getTime();
    for (i = 0; i < 50000; i++) a.push(i);
    var end : Number = new Date().getTime();
    trace ("add last i:" + i + " t:" + (end - start));
 
    // adding at start
    a = new Array(); start = end;
    for (i = 0; i < 50000; i++) a.unshift(i);
    end = new Date().getTime();
    trace ("add first i:" + i + " t:" + (end - start));
 
    // finding
    start = end;
    for (i = 0; i < 50000; i++) {
        if (i + a.indexOf(i) != 49999) throw new Error("error");
    }
    end = new Date().getTime();
    trace ("find i:" + i + " t:" + (end - start));
 
    // add last i:50000 t:16
    // add first i:50000 t:1812
    // find i:50000 t:24954
}

Associative Array

Sometimes the programming language supports associative arrays. In Flash we can use the dynamic Object class to create simple lookup tables. We are here restricted to number or string typed keys. Internally new properties are being added to the object at runtime. Random access (using the keys) or sequential access (for in loop) is possible. The for in loop does not preserve the insertion order. Also, duplicate keys are not possible. ActionScript3 did introduce a Dictionary class, wich acts mainly like the Object but allows additionally reference typed keys (objects, arrays, functions).

public function DictionaryTest() {
 
    var d : Dictionary = new Dictionary();
    var o : Array = new Array();
    var i : int;
    for (i = 0; i < 50000; i++) o[i] = {index:i};
 
    // adding
    var start : Number = new Date().getTime();
    for (i = 0; i < 50000; i++) d[o[i]] = i;
    var end : Number = new Date().getTime();
    trace ("add i:" + i + " t:" + (end - start));
 
    // finding
    start = end;
    for (i = 0; i < 50000; i++) {
        if (d[o[i]] != i) throw new Error("error");
    }
    end = new Date().getTime();
    trace ("find i:" + i + " t:" + (end - start));
 
    // add i:50000 t:16
    // find i:50000 t:15
}

Compositions

A third fundamental data container can be easily self-made by applying composition. The idea is to link objects among each other, what creates this way a sequential list or even a tree. We always need to save the first object from that we start enumeration. The composite structure cannot be accessed randomly. Iterating returns the items in the order they were inserted. The composition can manage the insertion of duplicate elements.

public function CompositionTest() {
 
    // adding at start
    var i : int;
    var first : Node = new Node(0, null);;
    var start : Number = new Date().getTime();
    for (i = 1; i < 50000; i++) {
        first = new Node(i, first);
    }
    var end : Number = new Date().getTime();
    trace ("add first i:" + i + " t:" + (end - start));
 
    // finding
    var node : Node;
    i = 0; start = end;
    for (i = 1; i < 1000; i++) {
        node = first;
        while (node) {
            if (node.item == i) break;
            node = node.right;
        }
    }
    end = new Date().getTime();
    trace ("find i:" + i + " t:" + (end - start));
 
    // add first i:50000 t:141
    // find i:1000 t:9719
}
 
class Node {
    public var right : Node;
    public var item : uint;
    public function Node(theItem : uint, theRight : Node) {
        item = theItem;
        right = theRight;
    }
}

… to collections

You have seen that the different approaches to collect data have their particular pros and cons. More structured, there are 4 fields of quality, the choice of a collection should be done in respect to.

• Performance of inserting an element at a specific position (at begin, in between, at end)
• Performance of finding an element (constant, logarithmic, linear or worse time)
• Order of the collection’s elements in enumeration (no order, insertion order, sorted order)
• Multiplicity of elements (unique, multiple)

Each of the three described built-in data containers supports a distinctive set of the qualities just mentioned. For example, the Array returns its items in insertion order but is pretty slow in finding one, while the Object enables a very fast lookup but enumeration is always surprisingly. Well, what about an example phone book application where we need ordering (phone book index) as well as direct element access (search)? In cases like this we simply combine the advantages of different containers. We use a sorted array to store the phone book’s entries (index) and set up an associative array (in Flash the Object) to save the participant’s name together with the accordant array index (search). We can think about various combinations, and some of them are that common, that they became names and have been included into the core libraries of many programming languages where they are now called collections.

Classification of collections

The Java Collections Framework defines three main collection types: Lists, sets and maps. (The queues can be considered as optimised lists.) Lists are always ordered, may contain duplicates and can be handled the same way as usual arrays. Sets cannot contain duplicates and provide random access to its elements. Maps connect unique keys with values, provide random access to its keys and may host duplicate values. The simplest implementions are respectively ArrayList, HashSet, HashMap. Different implementations are available for each of those types. Either they focus on ordering (LinkedHashSet, LinkedHashMap) or sorting (TreeSet, TreeMap) or fast inserting (LinkedXXX).

Besides the functional aspects, collections can also be classified by their internal structure (implementation). The table below lists a few important collections and their characteristics as well as realisation possibilies in ActionScript.

We can think of several applications for any of the different collections. The LinkedList would be for example perfectly suitable for an undo/redo history. Here we always add items at begin of the list and retrieve the elements sequentially. The phone book above uses the SortedMap. To reflect unmodifiable remote data we probably are going to use the LinkedMap, which enables access over an ID while it keeps the given order. The sets are most often used to collect runtime generated data. In a shopping application we might use a LinkedSet for the basket. Adding and removing of products can be done in constant time. The basket overview shows the products in the order they were added. When trying to add a product a second time, it’s simple to increase the quantity. Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

package as3.collections {
    import flash.display.Sprite;    
    public class SetBasketExample extends Sprite {
        private var basket : ILinkedSet;
        public function SetBasketExample() {
 
            basket = new LinkedSet();
            var shirt : Product = new Product("shirt", 19.90);
            var cap : Product = new Product("cap", 14.00);
            add(shirt);
            add(cap);
            add(shirt);
 
            trace (basket.toArray().join("\n"));
 
            // cap #1 $14
            // shirt #2 $39.8
        }
        public function add(product : Product) : void {
            if (basket.hasItem(product)) {
                product.quantity++;
            } else {
                basket.addItemAtStart(product);
            }
        }
    }
}
internal class Product {
    public var name : String;
    public var price : Number;
    public var quantity : uint = 1;
    public function Product(theName : String, thePrice : Number) {
        name = theName;
        price = thePrice;
    }
    public function toString() : String {
        return name + " #" + quantity + " $" + quantity * price;
    }
}

Until here, I have illustrated the potential of collections to solve common software problems. However, that’s not everything we can benefit from. In the next chapter I will give you a compact overview to the goals of collections, which moves the perspective more to software architecture and collaboration.

10 reasons for a collection framework

1. As we already know: Collections are design patterns for solutions of common problems with storing and retrieving data. Patterns help us in understanding situations and designing software. They clearly express their benefits and weaknesses.
2. Collections take over the implementation of the most commonly required functionality. No need to reinvent the wheel for each new project.
3. Wisely chosen, also in the mix with built-in containers, collections will enhance the performance of applications, even although they are built onto the programming language and are not part of the language itself.
4. Using collections results in far less and better readable source code.
5. Collections are entirely extendable. New functionality can be added using inheritance as well as by setting up completely new implementations for the particular interfaces.
6. Collections provide a generalised interface to the different underlying data structures. Wherever an ISet is accepted you can pass a Set, LinkedSet, SortedSet or MyCustomSet instance. May they internally hold an array or an object, the interface abstracts from the actual insertion strategy (push or []) and exposes the general addItem(). This way collections are interchangeable, portable and shareable.
7. Collections provide a uniform way of enumeration by engaging the iterator design pattern. Regardless of their distinctive implementations, collections can be interchangeable passed wherever an iterable object is expected.
8. A collection framework enables developers creating third party libraries based on collections rather than native containers. The libray interfaces are not restricted to accept ordinary arrays or objects. Without a framework, each libraray either would have to provide its own collection implementations, which can be considered as a reinvented framework, or simply had to abstain from using collections, which cannot be considered ;-).
9. The collection framework (assuming its existance) guarantees failure restistance, stability and sophistication. The framework is widely adapted, community based and proven by a lot of serious projects. Thus, it will be easy to explain its integration within official work flows.
10. Finally, an existing collection framework can make up one of the reasons keeping ActionScript/Flex being the technology of choice for web client application development. This is an important point in consideration of the fast growing JavaScript and JavaFX communities.

At this point of explanations, I have no doubt, you fully agree to the needs of a unified collection framework in ActionScript. I will put my thoughts about realisation possibilities right away.

Requirements to an ActionScript collection framework

As with all frameworks, the collection framework combines sophisticated software with an active and helpful community. The following requirements are therefore slightly generic.

Software requirements

• Slim and intuitive interfaces
  The framework consists only of the most necessary and commonly interfaces. Their definition is a challenging process and need not to be remade by each individual user. The framework integrates theoretical reflections, expert-knowledge and best practices and can be described as a general recommendation of approaches rather than as a ready-for-use library, which it is in the second place.
• High degree of extensibility
  To be applicable also in custom circumstances, the framework must provide straightforward mechanisms to extend the built-in functionality. There are three ways of doing this.
  1. An interface architecture allows interchangeable implementations of the same type. The collection framework must provide interfaces to all public functionality such as collections, iterators or configuration objects.
  2. Inheritance let’s the developers benefit from available basic implementations. The latter must therefore live in a public or protected namespace.
  3. Configuration as the third mechanism is dedicated the customisation of framework internal workflows by passing configuration objects (inversion of control). The collection framework encapsulates algorithms such as for sorting or comparing and makes them that way replaceable. Particular implementations can furthermore offer their own parametrisation.
• Ready-for-use implementations
  No framework would be accepted if it wouldn’t consists of a proper set of functionality applicable directly and without major preparation. The collection framework must contain base implemenations for all of the different collection types above.
• Predictable and consistent behaviour
  A framework should smoothly handle special or corner cases such as the absence of data, type mismatchs or range errors. Those cases have to be described and tested sufficiently as well as how the framework is supposed to behave normally.
• Good performance
  It’s obvious, that an unperformant framework is not much useful. The collection framework is targeted to the basis level of an application and bad performance here will be transferred to the overlying functionality. The performance of a collection depends on its structure and the algorithms modifying the structure. We have in ActionScript the high performing built-in Array and Dictionary, and in the most of the use cases it doesn’t get any faster than utilising them. A collection framework for ActionScript must reflect the special means and needs of the Flash platform.
  Performance has to be tested, compared and documented for each relevant function. Although performance is not the main goal of a collection framework, since performance and abstraction are a little bit contrary, it’s about to find the right balance between both poles.

Acceptance criteria

• Appropriate licence
  First of all, a framework shouldn’t have much limitations in useage.
• Easy utilisation
  Placing a new framework, you will need users for testing and feedback or getting convinced and hopefully spreading the word. For that, at least the installation of your framework should be exceedingly simple. Involving common software design concepts makes it relatively easy to get developers familiar with your framework. (In contrast, you cannot expect the user to spend much time to follow complicated and custom solutions.) This goes hand in hand with an intuitive and consistant naming of interfaces and methods, who should clearly express, what they are about and why they were invented.
• Documentation, examples, tutorials
  Depending on the purpose of the software, either end user documentation (in running text) or source code documentation or even both are adequate, which is the case with a collection framework.
  There never can be enough examples and good tutorials. Missing manuals can disappoint beginners and cause them to leave before they had the chance to enjoy the benefits of the software.
• Tested and stable software
  Existing test suites (and successful tests) are often the decisive factor for or against a third party software. A well-engineered framework ensures a high degree of stability. Subsequent and improved versions do not affect the base concepts and interfaces.
• Active community
  Obviously some frameworks are widely accepted and gain users while others live a dire existance. As a rule of thumb: Active communities tend to become more active :-) It’s the good balance between excellent software, clever PR and the support of the right people, what makes a framework popular. Open source projects often limit themselves to the first point. Popular authorities can advance even immature software to a high distribution. Good documentation and promotion can compensate both weaknesses of the software and absent supporters.
  Besides the software itself, an active framework offers many possibilities to join and support the associated community.
  • Independent project page
  • Source code repository
  • Feedback, error and change request management
  • Discussion board
  • Donation box
• High adoption rate
  There is no better recommendation as to have the software already being used in a large number of projects. A published list of applying projects provides confidence to new users and might give those projects a little advertisment.

I am now finished with the theoretical backgrounds of collections and collection frameworks. I will continue with a short review of some existing collection libraries for ActionScript.

Existing solutions

• Flex collection package
  Flex collections are designed to seamlessly integrate Flex user interfaces with data models. Whenever data changes, the Flex component gets automatically updated and vice versa. Using Flex collections without Flex components does not make much sense. The Flex collections actually consist only of a single list interface with two different implementations.
  http://livedocs.adobe.com/flex/3/html/help.html?content=about_dataproviders_1.html
• AS3 Data Structures For Game Developers
  The first choice (and best source) when it comes to bare algorithms and speed optimised data structures. Apparently the widest acceptance of all libraries. More a losely coupled set of distinctive implementations than a framework (doesn’t claim do be one). Great explanations and visual examples of data structures. Provided and maintained by the German Michael Baczynski.
  http://lab.polygonal.de/ds/
• dpdk_os_flash
  A pretty comprehensive and shophisticated library with excellent source code documentation. Entirely unit tested. Includes special purpose functionality such as commands, specifications, folding and mapping or remote data management and appears therefore a little bit overengineered. Maps are not dealed with. Provided and maintained by a Dutch media agency as their company framework.
  http://www.dpdk.nl/opensource/the-collections-package
• AS3-Collection-Framework
  A custom implementation of the Java interfaces. Provides various collections including a linked map. Very committed work. Could do with a little compression. Sometimes not using the best solution strategy. Developed by Tim Richter, Germany.
  http://www.addicted2flash.com/category/as3-collection-framework/
• as3commons
  A port of the Java Collections Framework to ActionScript, probably not longer active. The ported versions performed noticeable slow in tests. Might be an effect of the heavy composite architecture.
  http://sourceforge.net/projects/as3commons/
• ActionScript Foundry collection package
  The collections are part of the Foundry framework, which is targeted to simplify Flex application development. Is a port of the Java framework. I have not tested the collections, but after a short review of the code, I expect the collections performing similiar to those of the as3commons package.
  http://www.servebox.org/actionscript-foundry/actionscript-foundry-documentation/the-collections-framework/
• VEGAS
  Actually I didn’t get what VEGAS is especially for and if there are people out of the developer group using this huge library. However, they have their own package consisting of numerous different collections. Contains a lot of secondary and project internal functionality. Poor documented but readable source code. Depends on other VEGAS packages. It’s a bit tricky to come through to the sources.
  http://www.ekameleon.net/blog/index.php?pages/VEGAS-AS3-AS2-SSAS-Opensource-Framework
• Other libraries
  The Prada framework (nowadays Spring ActionScript) contains a map extension of the Flex collections. The same with Eric Feminella’s Open Source AS3 APIs.

Summary: We have quite a few solutions for exactly the same problem of how do we store and retrieve data in ActionScript client applications. There is obviously a need to work with collections rather than with native containers. Especially the general purpose frameworks rely on their custom collection implementations, who are often stuffed with internal functionality and are not likely to be used out of the box. Among the designated collection frameworks can be emphasized the dpdk_os_flash project because of the cleanest architecture and the AS3 Data Structures with the best algorithms.
None of the solutions reviewed match the most of the requirements prior proposed. However, the Dutch’s work is the most serious alternative and should be considered when planning to involve a third party collection library.

Thank you for reading these long explanations. I hope, I could bring some light into the matter and have made you hungry for working with data collections.