56.5. Argument Name Substitution

Overview

The API component framework requires that URI option names are unique within each proxy class (Java API class). This is not always the case for method argument names, however. For example, consider the following Java methods in an API class:
public void doSomething(int id, String name);
public void doSomethingElse(int id, String name);
When you build your Maven project, the camel-api-component-maven-plugin generates the configuration class, ProxyClassEndpointConfiguration, which contains getter and setter methods for all of the arguments in the ProxyClass class. For example, given the preceding methods, the plug-in would generate the following getter and setter methods in the configuration class:
public int  getId();
public void setId(int id);
public String getName();
public void   setName(String name);
But what happens, if the id argument appears multiple times as different types, as in the following example:
public void doSomething(int id, String name);
public void doSomethingElse(int id, String name);
public String lookupByID(String id);
In this case, the code generation would fail, because you cannot define a getId method that returns int and a getId method that returns String in the same scope. The solution to this problem is to use argument name substitution to customize the mapping of argument names to URI option names.

Syntax

The substitutions element can be defined with one or more substitution child elements, as follows:
<substitutions>
  <substitution>
    <method>MethodPattern</method>
    <argName>ArgumentNamePattern</argName>
    <argType>TypeNamePattern</argType>
    <replacement>SubstituteArgName</replacement>
    <replaceWithType>[true|false]</replaceWithType>
  </substitution>
  ...
</substitutions>
Where the argType element and the replaceWithType element are optional and can be omitted.

Scope

As shown in the following extract, the substitutions element can optionally appear as a child of the apis element and/or as a child of api elements:
<configuration>
  <apis>
    <api>
      <apiName>...</apiName>
      ...
 <substitutions>...</substitutions>
    </api>
 <substitutions>...</substitutions>
    ...
  </apis>
</configuration>
You can define the substitutions element at the following scopes:
  • As a child of an api element—the substitutions apply only to the API class specified by the api element.
  • As a child of the apis element—the substitutions apply to all API classes by default, but can be overridden at the api level.

Child elements

Each substitution element can be defined with the following child elements:
method
Specifies a regular expression (java.util.regex syntax) to match a method name from the Java API.
argName
Specifies a regular expression (java.util.regex syntax) to match an argument name from the matched method, where the pattern typically includes capturing groups.
argType
(Optional) Specifies a regular expression (java.util.regex syntax) to match the type of the argument. If you set the replaceWithType option to true, you would typically use capturing groups in this regular expression.
replacement
Given a particular match of the method pattern, argName pattern, and (optionally) argType pattern, the replacement element defines the substitute argument name (for use in a URI). The replacement text can be constructed using strings captured from the argName regular expression pattern (using the syntax, $1, $2, $3 to insert the first, second, or third capturing group, respectively). Alternatively, the replacement text can be constructed using strings captured from the argType regular expression pattern, if you set the replaceWithType option to true.
replaceWithType
When true, specifies that the replacement text is constructed using strings captured from the argType regular expression. Defaults to false.

Example

The following substitution example modifies every argument of java.lang.String type, by adding the suffix, Param to the argument name:
<substitutions>
  <substitution>
    <method>^.+$</method>
    <argName>^.+$</argName>
    <argType>java.lang.String</argType>
    <replacement>$1Param</replacement>
    <replaceWithType>false</replaceWithType>
  </substitution>
</substitutions>
For example, given the following method signature:
public String greetUs(String name1, String name2);
The arguments of this method would be specified through the options, name1Param and name2Param, in the endpoint URI.