Skip to content

Home

Jump to bottom
Oleg Smirnov edited this page Nov 18, 2021 · 1 revision

Welcome to the th2-codec-json wiki!

There you will find information about supported attributes for describing the message you need.

Defining messages

Depending on the messageTypeDetection parameter you will need to define messages in different ways.

messageTypeDetection == BY_HTTP_METHOD_AND_URI

This method is used for working with HTTP-like connections.

The message that is a request must have the following attributes:

  • Response of type java.lang.String - contains information about the excepted response on that request
  • Method of type java.lang.String - the HTTP method that should be used for that request
  • URI of type java.lang.String - the URI path that should be associated with that request.

Those attributes must be added to the request message only. The response message will be linked by the value in the Response attribute.

And more about those attributes in detail:

Response

This attribute should have the name of the response message from the dictionary. It is the attribute name in the message definition.

Example:

<message name="RequestMessageName">
  <attribute name="Response" type="java.lang.String">ResponseMessageName</attribute>
  //..
</message>
<message name="ResponseMessageName">
  //..
</message>

Method

The value for this attribute is one of the existing HTTP methods. The method name should be in the upper case.

Example:

<message name="RequestMessageName">
  <attribute name="Response" type="java.lang.String">ResponseMessageName</attribute>
  <attribute name="Method" type="java.lang.String">POST</attribute>
  //..
</message>

URI

Please, notice that this attribute should contain part of the URL that follows the host URL. E.g the host URL is https://some.host.com and you want to send a request to https://some.host.com/api/something. The attribute value should have the following value in that case: /api/something

Example:

<message name="RequestMessageName">
  <attribute name="Response" type="java.lang.String">ResponseMessageName</attribute>
  <attribute name="Method" type="java.lang.String">POST</attribute>
  <attribute name="URI" type="java.lang.String">/api/something</attribute>
  //..
</message>

The URI parameter might have variables. You can add them using the following structure: {valueName}. To pass the actual values you should define a field with the name URI in your message. It also should have an attribute IsURIParam of type java.lang.Boolean with the value true. The field should have a reference to another message that contains all required parameters for filling the URI.

Example:

<message name="YouParameters" id="M_YouParameters">
  <field name="id" type="java.lang.Long"/>
</message>

<message name="RequestMessageName">
  <attribute name="Response" type="java.lang.String">ResponseMessageName</attribute>
  <attribute name="Method" type="java.lang.String">GET</attribute>
  <attribute name="URI" type="java.lang.String">/api/something/{id}</attribute>
  <field name="URI" reference="M_YouParameters">
    <attribute name="IsURIParam" type="java.lang.Boolean">true</attribute>
  </field>
  //..
</message>

messageTypeDetection == BY_INNER_FIELD

In this case, each message that might be received by this codec should have:

  • the attribute MessageType of type java.lang.String that contains a value associated with that message
  • the field in the structure that matches the name specified in the messageTypeField parameter

Example:

Configuration:

  custom-config:
    codecSettings:
      messageTypeDetection: BY_INNER_FIELD
      messageTypeField: "type"

Message:

<message name="SomeMessage">
  <attribute name="MessageType" type="java.lang.String">T</attribute>
  <field name="type" type="java.lang.String"/>
</message>

Fields' and messages' attributes for customizing the JSON format

FieldName

The FieldName can be used to customize the name that the field should have in the JSON. For example, it must have spaces or some characters that are prohibited for fields names in the dictionary.

Example:

JSON structure:

{
  "User ID": 42
}

Message definition:

<message name="Test">
  <field name="userID" type="java.lang.Long">
    <attribute name="FieldName" type="java.lang.String">User ID</attribute>
  </field>
</message>

fromArray

The attribute can be used when the JSON value is an array of fixed length and you want to match them to the fields in the message. The values from the array will be mapped to the fields in the massage in order of their appearance. If the array contains more elements when the number of fields in the expected message the extra will be added as "Field" (they will be reported as unexpected if rejectUnexpectedFields is enabled or dropped if this parameter is disabled)

Example for the root message:

JSON structure:

[
  42,
  "a",
  "something else"
]

Message structure:

<message name="Test">
  <attribute name="fromArray" type="java.lang.Boolean">true</attribute>
  <field name="userID" type="java.lang.Long"/>
  <field name="code" type="java.lang.String"/>
  <field name="comment" type="java.lang.String"/>
</message>

Example for an inner message:

JSON structure:

{
  "info": [
    42,
    "a",
    "something else"
  ]
}

Message structure:

<message name="Test">
  <field name="info" reference="M_Inner">
    <attribute name="fromArray" type="java.lang.Boolean">true</attribute>
  </field>
</message>
<message name="Inner">
  <field name="userID" type="java.lang.Long"/>
  <field name="code" type="java.lang.String"/>
  <field name="comment" type="java.lang.String"/>
</message>

isSimpleRootValue

This attribute can be used if the JSON data is a simple value (not a JSON object). If you want to use this attribute the message must have a single writable field (fields with STUB or IsURIParam attributes are exluded)

Example:

JSON structure:

42

Message structure:

<message name="Test">
  <attribute name="isSimpleRootValue" type="java.lang.Boolean">true</attribute>
  <field name="userID" type="java.lang.Long"/>
</message>

With other fields that are excluded:

<message name="Test">
  // ...
  <attribute name="isSimpleRootValue" type="java.lang.Boolean">true</attribute>
  <field name="URI" reference="M_YouParameters">
    <attribute name="IsURIParam" type="java.lang.Boolean">true</attribute>
  </field>
  <field name="userID" type="java.lang.Long"/>
</message>
Clone this wiki locally