com.mathworks.mps.client.annotations

## Annotation Type MWStructureList

-     @Target(value={METHOD,CONSTRUCTOR,TYPE})
       @Retention(value=RUNTIME)
      public @interface MWStructureList

  This annotation must be used for an interface with methods representing MATLAB functions which expect a struct as input or output. It is also required while defining a java class that represents a MATLAB struct that contains other java classes which also represent MATLAB struct types (struct-within-struct). An instance of `java.lang.Class` contained in this annotation should represent a java bean that fulfills the requirements of a MATLAB struct.

  When used as an input to a MATLAB function, the bean gets marshaled into a MATLAB struct. The names of the public properties of this bean are used as the field names of the MATLAB struct. The values of these properties are marshaled into the field values of the MATLAB struct.

  If a MATLAB function returns a struct as output, it is marshaled into one of the types contained in this annotation. A type with public properties with names matching the field names of the MATLAB struct is chosen as the target type. Users can also provide a constructor, with `ConstructorProperties` annotation, that assigns values to all the properties in one step instead of using multiple set methods.

  A struct in MATLAB can be used in various contexts. It can be used as input or output to a MATLAB function, as a value of one of the fields of another struct (struct-within-struct) or as a value of one of the elements in a cell array. The context in which the struct is used in MATLAB decides the use of the `MWStructureList` annotation on the java side. It can be used in following different ways:

  - For a method in the interface. Represents the input and/or output structs of only that method

               interface StudentSorter {
                   @MWStructureList({Student.class})
                   Student[] sortstudents(Student[] students) throws IOException, MATLABException;
               }

  - For an interface. Represents input and output structs common to all the methods of the interface

               @MWStructureList({Student.class})
               interface StudentSorter {
                   Student[] sortstudentsAscending(Student[] students) throws IOException, MATLABException;
                   Student[] sortstudentsDescending(Student[] students) throws IOException, MATLABException;
               }

    This is same as :

               interface StudentSorter {
                   @MWStructureList({Student.class})
                   Student[] sortstudentsAscending(Student[] students) throws IOException, MATLABException;
                   @MWStructureList({Student.class})
                   Student[] sortstudentsDescending(Student[] students) throws IOException, MATLABException;
               }

  - For a function with a cell array as input or output when one of the elements of the cell array in a struct. In the following example, `updateCart` function of the `ShoppingCart` interface represents a MATLAB function that is expecting a cell array containing various items which are struct types. `Books`, `Shoes` and `Clothes` are java beans which represent MATLAB struct types.

                 interface ShoppingCart {
                     @MWStructureList({Books.class,Shoes.class,Clothes.class})
                     void updateCart(Object[] cartItems) throws IOException, MATLABException;
                 }

  - Representing a struct within struct

    - Class level annotation representing all the other struct types contained within it. In the following example, `Employee` class has properties of type `JoiningDate` and `Department` which are also representing MATLAB struct types. For simplicity, we will not get into declarations of these children types. An instance of `Employee` will be marshaled into a MATLAB struct with field names `date` and `department`. The values of these fields will be struct types with appropriate field names decided by the implementations of classes `JoiningDate` and `Department`.

                   @MWStructureList({JoiningDate.class,Department.class})
                   public class Employee {
                       private JoiningDate date;
                       private Department dept;

                       public void setDate(JoiningDate date){
                           this.date = date;
                       }

                       public JoiningDate getDate() {
                           return date;
                       }

                       public void setDepartment(Department dept){
                           this.dept = dept;
                       }

                       public Department getDepartment() {
                           return dept;
                       }
                   }

    - Method level annotation for individual properties. In this case, please make sure that the `MWStructureList` annotation is used for both the `get` and `set` methods for the property. Thus, `Employee` class can also be written like following (it is not as concise as the previous implementation):

                   public class Employee {
                       private JoiningDate date;
                       private Department dept;

                       @MWStructureList({JoiningDate.class})
                       public void setDate(JoiningDate date){
                           this.date = date;
                       }

                       @MWStructureList({JoiningDate.class})
                       public JoiningDate getDate() {
                           return date;
                       }

                       @MWStructureList({Department.class})
                       public void setDepartment(Department dept){
                           this.dept = dept;
                       }

                       @MWStructureList({Department.class})
                       public Department getDepartment() {
                           return dept;
                       }
                   }

    - Constructor level annotation. Following is a different version of `Employee` class where it makes more sense to use the `MWStructureList` annotation at the method/constructor level. It should be noted that the `get` methods are used when an instance of `Employee` is passed as input to a method. The constructor with `ConstructorProperties` annotation is used when `Employee` is received as output of a method.

                   public class Employee {

                       private String name;
                       private int age;
                       private Car car;

                       @ConstructorProperties({"name","age","car"})
                       @MWStructureList({Car.class})
                       public Employee(String name, int age, Car car){
                           this.name = name;
                           this.age = age;
                           this.car = car;
                       }

                       public String getName(){
                           return name;
                       }

                       public int getAge(){
                           return age;
                       }

                       @MWStructureList({Car.class})
                       public Car getCar(){
                           return car;
                       }
                   }

- - ### Required Element Summary

    Required Elements
    Modifier and Type | Required Element and Description
    --- | ---
    `java.lang.Class[]` | `value`

- - ### Element Detail

    - #### value

          public abstract java.lang.Class[] value

Copyright 2010-2022 The MathWorks, Inc.