Talend Component Kit Developer Reference Guide :: Talend Component Kit Reference guide

Widget and validation gallery

This gallery shows how widgets and validations are rendered in both Studio and web environments, along with sample implementation code.

You can also find sample working components for each of the configuration cases below:

ActiveIf: Add visibility conditions on some configurations.
Checkbox: Add checkboxes or toggles to your component.
Code: Allow users to enter their own code.
Credential: Mark a configuration as sensitive data to avoid displaying it as plain text.
Datastore: Add a button allowing to check the connection to a datastore.
Datalist: Two ways of implementing a dropdown list with predefined choices.
Integer: Add numeric fields to your component configuration.
Min/Max: Specify a minimum or a maximum value for a numeric configuration.
Multiselect: Add a list and allow users to select multiple elements of that list.
Pattern: Enforce rules based on a specific a pattern to prevent users from entering invalid values.
Required: Make a configuration mandatory.
Suggestions: Suggest possible values in a field based on what the users are entering.
Table: Add a table to your component configuration.
Textarea: Add a text area for configurations expecting long texts or values.
Input: Add a simple text input field to the component configuration
Update: Provide a button allowing to fill a part of the component configuration based on a service.
Validation: Specify constraints to make sure that a URL is well formed.

Widgets

Widgets allow to easily implement different types of input fields to your components.

Input/Text

@Option
String config;

Studio Rendering	Web Rendering

Password

@Option
@Credential
String config;

Studio Rendering	Web Rendering

Textarea

@Option
@Textarea
String config;

Studio Rendering	Web Rendering

Integer

@Option
@Documentation("This is a number")
public Integer number;

Studio Rendering	Web Rendering

Checkbox

@Option
Boolean config;

Studio Rendering	Web Rendering

List

@Option
@Proposable("valuesProvider")
String config;
/** service class */
@DynamicValues("valuesProvider")
public Values actions(){
  return new Values(asList(new Values.Item("1", "Delete"),
                    new Values.Item("2", "Insert"),
                    new Values.Item("3", "Update")));
}

or

@Option
ActionEnum config;

/** Define enum */
enum ActionEnum {
    Delete,
    Insert,
    Update
}

Studio Rendering	Web Rendering

Suggestions

@Option
@Suggestable(value = "loadModules", parameters = { "myconfig" })
@Documentation("module names are loaded using service")
public String moduleName;


// In Service class
@Suggestions("loadModules")
public SuggestionValues loadModules(@Option final MyConfig myconfig) { }

Studio Rendering	Web Rendering

Table

@Option
List<MyObject> config;

Studio Rendering	Web Rendering

Code

@Code("java")
@Option
String config;

Studio Rendering	Web Rendering

Schema

@Option
@Structure
List<String> config;

Studio Rendering	Web Rendering

Validations

Validations help restricting what can be entered or selected in an input field, to make sure that the value complies with the expected type of information.

Property validation

/** configuration class */
@Option
@Validable("url")
String config;

/** service class */
@AsyncValidation("url")
ValidationResult doValidate(String url) {
//validate the property
}

Studio Rendering	Web Rendering

Property validation with Pattern

/** configuration class */
@Option
@Pattern("/^[a-zA-Z\\-]+$/")
String username;

Studio Rendering	Web Rendering

Data store validation

@Datastore
@Checkable
public class config {
/** config ...*/
}

/** service class */
@HealthCheck
public HealthCheckStatus testConnection(){

//validate the connection
}

Studio Rendering	Web Rendering

You can also use other types of validation that are similar to @Pattern:

@Min, @Max to specify a minimum and maximum value for numerical fields.
@Uniques for collection values.
@Required for a required configuration.

Actions

Dynamic Values

Mark a method as being useful to fill potential values of a string option for a property denoted by its value. You can link a field as being completable using @Proposable(value). The resolution of the completion action is then done through the component family and value of the action. The callback doesn’t take any parameter.

Type: dynamic_values
API: @org.talend.sdk.component.api.service.completion.DynamicValues
Returned type: org.talend.sdk.component.api.service.completion.Values
Sample:

{
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Healthcheck

This class marks an action doing a connection test

Type: healthcheck
API: @org.talend.sdk.component.api.service.healthcheck.HealthCheck
Returned type: org.talend.sdk.component.api.service.healthcheck.HealthCheckStatus
Sample:

{
  "comment":"Something went wrong",
  "status":"KO"
}

Schema

Mark an action as returning a discovered schema. Its parameter MUST be a dataset. Dataset is configuration type annotated with @DataSet. If component has multiple datasets, then dataset used as action parameter should have the same identifier as this @DiscoverSchema.

Type: schema
API: @org.talend.sdk.component.api.service.schema.DiscoverSchema
Returned type: org.talend.sdk.component.api.record.Schema
Sample:

{
  "entries":[
    {
      "comment":"The column 1",
      "name":"column1",
      "nullable":false,
      "type":"STRING"
    },
    {
      "comment":"The int column",
      "name":"column2",
      "nullable":false,
      "type":"INT"
    }
  ],
  "type":"RECORD"
}

Suggestions

Mark a method as being useful to fill potential values of a string option. You can link a field as being completable using @Suggestable(value). The resolution of the completion action is then done when the user requests it (generally by clicking on a button or entering the field depending the environment).

Type: suggestions
API: @org.talend.sdk.component.api.service.completion.Suggestions
Returned type: org.talend.sdk.component.api.service.completion.SuggestionValues
Sample:

{
  "cacheable":false,
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Update

This class marks an action returning a new instance replacing part of a form/configuration.

Type: update
API: @org.talend.sdk.component.api.service.update.Update

User

Extension point for custom UI integrations and custom actions.

Type: user
API: @org.talend.sdk.component.api.service.Action

Validation

Mark a method as being used to validate a configuration.

this is a server validation so only use it if you can’t use other client side validation to implement it.

Type: validation
API: @org.talend.sdk.component.api.service.asyncvalidation.AsyncValidation
Returned type: org.talend.sdk.component.api.service.asyncvalidation.ValidationResult
Sample:

{
  "comment":"Something went wrong",
  "status":"KO"
}

Built In Actions

These actions are provided - or not - by the application the UI runs within.

always ensure you don’t require this action in your component.

built_in_suggestable

Mark the decorated field as supporting suggestions, i.e. dynamically get a list of valid values the user can use. It is however different from @Suggestable by looking up the implementation in the current application and not the services. Finally, it is important to note that it can do nothing in some environments too and that there is no guarantee the specified action is supported.

API: @org.talend.sdk.component.api.configuration.action.BuiltInSuggestable

Conditions

ActiveIf

If the evaluation of the element at the location matches value then the element is considered active, otherwise it is deactivated.

API: @org.talend.sdk.component.api.configuration.condition.ActiveIf
Type: if
Sample:

{
  "condition::if::evaluationStrategy":"DEFAULT",
  "condition::if::negate":"false",
  "condition::if::target":"test",
  "condition::if::value":"value1,value2"
}

ActiveIfs

Allows to set multiple visibility conditions on the same property.

API: @org.talend.sdk.component.api.configuration.condition.ActiveIfs
Type: ifs
Sample:

{
  "condition::if::evaluationStrategy::0":"DEFAULT",
  "condition::if::evaluationStrategy::1":"LENGTH",
  "condition::if::negate::0":"false",
  "condition::if::negate::1":"true",
  "condition::if::target::0":"sibling1",
  "condition::if::target::1":"../../other",
  "condition::if::value::0":"value1,value2",
  "condition::if::value::1":"SELECTED",
  "condition::ifs::operator":"AND"
}

Configuration types

Dataset

Mark a model (complex object) as being a dataset.

API: @org.talend.sdk.component.api.configuration.type.DataSet
Sample:

{
  "tcomp::configurationtype::name":"test",
  "tcomp::configurationtype::type":"dataset"
}

Datastore

Mark a model (complex object) as being a datastore (connection to a backend).

API: @org.talend.sdk.component.api.configuration.type.DataStore
Sample:

{
  "tcomp::configurationtype::name":"test",
  "tcomp::configurationtype::type":"datastore"
}

Constraints

MaxLength

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: maxLength
Parameter Type: double
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::maxLength":"12.34"
}

MinLength

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: minLength
Parameter Type: double
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::minLength":"12.34"
}

Pattern

Validate the decorated string with a javascript pattern (even into the Studio).

API: @org.talend.sdk.component.api.configuration.constraint.Pattern
Name: pattern
Parameter Type: java.lang.string
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::pattern":"test"
}

Max

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: max
Parameter Type: double
Supported Types: — java.lang.Number — int — short — byte — long — double — float
Sample:

{
  "validation::max":"12.34"
}

Min

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: min
Parameter Type: double
Supported Types: — java.lang.Number — int — short — byte — long — double — float
Sample:

{
  "validation::min":"12.34"
}

Required

Mark the field as being mandatory.

API: @org.talend.sdk.component.api.configuration.constraint.Required
Name: required
Parameter Type: -
Supported Types: — java.lang.Object
Sample:

{
  "validation::required":"true"
}

MaxItems

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: maxItems
Parameter Type: double
Supported Types: — java.util.Collection
Sample:

{
  "validation::maxItems":"12.34"
}

MinItems

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: minItems
Parameter Type: double
Supported Types: — java.util.Collection
Sample:

{
  "validation::minItems":"12.34"
}

UniqueItems

Ensure the elements of the collection must be distinct (kind of set).

API: @org.talend.sdk.component.api.configuration.constraint.Uniques
Name: uniqueItems
Parameter Type: -
Supported Types: — java.util.Collection
Sample:

{
  "validation::uniqueItems":"true"
}

Junit environments

the configuration is read from system properties, environment variables, ….

Contextual: _class: ContextualEnvironment.
Direct: _class: DirectRunnerEnvironment.
Flink: _class: FlinkRunnerEnvironment.
Spark: _class: SparkRunnerEnvironment.

Scanning

Jars Scanning

To find components the framework can scan the classpath but in this case, to avoid to scan the whole classpath which can be really huge an impacts a lot the startup time, several jars are excluded out of the box.

These jars use the following prefix:

ApacheJMeter
FastInfoset
HdrHistogram
HikariCP
PDFBox
RoaringBitmap-
XmlSchema-
accessors-smart
activation-
activeio-
activemq-
aeron
aether-
agrona
akka-
animal-sniffer-annotation
annotation
ant-
antlr-
antlr4-
aopalliance-
apache-el
apache-mime4j
apacheds-
api-asn1-
api-common-
api-util-
apiguardian-api-
app-
archaius-core
args4j-
arquillian-
asciidoctorj-
asm-
aspectj
async-http-client-
auto-value-
autoschema-
avalon-framework-
avro-
avro4s-
awaitility-
aws-
axis-
axis2-
base64-
batchee-jbatch
batik-
bcmail
bcpkix
bcprov-
beam-model-
beam-runners-
beam-sdks-
bigtable-client-
bigtable-protos-
boilerpipe-
bonecp
bootstrap.jar
brave-
bsf-
build-link
bval
byte-buddy
c3p0-
cache
carrier
cassandra-driver-core
catalina-
catalina.jar
cats
cdi-
cglib-
charsets.jar
chill
classindex
classmate
classutil
classycle
cldrdata
commands-
common-
commons-
component-api
component-form
component-runtime
component-server
component-spi
component-studio
components-adapter-beam
components-api
components-common
compress-lzf
config
constructr
container-core
contenttype
coverage-agent
cryptacular-
cssparser-
curator-
curvesapi-
cxf-
daikon
databinding
dataquality
dataset-
datastore-
debugger-agent
deltaspike-
deploy.jar
derby-
derbyclient-
derbynet-
dnsns
dom4j
draw2d
easymock-
ecj-
eclipselink-
ehcache-
el-api
enumeratum
enunciate-core-annotations
error_prone_annotations
expressions
fastutil
feign-core
feign-hystrix
feign-slf4j
filters-helpers
findbugs-
fluent-hc
fluentlenium-core
fontbox
freemarker-
fusemq-leveldb-
gax-
gcsio-
gef-
geocoder
geronimo-
gmbal
google-
gpars-
gragent.jar
graph
grizzled-scala
grizzly-
groovy-
grpc-
gson-
guava-
guice-
h2-
hadoop-
hamcrest-
hawtbuf-
hawtdispatch-
hawtio-
hawtjni-runtime
help-
hibernate-
hk2-
howl-
hsqldb-
htmlunit-
htrace-
httpclient-
httpcore-
httpmime
hystrix
iban4j-
icu4j-
idb-
idea_rt.jar
instrumentation-api
ion-java
isoparser-
istack-commons-runtime-
ivy-
j2objc-annotations
jBCrypt
jaccess
jackcess-
jackson-
janino-
jansi-
jasper-el.jar
jasper.jar
jasypt-
java-atk-wrapper
java-libpst-
java-support-
java-xmlbuilder-
javacsv
javaee-
javaee-api
javassist-
javaws.jar
javax.
jaxb-
jaxp-
jbake-
jboss-
jbossall-
jbosscx-
jbossjts-
jbosssx-
jcache
jce.jar
jcip-annotations
jcl-over-slf4j-
jcommander-
jdbcdslog-1
jempbox
jersey-
jets3t
jettison-
jetty-
jface
jfairy
jffi
jfr.jar
jfxrt.jar
jfxswt
jhighlight
jjwt
jline
jmatio-
jmdns-
jmespath-
jms
jmustache
jna-
jnr-
jobs-
joda-convert
joda-time-
johnzon-
jolokia-
joni-
jopt-simple
jruby-
json-
json4s-
jsonb-api
jsoup-
jsp-api
jsr
jsse.jar
jta
jul-to-slf4j-
juli-
junit-
junit5-
juniversalchardet
junrar-
jwt
jython
kafka
kahadb-
kotlin-runtime
kryo
leveldb
libphonenumber
lift-json
lmdbjava
localedata
log4j-
logback
logging-event-layout
logkit-
lombok
lucene
lz4
machinist
macro-compat
mail-
management-
mapstruct-
maven-
mbean-annotation-api-
meecrowave-
mesos-
metadata-extractor-
metrics-
microprofile-config-api
microprofile-openapi-api
microprofile-opentracing-api
mimepull-
mina-
minlog
mockito-core
mqtt-client-
multitenant-core
multiverse-core-
mx4j-
myfaces-
mysql-connector-java-
nashorn
neethi-
neko-htmlunit
nekohtml-
netflix
netty-
nimbus-jose-jwt
objenesis-
okhttp
okio
opencensus-
openejb-
openjpa-
openmdx-
opennlp-
opensaml-
opentest4j-
opentracing-api
openwebbeans-
openws-
ops4j-
options
org.apache.aries
org.apache.commons
org.apache.log4j
org.eclipse.
org.junit.
org.osgi.annotation.versioning
org.osgi.core-
org.osgi.enterprise
org.talend
orient-commons-
orientdb-core-
orientdb-nativeos-
oro-
osgi
paranamer
parquet
pax-url
pdfbox
play
plexus-
plugin.jar
poi-
postgresql
preferences-
prefixmapper
proto-
protobuf-
py4j-
pyrolite-
qdox-
quartz-2
quartz-openejb-
reactive-streams
reflectasm-
reflections
regexp-
registry-
resources.jar
rhino
ribbon
rmock-
rome
routes-compiler
routines
rt.jar
runners
runtime-
rxjava
rxnetty
saaj-
sac-
scala
scalap
scalatest
scannotation-
selenium
serializer-
serp-
service-common
servlet-api-
servo-
shaded
shapeless
shrinkwrap-
sisu-guice
sisu-inject
slf4j-
slick
smack-
smackx-
snakeyaml-
snappy-
spark-
specs2
spring-
sshd-
ssl-config-core
stax-api-
stax2-api-
stream
sunec.jar
sunjce_provider
sunpkcs11
surefire-
swagger-
swizzle-
sxc-
system-rules
tachyon-
tagsoup-
talend-icon
test-agent
test-interface
testng-
threetenbp
tika-
tomcat
tomee-
tools.jar
twirl
twitter4j-
tyrex
uncommons
unused
util
validation-api-
velocity-
wagon-
wandou
webbeans-
websocket
woodstox-core
workbench
ws-commons-util-
wsdl4j-
wss4j-
wstx-asl-
xalan-
xbean-
xercesImpl-
xlsx-streamer-
xml-apis-
xml-resolver-
xmlbeans-
xmlenc-
xmlgraphics-
xmlpcore
xmlpull-
xmlrpc-
xmlschema-
xmlsec-
xmltooling-
xmlunit-
xstream-
xz-
zipfs.jar
zipkin-
ziplock-
zkclient
zookeeper-
zstd-

Package Scanning

Since the framework can be used in the case of fatjars or shades, and because it still uses scanning, it is important to ensure we don’t scan the whole classes for performances reason.

Therefore, the following packages are ignored:

it is not recommanded but possible to add in your plugin module a TALEND-INF/scanning.properties file with classloader.includes and classloader.excludes entries to refine the scanning with custom rules. In such a case, exclusions win over inclusions.

Server configuration

the configuration is read from system properties, environment variables, ….

talend.component.server.cache.maxSize

Default value: 1000. Maximum items a cache can store, used for index endpoints.

talend.component.server.component.coordinates

A comma separated list of gav to locate the components

talend.component.server.component.documentation.translations

Default value: ${home}/documentations. A component translation repository. This is where you put your documentation translations. Their name must follow the pattern documentation_${container-id}_language.adoc where ${container-id} is the component jar name (without the extension and version, generally the artifactId).

talend.component.server.component.extend.dependencies

Default value: true. Should the component extensions add required dependencies.

talend.component.server.component.extension.maven.repository

If you deploy some extension, where they can create their dependencies if needed.

talend.component.server.component.extension.startup.timeout

Default value: 180000. Timeout for extension initialization at startup, since it ensures the startup wait extensions are ready and loaded it allows to control the latency it implies.

talend.component.server.component.registry

A property file (or multiple comma separated) where the value is a gav of a component to register(complementary with coordinates). Note that the path can end up with or .properties to take into account all properties in a folder.

talend.component.server.documentation.active

Default value: true. Should the /documentation endpoint be activated. Note that when called on localhost the doc is always available.

talend.component.server.environment.active

Default value: true. Should the /api/v1/environment endpoint be activated. It shows some internal versions and git commit which are not always desirable over the wire.

talend.component.server.filter.secured.tokens

Default value: -. Accepted tokens in Authorization header for remote calls to secured endpoints (/api/v1/environment or /documentation).

talend.component.server.jaxrs.exceptionhandler.defaultMessage

Default value: false. If set it will replace any message for exceptions. Set to false to use the actual exception message.

talend.component.server.lastUpdated.useStartTime

Default value: false. Should the lastUpdated timestamp value of /environment endpoint be updated with server start time.

talend.component.server.maven.repository

The local maven repository used to locate components and their dependencies

talend.component.server.request.log

Default value: false. Should the all requests/responses be logged (debug purposes - only work when running with CXF).

talend.component.server.security.command.handler

Default value: securityNoopHandler. How to validate a command/request. Accepted values: securityNoopHandler.

talend.component.server.security.connection.handler

Default value: securityNoopHandler. How to validate a connection. Accepted values: securityNoopHandler.

talend.component.server.user.extensions.location

A folder available for the server - don’t forget to mount it in docker if you are using the image - which accepts subfolders named as component plugin id (generally the artifactId or jar name without the version, ex: jdbc). Each family folder can contain:

a user-configuration.properties file which will be merged with component configuration system (see services). This properties file enables the function userJar(xxxx) to replace the jar named xxxx by its virtual gav (groupId:artifactId:version),
a list of jars which will be merged with component family classpath

talend.component.server.user.extensions.provisioning.location

Default value: auto. Should the implicit artifacts be provisionned to a m2. If set to auto it tries to detect if there is a m2 to provision - recommended, if set to skip it is ignored, else it uses the value as a m2 path.

User Interface API

@DefaultValue

Provide a default value the UI can use - only for primitive fields.

API: @org.talend.sdk.component.api.configuration.ui.DefaultValue

Sample:

{
  "ui::defaultvalue::value":"test"
}

@OptionsOrder

Allows to sort a class properties.

API: @org.talend.sdk.component.api.configuration.ui.OptionsOrder

Sample:

{
  "ui::optionsorder::value":"value1,value2"
}

@AutoLayout

Request the rendered to do what it thinks is best.

API: @org.talend.sdk.component.api.configuration.ui.layout.AutoLayout

Sample:

{
  "ui::autolayout":"true"
}

@GridLayout

Advanced layout to place properties by row, this is exclusive with @OptionsOrder.

API: @org.talend.sdk.component.api.configuration.ui.layout.GridLayout

Sample:

{
  "ui::gridlayout::value1::value":"first|second,third",
  "ui::gridlayout::value2::value":"first|second,third"
}

@GridLayouts

Allow to configure multiple grid layouts on the same class, qualified with a classifier (name)

API: @org.talend.sdk.component.api.configuration.ui.layout.GridLayouts

Sample:

{
  "ui::gridlayout::Advanced::value":"another",
  "ui::gridlayout::Main::value":"first|second,third"
}

@HorizontalLayout

Put on a configuration class it notifies the UI an horizontal layout is preferred.

API: @org.talend.sdk.component.api.configuration.ui.layout.HorizontalLayout

Sample:

{
  "ui::horizontallayout":"true"
}

@VerticalLayout

Put on a configuration class it notifies the UI a vertical layout is preferred.

API: @org.talend.sdk.component.api.configuration.ui.layout.VerticalLayout

Sample:

{
  "ui::verticallayout":"true"
}

@Code

Mark a field as being represented by some code widget (vs textarea for instance).

API: @org.talend.sdk.component.api.configuration.ui.widget.Code

Sample:

{
  "ui::code::value":"test"
}

@Credential

Mark a field as being a credential. It is typically used to hide the value in the UI.

API: @org.talend.sdk.component.api.configuration.ui.widget.Credential

Sample:

{
  "ui::credential":"true"
}

@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).

API: @org.talend.sdk.component.api.configuration.ui.widget.Structure

Sample:

{
  "ui::structure::discoverSchema":"test",
  "ui::structure::type":"IN",
  "ui::structure::value":"test"
}

@TextArea

Mark a field as being represented by a textarea(multiline text input).

API: @org.talend.sdk.component.api.configuration.ui.widget.TextArea

Sample:

{
  "ui::textarea":"true"
}