Constructing Parameters

Passing Parameters introduces the two methods for HTTP request parameters passing for REST services. As to the parameters for a specific resource, please refer to the corresponding parameter table introduced in the section of REST API. Below is the structure of the parameter table.

Item	Function
Field	The parameter name.
Type	The Java class corresponding to the parameter. This item indicates the parameter structure. Please refer to this item for parameter construction.
Definition	The description of the parameters.

Example parameters:

Field	Type	Definition
point2Ds	Point2D[]	Points set for measuring.
unit	unit	The unit of the expected result.

The Java type of point2Ds is Point2D[], which is a basic GIS object type in SuperMap iServer, representing two-dimensional geographic coordinates. The Java type of Parameter unit is Unit, which is an enumeration class in SuperMap iServer, representing the enumeration of distance units. They can be found in com.supermap.services.components.commontypes of iServer Javadoc.

There are two formats of parameters involved in SuperMap iServer REST services: JSON and XML. The construction of the parameters of both types are introduced below:

JSON format parameter construction
XML format parameter construction

1 JSON format parameter construction

1.1 JSON introduction

JSON is a lightweight data format. JSON is built on two structures:

A collection of name/value pairs.
An ordered list of values.

In JSON, they take on these forms:

An object is an unordered set of name/value pairs. An object begins with (left brace) and ends with (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma). For instance, value_a referred to in Passing Parameters can be {"A1":value1, "A2":value2}.
An array is an ordered collection of values. An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma). For instance, value_b referred to in Passing Parameters can be [value1, value2].

Where, value (e.g. value1, value2) can be string, number, true, false, null enclosed by double quotation marks, or an object, array constituting nested relations.

1.2 Parameter type and the corresponding relation with JSON

In SuperMap iServer REST API, there is description for the corresponding type (Java class) for each parameter. As mentioned before, the parameter construction takes the corresponding Java class as a reference. The description for a Java class can be found in the section of SuperMap iServer Java API.

The content related to constructing JSON format parameters includes:

Public member variables.
Attributes. The attribuThe name is a string with the initial lowercased. The string is a pair of get/set methods with get/set removed.

Their relationships with JSON are as follow:

Public member variable name/Value in Java corresponds to Name/value in JSON;
AttribuThe name/ Attribute value in Java corresponds to Name/Value in JSON.

The attribute values in Java have the following relationship with values in JSON:

Java

JSON

string

e.g.

String name="World";

string

e.g.

World

number

e.g.

double num=100.1;

number

e.g.

100.1

boolean

e.g.

boolean tag=false;

true/false

e.g.

false

null

e.g.

null

e.g.

null

Enumerated value

e.g.

Unit unit=Unit.METER;

Enumeration name expressed with a string.

e.g.

METER

other Java objectse.g.

e.g.

Point2D point=new Point2D(12.3, 15.6)

where the Point2D class has two public member variables: x and y.

JSON object

e.g.

{"x":12.3,"y":15.6}

Sample Array

e.g.

double[] scales=new double[]{1128.50, 564.25};

JSON array

e.g.

[1128.50, 564.25]

Java array

e.g.

Point2D[] points=new Point2D[2];

points[0]=new Point2D(1.1, 2.2);

points[1]=new Point2D(2.2, 3.3);

JSON array

Point2D[] corresponds to a JSON array: [value1,value2,…]. Each element in the array is a Point2D object. So the element in JSON array should be the JSON object corresponding to the Point2D object.

e.g.

[

{"x":1.1,"y":2.2},

{"x":2.2,"y":3.3}

]

Java list

e.g.

List<Point2D> lst = new ArrayList<Point2D>();

lst.add(new Point2D(1.1, 2.2));

JSON array

List<Point2D> corresponds to a JSON array: [value1,value2,…]. Each element in the array is a Point2D object. So the element in JSON array should be the JSON object corresponding to the Point2D object.

e.g.

[

{"x":1.1,"y":2.2},

{"x":2.2,"y":3.3}

]

The nested relations of Java objects corresponds to those of JSON.

2 XML format parameter construction

XML (eXtensible Markup Language) is a simple data storage language, using a series of simple tags to describe data. It is a very common data format in application development.

In the section of SuperMap iServer REST API, there is description for the corresponding type (Java class) for each parameter. The parameter construction takes the corresponding Java class as a reference. The description for a Java class can be found in the section of SuperMap iServer 6R Java API.

In REST API, the request body parameter can passed in XML format, which is got through XML serialization of Java objects. Below is the entity-body passing parameters in XML.

<Parameter 1>Serialization result of parameter 1</parameter 1>

<Parameter 2>Serialization result of parameter 1</parameter 2>

��

</Object>

The XML representation of a parameter named unit, of the Unit type, is as follows:

<unit>METER </unit>

The XML representation of a parameter named point, of the Point2D type, is as follows:

<point>

</point>

The XML representation of a parameter named points of the List<Point2D> type, is as follows:

</Point2D>

</Point2D>

</points>

Constructing Parameters

1 JSON format parameter construction

1.1 JSON introduction

1.2 Parameter type and the corresponding relation with JSON

2 XML format parameter construction

See