**- Undocumented Matlab - http://undocumentedmatlab.com -**

Using Java Collections in Matlab

Posted By Yair Altman On February 16, 2012 | __18 Comments__

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 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

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 `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 A potential limitation of using Java Collections is their inability

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).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

```
>> 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
```

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
```

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]}*.

Categories: Java, Low risk of breaking in future versions

18 Comments (Open | Close)

Article printed from Undocumented Matlab: **http://undocumentedmatlab.com**

URL to article: **http://undocumentedmatlab.com/articles/using-java-collections-in-matlab**

URLs in this post:

[1] tutorial: **http://docs.oracle.com/javase/tutorial/collections/**

[2] detailed reference: **http://docs.oracle.com/javase/6/docs/technotes/guides/collections/**

[3] Set: **http://docs.oracle.com/javase/6/docs/api/java/util/Set.html**

[4] List: **http://docs.oracle.com/javase/6/docs/api/java/util/List.html**

[5] optimized internal algorithms: **http://docs.oracle.com/javase/tutorial/collections/algorithms/**

[6] Queue: **http://docs.oracle.com/javase/6/docs/api/java/util/Queue.html**

[7] Map: **http://docs.oracle.com/javase/6/docs/api/java/util/Map.html**

[8] ability: **http://www.mathworks.com/help/techdoc/ref/containers.mapclass.html**

[9] example1: **http://www.mathworks.com/matlabcentral/fileexchange/26778**

[10] example2: **http://www.mathworks.com/matlabcentral/fileexchange/28586**

[11] inability: **http://stackoverflow.com/questions/436852/storing-matlab-structs-in-java-objects**

[12] * checkClass*:

[13] * uiinspect*:

[14] detailed: **http://www.mathworks.com/help/techdoc/matlab_external/f18070.html**

[15] Matlab-Java Programming book: **http://undocumentedmatlab.com/matlab-java-book/**

[16] Assessing Java object size in Matlab : **http://undocumentedmatlab.com/articles/assessing-java-object-size-in-matlab**

[17] Matlab callbacks for Java events : **http://undocumentedmatlab.com/articles/matlab-callbacks-for-java-events**

[18] Java stack traces in Matlab : **http://undocumentedmatlab.com/articles/java-stack-traces-in-matlab**

[19] Matlab-Java memory leaks, performance : **http://undocumentedmatlab.com/articles/matlab-java-memory-leaks-performance**

[20] Matlab-Java interface using a static control : **http://undocumentedmatlab.com/articles/matlab-java-interface-using-static-control**

[21] Converting Java vectors to Matlab arrays : **http://undocumentedmatlab.com/articles/converting-java-vectors-to-matlab-arrays**

[22] : **http://www.mathworks.com/products/javabuilder/**

[23] : **http://undocumentedmatlab.com/blog/jmi-java-to-matlab-interface/**

[24] : **http://undocumentedmatlab.com/blog/serializing-deserializing-matlab-data**

[25] : **http://eeenthusiast.com/java-queue-stack-implementation-tutorial-linked-list-programming-explained-from-scratch/**

[26] : **https://www.mathworks.com/help/matlab/matlab_external/handling-data-returned-from-java-methods.html#bvizhgf**

Click here to print.

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.

18 Comments To "Using Java Collections in Matlab"

#1 CommentByJoaoOn February 16, 2012 @ 09:25These are extremely useful. Are these deployable? If I compile the code into a Java library, will I be using a Java wrapper around a MATLAB wrapper around a Java class?

#2 CommentByYair AltmanOn February 16, 2012 @ 09:29@Joao – yes, they are deployable. You do not need to do anything special to compile them – it works directly “out of the box”.

As for the wrapper question, I’m not 100% sure, but I am almost sure that the Java objects will be called directly, without any intermediate Matlab wrapper.

It is actually extremely efficient: Calls to Java Collection methods take microseconds, not even one millisecond.

#3 CommentByQuangOn February 23, 2012 @ 06:04Hi,

I’ve noticed that it is not possible to add a Matlab object to a Java collection

—

Is there any workaround for this problem?

Thanks,

Quang.

#4 CommentByYair AltmanOn February 23, 2012 @ 06:08@Quang – as I’ve said in the article, Java containers can only contain simple objects, not Matlab structs or class objects. You need to either use

or to serialize (down-convert) your class object into simpler types that can be stored in Java.containers.Map#5 CommentByQuangOn February 23, 2012 @ 06:16Thanks a lot for the quick response! And sry, yes you did mention that in the article. I was reading it too fast 🙂 Is there any way to declare a Java class directly in Matlab instead of using its classdef syntax?

#6 CommentByYair AltmanOn February 23, 2012 @ 06:20You can prepare a Java class in an external class (MyClass.java), compile it using a Java compiler (=> MyClass.class) and then load and use this class in Matlab (just like you load and use

`java.util.ArrayList`

. You cannot declare Java code from within Matlab like you would declare a Matlab class.#7 CommentByQuangOn February 23, 2012 @ 06:24Thanks a lot. It really helped! 🙂

#8 CommentByRajpalOn April 22, 2013 @ 23:58How to call matlab fuction in java …

Give the sollution fast..plz..

#9 CommentByYair AltmanOn April 23, 2013 @ 00:09@Rajpal – either use the

^{[22]}toolbox ($$$) or use one of the free alternatives such as^{[23]}, JNI, JNA, COM etc. The toolbox costs money but saves you a lot of programming and QA time, so it could well be worth the investment.You can find more details in my

^{[15]}(Chapter 9).#10 CommentByYolaOn July 24, 2015 @ 00:40Can you please write something on how i can use java collections with user-defined types. How i can provide comparator for my type. Thanks!

#11 CommentByYair AltmanOn July 24, 2015 @ 00:51To store a Matlab class object in a Java collection, you would need to first

^{[24]}into a byte array that can then be stored in the Java collection object (and deserialize it when it is extracted).Comparators, AFAIK, can only be specified in Java code. I don’t think you can specify a Matlab function to act as a comparator function that Java understands.

#12 CommentBySepehrOn July 20, 2016 @ 03:32Hi Yair,

Great article. I have tried your suggestion on serializing objects so they can be used as both keys and values in a hashtable. It does not work.

Here a piece of code that shows hashtable fails at finding a byte array!

Also, when I use strings as keys and byte arrays as values, the retrieved values are scrambled! e.g.

Any suggestions?

#13 CommentByYair AltmanOn July 20, 2016 @ 10:39@Sepehr – while

`Hashtable`

does indeed accept arrays as keys, the automatic conversion between Java and Matlab data types causeshash.getnot to find the key. Instead, use a simpler data type such as a number or string.You also need to remember that all numeric data in Java is signed, unlike Matlab which uses

`uint8`

for its serialization. Therefore, you need to first convert into a signed`int16`

before storing in the Java array, and then to convert back to`uint8`

when loading back into Matlab from the hash:#14 CommentByChristopher VolpeOn August 16, 2016 @ 22:13Nice overview. Is there a reason why (Matlab’s interface to) java.util.LinkedList turns row vectors into column vectors? E.g.:

#15 CommentByYair AltmanOn August 16, 2016 @ 23:00@Christopher – primitive Java arrays (e.g.

`double[]`

) are automatically converted into a column vector in Matlab.When you store your data in a Java object using automated Matlab-Java type-conversions, Java strips away any such meta-info. Matlab has no way of knowing whether the array should be a row or column array, because this meta-info is not stored by Java, so the decision to create a column Matlab array is just as valid as a decision to create a row array.

If you wish to store the Matlab data including the meta-info, then you need to serialize your Matlab data before storing it, and deserialize it back when you read it:

^{[24]}#16 CommentByJonathan MathewsOn June 9, 2017 @ 09:34Thank you for the tutorial. I found this resource for a

^{[25]}. They cover an implementation through a linked list. Does it matter if you build it from scratch or through a linked list?Cheers,

John

#17 CommentByPhilOn February 19, 2019 @ 00:39Is there any workaround to prevent Matlab from automatic converting scalar, numeric Java types into doubles? (described here

^{[26]})See the following simple example:

#18 CommentByYair AltmanOn February 19, 2019 @ 10:16@Phil – as you discovered, this conversion is automatically done by Matlab. I am not familiar with a way to override it. The best choice is to store the scalar along with some dummy value, and only use the first item in the array when you fetch it back from the hashmap.