7.2. Message Structure

From the perspective of a service, the most important component of a message is the body. This is because it is used to convey information specific to the business logic. Both client and service must understand each other to interact. This understanding involves an agreement on the mode of transport (such as Java Message Service or HTTP) and the dialect to be used (the format in which the data is to appear in the message).
To take the simple case of a client sending a message directly to the example flight reservation service, you would need to decide how the service is going to determine which of the operations is concerned with the message. In this case, the developer decides that the opcode (operation code) will appear in the body as a string (reserve, query, upgrade) at the location called org.example.flight.opcode. Any other string value (or the absence of a value) will result in the message being considered illegal.

Important

Ensure that every value within a message is given a unique name. This prevents clashes with other clients and services.
The Message Body is the primary way in which data should be exchanged between clients and services. It is flexible enough to contain any number of arbitrary data types. (The other parameters required to execute the business logic associated with each operation should be suitably encoded.)
  • “org.example.flight.seatnumber” for the seat number, which will be an integer.
  • “org.example.flight.flightnumber” for the flight number, which will be a String.
  • “org.example.flight.upgradenumber” for the upgraded seat number, which will be an integer.

Table 7.1. Operation Parameters

Operation opcode seatnumber flightnumber upgradenumber
reserveSeat String: reserve integer String N/A
querySeat String: query integer String N/A
upgradeSeat String: upgrade integer String integer

All of these operations return information to the client by encapsulating it within a message. Response messages go through the same processes in order for their own formats to be determined. For simplicity, the response messages will be left out of this example.
Build the service using one or more actions. These pre-process the incoming message and transform its contents, before passing it on to the action which is responsible for the main business logic. Each of these actions can be written in isolation (possibly by different groups within the same organisation or even by completely different organisations). Always make sure that each action has a unique view of the message data upon which it acts. If this is not the case, it is possible that chained actions may either overwrite or otherwise interfere with each other.