talend-component-maven-plugin
intends to help you to write components
validating components match best practices and also generating transparently metadata used by Talend Studio.
Here is how to use it:
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${component.version}</version>
</plugin>
Note that this plugin is also an extension so you can declare it in your build/extensions
block as:
<extension>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${component.version}</version>
</extension>
Used as an extension, dependencies
, validate
and documentation
goals will be set up.
Dependencies
The first goal is a shortcut for the maven-dependency-plugin
, it will create the TALEND-INF/dependencies.txt
file
with the compile
and runtime
dependencies to let the component use it at runtime:
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${component.version}</version>
<executions>
<execution>
<id>talend-dependencies</id>
<goals>
<goal>dependencies</goal>
</goals>
</execution>
</executions>
</plugin>
Validate
The most important goal is here to help you to validate the common programming model of the component. Here is the execution definition to activate it:
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${component.version}</version>
<executions>
<execution>
<id>talend-component-validate</id>
<goals>
<goal>validate</goal>
</goals>
</execution>
</executions>
</plugin>
By default it will be bound to process-classes
phase. When executing it will do several validations which can be switched off
adding the corresponding flags to false
in the <configuration>
block of the execution:
Name | Description | Default |
---|---|---|
validateInternationalization |
Validates resource bundle are presents and contain commonly used keys (like |
true |
validateModel |
Ensure components pass validations of the |
true |
validateSerializable |
Ensure components are |
true |
validateMetadata |
Ensure components define an |
true |
validateDataStore |
Ensure any |
true |
validateComponent |
Ensure native programming model is respected, you can disable it when using another programming model like in beam case. |
true |
validateActions |
Validate actions signatures for the ones not tolerating dynamic binding ( |
true |
validateFamily |
Validate the family, i.e. the package containing the |
true |
validateDocumentation |
Ensure all 1. components and 2. |
true |
Documentation
This goal generates an Asciidoc file documenting your component from the configuration model (@Option
) and
@Documentation
you can put on options and the component itself.
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${component.version}</version>
<executions>
<execution>
<id>talend-component-documentation</id>
<goals>
<goal>asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
Name | Description | Default |
---|---|---|
level |
Which level are the root title |
2 which means |
output |
Where to store the output, it is NOT recommended to change it |
|
formats |
A map of the renderings to do, keys are the format ( |
- |
attributes |
A map of asciidoctor attributes when formats is set |
- |
templateDir / templateEngine |
Template configuration for the rendering |
- |
title |
Document title |
${project.name} |
attachDocumentations |
Should the documentations ( |
true |
if you use the extension you can add the property talend.documentation.htmlAndPdf and set it to true in your project
to automatically get a html and PDF rendering of the documentation.
|
Render your documentation
HTML
To render the generated documentation you can use the Asciidoctor Maven plugin (or Gradle equivalent):
<plugin> (1)
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${talend-component-kit.version}</version>
<executions>
<execution>
<id>documentation</id>
<phase>prepare-package</phase>
<goals>
<goal>asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin> (2)
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<executions>
<execution>
<id>doc-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${project.build.outputDirectory}/TALEND-INF</sourceDirectory>
<sourceDocumentName>documentation.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/documentation</outputDirectory>
<backend>html5</backend>
</configuration>
</execution>
</executions>
</plugin>
-
Will generate in
target/classes/TALEND-INF/documentation.adoc
the components documentation. -
Will render the documenation as an html file in
target/documentation/documentation.html
.
ensure to execute it after the documentation generation. |
If you prefer a PDF rendering you can configure the following execution in the asciidoctor plugin (note that you can configure both executions if you want both HTML and PDF rendering):
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<executions>
<execution>
<id>doc-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${project.build.outputDirectory}/TALEND-INF</sourceDirectory>
<sourceDocumentName>documentation.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/documentation</outputDirectory>
<backend>pdf</backend>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
</plugin>
Include the documentation into a document
If you want to add some more content or add a title, you can include the generated document into
another document using Asciidoc include
directive.
A common example is:
= Super Components
Super Writer
:toc:
:toclevels: 3
:source-highlighter: prettify
:numbered:
:icons: font
:hide-uri-scheme:
:imagesdir: images
Unresolved directive in build-tools-maven.adoc - include::{generated_doc}/documentation.adoc[]
This assumes you pass to the plugin the attribute generated_doc
, this can be done this way:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<executions>
<execution>
<id>doc-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${project.basedir}/src/main/asciidoc</sourceDirectory>
<sourceDocumentName>my-main-doc.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/documentation</outputDirectory>
<backend>html5</backend>
<attributes>
<generated_adoc>${project.build.outputDirectory}/TALEND-INF</generated_adoc>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
This is optional but allows to reuse maven placeholders to pass paths which is quite convenient in an automated build.
More
You can find more customizations on Asciidoctor website.
Web
Testing the rendering of your component(s) configuration into the Studio is just a matter of deploying a component
in Talend Studio (you can have a look to link::studio.html[Studio Documentation] page. But don’t forget
the component can also be deployed into a Cloud (web) environment. To ease the testing of the related rendering,
you can use the goal web
of the plugin:
mvn talend-component:web
Then you can test your component going on localhost:8080. You need to select which component form you want to see using the treeview on the left, then on the right the form will be displayed.
The two available configurations of the plugin are serverPort
which is a shortcut to change the default, 8080, port
of the embedded server and serverArguments
to pass Meecrowave options to the server. More on that configuration
is available at openwebbeans.apache.org/meecrowave/meecrowave-core/cli.html.
this command reads the component jar from the local maven repository so ensure to install the artifact before using it. |
Generate inputs or outputs
The Mojo generate
(maven plugin goal) of the same plugin also embeds a generator you can use to bootstrap any input or output component:
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${talend-component.version}</version>
<executions>
<execution> (1)
<id>generate-input</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<type>input</type>
</configuration>
</execution>
<execution> (2)
<id>generate-output</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<type>output</type>
</configuration>
</execution>
</executions>
</plugin>
1 | Generates an input (partition mapper + emitter) |
2 | Generates an output |
It is intended to be used from the command line (or IDE Maven integration):
$ mvn talend-component:generate \
-Dtalend.generator.type=[input|output] \ (1)
[-Dtalend.generator.classbase=com.test.MyComponent] \ (2)
[-Dtalend.generator.family=my-family] \ (3)
[-Dtalend.generator.pom.read-only=false] (4)
1 | select the type of component you want, input to generate a mapper and emitter and output to generate an output processor |
2 | set the class name base (will be suffixed by the component type), if not set the package will be guessed and classname based on the basedir name |
3 | set the component family to use, default to the base dir name removing (component[s] from the name, ex: my-component will lead to my as family if not explicitly set) |
4 | should the generator try to add component-api in the pom if not already here, if you added it you can set it to false directly in the pom |
For this command to work you will need to just register the plugin:
<plugin>
<groupId>org.talend.sdk.component</groupId>
<artifactId>talend-component-maven-plugin</artifactId>
<version>${talend-component.version}</version>
</plugin>
Talend Component Archive
Component ARchive (.car
) is the way to bundle a component to share it in Talend ecosystem. It is a plain Java ARchive (.jar
)
containing a metadata file and a nested maven repository containing the component and its depenencies.
mvn talend-component:car
It will create a .car
in your build directory which is shareable on Talend platforms.
Note that this CAR is executable and exposes the command studio-deploy
which takes as parameter
a Talend Studio home location. Executed it will install the dependencies into the studio and register the component
in your instance. Here is a sample launch command:
# for a studio
java -jar mycomponent.car studio-deploy /path/to/my/studio
# for a m2 provisioning
java -jar mycomponent.car maven-deploy /path/to/.m2/repository