Synapse Template Libraries

Synapse template libraries are a mechanism to group synapse templates and automatically expose it as a self contained set of function modules. It can be considered as a container consisting a set of templates grouped in a particular order. Currently a synapse template library is shipped as a ".zip" file and should be deployed inside {$SYNAPSE_HOME}/repository/conf/synapse-libs . If a given template container is successfully deployed, all templates within the library will be accessible to any Synapse user.

Following is a sample skeleton structure of a template library

|-- artifacts.xml |-- com | `-- synapse | `-- sample | `-- SynapseLibTestMediator.class |-- lib | `-- test-mediator-1.0.0.jar |-- template_dir-1 | |-- artifact.xml | |-- templ1_ns1.xml | `-- templ2_ns1.xml `-- template_dir-2 |-- artifact.xml |-- templ1_ns2.xml `-- templ2_ns2.xml

Following are these components at an overview.

  • artifacts.xml
    This contains synapse library name , package name information and template groupings.
    <artifacts> <artifact name="synapse.lib.name" package="synapse.lib.package.name"> <dependency artifact="template.group.name"/>* <description>sample synapse library</description>? </artifact> </artifacts>
  • artifact.xml
    This contains information about each individual template group.
    ie: - names of the templates in the group , corresponding configuration file ,etc.
    <artifact name="template.group.name" type="synapse/template"> <subArtifacts> <artifact name="template.name"> <file>template_file.xml</file> <description>a sample synapse library function</description>? </artifact>* </subArtifacts> </artifact>
  • template_file.xml
    This contains the implementation of each individual template configuration
  • ./lib
    This is the directory to add any classes for class loading or can contain the .class files from the root level.

Also utilizing a synapse library is a three step process.

  • Create and deploy the library
  • Importing the library into synapse Users should deploy a import_lib_name.xml into {$SYNAPSE_HOME}/repository/conf/synapse-config/imports
    <import xmlns="http://ws.apache.org/ns/synapse" name="SampleLibrary" package="synapse.lib"/>
  • Execute functions of library using a template invoker. Target template is a combination of the package of synapse library and the target template name target == {synapse_lib_package}.{template name}
    <call-template target="synapse.lib.pkg.name.template_name"> <with-param name="..." value="..."/>* </call-template>

Synapse Enterprise Integration Patterns library

Synapse Enterprise Integration Patterns library is a container consisting a set of templates grouped in a particular order by implementing commonly used Enterprise Integration Patterns from the set of patterns introduced by Gregor Hohpe and Bobby Woolf. Users can design their solutions using these well-known patterns and then simply configure and use these same patterns in Apache Synapse by calling up the function as required. So this will greatly reduce the effort required when building integrations.

Following lists all the built-in patterns of Synapse EIP library currently supports and describes their usage, functionality and configuration syntax. This excludes all generic EIP patterns supported by synapse out of the box.

Callout Block

This pattern is pretty much identical to the Routing slip pattern and this blocks external service invocation during mediation. And useful in scenarios such as service chaining. As default values are assigned to source and target xpaths, one can simply utilize this pattern by just defining serviceURL.

Call template target - synapse.lang.eip.callout_block
Parameters
service_URL - URL of the service
[action] - SOAP action(Optional)
[source_xpath | source_key] - Payload of the message( either Xpath or key and Optional)
[target_xpath | target_key] - A node to attach the response element ( either Xpath or key and optional)

Related Sample - Sample 850

Splitter

The Splitter pattern breaks out the composite message into a series of individual messages by finding matching elements for the XPath expression specified and then redirected to the given endpoint.

Call template target - synapse.lang.eip.splitter
Parameters
iterate_exp - Xpath expression from which element you want to split the message.
[attach_path] - Xpath expression to specify which elements needs to be attached to form new messages.( Optional)
endpoint_url - Endpoint which newly created messages are redirected to.
[attach_path_enabled] - Boolean value to enable attach path. Optional and by default this is false.

Related Sample - Sample 851

Aggregator

The Aggregator pattern builds a single message distilled from the individual messages. And messages will be merged by using the XPath expression specified for aggregator_exp.

Call template target - synapse.lang.eip.aggregator
Parameters
aggregator_exp - An XPath expression specifying based on which elements to aggregate.
[sequence_ref] - target sequence which message should be mediated after aggregation. (Optional and if this is not specified aggregator will send the aggregated message to the client).
[oncomplete_seq_enabled] - Boolean value to enable target sequence. (Optional and by default this is false)

Related Sample - Sample 851

Splitter-Aggregator

This pattern provides the combined functionality of Splitter and Aggregator patterns. Which is when you specified following parameters this pattern will split the message and does a synchronized call for the given endpoint and aggregates replies then send back to client or mediates to the defined target sequence.

Call template target - synapse.lang.eip.splitter_aggregator
Parameters
iterate_exp - An Xpath expression from which element you want to split the message.
[attach_path] - An Xpath expression to specify which elements needs to be attached to form new messages.( Optional)
endpoint_url - Endpoint which newly created messages are redirected to.
[attach_path_enabled] - Boolean value to enable attach path. Optional and by default this is false.
aggregator_exp - An XPath expression specifying based on which elements to aggregate.
[sequence_ref] - Target sequence which message should be mediated after aggregation. (Optional and if this is not specified aggregator will send the aggregated message to the client).
[oncomplete_seq_enabled] - Boolean value to enable target sequence. (Optional and by default this is false)

Related Sample - Sample 852

Scatter-Gather

The Scatter-Gather pattern broadcasts a message to multiple recipients and re-aggregates the responses back into a single message and send back to client or mediates to the defined target sequence.

Call template target - synapse.lang.eip.scatter_gather
Parameters
aggregator_exp - An XPath expression specifying based on which elements to aggregate.
[sequence_ref] - Target sequence which message should be mediated after aggregation. (Optional and if this is not specified aggregator will send the aggregated message to the client).
[oncomplete_seq_enabled] - Boolean value to enable target sequence. (Optional and by default this is false)
recipient_list - Set of recipient endpoints , which should be specified as comma separated values

Related Sample - Sample 853

Wire Tap

Wire Tap pattern enables route messages to a secondary channel while they are being forwarded to the main channel.

Call template target - synapse.lang.eip.wire_tap
Parameters
destination_uri - Endpoint of main channel
wiretap_uri - Endpoint of secondary channel

Related Sample - Sample 854

Content-Based Router

The Content Based Router pattern route messages to the appropriate sequence, according to the message contents. Routing decision is taken by matching given Xpath expression and Regular Expression. User can define multiple matching elements as regular expressions and a target sequence where if any of matching element evaluates to true then it mediates using the target sequence. If none of the case statements are matching and default case is specified, it will be executed.

Call template target - synapse.lang.eip.content_base_router
Parameters
routing_exp - Here you can specify the source xpath to be evaluated
match_content - This is a String which contains the matching conditions. Following is the syntax of it "IBM:cnd1_seq,MSFT:cnd2_seq;cnd3_seq"
User can define multiple matching conditions using "," splitter. regular expressions and target sequence should be separated by inserting":". And finally default sequence needs to be defined after inserting ";". If there is no any target sequence defined for a particular regular expression , default it will be mediated to the main sequence.

Related Sample - Sample 855

Dynamic Router

The Dynamic Router pattern route a message consecutively through a series of condition steps, which is parsed by the “conditions” parameter. The list of sequences through which the message should pass is decided dynamically at run time. It checks whether the route condition evaluates to true and mediates using the given sequence and user can define routing decision based on the message contents such as HTTP url,HTTP headers or combination of both.

Call template target - synapse.lang.eip.dynamic_router
Parameters
conditions - This is a String which contains the routing rules. Following is the syntax of it.
"header=foo:bar.*{AND}url=/services/;seq=seq1,header=header1:bar.*{OR}header=header1:foo.*;seq=seq2,header=header2:foo.*;seq=seq3"
User can define multiple routing rules by using "," splitter. Routing rule contains following format,
To match HTTP headers , use header=regEx:seqRef
header source and regular expression should be separated by inserting ":"
To match HTTP url, use url=/url
Then target sequence needs to be defined after inserting ";"
Also you can use"{AND}"as to specify logical AND , "{OR}" as to specify logical OR to match multiple headers and url in your expression.

Related Sample - Sample 856

Recipient List

The Recipient List pattern forward the message to all channels associated with the defined set of recipients.

Call template target - synapse.lang.eip.recipient_list
Parameters
recipient_list - set of recipient endpoints , which should be specified as comma separated values

Related Sample - Sample 857