Inconsistent array notation in Java interface generated by MATLAB Compiler SDK?

To call Matlab functions from Java, MATLAB's Compiler SDK generates functions with the following signatures.

/* mlx interface - List version*/                   
public void mysum(List lhs, List rhs)               
throws MWException                                  
                                                    
/* mlx interface - Array version*/                  
public void mysum(Object[] lhs, Object[] rhs)       
throws MWException                                  
                                                    
/* standard interface - no inputs */                
public Object[] mysum(int nargout)                  
throws MWException                                  
                                                    
/* standard interface - variable inputs */          
public Object[] mysum(int nargout, Object varargin) 
throws MWException                                  

Here, `mlx` seems to refer to an signature convention, and speculatively, the reasons for the name seem to be no longer relevant in the current context.

Here is an example invocation from within function getsum:

public double getsum(double[] vals) throws MWException              
{                                                                   
   myclass cls = null;  // Class containing the generated functions 
   Object[] x = {vals};                                             
   Object[] y = null;                                               
                                                                    
   try                                                              
   {                                                                
      cls = new myclass();                                          
      y = cls.mysum(1, x);                                          
                                                                    
...snip...                                                          

"[O]bject array [x] of length 1 is created and initialized with a reference to the supplied double array. This argument is passed to the mysum method. The result is known to be a scalar double..." The invocation matches 4th and last signature above.

Why is argument x of type Object array (Object[] x) when the 4th signature shows a scalar Object (Object varargin)?

I realize that an array itself (i.e., Object[] x) is also an Object, but if that is how the prototypes are to be interpretted, then why is the array nature of the arguments explicit in the 2nd prototype above (Object[] rhs) but not the 4th prototype (Object varargin)?

Answer 1

[Todd Flanagan]

You are correct that mlx is a convention. It refers to a c style interface that is familiar to people using other c-style MATLAB interfaces.

I don't know the specifics of why the particular signature was chosen and what the design trade offs were, but the signature does expect and Object [] array to be passed in as Object per the documentation.

In all cases, the varargin argument is passed as type Object. This lets you provide any number of inputs in the form of an array of Object, that is Object[], and the contents of this array are passed to the compiled MATLAB function in the order in which they appear in the array.

[FM]

Hi, Todd,

Would you believe me if I said that I totally get the inability to understand the reason for the convention? (Rhetorical question).

I just want to clarify that this question is about the inconsistency in the notation. It makes a newbie reader question whether one is really understanding the specification correctly.

Should readers try to make the same sense out of all the prototype conventions? If so, it means that the reader (me in this case) is missing something fundamental.

If the reader is simply supposed to accept that the conventions are different for historical reasons, that's a very important point that needs to be stated in no uncertain terms, in my opinion.

[Todd Flanagan]

...snip...

Should readers try to make the same sense out of all the prototype conventions? If so, it means that the reader (me in this case) is missing something fundamental.

...snip...

The number of signatures can definitely be overwhelming and we don't expect users to master them all. Once someone adopts a convention, we don't want to make them change their code later on, so we keep generating them. In no uncertain terms, I do not think you need to understand all of the signatures.

We stick to preferred signatures in our doc and examples. Since that doesn't always have the signatures you are looking for, we do provide sample generation in the libraryCompiler App. This lets you write a sample of how you would call the funciton in MATLAB and it will generate a sample in Java that you can look at and see how the data is constructed and the function is called.

I use the product quite regularly and prefer to use sample generation rather than write the Java myself. It is pretty convenient, particularly with the more intricate data types like structs and cells.

I updated one of your other questions with a struct example.

[FM]

Thanks, Todd. As a total newbie to Java, I don't yet have a convention. However, I may either have to accommodate a variable input argument list and somehow found a way to provide the name/value pairing of arguments that Matlabbers are use to. Better yet, do that and/or also provide a way to supply name/value pairs as struct properties/fields. When I see the different signature conventions, I will in fact choose one, but it was unclear that the actual notation had to be interpretted differently in order to understand them (one have explicit square brackets while the other does not).

Based on your explanation, I will resort to the standard interface, and I'll look into your example of a struct. Much appreciated.

[Todd Flanagan]

If you have a specific function signature with vararg and whatever else, I can put together a quick example. Just post it in the comments and I will add it to the answer.

[FM]

I appreciate the offer, Todd. With the clarity about different notations between standard/mlx interface, your advice on preferring the former, and your example coding of Matlab structs in Java, I'm going to see if I can cobble it together myself.

[FM]

Just a possible correction to the documentation: "In all cases, the varargin argument is passed as type Object". Of the four signatures, only the 4th contains "varargin". Notwithstanding argument name differences, I suspect that the statement only applies to the the 2nd & 4th signatures. It may apply to the 1st signature, which uses a "List" argument, but I'm not sure whether the ensuing sentence applies: "This lets you provide any number of inputs in the form of an array of Object, that is Object[]...". That depends on whether "List" qualifies as a form of "Object[]". Not being a seasoned veteran in Java, I could very well be wrong, but my OOP gut tells me that an instance of "List" is not an array of something, even though it may use an array internally. I followed List's class ancestory as far as "Iterable" and did not see any indication that List was a form of Object[]: https://docs.oracle.com/javase/8/docs/api/java/util/List.html