Calitha Collections Dojo Plugin

An extension for Dojo providing high-level collection based objects

Introduction

calitha-collections is a javascript dojo extension for supporting collection based objects. calitha-collections is based on the Java Collections framework. The intent was to have an API very close to this Java framework for several reasons. 1. Java Collections is a powerful, flexible and reliable framework. 2. The high-level approach to collections makes javascript development more productive. Some of this collections implementation is very different to Java, to make use of the special Javascript features, while other parts are almost identical.

Installation

There are two available downloads for each calitha-collections version:

calitha-collections has dependencies on Dojo core. To use calitha-collections you must unpack one of the files above and include collections.js (or the uncompressed.js file). An example how this can be done is shown here:

<html> <head> <script src="js/dojo/dojo.js"></script> <script src="js/calitha/collections.js"></script> </head> <body> ... </body> </html>

Documentation

The interface classes are extensively documented (mostly copied from the official JDK documentation). Each interface will describe if there are any differences between it and the Java interface. In the classes only the constructors with parameters are documented.

These are the main collection object implementations currently available:

The official JDK documentation can give you a lot of information too: Java 1.6 collections package summary

Examples

ArrayList Example

Add some numbers to a list and then calculate the sum of all numbers.

var list = calitha.collections.ArrayList(); list.add(1); list.add(4); list.add(9); var result; list.forEach(function(item) {result += item}); //result is 14

The same can be done with a LinkedList. Just create a calitha.collections.LinkedList

HashSet example

This example will add several custom Employee objects do some contains calls.

// Employee contains an equals and hashCode method, so that it can be inserted in a hashtable and retrieved for // later use dojo.declare("Employee", null, { // code is an int number constructor: function(code, firstName, lastName) { this.code = code; this.firstName = firstName; this.lastName = lastName; }, equals: function(obj) { if (obj == null) return false; if (this === obj) return true; if (!obj instanceof Employee)) return false; return this.code === obj.code; } , hashCode: function() { return this.code; } }); var set = calitha.collections.HashSet(); set.add(new Employee(1234, "John", "Doe")); set.add(new Employee(2222, "Sherlock", "Holmes")); // ... in some other part of your code var result1 = set.contains(new Employee(1234, "John", "Doe")); // is true var result2 = set.contains(new Employee(2300, "Jean-Luc", "Picard")); // is false

HashMap example

This example will add number-to-string entries to a HashMap and iterate over all entries.

// add an equals and hashCode method to Number.prototype so that they can be added to a HashMap dojo.collections.makeNumberHashCompatible(Number.prototype); var map = new calitha.collections.HashMap(); map.put(5, "five"); map.put(3, "three"); map.put(7, "seven"); var iterator = map.entrySet().iterator(); while (iterator.hasNext()) { var entry = iterator.next(); console.info(entry.getKey() + " - " + entry.getValue()); }

TreeSet

This example will add some strings to a TreeSet. The forEach call will show that the strings have been sorted in the set.

// let's sort case-insensitive var comparator = calitha.collections.caseInsenstiveStringComparator(); var set = new calitha.collections.TreeSet(comparator); set.add("Hello"); set.add("world!"); set.add("This"); set.add("is"); set.add("a"); set.add("test"); set.forEach(function(item) {console.info(item});

Implementation details

Functions and properties starting with an underscore are considered private or protected. This means that as a user of the library, it is not meant that you set those properties or call those functions. Doing so can cause unknown errors.

calitha-collections uses multiple inheritance. However, just like in Java, at most one implementation class is extended from, the others are interface classes. Interface classes are there just to make it clear which methods an object must have. Each of those methods will throw a calitha.exception.VirtualFunctionException meaning that the methods has not been implemented as the interface requires.

The Java Collection classes contain a lot of inner classes. In calitha-collections those inner classes have been put in seperate folders. Take for example the ListIterator in the LinkedList class. A folder names linkedlist is created in which a ListIterator.js file is put. calitha.collections.LinkedList will create an instance of calitha.collections.linkedlist.ListIterator and passes a reference of itself, so that it can function as an inner class.