All Products
Search
Document Center

Service interface definition specifications

Last Updated: Jan 28, 2021

Given the limitations on mobile development environment (especially iOS system) and to keep simple interface definition, you are not allowed to use the full collection of Java syntax when defining mobile service interfaces on servers. The interface definition specifications involve the following three categories:

Specifications for internally supported data classes

Unsupported data types

  • Container type cannot be multilayer nested.
  • List or Map must have generic information.
  • The generic information of List/Map cannot be array.
  • Single byte is not supported. Byte data byte [] is supported.
  • Object array is not supported. You must replace it with List.
  • Attribute name cannot be data or description, otherwise it might conflict with iOS attribute.
  • The key of Map type must be String.
  • Type cannot be abstract class.
  • Type cannot be interface class.

Incorrect example:

  1. public class Req {
  2. private Map<String,List<Person>> map; //Container type cannot be multilayer nested.
  3. private List<Map<Person>> list; //Container type cannot be multilayer nested.
  4. private List list1; //List or Map must have generic information.
  5. private Map map1; //List or Map must have generic information.
  6. private List<Person[]> listArray; //The generic information of List/Map cannot be array.
  7. private byte b; //It cannot be single byte.
  8. private Person[] personArray; //Object array is not supported. You must replace it with List.
  9. private String description; //Attribute name cannot be `description`.
  10. }

Supported data types

  1. boolean, char, double, float, int, long, short
  2. java.lang.Boolean
  3. java.lang.Character
  4. java.lang.Double
  5. java.lang.Float
  6. java.lang.Integer
  7. java.lang.Long
  8. java.lang.Short
  9. java.lang.String
  10. java.util.List (hereinafter referred to as "List"), but it must use type parameter and cannot use its concrete sub classes.
  11. java.util. Map (hereinafter referred to as " Map"), but it must use type parameter and cannot use its concrete sub classes. The key type must be string.
  12. Enum
  13. byte[]

Correct example:

  1. public class Req {
  2. private String s = "ss";
  3. private int i;
  4. private double d;
  5. private Long l;
  6. private long l1;
  7. private boolean b;
  8. private List<String> stringList;
  9. private List<Person> personList;
  10. private Map<String,Person> map;
  11. private byte[] bytes;
  12. private EnumType type;
  13. }
  14. public class Person {
  15. private String name;
  16. private int age;

Specifications for user-defined interface classes

Parameters of method

Reference not allowed for:

  • Enum type
  • Generic types except Map, List, and Set mentioned above
  • Abstract class
  • Interface class
  • Native array

Reference allowed for:

  • Concrete entity class. The reference type and actual object type must keep consistent. It is not allowed to use parent class to point to sub class objects.
  • Internally supported data class, but the collection types such as array, Map, List, and Set cannot be nested.

Incorrect example:

  1. Map<String,String[]>
  2. Map<String,List<Person>>(Person is a concrete entity class)
  3. List<Map<String,Persion>>
  4. List<Persion[]>

Returned value of method

Reference not allowed for:

  • Enum type
  • Generic types except Map, List, and Set mentioned above
  • Abstract class
  • Interface class
  • Native array

Reference allowed for:

  • Concrete data class. The reference type and actual object type must keep consistent. It is not allowed to use parent class to point to sub class objects. For example, you cannot use Object reference to point to other objects.

    Note: If the parent class is a concrete class, the generation tool cannot detect the error of such class.

  • Internally supported data class, see the content at the beginning of this article. The collection types such as array, Map, List, and Set cannot be nested. See the example mentioned above.

Definition of method

  • Use @OperationType annotation. The method without this annotation will be ignored.
  • The method cannot be overloaded.

Limitations on code generation tools

  • Allow the inheritance that is defined in the interface class, but the hierarchical relations will be merged.
  • Allow but ignore the variables that are defined in the interface class.
  • Allow but ignore the method declaration in the interface class.
  • One source file can only contain the definition of one interface class, and the definition of other classes (internal class, anonymous class, etc.) are not allowed.
  • The interface class defines itself and the types it references must be the internally supported data class, or can obtain the definition from source codes.

Specifications for user-defined entity classes

Definition of field

Reference not allowed for:

  • Enum type
  • Generic types except Map, List, and Set mentioned above
  • Abstract class
  • Interface class
  • Native array

Reference allowed for:

  • Concrete entity class. The reference type and actual object type must keep consistent. It is not allowed to use parent class to point to sub class objects.
  • Internally supported data class, but the collection types such as array, Map, List, and Set cannot be nested. See the example mentioned above.
  • The attributes with modifier including transient will be ignored.
  • Constants defined by using final static int. Other constants that don’t meet this requirement or static variables will be ignored.

    It is not recommended to define the member variables beginning with is.

Definition of class

  • A class can inherit from other entity class.
  • Ignore its method declaration. The generation tool will automatically generate setter/getter method based on the entity class’ fields.

Limitations on code generation tools

  • The attribute declaration must be one per line.
  • Allow but ignore the interfaces that are implemented by user-defined entity class.
  • One source file can only contain the definition of one user-defined entity class, and the definition of other classes (internal class, anonymous class, etc.) are not allowed.
  • The interface class defines itself and the types it references must be the internally supported data class, or can obtain the definition from source codes.