Chapter 55. Getting Started with the Framework
Abstract
This chapter explains the basic principles of implementing a Camel component using the API component framework, based on code generated using the
camel-archetype-api-component Maven archetype.
55.1. Generate Code with the Maven Archetype
Maven archetypes
A Maven archetype is analogous to a code wizard: given a few simple parameters, it generates a complete, working Maven project, populated with sample code. You can then use this project as a template, customizing the implementation to create your own application.
The API component Maven archetype
The API component framework provides a Maven archetype,
camel-archetype-api-component, that can generate starting point code for your own API component implementation. This is the recommended approach to start creating your own API component.
Prerequisites
The only prerequisites for running the
camel-archetype-api-component archetype are that Apache Maven is installed and the Maven settings.xml file is configured to use the standard JBoss Fuse repositories. For more details, see appendix "Red Hat JBoss A-MQ Maven Repositories" in "Installation on Apache Karaf".
Invoke the Maven archetype
To create an
Example component, which uses the example URI scheme, invoke the camel-archetype-api-component archetype to generate a new Maven project, as follows:
mvn archetype:generate \ -DarchetypeGroupId=org.apache.camel.archetypes \ -DarchetypeArtifactId=camel-archetype-api-component \ -DarchetypeVersion=2.15.1.redhat-621084 \ -DgroupId=org.jboss.fuse.example \ -DartifactId=camel-api-example \ -Dname=Example \ -Dscheme=example \ -Dversion=1.0-SNAPSHOT \ -DinteractiveMode=false
Note
The backslash character,
\, at the end of each line represents line continuation, which works only on Linux and UNIX platforms. On Windows platforms, remove the backslash and put the arguments all on a single line.
Options
Options are provided to the archetype generation command using the syntax,
-DName=Value. Most of the options should be set as shown in the preceding mvn archetype:generate command, but a few of the options can be modified, to customize the generated project. The following table shows the options that you can use to customize the generated API component project:
| Name | Description |
|---|---|
groupId | (Generic Maven option) Specifies the group ID of the generated Maven project. By default, this value also defines the Java package name for the generated classes. Hence, it is a good idea to choose this value to match the Java package name that you want. |
artifactId | (Generic Maven option) Specifies the artifact ID of the generated Maven project. |
name | The name of the API component. This value is used for generating class names in the generated code (hence, it is recommended that the name should start with a capital letter). |
scheme | The default scheme to use in URIs for this component. You should make sure that this scheme does not conflict with the scheme of any existing Camel components. |
archetypeVersion | (Generic Maven option) Ideally, this should be the Apache Camel version used by the container where you plan to deploy the component. If necessary, however, you can also modify the versions of Maven dependencies after you have generated the project. |
Structure of the generated project
Assuming that the code generation step completes successfully, you should see a new directory,
camel-api-example, which contains the new Maven project. If you look inside the camel-api-example directory, you will see that it has the following general structure:
camel-api-example/
pom.xml
camel-api-example-api/
camel-api-example-component/
At the top level of the project is an aggregate POM,
pom.xml, which is configured to build two sub-projects, as follows:
- camel-api-example-api
- The API sub-project (named as
ArtifactId-api) holds the Java API which you are about to turn into a component. If you are basing the API component on a Java API that you wrote yourself, you can put the Java API code directly into this project.The API sub-project can be used for one or more of the following purposes:- To package up the Java API code (if it is not already available as a Maven package).
- To generate Javadoc for the Java API (providing the needed metadata for the API component framework).
- To generate the Java API code from an API description (for example, from a WADL description of a REST API).
In some cases, however, you might not need to perform any of these tasks. For example, if the API component is based on a third-party API, which already provides the Java API and Javadoc in a Maven package. In such cases, you can delete the API sub-project. - camel-api-example-component
- The component sub-project (named as
ArtifactId-component) holds the implementation of the new API component. This includes the component implementation classes and the configuration of thecamel-api-component-mavenplug-in (which generates the API mapping classes from the Java API).
