Matlab callbacks for Java events

Tuesday, November 30th, 2010

A few days ago, a user posted a question on StackOverflow asking whether it is possible to trap a Java-based event in a Matlab callback.

It so happens that only a few weeks ago I completed a consulting project which required exactly this. The project was to integrate a Matlab computational engine with a Java interface to Interactive Brokers (IB) – a well-known online brokerage firm. The idea was to use the Java interface to fetch real-time data about securities (stocks, bonds, options etc.), use a Matlab processing utility, then use the Java interface again to send Buy or Sell orders back to IB.

If you are interested in the final result (i.e., a complete and field-tested Matlab-IB interface), look here.

The challenge

A big challenge in this project (aside from handling quite a few IB interface quirks), was to propagate events from the Java interface to the Matlab application. This had to be done asynchronously, since events such as order execution can occur at any time following the order placement. Moreover, even simple requests such as retrieving security information (bid/ask prices for example) is handled by IB via Java events, not as simple function return values.

Handling Java-based events in Matlab is not a trivial task. Not only merely undocumented, but it is also not intuitive. I have spent quite a few hours trying to crack this issue. In fact, I believe it was one of my more challenging tasks in figuring out the undocumented aspects of the Matlab-Java interface. Few other challenges were as difficult, yet with a happy ending (Drag & Drop is a similar issue – I will describe it in another article sometime).

The solution

Fast-forward all the fruitless attempted variations, here is the bottom line. Refer to the following simple Java class example:

public class EventTest
{
    private java.util.Vector data = new java.util.Vector();
    public synchronized void addMyTestListener(MyTestListener lis) {
        data.addElement(lis);
    }
    public synchronized void removeMyTestListener(MyTestListener lis) {
        data.removeElement(lis);
    }
    public interface MyTestListener extends java.util.EventListener {
        void testEvent(MyTestEvent event);
    }
    public class MyTestEvent extends java.util.EventObject {
        private static final long serialVersionUID = 1L;
        public float oldValue,newValue;        
        MyTestEvent(Object obj, float oldValue, float newValue) {
            super(obj);
            this.oldValue = oldValue;
            this.newValue = newValue;
        }
    }
    public void notifyMyTest() {
        java.util.Vector dataCopy;
        synchronized(this) {
            dataCopy = (java.util.Vector)data.clone();
        }
        for (int i=0; i<dataCopy.size(); i++) {
            MyTestEvent event = new MyTestEvent(this, 0, 1);
            ((MyTestListener)dataCopy.elementAt(i)).testEvent(event);
        }
    }
}

When compiling EventTest.java, three class files are created: EventTest.class, EventTest$MyTestEvent.class and EventTest$MyTestListener.class. Place them on Matlab’s Java static classpath, using edit(‘classpath.txt’) (using the dynamic classpath causes many problems that using the static classpath solves). They can now be accessed as follows:

>> which EventTest
EventTest is a Java method  % EventTest constructor
 
>> evt = EventTest
evt =
EventTest@16166fc
 
>> evt.get
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = 
	TestEventCallbackData = []
 
	BeingDeleted = off
	ButtonDownFcn = 
	Children = []
	Clipping = on
	CreateFcn = 
	DeleteFcn = 
	BusyAction = queue
	HandleVisibility = on
	HitTest = on
	Interruptible = on
	Parent = []
	Selected = off
	SelectionHighlight = on
	Tag = 
	Type = EventTest
	UIContextMenu = []
	UserData = []
	Visible = on
 
>> set(evt)
	Class
	TestEventCallback: string -or- function handle -or- cell array
	...
 
>> set(evt,'TestEventCallback',@(h,e)disp(h))
 
>> get(evt)
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = [ (1 by 1) function_handle array]   <= ok
	TestEventCallbackData = []
	...
 
>> evt.notifyMyTest   % invoke Java event
              0.0009765625   % <= Matlab callback

Note how Matlab automatically converted the Java event testEvent, declared in interface MyTestListener, into a Matlab callback TestEventCallback (the first character is always capitalized). All Java events are automatically converted in this fashion, by appending a ‘Callback’ suffix. Here is a code snippet from R2008a’s \toolbox\matlab\uitools\@opaque\addlistener.m that shows this (slightly edited):

hSrc = handle(jobj,'callbackproperties');
allfields = sortrows(fields(set(hSrc)));
for i = 1:length(allfields)
   fn = allfields{i};
   if ~isempty(findstr('Callback',fn))
      disp(strrep(fn,'Callback',''));
   end
end
 
callback = @(o,e) cbBridge(o,e,response);
hdl = handle.listener(handle(jobj), eventName, callback);
function cbBridge(o,e,response)
   hgfeval(response, java(o), e.JavaEvent)
end

Note that hgfeval, which is used within the cbBridge callback function, is a semi-documented pure-Matlab built-in function, which I described a few weeks ago.

If several events have the same case-insensitive name, then the additional callbacks will have an appended underscore character (e.g., ‘TestEventCallback_’):

// In the Java class:
public interface MyTestListener extends java.util.EventListener
{
    void testEvent(MyTestEvent e);
    void testevent(TestEvent2 e);
}
% …and back in Matlab:
>> evt=EventTest; evt.get
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = 
	TestEventCallbackData = []
	TestEventCallback_ = 
	TestEventCallback_Data = [] 
	...

To complete this discussion, it should be noted that Matlab also automatically defines corresponding Events in the Java object’s classhandle. Unfortunately, classhandle events are not differentiated in a similar manner – in this case only a single event is created, named Testevent. classhandle events, and their relationship to the preceding discussion, will be described in Donn Scull’s upcoming series on UDD.

An alternative to using callbacks on Java events, as shown above, is to use undocumented handle.listeners:

hListener = handle.listener(handle(evt),'TestEvent',callback);

There are several other odds and ends, but this article should be sufficient for implementing a fully-functional Java event handling mechanism in Matlab. Good luck!

Related posts:

  1. UDD and Java UDD provides built-in convenience methods to facilitate the integration of Matlab UDD objects with Java code - this article explains how...
  2. UDD Events and Listeners UDD event listeners can be used to listen to property value changes and other important events of Matlab objects...
  3. uisplittool & uitogglesplittool callbacks Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...
  4. JMI – Java-to-Matlab Interface JMI enables calling Matlab functions from within Java. This article explains JMI's core functionality....
  5. Converting Java vectors to Matlab arrays Converting Java vectors to Matlab arrays is pretty simple - this article explains how....
  6. Uicontrol callbacks This post details undocumented callbacks exposed by the underlying Java object of Matlab uicontrols, that can be used to modify the control's behavior in a multitude of different events...

Categories: High risk of breaking in future versions, Java, Listeners, Semi-documented function, Undocumented feature, Undocumented function

Tags: , , , , ,

Bookmark and SharePrint Print
If you like this post, please consider buying me a cup of coffee.

27 Responses to Matlab callbacks for Java events

  1. julien vergoz says:
    December 3, 2010 at 6:31 am

    Once again, a very nice article ! Thanks to you, we can now trigger matlab callbacks from java-events without an advanced knowledge of java… Thank you !
    I have a question about listening to MouseEvents : in a matlab application, I would like to trigger a matlab Callback when the mouse moves over a figure, without using the “WindowButtonMotionFcn”. In a previous article (http://undocumentedmatlab.com/blog/inactive-control-tooltips-event-chaining/), one of your special guests explained that you can do something like that attaching a listener to the “WindowButtonMotionEvent” (with the syntax handle.listener(gcf,’WindowButtonMotionEvent’,@myFigMouseMove)) . This works very well but unfortunately, the only EventData that you can retrieve is the CurrentPoint, which is quite poor. I would prefer to retrieve the MouseEvent java object.
    Do you know if there is a way of retrieving MouseEvent in matlab figures and attach a listener to it ?
    It would also be very useful to retrieve KeyEvent…
    Thank you very much in advance for your help,
    Julien

    Reply
  2. matt dash says:
    December 8, 2010 at 1:54 pm

    Could this method be used to have matlab run a callback when changes are made to a jtable? (I know i should just be able to use a uitable as a jtable, but uitable drives me crazy with everything else it does…)

    Reply
    • Yair Altman says:
      December 8, 2010 at 2:17 pm

      @Matt – yes, if you attach a Java event and wrap it as described in the article above. However, I think it would be *much* easier to simply attach a handle.listener on the relevant Java event/property, or simpler still – to attach a regular Matlab callback on the events already exposed by the Java object (e.g., DataChangedCallback, which is a callback-able property of the JTable model if I remember correctly).
      - Yair

    • matt dash says:
      December 8, 2010 at 2:29 pm

      Oh good, i was hoping there would be a much simpler way :D I’m still pretty new to java. I had checked before and didn’t see any relevant callbacks for JTable, but now I see that DefaultTableModel has TableChangedCallback that seems to do what I need it to. I’ll also check out handle.listener… it’s been a while since I looked at Matlab’s listener capabilities. I didn’t realize you could add them to general java objects… i thought they were just for Matlab’s handle graphics stuff. Thanks a lot for the info!

    • Yair Altman says:
      December 8, 2010 at 3:07 pm

      @Matt – take a look at this article, which presents three separate ways of accessing Java events using callbacks and handle.listener: http://UndocumentedMatlab.com/blog/continuous-slider-callback/

  3. Anonymous says:
    December 21, 2010 at 8:15 am

    Wow, that is tremendous! Great work. Though I have to say, running a live trading system on matlab and even undocumented matlab features is probably not wise on so many levels.

    Reply
  4. Yunde Zhong says:
    February 18, 2011 at 9:56 am

    Great work. I have one question: It seems the matlab callback is dynamically (a-synchronously) invoked. Is there any solution to synchronouly invoke the matlab callback in your example? Thanks.

    For example, if we add two lines to the function “notifyMyTest()”

    public void notifyMyTest() {
   java.util.Vector dataCopy;
   synchronized(this) {
      dataCopy = (java.util.Vector)data.clone();
   }
   for (int i=0; i<dataCopy.size(); i++) {
      MyTestEvent event = new MyTestEvent(this, 0, 1);
      System.out.println("Starting calling Callbacks...");
      ((MyTestListener)dataCopy.elementAt(i)).testEvent(event);
      System.out.println("Callbacks called");
   }
}

    We will see the prints as following:
    ———–
    Starting calling Callbacks…
    Callbacks called
    9.7656e-004
    ———–
    It looks like the Matlab callabck is invoked after the java code returns. Any suggestions? Thanks.

    Reply
    • Yair Altman says:
      February 19, 2011 at 9:21 am

      @Yunde – yes, this is how it works: the Matlab callback function is invoked on a different thread and the threads are not synchronized. In most cases this is exactly how we need it to behave. If you require synchronization, here’s one way to solve this: You could have your Matlab function set some internal Java property when it ends its processing, and have the original Java code wait (sleep) until it detects that the property value has been changed.

  5. Alessio says:
    March 8, 2011 at 6:51 am

    Well done!!! That’s what I need!!! However, I don’t understand something about Java code, in particular about TestEvent.class:

    1) Why are “addMyTestListener”, “removeMyTestListener” and notifyMyTest() methods declared “synchronized”?

    2) Why does “notifyMyTest()” execute “data.clone()”??

    3) For realizing callback, do I always have to implement an interface that extends java.util.EventListener??? If I don’t make it, for example I use an interface don’t extends java.util.EventListener, does it work???

    Thanks in advance!!!!!

    Alessio

    Reply
    • Yair Altman says:
      March 9, 2011 at 8:52 am

      @Alessio –

      1 + 2) this is an attempt to make the code re-entrant, i.e. enable several Java threads to access the class concurrently. Note that only the code surrounding access to data is synchronized.

      3) java.util.EventListener is an interface without any declared fields, properties or methods. It is simply used as a flag to indicate that the object is, well, an EventListener. All of your interface’s internal methods (testEvent() in this case) are user-defined methods. Behind the scenes, Matlab converts all such Java methods into Matlab callbacks, so testEvent() is automatically converted into TestEventCallback. In short – feel free to test variations of my code (it won’t bite you). Now that you have a working base, this should be easy. It was much harder for me when I didn’t have an initial working base…

  6. Dan says:
    March 17, 2011 at 5:30 am

    Dear Yair, though this request might seem out of topic, I would like to ask you if, referring to your sentence above ” Few other challenges were as difficult, yet with a happy ending (Drag & Drop is a similar issue – I will describe it in another article sometime) “, you could kindly point me to that “happy ending” you mention.

    I am trying to implement a Drag & Drop function that would allow me to rearrange a Matlab listbox rows with a mouse drag & drop technique on the same listbox (that is, by dragging and dropping its rows in the desired position).

    All I have been able to find on the subject (close to), was a discussion by you and others left unfinished on the Mathworks website back in 2009.

    Thank you in advance.

    Dan

    Reply
  7. iroln says:
    March 17, 2011 at 8:07 am

    Hi Yair,

    Is it possible to somehow handle the event PaintEvent of Java component in MATLAB (override methods paint and update)?

    For example, I’m creating a JPanel in MATLAB window and want to catch the paint event in a MATLAB function.

    hf = figure; 
jhp = javacomponent(javax.swing.JPanel, [10 10 200 200], hf);
 
function paint()
     % this processing of event PaintEvent for jhp
end

    Can I do this? Can I do write a class in Java, which is derived from JPanel with events for the paint()?

    Reply
    • Yair Altman says:
      March 20, 2011 at 3:28 pm

      @Iroln – this is an interesting idea. I never tried it, but I see no reason (except performance) why you cannot create a new Java class that derives JPanel and have the event delegated to Matlab using the mechanism described in the article above. Note that the paint event needs to receive the correct parameters (Graphics object and whatnot).

      Interesting idea indeed – please do post your findings (or a sample code) here, after you have experimented with it.

  8. Frank says:
    March 27, 2011 at 12:07 pm

    Thanks Yair for this post.
    However, I’m doing everything your way and when I use your last line
    ‘hListener = handle.listener(handle(evt),’TestEvent’,callback) ‘
    I get the error = Undefined function or variable ‘Callback’
    Is there anything missing ?

    Reply
    • Yair Altman says:
      March 27, 2011 at 12:38 pm

      @Frank – you forgot to define your callback, so of course you get an error when you try to use it in your listener. In my code I used the following callback definition:

      callback = @(o,e) cbBridge(o,e,response);
    • Frank says:
      March 28, 2011 at 5:59 pm

      Thanks for the answer Yair. I’m still struggling a bit. How can I get the oldValue and newValue in Matlab on every event ? May be with the hgfeval but I still don’t see how. Does a getvalue in the class myTestEvent would allow this and how would be the optimal way to get it from hgfeval ?

    • Yair Altman says:
      March 29, 2011 at 12:43 am

      @Frank – since both oldValue and newValue were declared as public, you can access them in your callback function as follows:

      function myCallbackFcn(hObject, eventData)
  oldVal = eventData.oldValue;
  newVal = eventData.newValue;
  ...
end  %myCallbackFcn

      Of course, a better way would be to declare oldValue and newValue as private in the Java class, and to have only public accessor methods. For example:

      public class MyTestEvent extends java.util.EventObject {
  private static final long serialVersionUID = 1L;
  private float oldValue, newValue;
  public float getOldValue() { return oldValue; }
  public float getNewValue() { return newValue; }
  MyTestEvent(Object obj, float oldValue, float newValue) {
    super(obj);
    this.oldValue = oldValue;
    this.newValue = newValue;
  }
}

      You would then access these values in the Matlab callback as follows:

      function myCallbackFcn(hObject, eventData)
  oldVal = eventData.getOldValue;  % alternative #1
  oldVal = get(eventData,'OldValue');  % alternative #2
  ...
end  %myCallbackFcn
  9. Alessio says:
    March 29, 2011 at 7:55 am

    Hi,

    Using the callback mechanism shown above, I realized a simple MATLAB + JAVA application that, from a “Java Layer”, generates Java event handled by Matlab function. In the software developed, Java code was inserted in a ‘.jar’ file (jar_app.jar). If I test the JAVA + MATLAB application developed using MATLAB, it works fine, but if I create an executable with MATLAB Compiler for it using the command

    mcc -m Demo_ Matlab_Java_App.m

    and then execute it from command prompt, I have the following error:

    java.lang.NullPointerException 
at com.mathworks.jmi.bean.MatlabBeanInterface.addCallback(MatlabBeanInterface.java:765) 
at com.mathworks.jmi.bean.MatlabCallbackInterface.addCallback(MatlabCallbackInterface.java:128)

    Reading other posts regarding this exception, it seems (but I’m not sure…) that ‘.jar’ file with java code isn’t detected; Probably, executable doesn’t access to the MATLAB “classpath.txt” file.
    Also, in Matlab code, I add this instruction:

    javaaddpath('C:\Alessio\workspace_matlab\new_app\jar_app.jar');

    but I think that it is unuseless; executable dosen’t work… How can I do to resolve this problem and realize a working executable??
    I hope that problem is clear… If it isn’t clear, please tell me, thank you…

    greetings

    Reply
    • Yair Altman says:
      March 29, 2011 at 8:18 am

      @Alessio – your theory is correct: the error that you see is exactly the error that can be seen in a regular Matlab desktop when trying to set callbacks to Java classes that were added using the dynamic (rather than the static) Java classpath.

      Try to place a classpath.txt file that contains your JAR file in your compiled application’s start-up folder. If my hunch is correct, this could solve your problem.

    • Alessio says:
      March 30, 2011 at 1:12 am

      Thanks Yair for your suggest…Finally, now all works fine ;-) !!!!!!!!!!!

      Again, Thanks a lot for all!!!!

  10. Alessio says:
    June 17, 2011 at 7:21 am

    Hi Yair,

    I just realized a new Java + Matlab application using Matlab Callback for Java Events mechanism that you suggest in this article. Java-side, I have a net-application containing a Server Thread and a Client Thread; Server Thread, after opening a ServerSocket, acquires a value (randomly generated at the moment) every 50 msec (“production value” rate), places it in a byte array (length 2) together with a sequence number (generated value in array position 1 seqNo in array position 2), and send it to the Java Client Thread through socket. Client Thread receives byte array (value + seqNo), puts it in a java event and finally notifies Matlab application using testEvent(event) method. The Matlab function invoked after the call of ‘testEvent(event)’ processes the value contained in the event and writes it in a ‘.txt’ file.

    After executing some test, I noticed that sometimes prints on file realized from Matlab after testEvent(event) invocations aren’t executed in the correct order; For example, if Java Client Thread receives byte arrays in the order , , , , , could be that Matlab printing (and processing) function writes this sequence (for example) in this order: , , , , even if the invocation of eventTest(event) are the following: eventTest(event()), eventTest(event()), eventTest(event()), eventTest(event()), eventTest(event()), eventTest(event())…

    Is testEvent(event) a synchronous method? If it isn’t, how can I do to have synchronous called of testEvent(event) method???

    Certainly, it isn’t a Matlab ‘printf’ problem. Infact, during debugging, I print on screen the event received from Matlab printing and processing function, the “call order” isn’t respected….

    I hope that my problem is clear….If it isn’t, please tell me, thank you!!

    Thanks a lot!!!

    Reply
    • Alessio says:
      June 17, 2011 at 7:53 am

      I have a problem in posting the message….I repeat the second part of message here…

      After executing some test, I noticed that sometimes prints on file realized from Matlab after testEvent(event) invocations aren’t executed in the correct order; For example, if Java Client Thread receives byte arrays in the order, {val0, 50}, {val1, 51}, {val2, 52}, {val3, 53}, {val4, 54} could be that Matlab printing (and processing) function writes this sequence (for example) in this order: {val2, 52}, {val3, 53}, {val4, 54}, {val0, 50}, {val1, 51}, even if the invocation of eventTest(event) are the following: eventTest(event({val0, 50})), eventTest(event({val1, 51})), eventTest(event({val2, 52})), eventTest(event({val3, 53})), eventTest(event({val4, 54}))…

    • michele says:
      August 12, 2011 at 9:59 am

      Hey guys, any luck regarding this? I’m observing the same behavior and I was wondering if you found a way to capture events in the same order as they’ve been dispatched.

      Thanks

  11. matlab says:
    September 5, 2011 at 2:33 am

    well done !!!!!!!! that’s it vat I need…..!

    Reply

  12. Pingback: Matlab-Java memory leaks, performance | Undocumented Matlab

  13. Lex says:
    February 9, 2012 at 8:43 am

    Hi,

    I try to start your example, but maybe don’t understand something.

     evt.notifyMyTest

    doesn’t show any result as in your case.

    I tried to debug it, but

    java.util.Vector data

    is empty, so it won’t be notified any of listeners. What do I do wrong?

    Here is my code in matlab:

    evt = package.EventTest
set(evt)
set(evt,'TestEventCallback',@(h,e)disp(h))
evt.notifyMyTest

    Should set(evt,’TestEventCallback’,@(h,e)disp(h)) add a listener? Or were do I add a listener?

    Thanks

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*

<pre lang="matlab">
a = magic(3);
sum(a)
</pre>