55.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
apielement—thesubstitutionsapply only to the API class specified by theapielement. - As a child of the
apiselement—thesubstitutionsapply to all API classes by default, but can be overridden at theapilevel.
Child elements
Each
substitution element can be defined with the following child elements:
method- Specifies a regular expression (
java.util.regexsyntax) to match a method name from the Java API. argName- Specifies a regular expression (
java.util.regexsyntax) to match an argument name from the matched method, where the pattern typically includes capturing groups. argType- (Optional) Specifies a regular expression (
java.util.regexsyntax) to match the type of the argument. If you set thereplaceWithTypeoption totrue, you would typically use capturing groups in this regular expression. replacement- Given a particular match of the
methodpattern,argNamepattern, and (optionally)argTypepattern, thereplacementelement defines the substitute argument name (for use in a URI). The replacement text can be constructed using strings captured from theargNameregular expression pattern (using the syntax,$1,$2,$3to insert the first, second, or third capturing group, respectively). Alternatively, the replacement text can be constructed using strings captured from theargTyperegular expression pattern, if you set thereplaceWithTypeoption totrue. replaceWithType- When
true, specifies that the replacement text is constructed using strings captured from theargTyperegular expression. Defaults tofalse.
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.
