Search results for Swagger
Talend Component scanning is based on plugins. To make sure that plugins can be developed in parallel and avoid conflicts, they need to be isolated (component or group of components in a single jar/plugin).
Multiple options are available:
Graph classloading: this option allows you to link the plugins and dependencies together dynamically in any direction. For example, the graph classloading can be illustrated by OSGi containers.
Tree classloading: a shared classloader inherited by plugin classloaders. However, plugin classloader classes are not seen by the shared classloader, nor by other plugins. For example, the tree classloading is commonly used by Servlet containers where plugins are web applications.
Flat classpath: listed for completeness but rejected by design because it doesn’t comply with this requirement.
In order to avoid much complexity added by this layer, Talend Component Kit relies on a tree classloading. The advantage is that you don’t need to define the relationship with other plugins/dependencies, because it is built-in.
Here is a representation of this solution:
The shared area contains Talend Component Kit API, which only contains by default the classes shared by the plugins.
Then, each plugin is loaded with its own classloader and dependencies.
This section explains the overall way to handle dependencies but the Talend Maven plugin provides a shortcut for that.
A plugin is a JAR file that was enriched with the list of its dependencies. By default, Talend Component Kit runtime is able to read the output of maven-dependency-plugin in TALEND-INF/dependencies.txt. You just need to make sure that your component defines the following plugin:
Once build, check the JAR file and look for the following lines:
What is important to see is the scope related to the artifacts:
The APIs (component-api and geronimo-annotation_1.3_spec) are provided because you can consider them to be there when executing (they come with the framework).
Your specific dependencies (awesome-project in the example above) are marked as compile: they are included as needed dependencies by the framework (note that using runtime works too).
the other dependencies are ignored. For example, test dependencies.
Even if a flat classpath deployment is possible, it is not recommended because it would then reduce the capabilities of the components.
The way the framework resolves dependencies is based on a local Maven repository layout. As a quick reminder, it looks like:
This is all the layout the framework uses. The logic converts t-uple {groupId, artifactId, version, type (jar)} to the path in the repository.
Talend Component Kit runtime has two ways to find an artifact:
From the file system based on a configured Maven 2 repository.
From a fat JAR (uber JAR) with a nested Maven repository under MAVEN-INF/repository.
The first option uses either ${user.home}/.m2/repository (default) or a specific path configured when creating a ComponentManager. The nested repository option needs some configuration during the packaging to ensure the repository is correctly created.
To create the nested MAVEN-INF/repository repository, you can use the nested-maven-repository extension:
Plugins are usually programmatically registered. If you want to make some of them automatically available, you need to generate a TALEND-INF/plugins.properties file that maps a plugin name to coordinates found with the Maven mechanism described above.
You can enrich maven-shade-plugin to do it:
Here is a final job/application bundle based on maven-shade-plugin:
The configuration unrelated to transformers depends on your application.
ContainerDependenciesTransformer embeds a Maven repository and PluginTransformer to create a file that lists (one per line) artifacts (representing plugins).
Both transformers share most of their configuration:
session: must be set to ${session}. This is used to retrieve dependencies.
scope: a comma-separated list of scopes to include in the artifact filtering (note that the default will rely on provided but you can replace it by compile, runtime, runtime+compile, runtime+system or test).
include: a comma-separated list of artifacts to include in the artifact filtering.
exclude: a comma-separated list of artifacts to exclude in the artifact filtering.
userArtifacts: set of artifacts to include (groupId, artifactId, version, type - optional, file - optional for plugin transformer, scope - optional) which can be forced inline. This parameter is mainly useful for PluginTransformer.
includeTransitiveDependencies: should transitive dependencies of the components be included. Set to true by default. It is active for userArtifacts.
includeProjectComponentDependencies: should component project dependencies be included. Set to false by default. It is not needed when a job project uses isolation for components.
With the component tooling, it is recommended to keep default locations. Also if you need to use project dependencies, you can need to refactor your project structure to ensure component isolation. Talend Component Kit lets you handle that part but the recommended practice is to use userArtifacts for the components instead of project
This document explains how Asciidoctor is used in the context of Talend Component Kit as well as the specific processes in place.
For general guidelines about Asciidoctor, refer to the Asciidoc Syntax quick reference page.
There are two ways to suggest modifications or new content. Both of the options below require you to have a GitHub account created.
On every page of the Talend Component Kit Developer Guide, a Suggest and edit button is available. It allows you to access the corresponding source file on GitHub and to create a pull request with the suggested edits. The pull request is then assessed by the team in charge of the project.
Fork the Runtime repository of the Talend Component Kit project and edit .adoc files located under documentation\src\main\antora\modules\ROOT\pages. Make sure to follow the guidelines outlined in the current document, especially for large modifications or new content, to make sure it can properly be rendered. When done, create a pull request that will be assessed by the team in charge of the project.
The documentation is made of:
Documentation files manually written under documentation\src\main\antora\modules\ROOT\pages.
Documentation files automatically generated from the source code under documentation\src\main\antora\modules\ROOT\pages\_partials. These files are individually called in manually written files through includes.
Assets, especially images, stored in the documentation\src\main\antora\modules\ROOT\assets folder. Some subfolders exist to categorize the assets.
Each file has a unique name and is rendered as a unique HTML page. Some of the files are prefixed to help identifying the type of content it contains. Most common examples are:
index- for pages referenced from the main index page. These pages also contain specific attributes to be correctly rendered on the main index page (see 'List of metadata attributes' below).
tutorial- for tutorials/guided examples.
generated_ for pages generated from the source code. These pages are generally stored in the _partials folder.
For all pages:
:page-partial indicates that the current .adoc file can be included in another document using an include::. This attribute has no value.
:page-talend_skipindexation: indicates that the current .adoc file must not be indexed. This attribute has no value. Add it to files that should not be returned in the search, like index files that only contain includes.
:description: is the meta description of the file. Each .adoc file is rendered as an HTML file.
:keywords: is the list of meta keywords relevant for the current .adoc file. Separate keywords using simple commas.
:page-talend_stage: draft indicates that the current document is a draft and is not final even if published. It triggers the display of a small banner indicating the status of the page. Remove this attribute once the page is final.
For pages that should appear as a tile on the index page:
:page-documentationindex-index: is the weight of the page. A low weight indicates that the page should be one of the first tiles to appear. A high weight will push the tile towards the end of the list in the index page.
:page-documentationindex-label: is the title of the tile in the index page.
:page-documentationindex-icon: is the icon of the tile in the index page. The value of this attribute should be the name of a free icon on fontawesome.
:page-documentationindex-description: is a short description of the page that will be displayed in the tile under its title.
For pages containing API descriptions:
:page-talend_Swaggerui: true indicates that the page contains some API reference that should be displayed using Swagger UI
The Talend Component Kit documentation is published as HTML and PDF. Some parts can differ between these two versions, such as lists of links, that are not functional in the PDF version.
To avoid this, it is possible to define some conditionality to have some content only displaying in one of the output formats only. For example:
Every .adoc file can only contain one 'level 1' title (=). It is the title of the page and is located at the top of the document. It is a best practices that all sublevels added to the document are kept consistent. For example, don’t use a 'level 3' (===) section directly inside a 'level 1'.
When possible, avoid going lower than section 2 (===) to keep the page readable. In the HTML output, the document title is renderedh1, section 1 titles as h2, etc. The "in-page" navigation available on the right side of the HTML rendering only considers h2 and h3 elements. Other levels are ignored to keep the navigation readable and simple.
It is possible to reuse content through "includes". Includes can be used to reuse entire files in other files, allowing to avoid copy pasting.
When using an 'include' (calling an .adoc file from another .adoc file), you can specify a level offset to keep the hierarchy consistent in the current document. Avoid using includes if not absolutely necessary. An include can be done as follows:
In this case, both doc1.adoc and doc2.adoc are rendered in the same page and their content is offset by one level, meaning that the document title of doc1 becomes a section 1 title (h2) instead of an h1 in the final rendering, and so on.
Note that both doc1.adoc and doc2.adoc will in addition be rendered as standalone pages (doc1.html and doc2.html).
All images are stored under documentation > src > main > antora > modules > ROOT > assets > images. Relatively to .adoc files, it can be ../assets/images/ or ../../assets/images for _partials (automatically generated from code) pages. To avoid handling different relative paths, the backend already resolves directly image: to the image folder. Hence, paths to images should start with the following:
image:(