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: Applicable for the supported Java native classes and wrapper classes.
- Specifications for user-defined interface classes: Applicable for the user-defined interfaces, including the method declaration of API call.
- Specifications for user-defined entity classes: Applicable for the user-defined entity classes (including field declaration). Method parameters or returned value, and other user-defined entity classes will be referenced.
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
ordescription
, 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:
public class Req {
private Map<String,List<Person>> map; //Container type cannot be multilayer nested.
private List<Map<Person>> list; //Container type cannot be multilayer nested.
private List list1; //List or Map must have generic information.
private Map map1; //List or Map must have generic information.
private List<Person[]> listArray; //The generic information of List/Map cannot be array.
private byte b; //It cannot be single byte.
private Person[] personArray; //Object array is not supported. You must replace it with List.
private String description; //Attribute name cannot be `description`.
}
Supported data types
boolean, char, double, float, int, long, short
java.lang.Boolean
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.String
java.util.List (hereinafter referred to as "List"), but it must use type parameter and cannot use its concrete sub classes.
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.
Enum
byte[]
Correct example:
public class Req {
private String s = "ss";
private int i;
private double d;
private Long l;
private long l1;
private boolean b;
private List<String> stringList;
private List<Person> personList;
private Map<String,Person> map;
private byte[] bytes;
private EnumType type;
}
public class Person {
private String name;
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:
Map<String,String[]>
Map<String,List<Person>>(Person is a concrete entity class)
List<Map<String,Persion>>
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.