Go: Marshal Method for FTL Messages

Methods

The Message type has two methods to conveniently import and export message fields:

• Marshal imports a Go structure or map into an FTL message.
• Unmarshal exports the fields of an FTL message to a Go structure or map.

FTL marshaling and unmarshaling support only those maps with key type string.

Marshaling ignores nil as the field value of a Go structure and as a slice element.

FTL Numeric Field Types

FTL messages store all Go language integral types as TIB_FIELD_TYPE_LONG fields, corresponding to the Go language type int64.

FTL messages store all Go language floating-point types as TIB_FIELD_TYPE_DOUBLE fields, corresponding to the Go language type float64.

These designations apply within the following tables.

• IT refers to any of the following integral types: int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, uintptr, bool.
• FT refers to any of the following floating-point types: float32, float64.

Field Tags in struct Definitions

For convenience, you can use field tags to guide marshaling and unmarshaling (similar to JSON processing). For example:

type myStructType struct {
    myFieldA   int `json:"my_field_A" ftl:"myFieldA"`
    myFieldB   int `json:"my_field_B" ftl:"myFieldB,strict"`
    myFieldC   int `json:"my_field_C" ftl:"myFieldC,zeromissing,omitzero"`
}

FTL software recognizes tags with this general form:

ftl:"<fieldname>[,<options>]"

• <fieldname> is the name of a field in an FTL message, corresponding to the tagged field of the Go struct definition.
• <options> is a comma-separated list of options to apply marshaling and unmarshaling the field (see the following table).
• Separate the individual tags with a space character. Each line of the example illustrates this with a space between the JSON tag and FTL tag.

Examples

The FTL go API provides a simple mechanism for marshaling structures into an FTL message, and for unmarshaing FTL messages into a structure. The use of field tags is similar to that found in the encoding/json package. Note that structure fields must be exportable in order to be marshaled or unmarshaled. In simple terms, this means the field name must begin with an upper-case letter.

Marshal/unmarshal also supports the use of maps, in the form map[string]interface{}. In this case, the FTL field name corresponds to the map entry key, and the FTL field value corresponds to the map entry value.

The following example unmarshals message data into a Go structure:

type HelloMessage struct {
	Type  string `ftl:"type"`
	Message string `ftl:"message"`
}
func main() {
	// Create an instance of the HelloMessage structure. Then unmarshal
	// the message into the structure, based on the tags attached to 
	// each field in the structure.
	//
	// Note that a pointer to the structure (or map) must be passed to 
	// the Unmarshal() function.
	helloMsg := HelloMessage{}
	if err = msg.Unmarshal(&helloMsg); err != nil {
	log.Fatal(ftl.ErrStack(err))
	}
	// Print the message contents, both as a formatted FTL message
	// (via the message String() function) and the as the
	// unmarshaled structure content (using go's %#v formatting directive).
	//
	log.Printf("message: %s\n", msg.String())
	log.Printf("Unmarshalled message: %#v\n", helloMsg)
}

The following example marshals Go structure data into a message:

func main() {
	msg, err := realm.NewMessage("helloworld")
	if err != nil {
	log.Fatal(ftl.ErrStack(err))
	}
	// Defer the destruction of the message.
	defer msg.Destroy()
	// Construct the message content into a map[string]interface{}.
	content := make(map[string]interface{})
	content["type"] = "hello"
	content["message"] = "hello world earth"
	// Marshal the message content into the FTL message. Note that a 
	// pointer to the map must be passed to msg.Marshal().
	if err = msg.Marshal(&content); err != nil {
	log.Fatal(ftl.ErrStack(err))
	}
}

For more information about FTL message marshaling/unmarshaling, see the samples in .../samples/src/golang/src/tibco.com/ftl-sample.