Using custom EL mapping extensions
Apama's correlator-integrated adapter for JMS uses 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: 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.
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 Software AG Designer 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.
Use a <jms:classpath> element to enclose the ELMappingExtensionProviderList bean.