Structures

The easiest way to create a structure is to have it derived from a SQL statement as part of generating a method implementation from SQL. You can also derive a structure from a SQL statement or from a table definition as a separate action.

Finally, it is also possible to create a structure by defining all its aspects manually in the Structures window or tab. To do this, choose Define, Structures from the menu.

Structures in USoft Service Definer are used to easily consume and produce, in a REST service, both JSON and XML data formats. You can use the same structure to generate JSON or XML or both.

Accepts attribute

If a structure is specified as input parameter of a REST method, you can have the runtime Services Framework convert the XML or JSON format of the posted input data to fields in the structure. Do this by specifying, in Service Definer, one of the following media types as the value of the Accepts attribute of the method:

At runtime, the client specifies the actual format of the request message by setting the Content-Type HTTP header.

The Accepts attribute must be empty if the HTTP verb is GET. The default value for the Accepts attribute is 'text/xml'.

Produces attribute

Likewise, if a structure is specified as return parameter of a REST method, you can have the runtime Services Platform pass the return data produced by the method as either XML or JSON. Do this by specifying, in Service Definer, one of the following media types as the value of the Produces attribute of the method:

At runtime, the client specifies the actual format of the reponse message by setting the Accept HTTP header.

The default value for the Produces attribute is 'text/xml'.

Structures in USoft Service Definer are also used to easily get or set the output or input of a SQL statement.

At runtime, USoft will automatically fill the fields of a structure with the output of a SELECT statement if the field specifies a mapping to a output column in the SQL Statement. The mapping may be specified as Annotation of a field, using the syntax @Column(name="<label name>").

Example

@Column(name="RES_ID") indicates that a field corresponds to an output column of a SQL Statement that has RES_ID as its column name or alias name.

If a structure is specified as input parameter of a REST method, you can have the runtime Services Framework automatically setting host variables in a SQL Statement to incoming data values. Do this by setting the Annotation attribute of the field using the syntax @Column(name="<host variable name>").

In this scenario,you do not need to create structures by manual coding. The necessary structures are automatically created when you generate a REST method from the SQL statement. In the SQL statement, the name of the structure is used in the host variable. The syntax is :<structure name>.<field name>.

Example

In this SQL statement, the name of the structure is 'MyPersonNameStructure':

The input parameter ':id' in the WHERE clause is of a different type than the host variables in the SET clause. This input parameter is passed at runtime as part of the request URL of the REST service.

In this example, the structure is used as follows in the Implementation of the method:

where UPDATE_PERSON is the name of the SQL statement.

If the output of a SQL statement has multiple rows you can use arrays of structures to receive all rows. The syntax is: MyReservationStructure[], where MyReservationStructure is the name of the structure. For example, you can write as the Implementation of a method:

If the output or input of a REST Service contains has a list of elements held in an XML or JSON array, you can use the same syntax MyReservationStructure[] in the Type field of the Parameter. Such a list of elements could look like this in XML:

Or it could look like this in JSON:

Using annotations, you can map data in incoming and outgoing XML messages variously to XML elements or to XML attributes:

•To specify that a field of a structure maps to an element in the XML structure, specify @XmlElement(name="<xml element name>") as Annotation for the field.

•To specify that a field of a structure maps to an attribute in the XML structure, specify @XmlAttribute(name="<attribute name>") as Annotation for the field.

Example

You have a REST service that produces the following XML response message on the basis of a structure named MyPersonStructure:

You want this output to look like this:

To achieve this, follow these steps:

@Entity;@XmlRootElement(name="Client")

@Column(name="PERSON_ID");@XmlAttribute(name="ID")

@Column(name="FIRST_NAME");@XmlElement(name="FirstName")

@Column(name="FAMILY_NAME");@XmlElement(name="Surname")

In the Implementation code of a method, you can access data from a structure, for example (for a structure named "MyBookingStructure"):

and then use that data in a subsequent sql() function in that same Implementation code, for example: