| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| |
| <!-- |
| ~ Licensed to the Apache Software Foundation (ASF) under one |
| ~ or more contributor license agreements. See the NOTICE file |
| ~ distributed with this work for additional information |
| ~ regarding copyright ownership. The ASF licenses this file |
| ~ to you under the Apache License, Version 2.0 (the |
| ~ "License"); you may not use this file except in compliance |
| ~ with the License. You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, |
| ~ software distributed under the License is distributed on an |
| ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~ KIND, either express or implied. See the License for the |
| ~ specific language governing permissions and limitations |
| ~ under the License. |
| --> |
| |
| <document> |
| <properties> |
| <title>Apache Synapse - Synapse Template Libraries</title> |
| </properties> |
| <body> |
| <section name="Synapse Template Libraries"> |
| <p> |
| 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. |
| </p> |
| <p>Following is a sample skeleton structure of a template library</p> |
| <div class="xmlConf">|-- 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</div> |
| <p>Following are these components at an overview.</p> |
| <p> |
| <ul> |
| <li>artifacts.xml |
| <br/> |
| This contains synapse library name , package name information and template groupings. |
| <div class="xmlConf"><artifacts> |
| <artifact name="synapse.lib.name" package="synapse.lib.package.name"> |
| <dependency artifact="template.group.name"/>* |
| <description>sample synapse library</description>? |
| </artifact> |
| </artifacts></div></li> |
| <li>artifact.xml |
| <br/> |
| This contains information about each individual template group. |
| <br/> |
| ie: - names of the templates in the group , corresponding configuration file ,etc. |
| <div class="xmlConf"><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></div> |
| </li> |
| <li>template_file.xml |
| <br/> |
| This contains the implementation of each individual template configuration |
| </li> |
| <li>./lib |
| <br/> |
| This is the directory to add any classes for class loading or can contain the .class files from |
| the root |
| level. |
| </li> |
| </ul> |
| </p> |
| <p>Also utilizing a synapse library is a three step process.</p> |
| <p> |
| <ul> |
| <li>Create and deploy the library</li> |
| <li>Importing the library into synapse |
| Users should deploy a import_lib_name.xml into |
| {$SYNAPSE_HOME}/repository/conf/synapse-config/imports |
| <div class="xmlConf"><import xmlns="http://ws.apache.org/ns/synapse" name="SampleLibrary" package="synapse.lib"/></div> |
| </li> |
| <li>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} |
| |
| <div class="xmlConf"><call-template target="synapse.lib.pkg.name.template_name"> |
| <with-param name="..." value="..."/>* |
| </call-template></div> |
| </li> |
| </ul> |
| </p> |
| </section> |
| <section name="Synapse Enterprise Integration Patterns library"> |
| <p>Synapse Enterprise Integration Patterns library is a container consisting a set of |
| templates grouped in a particular order by implementing commonly used |
| <a href="http://www.eaipatterns.com">Enterprise |
| Integration Patterns |
| </a> |
| 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. |
| </p> |
| <p>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. |
| </p> |
| <p> |
| <ul> |
| <li> |
| <a href="#CalloutBlock">Callout Block</a> |
| </li> |
| <li> |
| <a href="#Splitter">Splitter</a> |
| </li> |
| <li> |
| <a href="#Aggregator">Aggregator</a> |
| </li> |
| <li> |
| <a href="#SplitterAggregator">Splitter-Aggregator</a> |
| </li> |
| <li> |
| <a href="#ScatterGather">Scatter-Gather</a> |
| </li> |
| <li> |
| <a href="#WireTap">Wire Tap</a> |
| </li> |
| <li> |
| <a href="#ContentBasedRouter">Content-Based Router</a> |
| </li> |
| <li> |
| <a href="#DynamicRouter">Dynamic Router</a> |
| </li> |
| <li> |
| <a href="#RecipientList">Recipient List</a> |
| </li> |
| </ul> |
| </p> |
| <subsection name="Callout Block" id="CalloutBlock"> |
| <p> |
| This pattern is pretty much identical to the |
| <a href="http://www.eaipatterns.com/RoutingTable.html">Routing slip pattern</a> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.callout_block</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>service_URL</b> |
| - URL of the service |
| <br/> |
| <b>[action]</b> |
| - SOAP action(Optional) |
| <br/> |
| <b>[source_xpath | source_key]</b> |
| - Payload of the message( either Xpath or key and Optional) |
| <br/> |
| <b>[target_xpath | target_key]</b> |
| - A node to attach the response element ( either Xpath or key and optional) |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample850.html">Sample 850</a> |
| </p> |
| </subsection> |
| <subsection name="Splitter" id="Splitter"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/Sequencer.html">Splitter pattern</a> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.splitter</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>iterate_exp</b> |
| - Xpath expression from which element you want to split the message. |
| <br/> |
| <b>[attach_path]</b> |
| - Xpath expression to specify which elements needs to be attached to form new messages.( Optional) |
| <br/> |
| <b>endpoint_url</b> |
| - Endpoint which newly created messages are redirected to. |
| <br/> |
| <b>[attach_path_enabled]</b> |
| - Boolean value to enable attach path. Optional and by default this is false. |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample851.html">Sample 851</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Aggregator" id="Aggregator"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/Aggregator.html">Aggregator pattern</a> |
| builds a single message distilled from the individual messages. |
| And messages will be merged by using the XPath expression specified for aggregator_exp. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.aggregator</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>aggregator_exp</b> |
| - An XPath expression specifying based on which elements to aggregate. |
| <br/> |
| <b>[sequence_ref]</b> |
| - 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). |
| <br/> |
| <b>[oncomplete_seq_enabled]</b> |
| - Boolean value to enable target sequence. (Optional and by default this is false) |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample851.html">Sample 851</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Splitter-Aggregator" id="SplitterAggregator"> |
| <p> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.splitter_aggregator</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>iterate_exp</b> |
| - An Xpath expression from which element you want to split the message. |
| <br/> |
| <b>[attach_path]</b> |
| - An Xpath expression to specify which elements needs to be attached to form new messages.( |
| Optional) |
| <br/> |
| <b>endpoint_url</b> |
| - Endpoint which newly created messages are redirected to. |
| <br/> |
| <b>[attach_path_enabled]</b> |
| - Boolean value to enable attach path. Optional and by default this is false. |
| <br/> |
| <b>aggregator_exp</b> |
| - An XPath expression specifying based on which elements to aggregate. |
| <br/> |
| <b>[sequence_ref]</b> |
| - 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). |
| <br/> |
| <b>[oncomplete_seq_enabled]</b> |
| - Boolean value to enable target sequence. (Optional and by default this is false) |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample852.html">Sample 852</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Scatter-Gather" id="ScatterGather"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/BroadcastAggregate.html">Scatter-Gather pattern</a> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.scatter_gather</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>aggregator_exp</b> |
| - An XPath expression specifying based on which elements to aggregate. |
| <br/> |
| <b>[sequence_ref]</b> |
| - 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). |
| <br/> |
| <b>[oncomplete_seq_enabled]</b> |
| - Boolean value to enable target sequence. (Optional and by default this is false) |
| <br/> |
| <b>recipient_list</b> |
| - Set of recipient endpoints , which should be specified as comma separated values |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample853.html">Sample 853</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Wire Tap" id="WireTap"> |
| <p> |
| <a href="http://www.eaipatterns.com/WireTap.html">Wire Tap pattern</a> |
| enables route messages to a secondary channel while they are being forwarded to the main channel. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.wire_tap</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>destination_uri</b> |
| - Endpoint of main channel |
| <br/> |
| <b>wiretap_uri</b> |
| - Endpoint of secondary channel |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample854.html">Sample 854</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Content-Based Router" id="ContentBasedRouter"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/ContentBasedRouter.html">Content Based Router pattern</a> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.content_base_router</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>routing_exp</b> |
| - Here you can specify the source xpath to be evaluated |
| <br/> |
| <b>match_content</b> |
| - This is a String which contains the matching conditions. Following is the syntax of it |
| <b>"IBM:cnd1_seq,MSFT:cnd2_seq;cnd3_seq"</b> |
| <br/> |
| 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. |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample855.html">Sample 855</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Dynamic Router" id="DynamicRouter"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/DynamicRouter.html">Dynamic Router pattern</a> |
| 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. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.dynamic_router</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>conditions</b> |
| - This is a String which contains the routing rules. Following is the syntax of it. |
| <br/> |
| <b> |
| "header=foo:bar.*{AND}url=/services/;seq=seq1,header=header1:bar.*{OR}header=header1:foo.*;seq=seq2,header=header2:foo.*;seq=seq3" |
| </b> |
| <br/> |
| User can define multiple routing rules by using "," splitter. Routing rule contains following |
| format, |
| <br/> |
| To match HTTP headers , use |
| <b>header=regEx:seqRef</b> |
| <br/> |
| header source and regular expression should be separated by inserting ":" |
| <br/> |
| To match HTTP url, use |
| <b>url=/url</b> |
| <br/> |
| Then target sequence needs to be defined after inserting ";" |
| <br/> |
| |
| Also you can use<b>"{AND}"</b>as to specify logical AND , |
| <b>"{OR}"</b> |
| as to specify logical OR to match |
| multiple headers and url in your expression. |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample856.html">Sample 856</a> |
| </p> |
| </subsection> |
| |
| <subsection name="Recipient List" id="RecipientList"> |
| <p> |
| The |
| <a href="http://www.eaipatterns.com/RecipientList.html">Recipient List pattern</a> |
| forward the message to all channels associated with the defined set of recipients. |
| <br/> |
| <br/> |
| |
| Call template target - |
| <b>synapse.lang.eip.recipient_list</b> |
| <br/> |
| Parameters |
| <br/> |
| <b>recipient_list</b> |
| - set of recipient endpoints , which should be specified as comma separated values |
| <br/> |
| <br/> |
| Related Sample - <a href="samples/sample857.html">Sample 857</a> |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
