Parameter Data Types and Formatters

String data type represents a simple parameter which is an individual string key-value parameter. This is the most commonly used data type and the default type, if not specified explicitly.

Record data type handles complex parameters involving a collection of related key-value pairs. These parameters can have indices's for one or more parameter entry. Such parameters can ideally be represented with an IS document type, and configured as a "Record" data type.

Consider a complex parameter structure as follows:

This needs to be represented as a query string like:

Filter.1.Name=instance-type&Filter.1.Value.1=m1.small&Filter.1.Value.2=t1.micro

Such a parameter can be defined by creating an IS document type, and referring it as a "Record" data type parameter within the resource definition.

CloudStreams provides the capability to represent and transform such complex parameters into the desired format using its predefined formatter implementation. The resource's parameter definition can be enhanced to refer to a formatter, as follows:

At runtime, the resource path would look like:

For more details on formatters and customizing the formatter behavior, see the following section on "Parameter Formatters".

Parameter Formatters

CloudStreams provides a parameter formatter which enables you to format input data into a desired custom format.

Alternatively, in cases where the default parameter formatter is not sufficient to achieve the desired parameter behavior, you can write a custom implementation for the parameter formatter.

The input will typically be data present in a complex structure, for example, an IS document type. The output will be data organized in a desired output format, for example, a URL query string. The format in which the output data is generated depends on the implementation of the formatter.

Typically, you will use the Query or the Form Encoded parameter types to format the input data into a desired output format, for example, a URL query string in case of Query or in case of Form encoded, a formatted query string in the Request body.

In order to form the query string, you can write a custom formatter service by implementing the bundled IS specification wm.cloudstreams.service.common.lookup.specs:formatterSpec.

At run time, CloudStreams will give control to the formatter service to format the data appropriately and to return the formatted string data. Then, CloudStreams will encode the data during a post-processing step, and the final query string will be formed.

Using the Default Parameter Formatter

For convenience, CloudStreams provides a default formatter implementation that handles the most common formatter usage:

wm.cloudstreams.service.util.formatters:paramFormatter

This formatter allows you to specify a complex IS document type and to implement the desired output. The input will typically be data in a complex structure, for example, an IS document type. The output will be a data organized in a desired output format, for example, a URL query string. The format in which the output data is generated depends on the implementation of the formatter. Typically, the formatter is used in conjunction with the Query parameter type.

A SaaS back end is expecting the following parameter:

BlockDeviceMapping.n.DeviceName
BlockDeviceMapping.n.VirtualName
BlockDeviceMapping.n.Ebs.NoDevice
BlockDeviceMapping.n.Ebs.VolumeSize

where n represents a number.

1. Create IS document types for the above parameter definition. The IS document structure would look like this:

3. Set the document reference (documentRef) to the newly created IS document type in step 1.

4. Specify a formatter element within the parameter element, along with the service name (service attribute) and type (type attribute).

In case the implementation contains supported arguments, specify any customization by adding the appropriate argument name and value. The parameter definition for a resource using the above, within the Connector Descriptor, would look like this:

Note: The default value for the type attribute within the scope of a parameter definition is "paramFormatter". This type refers to the bundled IS Specification:

The generated representation of the above parameter would look like this:

BlockDeviceMapping.1.DeviceName=/dev/sdj&;BlockDeviceMapping
.1.Ebs.NoDevice=true&;BlockDeviceMapping
.2.DeviceName=/dev/sdh&;BlockDeviceMapping
.2.Ebs.VolumeSize=300&;BlockDeviceMapping
.3.DeviceName=/dev/sdc&;BlockDeviceMapping
.3.VirtualName=ephemeral1

The default formatter can be configured with the following supported arguments:

Argument	Default Value	Description
startIndex	0	Determines the index values of the keys e.g. should the n present in BlockDeviceMapping.n.DeviceName start with 0 or 1 or some number of your choice.
format	. (period)	Specifies how the document entries be separated. For example, BlockDeviceMapping.3.DeviceName is separated by a period (.).

Implementing a Custom Parameter Formatter

In cases where the default parameter formatter is not sufficient to achieve the desired parameter behavior, you can write a custom implementation for the parameter formatter.

Implement a custom formatter as follows:

1. Write an IS service implementation, adhering to the bundled IS specification wm.cloudstreams.service.common.lookup.specs:formatterSpec.

2. The fully-qualified service namespace should be referred with the formatter service attribute under the parameter definition. Ensure that the formatter type attribute is set to "paramFormatter".

3. Optionally, any service arguments can be specified within the formatter element definition.

Consider a custom service implementation:

my.custom.formatter:sample

The parameter definition for a resource using the above, within the Connector Descriptor, would look like this: