singer-java module provide a Java API to write a custom singer. To import it, add the following dependency: Then you have access to the Singer class and its companion which provides the primitives to output properly the data: To build schema, keys, bookmarks, json and state which are all either JsonObject or JsonArray you can rely on JsonBuilderFactory which can be instantiated with this snippet: component-kitap is the name of the integration between singer-java and Talend Component Kit. It enables to run native Talend Component Kit components through a tap. The module relies on a proper setup of the component and classpath: Classpath is well setup - composed of component-kitap with a default SLF4J binding configured to log only errors on stderr. For convenience, you can use the all in one bundle provided by the module: org.talend.sdk.component:component-kitapp:${kit.version}:fatjar. Component is "deployed" - i.e. its maven repository is set provisionned with its dependencies. If you downloaded a component as a .car then you can run the car to do it. You can enforce the maven location through the system property talend.component.manager.m2.repository. Regarding SLF4J, the fatjar uses slf4j-standard of the framework which enables to set the logged level to error through a system property: -Dorg.talend.sdk.component.slf4j.StdLogger.level=err. To automatically register a component plugin/family you must add to the classpath a TALEND-INF/plugins.properties: The file only need to contain the registration of the plugin jar: Therefore the launch command can look like: Alternatively you can use org.talend.sdk.component.singer.kitap.Carpates main to launch the application, it differs from Kitap in the sense it takes a .car as option and avoids to pre-build the m2 repository: Here is an example with a real component: The config.json must respect this format: in some environment, such a JSON is not desirable, it is possible to put component_config attribute as a string containing the full json (escaped indeed) too.

The component configuration is defined in the Configuration.java file of the package. It consists in defining the configurable part of the component that will be displayed in the UI. To do that, you can specify parameters. When you import the project in your IDE, the parameters that you have specified in the starter are already present. All input and output components must reference a dataset in their configuration. Refer to Defining datasets and datastores. Components are configured using their constructor parameters. All parameters can be marked with the @Option property, which lets you give a name to them. For the name to be correct, you must follow these guidelines: Use a valid Java name. Do not include any . character in it. Do not start the name with a $. Defining a name is optional. If you don’t set a specific name, it defaults to the bytecode name. This can require you to compile with a -parameter flag to avoid ending up with names such as arg0, arg1, and so on. Examples of option name: Option name Valid myName my_name my.name $myName Parameter types can be primitives or complex objects with fields decorated with @Option exactly like method parameters. It is recommended to use simple models which can be serialized in order to ease serialized component implementations. For example: Using this kind of API makes the configuration extensible and component-oriented, which allows you to define all you need. The instantiation of the parameters is done from the properties passed to the component. A primitive is a class which can be directly converted from a String to the expected type. It includes all Java primitives, like the String type itself, but also all types with a org.apache.xbean.propertyeditor.Converter: BigDecimal BigInteger File InetAddress ObjectName URI URL Pattern LocalDateTime ZonedDateTime The conversion from property to object uses the Dot notation. For example, assuming the method parameter was configured with @Option("file"): matches Lists rely on an indexed syntax to define their elements. For example, assuming that the list parameter is named files and that the elements are of the FileOptions type, you can define a list of two elements as follows: if you desire to override a config to truncate an array, use the index length, for example to truncate previous example to only CSV, you can set: Similarly to the list case, the map uses .key[index] and .value[index] to represent its keys and values: Avoid using the Map type. Instead, prefer configuring your component with an object if this is possible. You can use metadata to specify that a field is required or has a minimum size, and so on. This is done using the validation metadata in the org.talend.sdk.component.api.configuration.constraint package: 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: 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: 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: 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: 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: 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: 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: 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: 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: When using the programmatic API, metadata is prefixed by tcomp::. This prefix is stripped in the web for convenience, and the table above uses the web keys. Also note that these validations are executed before the runtime is started (when loading the component instance) and that the execution will fail if they don’t pass. If it breaks your application, you can disable that validation on the JVM by setting the system property talend.component.configuration.validation.skip to true. Datasets and datastores are configuration types that define how and where to pull the data from. They are used at design time to create shared configurations that can be stored and used at runtime. All connectors (input and output components) created using Talend Component Kit must reference a valid dataset. Each dataset must reference a datastore. Datastore: The data you need to connect to the backend. Dataset: A datastore coupled with the data you need to execute an action. Make sure that: a datastore is used in each dataset. each dataset has a corresponding input component (mapper or emitter). This input component must be able to work with only the dataset part filled by final users. Any other property implemented for that component must be optional. These rules are enforced by the validateDataSet validation. If the conditions are not met, the component builds will fail. Make sure that: a datastore is used in each dataset. each dataset has a corresponding input component (mapper or emitter). This input component must be able to work with only the dataset part filled by final users. Any other property implemented for that component must be optional. These rules are enforced by the validateDataSet validation. If the conditions are not met, the component builds will fail. A datastore defines the information required to connect to a data source. For example, it can be made of: a URL a username a password. You can specify a datastore and its context of use (in which dataset, etc.) from the Component Kit Starter. Make sure to modelize the data your components are designed to handle before defining datasets and datastores in the Component Kit Starter. Once you generate and import the project into an IDE, you can find datastores under a specific datastore node. Example of datastore: A dataset represents the inbound data. It is generally made of: A datastore that defines the connection information needed to access the data. A query. You can specify a dataset and its context of use (in which input and output component it is used) from the Component Kit Starter. Make sure to modelize the data your components are designed to handle before defining datasets and datastores in the Component Kit Starter. Once you generate and import the project into an IDE, you can find datasets under a specific dataset node. Example of dataset referencing the datastore shown above: The display name of each dataset and datastore must be referenced in the message.properties file of the family package. The key for dataset and datastore display names follows a defined pattern: ${family}.${configurationType}.${name}._displayName. For example: These keys are automatically added for datasets and datastores defined from the Component Kit Starter. When deploying a component or set of components that include datasets and datastores to Talend Studio, a new node is created under Metadata. This node has the name of the component family that was deployed. It allows users to create reusable configurations for datastores and datasets. With predefined datasets and datastores, users can then quickly fill the component configuration in their jobs. They can do so by selecting Repository as Property Type and by browsing to the predefined dataset or datastore. Studio will generate connection and close components auto for reusing connection function in input and output components, just need to do like this example: Then the runtime mapper and processor only need to use @Connection to get the connection like this: The component server scans all configuration types and returns a configuration type index. This index can be used for the integration into the targeted platforms (Studio, web applications, and so on). Mark a model (complex object) as being a dataset. API: @org.talend.sdk.component.api.configuration.type.DataSet Sample: Mark a model (complex object) as being a datastore (connection to a backend). API: @org.talend.sdk.component.api.configuration.type.DataStore Sample: Mark a model (complex object) as being a dataset discovery configuration. API: @org.talend.sdk.component.api.configuration.type.DatasetDiscovery Sample: The component family associated with a configuration type (datastore/dataset) is always the one related to the component using that configuration. The configuration type index is represented as a flat tree that contains all the configuration types, which themselves are represented as nodes and indexed by ID. Every node can point to other nodes. This relation is represented as an array of edges that provides the child IDs. As an illustration, a configuration type index for the example above can be defined as follows: If you need to define a binding between properties, you can use a set of annotations: 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: Allows to set multiple visibility conditions on the same property. API: @org.talend.sdk.component.api.configuration.condition.ActiveIfs Type: ifs Sample: Where: target is the element to evaluate. value is the value to compare against. strategy (optional) is the evaluation criteria. Possible values are: CONTAINS: Checks if a string or list of strings contains the defined value. DEFAULT: Compares against the raw value. LENGTH: For an array or string, evaluates the size of the value instead of the value itself. negate (optional) defines if the test must be positive (default, set to false) or negative (set to true). operator (optional) is the comparison operator used to combine several conditions, if applicable. Possible values are AND and OR. The target element location is specified as a relative path to the current location, using Unix path characters. The configuration class delimiter is /. The parent configuration class is specified by ... Thus, ../targetProperty denotes a property, which is located in the parent configuration class and is named targetProperty. When using the programmatic API, metadata is prefixed with tcomp::. This prefix is stripped in the web for convenience, and the previous table uses the web keys. For more details, refer to the related Javadocs. A common use of the ActiveIf condition consists in testing if a target property has a value. To do that, it is possible to test if the length of the property value is different from 0: target: foo - the path to the property to evaluate. strategy: LENGTH - the strategy consists here in testing the length of the property value. value: 0 - the length of the property value is compared to 0. negate: true - setting negate to true means that the strategy of the target must be different from the value defined. In this case, the LENGTH of the value of the foo property must be different from 0. The following example shows how to implement visibility conditions on several fields based on several checkbox configurations: If the first checkbox is selected, an additional input field is displayed. if the second or the third checkbox is selected, an additional input field is displayed. if both second and third checkboxes are selected, an additional input field is displayed. In some cases, you may need to add metadata about the configuration to let the UI render that configuration properly. For example, a password value that must be hidden and not a simple clear input box. For these cases - if you want to change the UI rendering - you can use a particular set of annotations: Provide a default value the UI can use - only for primitive fields. API: @org.talend.sdk.component.api.configuration.ui.DefaultValue Allows to sort a class properties. API: @org.talend.sdk.component.api.configuration.ui.OptionsOrder Request the rendered to do what it thinks is best. API: @org.talend.sdk.component.api.configuration.ui.layout.AutoLayout Advanced layout to place properties by row, this is exclusive with @OptionsOrder. the logic to handle forms (gridlayout names) is to use the only layout if there is only one defined, else to check if there are Main and Advanced and if at least Main exists, use them, else use all available layouts. API: @org.talend.sdk.component.api.configuration.ui.layout.GridLayout 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 Put on a configuration class it notifies the UI an horizontal layout is preferred. API: @org.talend.sdk.component.api.configuration.ui.layout.HorizontalLayout Put on a configuration class it notifies the UI a vertical layout is preferred. API: @org.talend.sdk.component.api.configuration.ui.layout.VerticalLayout Mark a table column filled by component’s schema auto. Only for studio. API: @org.talend.sdk.component.api.configuration.ui.widget.BasedOnSchema Mark a field as being represented by some code widget (vs textarea for instance). API: @org.talend.sdk.component.api.configuration.ui.widget.Code 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 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 Mark a string field as being represented by selected module list widget, only for studio API: @org.talend.sdk.component.api.configuration.ui.widget.ModuleList Mark a option as being represented by file or directory widget. Only for studio. API: @org.talend.sdk.component.api.configuration.ui.widget.Path Mark a List or List

This tutorial walks you through the creation, from scratch, of a complete Talend input component for Hazelcast using the Talend Component Kit (TCK) framework. Hazelcast is an in-memory distributed system that can store data, which makes it a good example of input component for distributed systems. This is enough for you to get started with this tutorial, but you can find more information about it here: hazelcast.org/. A TCK project is a simple Java project with specific configurations and dependencies. You can choose your preferred build tool from Maven or Gradle as TCK supports both. In this tutorial, Maven is used. The first step consists in generating the project structure using Talend Starter Toolkit . Go to starter-toolkit.talend.io/ and fill in the project information as shown in the screenshots below, then click Finish and Download as ZIP. image::tutorial_hazelcast_generateproject_1.png[] image::tutorial_hazelcast_generateproject_2.png[] Extract the ZIP file into your workspace and import it to your preferred IDE. This tutorial uses Intellij IDE, but you can use Eclipse or any other IDE that you are comfortable with. You can use the Starter Toolkit to define the full configuration of the component, but in this tutorial some parts are configured manually to explain key concepts of TCK. The generated pom.xml file of the project looks as follows: Change the name tag to a more relevant value, for example: Component Hazelcast. The component-api dependency provides the necessary API to develop the components. talend-component-maven-plugin provides build and validation tools for the component development. The Java compiler also needs a Talend specific configuration for the components to work correctly. The most important is the -parameters option that preserves the parameter names needed for introspection features that TCK relies on. Download the mvn dependencies declared in the pom.xml file: You should get a BUILD SUCCESS at this point: Create the project structure: Create the component Java packages. Packages are mandatory in the component model and you cannot use the default one (no package). It is recommended to create a unique package per component to be able to reuse it as dependency in other components, for example to guarantee isolation while writing unit tests. The project is now correctly set up. The next steps consist in registering the component family and setting up some properties. Registering every component family allows the component server to properly load the components and to ensure they are available in Talend Studio. The family registration happens via a package-info.java file that you have to create. Move to the src/main/java/org/talend/components/hazelcast package and create a package-info.java file: @Components: Declares the family name and the categories to which the component belongs. @Icon: Defines the component family icon. This icon is visible in the Studio metadata tree. Talend Component Kit supports internationalization (i18n) via Java properties files. Using these files, you can customize and translate the display name of properties such as the name of a component family or, as shown later in this tutorial, labels displayed in the component configuration. Go to src/main/resources/org/talend/components/hazelcast and create an i18n Messages.properties file as below: You can define the component family icon in the package-info.java file. The icon image must exist in the resources/icons folder. TCK supports both SVG and PNG formats for the icons. Create the icons folder and add an icon image for the Hazelcast family. This tutorial uses the Hazelcast icon from the official GitHub repository that you can get from: avatars3.githubusercontent.com/u/1453152?s=200&v=4 Download the image and rename it to Hazelcast_icon32.png. The name syntax is important and should match _icon.32.png. The component registration is now complete. The next step consists in defining the component configuration. All Input and Output (I/O) components follow a predefined model of configuration. The configuration requires two parts: Datastore: Defines all properties that let the component connect to the targeted system. Dataset: Defines the data to be read or written from/to the targeted system. Connecting to the Hazelcast cluster requires the IP address, group name and password of the targeted cluster. In the component, the datastore is represented by a simple POJO. Create a HazelcastDatastore.java class file in the src/main/java/org/talend/components/hazelcast folder. Define the i18n properties of the datastore. In the Messages.properties file let add the following lines: The Hazelcast datastore is now defined. Hazelcast includes different types of datastores. You can manipulate maps, lists, sets, caches, locks, queues, topics and so on. This tutorial focuses on maps but still applies to the other data structures. Reading/writing from a map requires the map name. Create the dataset class by creating a HazelcastDataset.java file in src/main/java/org/talend/components/hazelcast. The @Dataset annotation marks the class as a dataset. Note that it also references a datastore, as required by the components model. Just how it was done for the datastore, define the i18n properties of the dataset. To do that, add the following lines to the Messages.properties file. The component configuration is now ready. The next step consists in creating the Source that will read the data from the Hazelcast map. The Source is the class responsible for reading the data from the configured dataset. A source gets the configuration instance injected by TCK at runtime and uses it to connect to the targeted system and read the data. Create a new class as follows. The source also needs i18n properties to provide a readable display name. Add the following line to the Messages.properties file. At this point, it is already possible to see the result in the Talend Component Web Tester to check how the configuration looks like and validate the layout visually. To do that, execute the following command in the project folder. This command starts the Component Web Tester and deploys the component there. Access localhost:8080/. The source is set up. It is now time to start creating some Hazelcast specific code to connect to a cluster and read values for a map. Add the hazelcast-client Maven dependency to the pom.xml of the project, in the dependencies node. Add a Hazelcast instance to the @PostConstruct method. Declare a HazelcastInstance attribute in the source class. Any non-serializable attribute needs to be marked as transient to avoid serialization issues. Implement the post construct method. The component configuration is mapped to the Hazelcast client configuration to create a Hazelcast instance. This instance will be used later to get the map from its name and read the map data. Only the required configuration in the component is exposed to keep the code as simple as possible. Implement the code responsible for reading the data from the Hazelcast map through the Producer method. The Producer implements the following logic: Check if the map iterator is already initialized. If not, get the map from its name and initialize the map iterator. This is done in the @Producer method to ensure the map is initialized only if the next() method is called (lazy initialization). It also avoids the map initialization in the PostConstruct method as the Hazelcast map is not serializable. All the objects initialized in the PostConstruct method need to be serializable as the source can be serialized and sent to another worker in a distributed cluster. From the map, create an iterator on the map keys that will read from the map. Transform every key/value pair into a Talend Record with a "key, value" object on every call to next(). The RecordBuilderFactory class used above is a built-in service in TCK injected via the Source constructor. This service is a factory to create Talend Records. Now, the next() method will produce a Record every time it is called. The method will return "null" if there is no more data in the map. Implement the @PreDestroy annotated method, responsible for releasing all resources used by the Source. The method needs to shut the Hazelcast client instance down to release any connection between the component and the Hazelcast cluster. The Hazelcast Source is completed. The next section shows how to write a simple unit test to check that it works properly. TCK provides a set of APIs and tools that makes the testing straightforward. The test of the Hazelcast Source consists in creating an embedded Hazelcast instance with only one member and initializing it with some data, and then in creating a test Job to read the data from it using the implemented Source. Add the required Maven test dependencies to the project. Initialize a Hazelcast test instance and create a map with some test data. To do that, create the HazelcastSourceTest.java test class in the src/test/java folder. Create the folder if it does not exist. The above example creates a Hazelcast instance for the test and creates the MY-DISTRIBUTED-MAP map. The getMap creates the map if it does not already exist. Some keys and values uses in the test are added. Then, a simple test checks that the data is correctly initialized. Finally, the Hazelcast test instance is shut down. Run the test and check in the logs that a Hazelcast cluster of one member has been created and that the test has passed. To be able to test components, TCK provides the @WithComponents annotation which enables component testing. Add this annotation to the test. The annotation takes the component Java package as a value parameter. Create the test Job that configures the Hazelcast instance and link it to an output that collects the data produced by the Source. Execute the unit test and check that it passes, meaning that the Source is reading the data correctly from Hazelcast. The Source is now completed and tested. The next section shows how to implement the Partition Mapper for the Source. In this case, the Partition Mapper will split the work (data reading) between the available cluster members to distribute the workload. The Partition Mapper calculates the number of Sources that can be created and executed in parallel on the available workers of a distributed system. For Hazelcast, it corresponds to the cluster member count. To fully illustrate this concept, this section also shows how to enhance the test environment to add more Hazelcast cluster members and initialize it with more data. Instantiate more Hazelcast instances, as every Hazelcast instance corresponds to one member in a cluster. In the test, it is reflected as follows: The above code sample creates two Hazelcast instances, leading to the creation of two Hazelcast members. Having a cluster of two members (nodes) will allow to distribute the data. The above code also adds more data to the test map and updates the shutdown method and the test. Run the test on the multi-nodes cluster. The Source is a simple implementation that does not distribute the workload and reads the data in a classic way, without distributing the read action to different cluster members. Start implementing the Partition Mapper class by creating a HazelcastPartitionMapper.java class file. When coupling a Partition Mapper with a Source, the Partition Mapper becomes responsible for injecting parameters and creating source instances. This way, all the attribute initialization part moves from the Source to the Partition Mapper class. The configuration also sets an instance name to make it easy to find the client instance in the logs or while debugging. The Partition Mapper class is composed of the following: constructor: Handles configuration and service injections Assessor: This annotation indicates that the method is responsible for assessing the dataset size. The underlying runner uses the estimated dataset size to compute the optimal bundle size to distribute the workload efficiently. Split: This annotation indicates that the method is responsible for creating Partition Mapper instances based on the bundle size requested by the underlying runner and the size of the dataset. It creates as much partitions as possible to parallelize and distribute the workload efficiently on the available workers (known as members in the Hazelcast case). Emitter: This annotation indicates that the method is responsible for creating the Source instance with an adapted configuration allowing to handle the amount of records it will produce and the required services. I adapts the configuration to let the Source read only the requested bundle of data. The Assessor method computes the memory size of every member of the cluster. Implementing it requires submitting a calculation task to the members through a serializable task that is aware of the Hazelcast instance. Create the serializable task. The purpose of this class is to submit any task to the Hazelcast cluster. Use the created task to estimate the dataset size in the Assessor method. The Assessor method calculates the memory size that the map occupies for all members. In Hazelcast, distributing a task to all members can be achieved using an execution service initialized in the getExecutorService() method. The size of the map is requested on every available member. By summing up the results, the total size of the map in the distributed cluster is computed. The Split method calculates the heap size of the map on every member of the cluster. Then, it calculates how many members a source can handle. If a member contains less data than the requested bundle size, the method tries to combine it with another member. That combination can only happen if the combined data size is still less or equal to the requested bundle size. The following code illustrates the logic described above. The next step consists in adapting the source to take the Split into account. The following sample shows how to adapt the Source to the Split carried out previously. The next method reads the data from the members received from the Partition Mapper. A Big Data runner like Spark will get multiple Source instances. Every source instance will be responsible for reading data from a specific set of members already calculated by the Partition Mapper. The data is fetched only when the next method is called. This logic allows to stream the data from members without loading it all into the memory. Implement the method annotated with @Emitter in the HazelcastPartitionMapper class. The createSource() method creates the source instance and passes the required services and the selected Hazelcast members to the source instance. Run the test and check that it works as intended. The component implementation is now done. It is able to read data and to distribute the workload to available members in a Big Data execution environment. Refactor the component by introducing a service to make some pieces of code reusable and avoid code duplication. Refactor the Hazelcast instance creation into a service. Inject this service to the Partition Mapper to reuse it. Adapt the Source class to reuse the service. Run the test one last time to ensure everything still works as expected. Thank you for following this tutorial. Use the logic and approach presented here to create any input component for any system.

To develop new components, Talend Component Kit requires a build tool in which you will import the component project generated from the starter. You will then be able to install and deploy it to Talend applications. A Talend Component Kit plugin is available for each of the supported build tools. talend-component-maven-plugin helps you write components that match best practices and generate transparently metadata used by Talend Studio. You can use it as follows: This plugin is also an extension so you can declare it in your build/extensions block as: Used as an extension, the goals detailed in this document will be set up. The Talend Component Kit plugin integrates some specific goals within Maven build lifecycle. For example, to compile the project and prepare for deploying your component, run mvn clean install. Using this command, the following goals are executed: The build is split into several phases. The different goals are executed in the order shown above. Talend Component Kit uses default goals from the Maven build lifecycle and adds additional goals to the building and packaging phases. Goals added to the build by Talend Component Kit are detailed below. The default lifecycle is detailed in Maven documentation. The Talend Component Kit plugin for Maven integrates several specific goals into Maven build lifecycle. To run specific goals individually, run the following command from the root of the project, by adapting it with each goal name, parameters and values: The first goal is a shortcut for the maven-dependency-plugin. It creates the TALEND-INF/dependencies.txt file with the compile and runtime dependencies, allowing the component to use it at runtime: The scan-descriptor goal scans the current module and optionally other configured folders to precompute the list of interesting classes for the framework (components, services). It allows to save some bootstrap time when launching a job, which can be useful in some execution cases: Configuration - excluding parameters used by default only: Name Description User property Default output Where to dump the scan result. Note: It is not supported to change that value in the runtime. talend.scan.output ${project.build.outputDirectory}/TALEND-INF/scanning.properties scannedDirectories Explicit list of directories to scan. talend.scan.scannedDirectories If not set, defaults to ${project.build.outputDirectory} scannedDependencies Explicit list of dependencies to scan - set them in the groupId:artifactId format. The list is appended to the file to scan. talend.scan.scannedDependencies - The svg2png goal scans a directory - default to target/classes/icons - to find .svg files and copy them in a PNG version size at 32x32px and named with the suffix _icon32.png to enable the studio to read it: Configuration: Name Description User property Default icons Where to scan for the SVG icons to convert in PNG. talend.icons.source ${project.build.outputDirectory}/icons workarounds By default the shape of the icon will be enforce in the RGB channels (in white) using the alpha as reference. This is useful for black/white images using alpha to shape the picture because Eclipse - Talend Studio - caches icons using RGB but not alpha channel, pictures not using alpha channel to draw their shape should disable that workaround. talend.icons.workaround true if you use that plugin, ensure to set it before the validate mojo otherwise validation can miss some png files. This goal helps you validate the common programming model of the component. To activate it, you can use following execution definition: It is bound to the process-classes phase by default. When executed, it performs several validations that can be disabled by setting the corresponding flags to false in the block of the execution: Name Description User property Default validateInternationalization Validates that resource bundles are presents and contain commonly used keys (for example, _displayName) talend.validation.internationalization true validateModel Ensures that components pass validations of the ComponentManager and Talend Component runtime talend.validation.model true validateSerializable Ensures that components are Serializable. This is a sanity check, the component is not actually serialized here. If you have a doubt, make sure to test it. It also checks that any @Internationalized class is valid and has its keys. talend.validation.serializable true validateMetadata Ensures that components have an @Icon and a @Version defined. talend.validation.metadata true validateDataStore Ensures that any @DataStore defines a @HealthCheck and has a unique name. talend.validation.datastore true validateDataSet Ensures that any @DataSet has a unique name. Also ensures that there is a source instantiable just filling the dataset properties (all others not being required). Finally, the validation checks that each input or output component uses a dataset and that this dataset has a datastore. talend.validation.dataset true validateComponent Ensures that the native programming model is respected. You can disable it when using another programming model like Beam. talend.validation.component true validateActions Validates action signatures for actions not tolerating dynamic binding (@HealthCheck, @DynamicValues, and so on). It is recommended to keep it set to true. talend.validation.action true validateFamily Validates the family by verifying that the package containing the @Components has a @Icon property defined. talend.validation.family true validateDocumentation Ensures that all components and @Option properties have a documentation using the @Documentation property. talend.validation.documentation true validateLayout Ensures that the layout is referencing existing options and properties. talend.validation.layout true validateOptionNames Ensures that the option names are compliant with the framework. It is highly recommended and safer to keep it set to true. talend.validation.options true validateLocalConfiguration Ensures that if any TALEND-INF/local-configuration.properties exists then keys start with the family name. talend.validation.localConfiguration true validateOutputConnection Ensures that an output has only one input branch. talend.validation.validateOutputConnection true validatePlaceholder Ensures that string options have a placeholder. It is highly recommended to turn this property on. talend.validation.placeholder false locale The locale used to validate internationalization. talend.validation.locale root The asciidoc goal generates an Asciidoc file documenting your component from the configuration model (@Option) and the @Documentation property that you can add to options and to the component itself. Name Description User property Default level Level of the root title. talend.documentation.level 2 (==) output Output folder path. It is recommended to keep it to the default value. talend.documentation.output ${classes}/TALEND-INF/documentation.adoc formats Map of the renderings to do. Keys are the format (pdf or html) and values the output paths. talend.documentation.formats - attributes Asciidoctor attributes to use for the rendering when formats is set. talend.documentation.attributes - templateEngine Template engine configuration for the rendering. talend.documentation.templateEngine - templateDir Template directory for the rendering. talend.documentation.templateDir - title Document title. talend.documentation.title ${project.name} version The component version. It defaults to the pom version talend.documentation.version ${project.version} workDir The template directory for the Asciidoctor rendering - if 'formats' is set. talend.documentation.workdDir ${project.build.directory}/talend-component/workdir attachDocumentations Allows to attach (and deploy) the documentations (.adoc, and formats keys) to the project. talend.documentation.attach true htmlAndPdf If you use the plugin as an extension, you can add this property and set it to true in your project to automatically get HTML and PDF renderings of the documentation. talend.documentation.htmlAndPdf false To render the generated documentation in HTML or PDF, you can use the Asciidoctor Maven plugin (or Gradle equivalent). You can configure both executions if you want both HTML and PDF renderings. Make sure to execute the rendering after the documentation generation. If you prefer a HTML rendering, you can configure the following execution in the asciidoctor plugin. The example below: Generates the components documentation in target/classes/TALEND-INF/documentation.adoc. Renders the documentation as an HTML file stored in target/documentation/documentation.html. If you prefer a PDF rendering, you can configure the following execution in the asciidoctor plugin: If you want to add some more content or a title, you can include the generated document into another document using Asciidoc include directive. For example: To be able to do that, you need to pass the generated_doc attribute to the plugin. For example: This is optional but allows to reuse Maven placeholders to pass paths, which can be convenient in an automated build. You can find more customization options on Asciidoctor website. Testing the rendering of your component configuration into the Studio requires deploying the component in Talend Studio. Refer to the Studio documentation. In the case where you need to deploy your component into a Cloud (web) environment, you can test its web rendering by using the web goal of the plugin: Run the mvn talend-component:web command. Open the following URL in a web browser: localhost:8080. Select the component form you want to see from the treeview on the left. The selected form is displayed on the right. Two parameters are available with the plugin: serverPort, which allows to change the default port (8080) of the embedded server. Its associated user property is talend.web.port. serverArguments, that you can use to pass Meecrowave options to the server. Learn more about that configuration at openwebbeans.apache.org/meecrowave/meecrowave-core/cli.html. Make sure to install the artifact before using this command because it reads the component JAR from the local Maven repository. Finally, you can switch the lang of the component UI (documentation, form) using language query parameter in the webapp. For instance localhost:8080?language=fr. If you built a custom UI (JS + CSS) bundle and want to test it in the web application, you can configure it in the pom.xml file as follows: This is an advanced feature designed for expert users. Use it with caution. Component ARchive (.car) is the way to bundle a component to share it in the Talend ecosystem. It is an executable Java ARchive (.jar) containing a metadata file and a nested Maven repository containing the component and its dependencies. This command creates a .car file in your build directory. This file can be shared on Talend platforms. This command has some optional parameters: Name Description User property Default attach Specifies whether the component archive should be attached. talend.car.attach true classifier The classifier to use if attach is set to true. talend.car.classifier component metadata Additional custom metadata to bundle in the component archive. - - output Specifies the output path and name of the archive talend.car.output ${project.build.directory}/${project.build.finalName}.car packaging Specifies the packaging - ${project.packaging} type Specifies the type: `connector' or server `extension' talend.car.type connector This CAR is executable and exposes the studio-deploy command which takes a Talend Studio home path as parameter. When executed, it installs the dependencies into the Studio and registers the component in your instance. For example: You can also upload the dependencies to your Nexus server using the following command: In this command, Nexus URL and repository name are mandatory arguments. All other arguments are optional. If arguments contain spaces or special symbols, you need to quote the whole value of the argument. For example: The deploy-in-studio goal deploys the current component module into a local Talend Studio instance. Name Description User property Default studioHome Path to the Studio home directory talend.component.studioHome - studioM2 Path to the Studio maven repository if not the default one talend.component.studioM2 - You can use the following command from the root folder of your project: The help goal displays help information on talend-component-maven-plugin. Call mvn talend-component:help -Ddetail=true -Dgoal= to display the parameter details of a specific goal. Name Description User property Default detail Displays all settable properties for each goal. detail false goal The name of the goal for which to show help. If unspecified, all goals are displayed. goal - indentSize Number of spaces per indentation level. This integer should be positive. indentSize 2 lineLength Maximum length of a display line. This integer should be positive. lineLength 80

This tutorial shows how to adapt the test configuration of the Zendesk search component that was done in this previous tutorial to make it work in a Continuous Integration environment. In the test, the Zendesk credentials are used directly in the code to perform a first capture of the API response. Then, fake credentials are used in the simulation mode because the real API is not called anymore. However, in some cases, you can require to continue calling the real API on a CI server or on a specific environment. To do that, you can adapt the test to get the credentials depending on the execution mode (simulation/passthrough). These instructions concern the CI server or on any environment that requires real credentials. This tutorial uses: A Maven server that supports password encryption as a credential provider. Encryption is optional but recommended. The MavenDecrypterRule test rule provided by the framework. This rule lets you get credentials from Maven settings using a server ID. To create encrypted server credentials for the Zendesk instance: Create a master password using the command: mvn --encrypt-master-password . Store this master password in the settings-security.xml file of the ~/.m2 folder. Encrypt the Zendesk instance password using the command: mvn --encrypt-password . Create a server entry under servers in Maven settings.xml file located in the ~/.m2 folder. You can store the settings-security.xml and settings.xml files elsewhere that the default location (~/.m2). To do that, set the path of the directory containing the files in the talend.maven.decrypter.m2.location environment variable. Add the MavenDecrypterRule rule to the test class. This rule allows to inject server information stored in Maven settings.xml file to the test. The rule also decrypts credentials if they are encrypted. Inject the Zendesk server to the test. To do that, add a new field to the class with the @DecryptedServer annotation, that holds the server ID to be injected. The MavenDecrypterRule is able to inject the server instance into this class at runtime. The server instance contains the username and the decrypted password. Use the server instance in the test to get the real credentials in a secured manner. Once modified, the complete test class looks as follows: This test will continue to work in simulation mode, because the API simulation proxy is activated. This tutorial shows how to set up a CI server in passthrough mode using Jenkins. Log in to Jenkins. Click New Item to create a new build job. Enter an Item name (Job name) and choose the freestyle job. Then click OK. In the Source Code Management section, enter your project repository URL. A GitHub repository is used in this tutorial. Specify the master branch as Branches to build. In the Build section, click Add build step and choose Invoke top-level Maven targets. Choose your Maven version and enter the Maven build command. In this case: clean install. Then, click Save. The -Dtalend.junit.http.passthrough=true option is part of the build command. This option tells the API simulation proxy to run in passthrough mode. This way, all the HTTP requests made in the test are forwarded to the real API server. The MavenDecrypterRule rule allows to get the real credentials. You can configure the passthrough mode globally on your CI server by setting the talend.junit.http.passthrough environment variable to true. Test the job by selecting Build now, and check that the job has built correctly. Now your tests run in a simulation mode on your development environment and in a passthrough mode on your CI server.

It is possible to extend the Component API for custom front features. What is important here is to keep in mind that you should do it only if it targets not portable components (only used by the Studio or Beam). It is recommended to create a custom xxxx-component-api module with the new set of annotations. To extend the UI, add an annotation that can be put on @Option fields, and that is decorated with @Ui. All its members are then put in the metadata of the parameter. For example:

Datasets and datastores are configuration types that define how and where to pull the data from. They are used at design time to create shared configurations that can be stored and used at runtime. All connectors (input and output components) created using Talend Component Kit must reference a valid dataset. Each dataset must reference a datastore. Datastore: The data you need to connect to the backend. Dataset: A datastore coupled with the data you need to execute an action. Make sure that: a datastore is used in each dataset. each dataset has a corresponding input component (mapper or emitter). This input component must be able to work with only the dataset part filled by final users. Any other property implemented for that component must be optional. These rules are enforced by the validateDataSet validation. If the conditions are not met, the component builds will fail. Make sure that: a datastore is used in each dataset. each dataset has a corresponding input component (mapper or emitter). This input component must be able to work with only the dataset part filled by final users. Any other property implemented for that component must be optional. These rules are enforced by the validateDataSet validation. If the conditions are not met, the component builds will fail. A datastore defines the information required to connect to a data source. For example, it can be made of: a URL a username a password. You can specify a datastore and its context of use (in which dataset, etc.) from the Component Kit Starter. Make sure to modelize the data your components are designed to handle before defining datasets and datastores in the Component Kit Starter. Once you generate and import the project into an IDE, you can find datastores under a specific datastore node. Example of datastore: A dataset represents the inbound data. It is generally made of: A datastore that defines the connection information needed to access the data. A query. You can specify a dataset and its context of use (in which input and output component it is used) from the Component Kit Starter. Make sure to modelize the data your components are designed to handle before defining datasets and datastores in the Component Kit Starter. Once you generate and import the project into an IDE, you can find datasets under a specific dataset node. Example of dataset referencing the datastore shown above: The display name of each dataset and datastore must be referenced in the message.properties file of the family package. The key for dataset and datastore display names follows a defined pattern: ${family}.${configurationType}.${name}._displayName. For example: These keys are automatically added for datasets and datastores defined from the Component Kit Starter. When deploying a component or set of components that include datasets and datastores to Talend Studio, a new node is created under Metadata. This node has the name of the component family that was deployed. It allows users to create reusable configurations for datastores and datasets. With predefined datasets and datastores, users can then quickly fill the component configuration in their jobs. They can do so by selecting Repository as Property Type and by browsing to the predefined dataset or datastore. Studio will generate connection and close components auto for reusing connection function in input and output components, just need to do like this example: Then the runtime mapper and processor only need to use @Connection to get the connection like this: The component server scans all configuration types and returns a configuration type index. This index can be used for the integration into the targeted platforms (Studio, web applications, and so on). Mark a model (complex object) as being a dataset. API: @org.talend.sdk.component.api.configuration.type.DataSet Sample: Mark a model (complex object) as being a datastore (connection to a backend). API: @org.talend.sdk.component.api.configuration.type.DataStore Sample: Mark a model (complex object) as being a dataset discovery configuration. API: @org.talend.sdk.component.api.configuration.type.DatasetDiscovery Sample: The component family associated with a configuration type (datastore/dataset) is always the one related to the component using that configuration. The configuration type index is represented as a flat tree that contains all the configuration types, which themselves are represented as nodes and indexed by ID. Every node can point to other nodes. This relation is represented as an array of edges that provides the child IDs. As an illustration, a configuration type index for the example above can be defined as follows:

You can integrate and start using components developed using Talend Component Kit in Talend applications very easily. As both the development framework and Talend applications evolve over time, you need to ensure compatibility between the components you develop and the versions of Talend applications that you are targeting, by making sure that you use the right version of Talend Component Kit. The version of Talend Component Kit you need to use to develop new components depends on the versions of the Talend applications in which these components will be integrated. Talend product Talend Component Kit version Talend Studio 8.8.8 (aka master) latest release Talend Studio 8.0.1 latest release QA approved Talend Studio 7.3.1 Framework until 1.38.x Talend Studio 7.2.1 Framework until 1.1.10 Talend Studio 7.1.1 Framework until 1.1.1 Talend Studio 7.0.1 Framework until 0.0.5 Talend Cloud latest release QA and cloud teams approved More recent versions of Talend Component Kit contain many fixes, improvements and features that help developing your components. However, they can cause some compatibility issues when deploying these components to older/different versions of Talend Studio and Talend Cloud. Choose the version of Talend Component Kit that best fits your needs. Creating a project using the Component Kit Starter always uses the latest release of Talend Component Kit. However, you can manually change the version of Talend Component Kit directly in the generated project. Go to your IDE and access the project root .pom file. Look for the org.talend.sdk.component dependency nodes. Replace the version in the relevant nodes with the version that you need to use for your project. You can use a Snapshot of the version under development using the -SNAPSHOT version and Sonatype snapshot repository.