In this blog, I posted numerous articles showing how built-in Java functionality can greatly increase Matlab programming productivity and the resulting program power. While not really “undocumented” in the true sense (most of the material is actually documented separately in Matlab and Java), in practice, such Java gems are unfortunately often overlooked by Matlab programmers. Many of these tricks are GUI related, but Java has a lot to offer in non-GUI aspects. Today I will show how we can leverage Java’s extensive Collections classes in non-GUI Matlab programming.

Java Collections

Java contains a wide variety of predefined data structures (specifically Collections and Maps), which can easily be adapted to fit most programming tasks. It is unfortunate that the Matlab programming language does not contain similar predefined collection types, apart from its basic cell, array and struct elements. Matlab R2008b (7.7) added containers.Map, which is a much-scaled-down Matlab version of the java.util.Map interface, but is a step in the right direction. Some Matlab programmers prepared their own implementations of data structures, which can be found on the File Exchange.
Matlab’s limitation can easily be overcome with Java’s out-of-the-box set of predefined classes, as described below. Java collections have many advantages over hand-coded Matlab equivalents, in addition to the obvious time saving: Java’s classes are extensively debugged and performance-tuned, which is especially important when searching large collections. Also, these classes provide a consistent interface, are highly configurable and extendable, enable easy cross-type interoperability and generally give Matlab programmers the full power of Java’s collections without needing to program the nuts-and-bolts.
To start using Java collections, readers should first be familiar with them. These classes are part of the core Java language, and are explained in any standard Java programming textbook. The official Java website provides a detailed online tutorial ^[1] about these classes, their usage and differences, in addition to a detailed reference ^[2] of these classes.
Java Collections include interfaces and implementation classes. As of Matlab R2011b, Java interfaces cannot be used directly – only the implementation classes. Of the many Collection classes, the following are perhaps most useful (all classes belong to the java.util package, unless otherwise noted):

• Set ^[3]: an interface that is implemented by classes characterized by their prevention of duplicate elements. Some notable implementation classes: EnumSet, HashSet, LinkedHashSet, TreeSet.
• List ^[4]: an interface that is implemented by classes characterized by ordered elements (a.k.a. sequences), which may be duplicates of each other and accessed based on their exact position within the list. Specially optimized internal algorithms ^[5] enable sorting, shuffling, reversing, rotating, and other modifications of the list. Some notable implementation classes: Vector, Stack, LinkedList.
• Queue ^[6]: an interface that is implemented by classes designed for holding elements prior to processing, in an ordered list accessible only at one (=head) or two (head and tail) positions. All classes include specialized insertion, extraction and inspection methods. Some notable implementation classes: LinkedList, ArrayDeque, PriorityQueue.
• Map ^[7]: an interface that is implemented by classes characterized by elements of unique keys paired with associated values. Early Java versions used the java.util.Dictionary abstract superclass, but this was subsequently replaced by the java.util.Map interface class. Maps contain specialized algorithms for fast retrieval based on a supplied key. Some of the notable implementation classes: EnumMap, HashMap, Hashtable, TreeMap, LinkedHashMap.

As noted, Matlab R2008b (7.7)’s new containers.Map class is a scaled-down Matlab version of the java.util.Map interface. It has the added benefit of seamless integration with all Matlab types (unlike Java Collections – see below), as well as the ability ^[8] since Matlab 7.10 (R2010a) to specify data types. Serious Matlab implementations requiring key-value maps/dictionaries should still use Java’s Map classes to gain access to their larger functionality if not performance. Matlab versions earlier than R2008b have no real alternative in any case and must use the Java classes. The reader may also be interested to examine pure-Matlab object-oriented (class-based) Hashtable implementations, available on the File Exchange (example1 ^[9], example2 ^[10]).
A potential limitation of using Java Collections is their inability ^[11] to contain non-primitive Matlab types such as structs. To overcome this, either down-convert the types to some simpler type (using the struct2cell function or programmatically), or create a separate Java object that holds the information and store this object in the Collection.
Many additional Collection classes offer implementation of specialized needs. For example, java.util.concurrent.LinkedBlockingDeque implements a Queue which is also a LinkedList, is a double-ended queue (Deque) and is blocking (meaning that extraction operations will block until at least one element is extractable).

Programming interface

All the Java Collections have intentionally similar interfaces, with additional methods specific to each implementation class based on its use and intent. Most Collections implement the following common self-explanatory methods (simplified interface):

int size()
int hashCode()
boolean isEmpty()
boolean contains(Object element)
boolean containsAll(Collection c)
Iterator iterator()
boolean add(Object element)
boolean remove(Object element)
boolean addAll(Collection c)
boolean removeAll(Collection c)
boolean retainAll(Collection c)
void clear()
Object clone()
Object[] toArray()
String toString()

The full list of supported methods in a specific Collection class can, as any other Java object/class, be inspected using Matlab’s methods or methodsview functions (or my utilities, checkClass ^[12] and uiinspect ^[13]):

>> methods('java.util.Hashtable')
Methods for class java.util.Hashtable:
Hashtable	containsKey	  equals	isEmpty   notifyAll	size
clear		containsValue	  get		keyset    put		toString
clone		elements	  getClass	keys      putAll	values
contains	entrySet	  hashCode	notify    remove	wait

Collections example: Hashtable

A detailed Matlab example that utilizes Hashtable (actually, java.util.Properties, which is a subclass of java.util.Hashtable) for a phone-book application is detailed ^[14] in Matlab’s External Interface/Java section. The following code snippet complements that example by showing some common characteristics of Collections:

>> hash = java.util.Hashtable;
>> hash.put('key #1','myStr');
>> hash.put('2nd key',magic(3));
>> disp(hash)  % same as: hash.toString
{2nd key=[[D@59da0f, key #1=myStr}
>> disp(hash.containsKey('2nd key'))
     1                        % = true
>> disp(hash.size)
     2
>> disp(hash.get('key #2'))   % key not found
     []
>> disp(hash.get('key #1'))   % key found and value retrieved
myStr
>> disp(hash.entrySet) % java.util.Collections$SynchronizedSet object
[2nd key=[[D@192094b, key #1=myStr]
>> entries = hash.entrySet.toArray
entries =
java.lang.Object[]:
    [java.util.Hashtable$Entry]
    [java.util.Hashtable$Entry]
>> disp(entries(1))
2nd key=[[D@192094b
>> disp(entries(2))
key #1=myStr
>> hash.values  % a java.util.Collections$SynchronizedCollection
ans =
[[[D@59da0f, myStr]
>> vals = hash.values.toArray
vals =
java.lang.Object[]:
    [3x3 double]
    'myStr'
>> vals(1)
ans =
     8     1     6
     3     5     7
     4     9     2
>> vals(2)
ans =
myStr

Enumerators / Iterators

Java Iterators (aka Enumerators), such as those returned by the hash.keys() method, are temporary memory constructs. A common pitfall is to directly chain such constructs. While legal from a syntax viewpoint, this would produce results that are repetitive and probably unintended, as the following code snippet shows:

>> hash.keys
ans =
java.util.Hashtable$Enumerator@7b1d52    < = enumerator reference
>> hash.keys
ans =
java.util.Hashtable$Enumerator@127d1b4   < = new reference object
>> disp(hash.keys.nextElement)
2nd key   < = 1st key enumerated in the hash
>> disp(hash.keys.nextElement)
2nd key   < = same key returned, because of the new enumeration obj
>> % Wrong way: causes an endless loop since hash.keys regenerates
>> % ^^^^^^^^^  so hash.keys.hasMoreElements is always true
>> while hash.keys.hasMoreElements, doAbc();  end   % endless loop
>> % Correct way: store the enumerator in a temporary variable
>> hashKeys = hash.keys;
>> while hashKeys.hasMoreElements,  doAbc();  end
>> hash.keys.methods
Methods for class java.util.Hashtable$Enumerator:
equals            hasNext    nextElement   remove
getClass          hashCode   notify        toString
hasMoreElements   next       notifyAll     wait
>> % And similarly for ArrayList iterators:
>> jList = java.util.ArrayList;
>> jList.add(pi); jList.add('text'); jList.add(magic(3)); disp(jList)
[3.141592653589793, text, [[D@1c8f959]
>> iterator = jList.iterator
iterator =
java.util.AbstractList$Itr@1ab3929
>> disp(iterator.next); fprintf('hasNext: %d\n',iterator.hasNext)
          3.14159265358979
hasNext: 1
>> disp(iterator.next); fprintf('hasNext: %d\n',iterator.hasNext)
text
hasNext: 1
>> disp(iterator.next); fprintf('hasNext: %d\n',iterator.hasNext)
     8     1     6
     3     5     7
     4     9     2
hasNext: 0

More on this topic and other non-GUI Java libraries that can be used in Matlab, can be found in Chapter 2 of my Matlab-Java Programming book ^[15].

18 Comments To "Using Java Collections in Matlab"

#1 Comment By Joao On February 16, 2012 @ 09:25

#2 Comment By Yair Altman On February 16, 2012 @ 09:29

#3 Comment By Quang On February 23, 2012 @ 06:04

classdef Person
   properties
       name;
       age;
   end
   
   methods
       function obj = Person(n, a)
           obj.name = n;
           obj.age = a;
       end
   end
end

p = Person('MyName', 18);
l = java.util.ArrayList;
l.add(p) % Error message....

#4 Comment By Yair Altman On February 23, 2012 @ 06:08

#5 Comment By Quang On February 23, 2012 @ 06:16

#6 Comment By Yair Altman On February 23, 2012 @ 06:20

#7 Comment By Quang On February 23, 2012 @ 06:24

#8 Comment By Rajpal On April 22, 2013 @ 23:58

#9 Comment By Yair Altman On April 23, 2013 @ 00:09

#10 Comment By Yola On July 24, 2015 @ 00:40

#11 Comment By Yair Altman On July 24, 2015 @ 00:51

#12 Comment By Sepehr On July 20, 2016 @ 03:32

>> hash = java.util.Hashtable;
>> key = getByteStreamFromArray([1,2]);
>> value = getByteStreamFromArray([2,3]);
>> hash.put(key,value)
ans =
     []

>> hash.containsKey(key)
ans =
     0

>> hash = java.util.Hashtable;
>> hash.put('mykey',getByteStreamFromArray([2,3]));
>> getArrayFromByteStream(hash.get('mykey'))
Error using getArrayFromByteStream
The input must be a uint8 byte stream.

#13 Comment By Yair Altman On July 20, 2016 @ 10:39

>> data = int16(getByteStreamFromArray([2,3]));
>> hash.put('mykey', data);
...
>> data2 = getArrayFromByteStream(uint8(hash.get('mykey')))
data2 =
     2     3

#14 Comment By Christopher Volpe On August 16, 2016 @ 22:13

>> dummyQueue = java.util.LinkedList
dummyQueue =
[]

>> vecIn = [1,2,3]
vecIn =
     1     2     3

>> dummyQueue.add(vecIn)
ans =
     1

>> vecOut = dummyQueue.remove()
vecOut =
     1
     2
     3

#15 Comment By Yair Altman On August 16, 2016 @ 23:00

#16 Comment By Jonathan Mathews On June 9, 2017 @ 09:34

#17 Comment By Phil On February 19, 2019 @ 00:39

% initialize hashmap
map = java.util.LinkedHashMap();

% add a k/v pair with integer vector value
map.put('key1', int32([5 6 7]));

% add a k/v pair with integer scalar value
map.put('key2', int32(5));

% get the value for key1 - it's an int32, as one would expect
class(map.get('key1'))

% get the value for key2 - it's a double - Matlab automatically converted this
% is there any way to get this value's type before it is converted?
% conversion, so that I cam 
class(map.get('key2'))

#18 Comment By Yair Altman On February 19, 2019 @ 10:16

>> map.put('key2', int32([5,0]));
>> data = map.get('key2')
data =
  2×1 int32 column vector
   5
   0
>> data(1)
ans =
  int32
   5