For common concerns such as caching, auditing, and so on, you can use an interceptor-like API. It is enabled on services by the framework. An interceptor defines an annotation marked with @Intercepts, which defines the implementation of the interceptor (interceptorHandler). For example: The handler is created from its constructor and can take service injections (by type). The first parameter, however, can be BiFunction, which represents the invocation chain if your interceptor can be used with others. If you make a generic interceptor, pass the invoker as first parameter. Otherwise you cannot combine interceptors at all. Here is an example of interceptor implementation for the @Logged API: This implementation is compatible with interceptor chains because it takes the invoker as first constructor parameter and it also takes a service injection. Then, the implementation simply does what is needed, which is logging the invoked method in this case. The findAnnotation annotation, inherited from interceptorHandler, is an utility method to find an annotation on a method or class (in this order).

Services are configurations that can be reused across several classes. Talend Component Kit comes with a predefined set of services that you can easily use. You can still define your own services under the service node of your component project. By default, the Component Kit Starter generates a dedicated class in your project in which you can implement services. Built-in services Internationalizing a service Providing actions through a service Services and interceptors Defining a custom API

The framework provides built-in services that you can inject by type in components and actions. Type Description org.talend.sdk.component.api.service.cache.LocalCache Provides a small abstraction to cache data that does not need to be recomputed very often. Commonly used by actions for UI interactions. org.talend.sdk.component.api.service.dependency.Resolver Allows to resolve a dependency from its Maven coordinates. It can either try to resolve a local file or (better) creates for you a preinitialized classloader. javax.json.bind.Jsonb A JSON-B instance. If your model is static and you don’t want to handle the serialization manually using JSON-P, you can inject that instance. javax.json.spi.JsonProvider A JSON-P instance. Prefer other JSON-P instances if you don’t exactly know why you use this one. javax.json.JsonBuilderFactory A JSON-P instance. It is recommended to use this one instead of a custom one to optimize memory usage and speed. javax.json.JsonWriterFactory A JSON-P instance. It is recommended to use this one instead of a custom one to optimize memory usage and speed. javax.json.JsonReaderFactory A JSON-P instance. It is recommended to use this one instead of a custom one to optimize memory usage and speed. javax.json.stream.JsonParserFactory A JSON-P instance. It is recommended to use this one instead of a custom one to optimize memory usage and speed. javax.json.stream.JsonGeneratorFactory A JSON-P instance. It is recommended to use this one instead of a custom one to optimize memory usage and speed. org.talend.sdk.component.api.service.dependency.Resolver Allows to resolve files from Maven coordinates (like dependencies.txt for component). Note that it assumes that the files are available in the component Maven repository. org.talend.sdk.component.api.service.injector.Injector Utility to inject services in fields marked with @Service. org.talend.sdk.component.api.service.factory.ObjectFactory Allows to instantiate an object from its class name and properties. org.talend.sdk.component.api.service.record.RecordBuilderFactory Allows to instantiate a record. org.talend.sdk.component.api.service.record.RecordPointerFactory Allows to instantiate a RecordPointer which enables to extract a data from a Record based on jsonpointer specification. org.talend.sdk.component.api.service.record.RecordService Some utilities to create records from another one. It is typically what is used when you want to add an entry in a record and passthrough the other ones. It also provides a nice RecordVisitor API for advanced cases. org.talend.sdk.component.api.service.configuration.LocalConfiguration Represents the local configuration that can be used during the design. It is not recommended to use it for the runtime because the local configuration is usually different and the instances are distinct. You can also use the local cache as an interceptor with @Cached Every interface that extends HttpClient and that contains methods annotated with @Request Lets you define an HTTP client in a declarative manner using an annotated interface. See the Using HttpClient for more details. All these injected services are serializable, which is important for big data environments. If you create the instances yourself, you cannot benefit from these features, nor from the memory optimization done by the runtime. Prefer reusing the framework instances over custom ones. The local configuration uses system properties and the environment (replacing dots per underscores) to look up the values. You can also put a TALEND-INF/local-configuration.properties file with default values. This allows to use the local_configuration: syntax in @Ui annotation. Here is an example to read the default value of a property from the configuration: Ensure your key is unique across all components to avoid global overrides on the JVM. In practice, it is strongly recommended to always use the family as a prefix. Also note that you can use @Configuration("prefix") to inject a mapping of the LocalConfiguration in a component. It uses the same rules as for any configuration object. If you prefer to inject you configuration in a service, ensure to wrap it in a Supplier to always have an up to date version. If you want to ignore the local-configuration.properties, you can set the system property: talend.component.configuration.${componentPluginId}.ignoreLocalConfiguration=true. Here a sample @Configuration model: Here is how to use it from a service: And finally, here is how to use it in a component: it is recommended to convert this configuration in a runtime model in components to avoid to transport more than desired during the job distribution. You can access the API reference in the Javadocs. The HttpClient usage is described in this section by using the REST API example below. Assuming that it requires a basic authentication header: GET /api/records/{id} - POST /api/records JSON payload to be created: {"id":"some id", "data":"some data"} To create an HTTP client that is able to consume the REST API above, you need to define an interface that extends HttpClient. The HttpClient interface lets you set the base for the HTTP address that the client will hit. The base is the part of the address that needs to be added to the request path to hit the API. It is now possible, and recommended, to use @Base annotation. Every method annotated with @Request in the interface defines an HTTP request. Every request can have a @Codec parameter that allows to encode or decode the request/response payloads. You can ignore the encoding/decoding for String and Void payloads. The interface should extend HttpClient. In the codec classes (that implement Encoder/Decoder), you can inject any of your service annotated with @Service or @Internationalized into the constructor. Internationalization services can be useful to have internationalized messages for errors handling. The interface can be injected into component classes or services to consume the defined API. By default, /+json are mapped to JSON-P and /+xml to JAX-B if the model has a @XmlRootElement annotation. For advanced cases, you can customize the Connection by directly using @UseConfigurer on the method. It calls your custom instance of Configurer. Note that you can use @ConfigurerOption in the method signature to pass some Configurer configurations. For example, if you have the following Configurer: You can then set it on a method to automatically add the basic header with this kind of API usage: The framework provides in the component-api an OAuth1.Configurer which can be used as an example of configurer implementation. It expects a single OAuth1.Configuration parameter to be passed to the request as a @ConfigurationOption. Here is a sample showing how it can be used: By default, the client loads in memory the payload. In case of big payloads, it can consume too much memory. For these cases, you can get the payload as an InputStream: You can use the Response wrapper, or not.

The HTTP API intends to expose most Talend Component Kit features over HTTP. It is a standalone Java HTTP server. The WebSocket protocol is activated for the endpoints. Endpoints then use /websocket/v1 as base instead of /api/v1. See WebSocket for more details. Browse the API description using interface. To make sure that the migration can be enabled, you need to set the version the component was created with in the execution configuration that you send to the server (component version is in component the detail endpoint). To do that, use tcomp::component::version key. Endpoints that are intended to disappear will be deprecated. A X-Talend-Warning header will be returned with a message as value. You can connect yo any endpoint by: Replacing /api with /websocket Appending / to the URL Formatting the request as: For example: The response is formatted as follows: All endpoints are logged at startup. You can then find them in the logs if you have a doubt about which one to use. If you don’t want to create a pool of connections per endpoint/verb, you can use the bus endpoint: /websocket/v1/bus. This endpoint requires that you add the destinationMethod header to each request with the verb value (GET by default): the configuration is read from system properties, environment variables, …. Default value: 1000. Maximum items a cache can store, used for index endpoints. A comma separated list of gav to locate the components 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). Default value: true. Should the component extensions add required dependencies. If you deploy some extension, where they can create their dependencies if needed. 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. 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. Default value: true. Should the /documentation endpoint be activated. Note that when called on localhost the doc is always available. 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. Default value: false. Should the components using a @GridLayout support tab translation. Studio does not suppot that feature yet so this is not enabled by default. 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). Default value: false. If set it will replace any message for exceptions. Set to false to use the actual exception message. Default value: false. Should the lastUpdated timestamp value of /environment endpoint be updated with server start time. Default value: en*=en fr*=fr zh*=zh_CN ja*=ja de*=de. For caching reasons the goal is to reduce the locales to the minimum required numbers. For instance we avoid fr and fr_FR which would lead to the same entries but x2 in terms of memory. This mapping enables that by whitelisting allowed locales, default being en. If the key ends with it means all string starting with the prefix will match. For instance fr will match fr_FR but also fr_CA. The local maven repository used to locate components and their dependencies Default value: false. Should the plugins be un-deployed and re-deployed. Default value: 600. Interval in seconds between each check if plugins re-loading is enabled. Specify a file to check its timestamp on the filesystem. This file will take precedence of the default ones provided by the talend.component.server.component.registry property (used for timestamp method). Default value: timestamp. Re-deploy method on a timestamp or connectors version change. By default, the timestamp is checked on the file pointed by talend.component.server.component.registry or talend.component.server.plugins.reloading.marker variable, otherwise we inspect the content of the CONNECTORS_VERSION file. Accepted values: timestamp, anything else defaults to connectors. Default value: false. Should the all requests/responses be logged (debug purposes - only work when running with CXF). Default value: securityNoopHandler. How to validate a command/request. Accepted values: securityNoopHandler. Default value: securityNoopHandler. How to validate a connection. Accepted values: securityNoopHandler. 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 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. The configuration uses Microprofile Config for most entries. It means it can be passed through system properties and environment variables (by replacing dots with underscores and making the keys uppercase). To configure a Docker image rather than a standalone instance, Docker Config and secrets integration allows you to read the configuration from files. You can customize the configuration of these integrations through system properties. Docker integration provides a secure: support to encrypt values and system properties, when required. It is fully implemented using the Apache Geronimo Microprofile Config extensions. Using the server ZIP (or Docker image), you can configure HTTPS by adding properties to _JAVA_OPTIONS. Assuming that you have a certificate in /opt/certificates/component.p12 (don’t forget to add/mount it in the Docker image if you use it), you can activate it as follows: You can define simple queries on the configuration types and components endpoints. These two endpoints support different parameters. Queries on the configurationtype/index endpoint supports the following parameters: type id name metadata of the first configuration property as parameters. Queries on the component/index endpoint supports the following parameters: plugin name id familyId metadata of the first configuration property as parameters. In both cases, you can combine several conditions using OR and AND operators. If you combine more than two conditions, note that they are evaluated in the order they are written. Each supported parameter in a condition can be "equal to" (=) or "not equal to" (!=) a defined value (case-sensitive). For example: In this example, the query gets components that have a dataset and belong to the jdbc-component plugin, or components that are named input. The component-form library provides a way to build a component REST API facade that is compatible with React form library. for example: the Client can be created using ClientFactory.createDefault(System.getProperty("app.components.base", "http://localhost:8080/api/v1")) and the service can be a simple new UiSpecService<>(). The factory uses JAX-RS if the API is available (assuming a JSON-B provider is registered). Otherwise, it tries to use Spring. The conversion from the component model (REST API) to the uiSpec model is done through UiSpecService. It is based on the object model which is mapped to a UI model. Having a flat model in the component REST API allows to customize layers easily. You can completely control the available components, tune the rendering by switching the uiSchema, and add or remove parts of the form. You can also add custom actions and buttons for specific needs of the application. The /migrate endpoint was not shown in the previous snippet but if you need it, add it as well. This Maven dependency provides the UISpec model classes. You can use the Ui API (with or without the builders) to create UiSpec representations. For Example: The model uses the JSON-B API to define the binding. Make sure to have an implementation in your classpath. To do that, add the following dependencies: The following module enables you to define through annotations a uispec on your own models: this can’t be used in components and is only intended for web applications. org.talend.sdk.component.form.uispec.mapper.api.service.UiSpecMapper enables to create a Ui instance from a custom type annotated with org.talend.sdk.component.form.uispec.mapper.api.model.View and org.talend.sdk.component.form.uispec.mapper.api.model.View.Schema. UiSpecMapper returns a Supplier and not directly an Ui because the ui-schema is re-evaluated when `get()̀ is called. This enables to update the title maps for example. Here is an example: This API maps directly the UiSpec model (json schema and ui schema of Talend UIForm). The default implementation of the mapper is available at org.talend.sdk.component.form.uispec.mapper.impl.UiSpecMapperImpl. Here is an example: The getTitleMapProviders() method will generally lookup a set of TitleMapProvider instances in your IoC context. This API is used to fill the titleMap of the form when a reference identifier is set on the @Schema annotation. component-kit.js is no more available (previous versions stay on NPM) and is replaced by @talend/react-containers. The previous import can be replaced by import kit from '@talend/react-containers/lib/ComponentForm/kit';. Default JavaScript integration goes through the Talend UI Forms library and its Containers wrapper. Documentation is now available on the previous link. The logging uses Log4j2. You can specify a custom configuration by using the -Dlog4j.configurationFile system property or by adding a log4j2.xml file to the classpath. Here are some common configurations: Console logging: Output messages look like: JSON logging: Output messages look like: Rolling file appender: More details are available in the RollingFileAppender documentation. You can compose previous layout (message format) and appenders (where logs are written). The server image is deployed on Docker. Its version is suffixed with a timestamp to ensure images are not overridden and can break your usage. You can check the available version on Docker hub. You can run the docker image by executing this command : You can set the env variable _JAVA_OPTIONS to customize the server, by default it is installed in /opt/talend/component-kit. The maven repository is the default one of the machine, you can change it setting the system property talend.component.server.maven.repository=/path/to/your/m2. If you want to deploy some components you can configure which ones in _JAVA_OPTIONS (see server doc online) and redirect your local m2: The component server docker image comes with two log4j2 profiles: TEXT (default) and JSON. The logging profile can be changed by setting the environment variable LOGGING_LAYOUT to JSON. Note that Component Server adds to these default Talend profiles the KAFKA profile. With this profile, all logs are sent to Kafka. You can check the exact configuration in the component-runtime/images/component-server-image/src/main/resources folder. The console logging is on at INFO level by default. You can customize it by setting the CONSOLE_LOG_LEVEL environment variable to DEBUG, INFO, WARN or to any other log level supported by log4j2. Run docker image with console logging: The JSON profile does the following: Logs on the console using the CONSOLE_LOG_LEVEL configuration as the default profile. It uses the formatting shown below. If the TRACING_KAFKA_URL environment variable is set, it logs the opentracing data on the defined Kafka using the topic TRACING_KAFKA_TOPIC. This level can be customized by setting the KAFKA_LOG_LEVEL environment variable (INFO by default). Events are logged in the following format: This profile is very close to the JSON profile and also adds the LOG_KAFKA_TOPIC and LOG_KAFKA_URL configuration. The difference is that it logs the default logs on Kafka in addition to the tracing logs. The component server uses Geronimo OpenTracing to monitor request. The tracing can be activated by setting the TRACING_ON environment variable to true. The tracing rate is configurable by setting the TRACING_SAMPLING_RATE environment variable. It accepts 0 (none) and 1 (all, default) as values to ensure the consistency of the reporting. You can find all the details on the configuration in org.talend.sdk.component.server.configuration.OpenTracingConfigSource. Run docker image with tracing on: By default, Geronimo OpenTracing will log the spans in a Zipking format so you can use the Kafka profile as explained before to wire it over any OpenTracing backend. You can register component server images in Docker using these instructions in the corresponding image directory: Docker Compose allows you to deploy the server with components, by mounting the component volume into the server image. docker-compose.yml example: If you want to mount it from another image, you can use this compose configuration: To run one of the previous compose examples, you can use docker-compose -f docker-compose.yml up. Only use the configuration related to port 5005 (in ports and the -agentlib option in _JAVA_OPTIONS) to debug the server on port 5005. Don’t set it in production. You can mount a volume in /opt/talend/component-kit/custom/ and the jars in that folder which will be deployed with the server. Since the server relies on CDI (Apache OpenWebBeans) you can use that technology to enrich it, including JAX-RS endpoints, interceptors etc…or just libraries needing to be in the JVM.