56.3. Method Aliases

Overview

Often it can be useful to define additional names (aliases) for a given method, in addition to the standard method name that appears in the Java API. A particularly common case is where you allow a property name (such as widget) to be used as an alias for an accessor method (such as getWidget or setWidget).

Syntax

The aliases element can be defined with one or more alias child elements, as follows:
<aliases>
  <alias>
    <methodPattern>MethodPattern</methodPattern>
    <methodAlias>Alias</methodAlias>
  </alias>
  ...
</aliases>
Where MethodPattern is a regular expression (java.util.regex syntax) for matching method names from the Java API, and the pattern typically includes capturing groups. The Alias is the replacement expression (for use in a URI), which can use the text from the preceding capturing groups (for example, specified as $1, $2, or $3 for the text from the first, second, or third capturing group).

Scope

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

Example

The following example shows how to generate aliases for the common get/set bean method pattern:
<aliases>
  <alias>
    <methodPattern>[gs]et(.+)</methodPattern>
    <methodAlias>$1</methodAlias>
  </alias>
</aliases>
With the preceding alias definition, you could use widget as an alias for either of the methods getWidget or setWidget. Note the use of a capturing group, (.+), to capture the latter part of the method name (for example, Widget).