Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 55. Configuring the API Component Maven Plug-In

Abstract

This chapter provides a reference for all of the configuration options available on the API component Maven plug-in.

55.1. Overview of the Plug-In Configuration
Copier lien

Overview
Copier lien

The main purpose of the API component Maven plug-in, camel-api-component-maven-plugin, is to generate the API mapping classes, which implement the mapping between endpoint URIs and API method invocations. By editing the configuration of the API component Maven plug-in, you can customize various aspects of the API mapping.

Location of the generated code
Copier lien

The API mapping classes generated by the API component Maven plug-in are placed in the following location, by default: 
ProjectName-component/target/generated-sources/camel-component
Copy to Clipboard Toggle word wrap

Prerequisites
Copier lien

The main inputs to the API component Maven plug-in are the Java API classes and the Javadoc metadata. These are made available to the plug-in by declaring them as regular Maven dependencies (where the Javadoc Maven dependencies should be declared with provided scope).

Setting up the plug-in
Copier lien

The recommended way to set up the API component Maven plug-in is to generate starting point code using the API component archetype. This generates the default plug-in configuration in the ProjectName-component/pom.xml file, which you can then customize for your project. The main aspects of the plug-in set-up are, as follows:
  1. Maven dependencies must be declared for the requisite Java API and for the Javadoc metadata.
  2. The plug-in's base configuration is declared in the pluginManagement scope (which also defines the version of the plug-in to use).
  3. The plug-in instance itself is declared and configured.
  4. The build-helper-maven plug-in is configured to pick up the generated sources from the target/generated-sources/camel-component directory and include them in the Maven build.

Example base configuration
Copier lien

The following POM file extract shows the base configuration of the API component Maven plug-in, as defined in the Maven pluginManagement scope when the code has been generated using the API component archetype: 
<?xml version="1.0" encoding="UTF-8"?>
<project ...>
  ...
  <build>
    ...
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.camel</groupId>
          <artifactId>camel-api-component-maven-plugin</artifactId>
          <version>2.15.1.redhat-620133</version>
          <configuration>
            <scheme>${schemeName}</scheme>
            <componentName>${componentName}</componentName>
            <componentPackage>${componentPackage}</componentPackage>
            <outPackage>${outPackage}</outPackage>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
    ...
  </build>
  ...
</project
Copy to Clipboard Toggle word wrap
The configuration specified in the pluginManagement scope provides default settings for the plug-in. It does not actually create an instance of a plug-in, but its default settings will be used by any API component plug-in instance.

Base configuration
Copier lien

In addition to specifying the plug-in version (in the version element), the preceding base configuration specifies the following configuration properties:
scheme
The URI scheme for this API component.
componentName
The name of this API component (which is also used as a prefix for generated class names).
componentPackage
Specifies the Java package containing the classes generated by the API component Maven archetype. This package is also exported by the default maven-bundle-plugin configuration. Hence, if you want a class to be publicly visible, you should place it in this Java package.
outPackage
Specifies the Java package where the generated API mapping classes are placed (when they are generated by the API component Maven plug-in). By default, this has the value of the componentName property, with the addition of the .internal suffix. This package is declared as private by the default maven-bundle-plugin configuration. Hence, if you want a class to be private, you should place it in this Java package.

Example instance configuration
Copier lien

The following POM file extract shows a sample instance of the API component Maven plug-in, which is configured to generate an API mapping during the Maven build: 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  ...
  <build>
    <defaultGoal>install</defaultGoal>

    <plugins>
      ...
      <!-- generate Component source and test source -->
      <plugin>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-api-component-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-test-component-classes</id>
            <goals>
              <goal>fromApis</goal>
            </goals>
            <configuration>
              <apis>
                <api>
                  <apiName>hello-file</apiName>
                  <proxyClass>org.jboss.fuse.example.api.ExampleFileHello</proxyClass>
                  <fromSignatureFile>signatures/file-sig-api.txt</fromSignatureFile>
                </api>
                <api>
                  <apiName>hello-javadoc</apiName>
                  <proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass>
                  <fromJavadoc/>
                </api>
              </apis>
            </configuration>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
Copy to Clipboard Toggle word wrap

Basic mapping configuration
Copier lien

The plug-in is configured by the configuration element, which contains a single apis child element to configure the classes of the Java API. Each API class is configured by an api element, as follows:
apiName
The API name is a short name for the API class and is used as the endpoint-prefix part of an endpoint URI.
Note
If the API consists of just a single Java class, you can leave the apiName element empty, so that the endpoint-prefix becomes redundant, and you can then specify the endpoint URI using the format shown in the section called “URI format for a single API class”.
proxyClass
This element specifies the fully-qualified name of the API class.
fromJavadoc
If the API class is accompanied by Javadoc metadata, you must indicate this by including the fromJavadoc element and the Javadoc itself must also be specified in the Maven file, as a provided dependency.
fromSignatureFile
If the API class is accompanied by signature file metadata, you must indicate this by including the fromSignatureFile element, where the content of this element specifies the location of the signature file.
Note
The signature files do not get included in the final package built by Maven, because these files are needed only at build time, not at run time.

Customizing the API mapping
Copier lien

The following aspects of the API mapping can be customized by configuring the plug-in:
  • Method aliases—you can define additional names (aliases) for an API method using the aliases configuration element. For details, see Section 55.3, “Method Aliases”.
  • Nullable options—you can use the nullableOptions configuration element to declare method arguments that default to null. For details, see Section 55.4, “Nullable Options”.
  • Argument name substitution—due to the way the API mapping is implemented, the arguments from all of the methods in a particular API class belong to the same namespace. If two arguments with the same name are declared to be of different type, this leads to a clash. To avoid such name clashes, you can use the substitutions configuration element to rename method arguments (as they would appear in a URI). For details, see Section 55.5, “Argument Name Substitution”.
  • Excluding arguments—when it comes to mapping Java arguments to URI options, you might sometimes want to exclude certain arguments from the mapping. You can filter out unwanted arguments by specifying either the excludeConfigNames element or the excludeConfigTypes element. For details, see Section 55.6, “Excluded Arguments”.
  • Extra options—sometimes you might want to define extra options, which are not part of the Java API. You can do this using the extraOptions configuration element.

Configuring Javadoc metadata
Copier lien

It is possible to filter the Javadoc metadata to ignore or explicitly include certain content. For details of how to do this, see Section 55.2, “Javadoc Options”.

Configuring signature file metadata
Copier lien

In cases where no Javadoc is available, you can resort to signature files to supply the needed mapping metadata. The fromSignatureFile is used to specify the location of the corresponding signature file. It has no special options.
Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat