Talend Component Kit Reference guide

=== List

[source,java] ---- @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"))); } ----

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

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Suggestions

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

@Suggestions("loadModules") public SuggestionValues loadModules(@Option final MyConfig myconfig) { } ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Table

[source,java] ---- @Option List<MyObject> config; ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Code

[source,java] ---- @Code("java") @Option String config; ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Schema

[source,java] ---- @Option @Structure List<String> config; ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

== 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

[source,java] ---- / configuration class */ @Option @Validable("url") String config;

/ service class */ @AsyncValidation("url") ValidationResult doValidate(String url) { } ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Property validation with Pattern

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

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

=== Data store validation

[source,java] ---- @Datastore @Checkable public class config { / config …​*/ }

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

} ----

[cols="1a,1a",role="table gallery table-striped",options="header,autowidth",width="100%"]

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.

:leveloffset!:

== Actions

:leveloffset: +2

= 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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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.

IMPORTANT: 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:

[source,js] ---- { "comment":"Something went wrong", "status":"KO" } ----

== Built In Actions

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

TIP: 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

:leveloffset: 1

== Conditions

:leveloffset: +2

= 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:

[source,js] ---- { "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:

[source,js] ---- { "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" } ----

:leveloffset: 1

== Configuration types

:leveloffset: +2

= Dataset

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

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

[source,js] ---- { "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:

[source,js] ---- { "tcomp::configurationtype::name":"test", "tcomp::configurationtype::type":"datastore" } ----

:leveloffset: 1

== Constraints

:leveloffset: +2

= 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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "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:

[source,js] ---- { "validation::uniqueItems":"true" } ----

:leveloffset: 1

== Junit environments

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

Contextual:: class: ContextualEnvironment_. Direct:: class: DirectRunnerEnvironment_. Flink:: class: FlinkRunnerEnvironment_. Spark:: class: SparkRunnerEnvironment_.

== Scanning

:leveloffset: +2

= 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:

[.talend-filterlist] - avro.shaded - com.codehale.metrics - com.ctc.wstx - com.datastax.driver.core - com.fasterxml.jackson.annotation - com.fasterxml.jackson.core - com.fasterxml.jackson.databind - com.fasterxml.jackson.dataformat - com.fasterxml.jackson.module - com.google.common - com.google.thirdparty - com.ibm.wsdl - com.jcraft.jsch - com.kenai.jffi - com.kenai.jnr - com.sun.istack - com.sun.xml.bind - com.sun.xml.messaging.saaj - com.sun.xml.txw2 - com.thoughtworks - io.jsonwebtoken - io.netty - io.swagger.annotations - io.swagger.config - io.swagger.converter - io.swagger.core - io.swagger.jackson - io.swagger.jaxrs - io.swagger.model - io.swagger.models - io.swagger.util - javax - jnr - junit - net.sf.ehcache - net.shibboleth.utilities.java.support - org.aeonbits.owner - org.apache.activemq - org.apache.beam - org.apache.bval - org.apache.camel - org.apache.catalina - org.apache.commons.beanutils - org.apache.commons.cli - org.apache.commons.codec - org.apache.commons.collections - org.apache.commons.compress - org.apache.commons.dbcp2 - org.apache.commons.digester - org.apache.commons.io - org.apache.commons.jcs.access - org.apache.commons.jcs.admin - org.apache.commons.jcs.auxiliary - org.apache.commons.jcs.engine - org.apache.commons.jcs.io - org.apache.commons.jcs.utils - org.apache.commons.lang - org.apache.commons.lang3 - org.apache.commons.logging - org.apache.commons.pool2 - org.apache.coyote - org.apache.cxf - org.apache.geronimo.javamail - org.apache.geronimo.mail - org.apache.geronimo.osgi - org.apache.geronimo.specs - org.apache.http - org.apache.jcp - org.apache.johnzon - org.apache.juli - org.apache.logging.log4j.core - org.apache.logging.log4j.jul - org.apache.logging.log4j.util - org.apache.logging.slf4j - org.apache.meecrowave - org.apache.myfaces - org.apache.naming - org.apache.neethi - org.apache.openejb - org.apache.openjpa - org.apache.oro - org.apache.tomcat - org.apache.tomee - org.apache.velocity - org.apache.webbeans - org.apache.ws - org.apache.wss4j - org.apache.xbean - org.apache.xml - org.apache.xml.resolver - org.bouncycastle - org.codehaus.jackson - org.codehaus.stax2 - org.codehaus.swizzle.Grep - org.codehaus.swizzle.Lexer - org.cryptacular - org.eclipse.jdt.core - org.eclipse.jdt.internal - org.fusesource.hawtbuf - org.h2 - org.hamcrest - org.hsqldb - org.jasypt - org.jboss.marshalling - org.joda.time - org.jose4j - org.junit - org.jvnet.mimepull - org.metatype.sxc - org.objectweb.asm - org.objectweb.howl - org.openejb - org.opensaml - org.slf4j - org.swizzle - org.terracotta.context - org.terracotta.entity - org.terracotta.modules.ehcache - org.terracotta.statistics - org.tukaani - org.yaml.snakeyaml - serp

NOTE: 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.

:leveloffset: 1

== Server configuration

NOTE: 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.icon.paths:: Default value: icons/%s.svg,icons/svg/%s.svg,icons/%s_icon32.png,icons/png/%s_icon32.png. These patterns are used to find the icons in the classpath(s). 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

:leveloffset: +2

= @DefaultValue

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

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

== Snippets

[source,js] ---- { "ui::defaultvalue::value":"test" } ----

= @OptionsOrder

Allows to sort a class properties.

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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "ui::credential":"true" } ----

= @DateTime

Mark a field as being a date. It supports and is implicit - which means you don’t need to put that annotation on the option - for java.time.ZonedDateTime, java.time.LocalDate and java.time.LocalDateTime and is unspecified for other types.

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

== Snippets

[source,js] ---- { "ui::datetime":"time" } ----

[source,js] ---- { "ui::datetime":"date" } ----

[source,js] ---- { "ui::datetime":"datetime" } ----

[source,js] ---- { "ui::datetime":"zoneddatetime" } ----

= @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

== Snippets

[source,js] ---- { "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

== Snippets

[source,js] ---- { "ui::textarea":"true" } ----

:leveloffset: 1