Using custom EL mapping extensions
Apama's Web Services Client adapter and Correlator-Integrated adapter for JMS both use an expression-based mapping layer to map between Apama events and external message payloads. The expressions use Java Unified Expression Language (EL) resolvers and methods, which must be registered to the mapping layer. Apama includes a set of EL resolvers and EL methods that are registered for you and that you can use in mapping expressions. If you want you can register your own EL resolvers and EL methods and then use them as custom mapping extensions.
See the ApamaDoc API reference information for details about the APIs mentioned in the following steps. An example that uses these APIs is in the samples\correlator_jms\mapping-extensions folder of your Apama installation directory.
To register and use custom mapping extensions:
1. Define a public class that imports com.apama.adapters.el.api.ELMappingExtensionProvider and com.apama.adapters.el.api.ELMappingExtensionManager.
2. Implement ELMappingExtensionProvider.
3. Override the ELMappingExtensionProvider.registerExtensions()method and register each custom EL method and each custom EL resolver with a call to ELMappingExtensionManager.registerMethod() or ELMappingExtensionManager.registerResolver(), as appropriate. For example:
package com.apama.test;
import com.apama.adapters.el.api.ELMappingExtensionManager;
import com.apama.adapters.el.api.ELMappingExtensionProvider;
public class MyStringMethods implements ELMappingExtensionProvider {
// Register EL methods:
@Override
public void registerExtensions(ELMappingExtensionManager manager) {
throws Exception {
manager.registerMethod("reverse", getClass().getMethod("reverse", String.class));
manager.registerMethod("p:prefix", getClass().getMethod("prefix", String.class, String.class));
}
public static String reverse(String str) {
return new StringBuilder(str).reverse().toString();
}
public static String prefix(String str, String prefix) {
if (str != null) {
return prefix + str;
} else {
return prefix;
}
}
}
4. Register the list of mapping extension providers by adding a com.apama.adapters.el.config.ELMappingExtensionProviderList bean to the XML configuration, and setting its mappingExtensionProviders property. For example:
The place to set this bean XML snippet is as follows:
For Correlator-Integrated adapters for JMS, specify the
com.apama.adapters.el.config.ELMappingExtensionProviderList bean in an existing spring XML file or in a separate file in the same location as other spring files. The recommended location is the
jms-global-spring.xml file
For Web Services Client adapters, after Apama Studio generates the
WebServices_instanceName_ spring.xml file, add the
com.apama.adapters.el.config.ELMappingExtensionProviderList bean. If the
WebServices_instanceName_spring.xml file must be re-generated, your entry will be overwritten and you will need to re-add it. It is expected that Apama Studio will be enhanced in a future release to avoid the need to re-add this bean.
5. Use mapping extensions in expressions inside the source expressions of mapping rules for both send and receive mappings.
For example, consider a custom static method that takes a string parameter, returns the reverse string, and is registered with the name my:reverse. You can use it in a mapping rule as follows:
<mapping:rule
source="${my:reverse(apamaEventType['test.MyMessage'].apamaEvent['body'])}"
target="${jms.body.textmessage}" type="BINDING_PARAM"/>
In this example, my:reverse is applied to the expression "apamaEventType['test.MyMessage].apamaEvent['body']". This means that the value of the input parameter for the my:reverse method will be the value returned by the expression "apamaEventType['test.TextMessage'].apamaEvent['body']", which returns the value of the "body" field of the "test.MyMessage" event. The result is that the value of the source expression "my:reverse(apamaEventType['test.MyMessage'].apamaEvent['body'])" will be the reverse of the string contained in the "body" field.
You can use Apama Studio to add custom expressions to event mappings. In the Event Mappings tab of your adapter editor, right-click the <Custom> node and select Add Node…. This displays the Add Node dialog, which prompts you to enter a custom expression.
6. Ensure that the jar file that contains your mapping extension providers is on the appropriate classpath.
For a Correlator-Integrated adapter for JMS, use a <jms:classpath> element to enclose the ELMappingExtensionProviderList bean.
For a Web Services Client adapter, the jar file must be on the adapter's classpath.