Talend Component Kit Developer Reference Guide

Component are configured through their constructor parameters. They can all be marked with @Option which will let you give a name to parameters (if not it will use the bytecode name which can require you to compile with -parameter flag to not have arg0, arg1, … as names).

The parameter types can be primitives or complex objects with fields decorated with @Option exactly like method parameters.

it is recommanded to use simple models which can be serialized by components to avoid headaches when implementing serialized components.

Here is an example:

class FileFormat implements Serializable {
    @Option("type")
    private FileType type = FileType.CSV;

    @Option("max-records")
    private int maxRecords = 1024;
}

@PartitionMapper(family = "demo", name = "file-reader")
public MyFileReader(@Option("file-path") final File file,
                    @Option("file-format") final FileFormat format) {
    // ...
}

Using this kind of API makes the configuration extensible and component oriented letting the user define all he needs.

The instantiation of the parameters is done from the properties passed to the component (see next part).

Primitives

What is considered as a primitive in this mecanism is a class which can be directly converted from a String to the expected type.

It obviously includes all java primitives, String type itself but also all the types with a org.apache.xbean.propertyeditor.Converter.

This includes out of the box:

BigDecimal
BigInteger
File
InetAddress
ObjectName
URI
URL
Pattern

Complex object mapping

The conversion from properties to object is using the dotted notation. For instance:

file.path = /home/user/input.csv
file.format = CSV

will match

public class FileOptions {
    @Option("path")
    private File path;

    @Option("format")
    private Format format;
}

assuming the method parameter was configured with @Option("file").

List case

Lists use the same syntax but to define their elements their rely on an indexed syntax. Assuming the list parameter is named files and the elements are of FileOptions type, here is how to define a list of 2 elements:

files[0].path = /home/user/input1.csv
files[0].format = CSV
files[1].path = /home/user/input2.xml
files[2].format = EXCEL

Map case

Inspired from the list case, the map uses .key[index] and .value[index] to represent its key and values:

// Map<String, FileOptions>
files.key[0] = first-file
files.value[0].path = /home/user/input1.csv
files.value[0].type = CSV
files.key[1] = second-file
files.value[1].path = /home/user/input2.xml
files.value[1].type = EXCEL

// Map<FileOptions, String>
files.key[0].path = /home/user/input1.csv
files.key[0].type = CSV
files.value[0] = first-file
files.key[1].path = /home/user/input2.xml
files.key[1].type = EXCEL
files.value[1] = second-file

don’t abuse of map type. If not needed for your configuration (= if you can configure your component with an object) don’t use it.

Constraints and validation on the configuration/input

It is common to need to add as metadata a field is required, another has a minimum size etc. This is done with the validation in org.talend.sdk.component.api.configuration.constraint package:

API	Name	Parameter Type	Description	Supported Types	Metadata sample
@org.talend.sdk.component.api.configuration.constraint.Max	maxLength	double	Ensure the decorated option size is validated with a higher bound.	CharSequence	{"validation::maxLength":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Min	minLength	double	Ensure the decorated option size is validated with a lower bound.	CharSequence	{"validation::minLength":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Pattern	pattern	string	Validate the decorated string with a java pattern, you can use xregex library in javascript.	CharSequence	{"validation::pattern":"test"}
@org.talend.sdk.component.api.configuration.constraint.Max	max	double	Ensure the decorated option size is validated with a higher bound.	Number, int, short, byte, long, double, float	{"validation::max":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Min	min	double	Ensure the decorated option size is validated with a lower bound.	Number, int, short, byte, long, double, float	{"validation::min":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Required	required	-	Mark the field as being mandatory.	Object	{"validation::required":"true"}
@org.talend.sdk.component.api.configuration.constraint.Max	maxItems	double	Ensure the decorated option size is validated with a higher bound.	Collection	{"validation::maxItems":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Min	minItems	double	Ensure the decorated option size is validated with a lower bound.	Collection	{"validation::minItems":"12.34"}
@org.talend.sdk.component.api.configuration.constraint.Uniques	uniqueItems	-	Ensure the elements of the collection must be distinct (kind of set).	Collection	{"validation::uniqueItems":"true"}

using the programmatic API the metadata are prefixed by tcomp:: but this prefix is stripped in the web for convenience, the previous table uses the web keys.

Marking a configuration as a particular type of data

It is common to classify the incoming data. You can see it as tagging them in several types. The most common ones are the:

datastore: all the data you need to connect to the backend
dataset: a datastore coupled with all the data you need to execute an action

API	Type	Description	Metadata sample
org.talend.sdk.component.api.configuration.type.DataSet	dataset	Mark a model (complex object) as being a dataset.	{"tcomp::configurationtype::type":"dataset","tcomp::configurationtype::name":"test"}
org.talend.sdk.component.api.configuration.type.DataStore	datastore	Mark a model (complex object) as being a datastore (connection to a backend).	{"tcomp::configurationtype::type":"datastore","tcomp::configurationtype::name":"test"}

the component family associated with a configuration type (datastore/dataset) is always the one related to the component using that configuration.

Those configuration types can be composed to provide one configuration item. For example a dataset type will often need a datastore type to be provided. and a datastore type (that provides the connection information) will be used to create a dataset type.

Those configuration types will also be used at design time to create shared configuration that can be stored and used at runtime.

For example, we can think about a relational database that support JDBC:

A datastore may provide:
- jdbc url, username, password
A dataset may be:
- datastore (that will provide the connection data to the database)
- table name, data []

The component server will scan all those configuration types and provide a configuration type index. This index can be used for the integration into the targeted platforms (studio, web applications…)

The configuration type index is represented as a flat tree that contains all the configuration types represented as nodes and indexed by their ids.

Also, every node can point to other nodes. This relation is represented as an array of edges that provide the childes ids.

For example, a configuration type index for the above example will be:

{nodes: {
             "idForDstore": { datastore:"datastore data", edges:[id:"idForDset"] },
             "idForDset":   { dataset:"dataset data" }
    }
}

Define links between properties

It can be needed to define a binding between properties, a set of annotations allows to do it:

API	Name	Description	Metadata Sample
@org.talend.sdk.component.api.configuration.condition.ActiveIf	if	If the evaluation of the element at the location matches value then the element is considered active, otherwise it is deactivated.	{"condition::if::target":"test","condition::if::value":"value1,value2"}
@org.talend.sdk.component.api.configuration.condition.ActiveIfs	ifs	Allows to set multiple visibility conditions on the same property.	{"condition::if::value::0":"value1,value2","condition::if::value::1":"SELECTED","condition::if::target::0":"sibling1","condition::if::target::1":"../../other"}

Target element location is specified as a relative path to current location using Unix path characters. Configuration class delimiter is /. Parent configuration class is specified by ... Thus ../targetProperty denotes a property, which is located in parent configuration class and has name targetProperty.

using the programmatic API the metadata are prefixed by tcomp:: but this prefix is stripped in the web for convenience, the previous table uses the web keys.

Add hints about the rendering based on configuration/component knowledge

In some case it can be needed to add some metadata about the configuration to let the UI render properly the configuration. A simple example is a password value must be hidden and not a simple clear input box. For these cases - when the component developper wants to influence the UI rendering - you can use a particular set of annotations:

API	Description	Generated property metadata
@org.talend.sdk.component.api.configuration.ui.DefaultValue	Provide a default value the UI can use - only for primitive fields.	{"ui::defaultvalue::value":"test"}
@org.talend.sdk.component.api.configuration.ui.OptionsOrder	Allows to sort a class properties.	{"ui::optionsorder::value":"value1,value2"}
@org.talend.sdk.component.api.configuration.ui.layout.AutoLayout	Request the rendered to do what it thinks is best.	{"ui::autolayout":"true"}
@org.talend.sdk.component.api.configuration.ui.layout.GridLayout	Advanced layout to place properties by row, this is exclusive with `@OptionsOrder`.	{"ui::gridlayout::value1::value":"first
second,third","ui::gridlayout::value2::value":"first	second,third"}	@org.talend.sdk.component.api.configuration.ui.layout.GridLayouts
Allow to configure multiple grid layouts on the same class, qualified with a classifier (name)	{"ui::gridlayout::Advanced::value":"another","ui::gridlayout::Main::value":"first	second,third"}
@org.talend.sdk.component.api.configuration.ui.layout.HorizontalLayout	Put on a configuration class it notifies the UI an horizontal layout is preferred.	{"ui::horizontallayout":"true"}
@org.talend.sdk.component.api.configuration.ui.layout.VerticalLayout	Put on a configuration class it notifies the UI a vertical layout is preferred.	{"ui::verticallayout":"true"}
@org.talend.sdk.component.api.configuration.ui.widget.Code	Mark a field as being represented by some code widget (vs textarea for instance).	{"ui::code::value":"test"}
@org.talend.sdk.component.api.configuration.ui.widget.Credential	Mark a field as being a credential. It is typically used to hide the value in the UI.	{"ui::credential":"true"}
@org.talend.sdk.component.api.configuration.ui.widget.Structure	Mark a List<String> or Map<String, String> field as being represented as the component data selector (field names generally or field names as key and type as value).	{"ui::structure::type":"null","ui::structure::discoverSchema":"test","ui::structure::value":"test"}
@org.talend.sdk.component.api.configuration.ui.widget.TextArea	Mark a field as being represented by a textarea(multiline text input).	{"ui::textarea":"true"}

using the programmatic API the metadata are prefixed by tcomp:: but this prefix is stripped in the web for convenience, the previous table uses the web keys.

target support should cover org.talend.core.model.process.EParameterFieldType but we need to ensure web renderers is able to handle the same widgets.

Configuring components

Primitives

Complex object mapping

List case

Map case

Constraints and validation on the configuration/input

Marking a configuration as a particular type of data

Define links between properties

Add hints about the rendering based on configuration/component knowledge