How formatters work

Operations, operation steps, and services use formatters to convert data items into formatted strings and to update data elements. The following is a description of how the toolkit creates the formatted strings:

  1. The toolkit initializes the formatter instance using an external definition. This definition can be in the toolkit format definition file or it can be in an operation or processor self-defined file.
  2. A toolkit entity such as an operation needs to convert a data element into a string representation of the data element with a particular format. It calls the format method of a formatter instance and passes the context that contains name of the data element instance that requires conversion. An instance variable in the formatter instance stores the name of the data element that the formatter will convert.
  3. The formatter converts the data element into a string according to how the formatter was defined.
  4. The formatter may call a decorator to apply additional formatting to the string.

Alternatively, if the toolkit entity needs to update a data element from a formatted string, the process would be:

  1. A toolkit entity such as an operation needs to convert a string into a data element. If needed, the entity calls one or more decorators to modify the string so that a formatter can process the string.
  2. The toolkit initializes the formatter instance using an external definition. This definition can be in the toolkit format definition file or it can be in an operation or processor self-defined file.
  3. The entity calls the unformat method of the formatter instance and passes the data element and the string that requires parsing.
  4. The formatter extracts the substring from the passed string.
  5. If the formatter is a decorator, the format removes the decoration.
  6. The formatter parses the substring.
  7. The formatter the updates the data element with the results of parsing the substring.

The toolkit entity can also just obtain a substring in the string such as obtaining a particular data field string from a collection. To do this, the toolkit entity uses the extract method and passes the string. The formatter identifies the substring and extracts (and removes) it. The formatter then passes the extracted substring and the remaining string as elements in an array.

If the formatting process requires one or more decorators to modify the formatted string, the toolkit entity calls the appropriate method (addDecoration or removeDecoration) in the decorator. The decorator then calls the format or unformat method of the formatter (or calls other decorators if the string needs additional modification before it calls the formatter.)