Google Git
Sign in
apache / synapse / refs/tags/2.1.0 / . / src / site / xdoc / userguide / config.xml
blob: 77b3cb85a037d78932bc610d1d38eeae8aeea2f6 [file] [log] [blame]
<?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 - Configuration Language Guide</title>
</properties>
<body>
<section name="Introduction" id="Intro">
<p>
Apache Synapse loads its configuration from a set of XML files. This enables the
user to easily hand edit the configuration, maintain backups and even include the
entire configuration in a version control system for easier management and control.
For an example one may check-in all Synapse configuration files into a version
control system such as Subversion and easily move the configuration files from
development, through QA, staging and into production.
</p>
<p>
All the configuration files related to Synapse are housed in the repository/conf/synapse-config
directory of the Synapse installation. Synapse is also capable of loading certain
configuration elements (eg: sequences, endpoints) from an external SOA registry.
When using a registry to store fragments of the configuration, some configuration
elements such as endpoints can be updated dynamically while Synapse is executing.
</p>
<p>
This article describes the hierarchy of XML files from which Synapse reads its
configuration. It describes the high level structure of the file set and the XML
syntax used to configure various elements in Synapse.
</p>
</section>
<section name="Contents">
<ul>
<li>
<a href="#SynapseConfig">Synapse Configuration</a>
<ul>
<li><a href="#ServiceMediation">Service Mediation (Proxy Services)</a></li>
<li><a href="#MessageMediation">Message Mediation</a></li>
<li><a href="#TaskScheduling">Task Scheduling</a></li>
<li><a href="#Eventing">Eventing</a></li>
</ul>
</li>
<li>
<a href="#Overview">Functional Components Overview</a>
<ul>
<li><a href="#MediatorsAndSequences">Mediators and Sequences</a></li>
<li><a href="#Endpoints">Endpoints</a></li>
<li><a href="#ProxyServices">Proxy Services</a></li>
<li><a href="#ScheduledTasks">Scheduled Tasks</a></li>
<li><a href="#Templates">Templates</a></li>
<li><a href="#Registry">Remote Registry and Local Registry</a></li>
<li><a href="#API">APIs</a></li>
<li><a href="#PriorityExecutors">Priority Executors</a></li>
<li><a href="#Stores">Message Stores and Processors</a></li>
</ul>
</li>
<li><a href="#ConfigFiles">Synapse Configuration Files</a></li>
<li><a href="#Syntax">Configuration Syntax</a></li>
<li><a href="#RegistryConfig">Registry Configuration</a></li>
<li><a href="#LocalEntryConfig">Local Entry (Local Registry) Configuration</a></li>
<li><a href="#SequenceConfig">Sequence Configuration</a></li>
<li>
<a href="#EndpointConfig">Endpoint Configuration</a>
<ul>
<li><a href="#AddressEndpointConfig">Address Endpoint</a></li>
<li><a href="#DefaultEndpointConfig">Default Endpoint</a></li>
<li><a href="#WSDLEndpointConfig">WSDL Endpoint</a></li>
<li><a href="#LBEndpointConfig">Load Balance Endpoint</a></li>
<li><a href="#DLBEndpointConfig">Dynamic Load Balance Endpoint</a></li>
<li><a href="#FOEndpointConfig">Fail-Over Endpoint</a></li>
<li><a href="#RecipientListEndpointConfig">Recipient List Endpoint"</a></li>
</ul>
</li>
<li><a href="#ProxyServiceConfig">Proxy Service Configuration</a></li>
<li><a href="#TaskConfig">Scheduled Task Configuration</a></li>
<li><a href="#TemplateConfig">Template Configuration</a></li>
<li><a href="#EventSourceConfig">Event Source Configuration</a></li>
<li><a href="#APIConfig">API Configuration</a></li>
<li><a href="#ExecutorConfig">Priority Executor Configuration</a></li>
<li><a href="#StoresConfig">Message Stores and Processors Configuration</a></li>
</ul>
</section>
<section name="The Synapse Configuration" id="SynapseConfig">
<p>
A typical Synapse configuration is comprised of sequences, endpoints, proxy services
and local entries. In certain advanced scenarios, Synapse configuration may also
contain scheduled tasks, event sources, messages stores and priority executors.
Synapse configuration may also include a registry adapter through which the mediation
engine can import various resources to the mediation engine at runtime. Following
diagram illustrates different functional components of Synapse and how they interact
with each other.
</p>
<img src="../images/synapse-flow.png"/>
<p>
All the functional components of the Synapse configuration are configured through
XML files. The Synapse configuration language governs the XML syntax used to define
and configure different types of components. This configuration language is now
available as a <a href="http://synapse.apache.org/ns/2010/04/configuration/synapse_config.xsd">XML schema</a>.
</p>
<p>
Typically the Synapse ESB is used to mediate the message flow between a client
and a back-end service implementation. Therefore Synapse can accept a message on
behalf of the actual service and perform a variety of mediation tasks on it such
as authentication, validation, transformation, logging and routing. Synapse can also
detect timeouts and other communication errors when connecting to back-end services.
In addition to that users can configure Synapse to perform load balancing, access
throttling and response caching. In case of a fault scenario, such as an authentication
failure or a schema validation failure, the Synapse ESB can be configured to return
a custom message or a SOAP fault to the requesting client without forwarding the
message to the back-end service. All these scenarios and use cases can be put into
action by selecting the right set of functional components of Synapse and combining
them appropriately through the Synapse configuration.
</p>
<p>
Depending on how functional components are used in the Synapse configuration, Synapse
can execute in one or more of the following operational modes.
</p>
<subsection name="Service Mediation (Proxy Services)" id="ServiceMediation">
<p>
In service mediation, the Synapse ESB exposes a service endpoint on the ESB, which
accepts messages from clients. Typically these services acts as proxies for existing
(external) services, and the role of Synapse would be to 'mediate' these messages
before they are delivered to the actual service. In this mode, Synapse could expose
a service already available in one transport, over a different transport; or expose
a service that uses one schema or WSDL as a service that uses a different schema or
WSDL. A Proxy service could define the transports over which the service is exposed,
and point to the mediation sequences that should be used to process request and
response messages. A proxy service maybe a SOAP or a REST/POX service over HTTP/S or
SOAP, POX, plain text or binary/legacy service for other transports such as JMS
and VFS file systems.
</p>
</subsection>
<subsection name="Message Mediation" id="MessageMediation">
<p>
In message mediation, Synapse acts as a transparent proxy for clients. This way,
Synapse could be configured to filter all the messages on a network for logging,
access control etc, and could 'mediate' messages without the explicit knowledge
of the original client. If Synapse receives a message that is not accepted by any
proxy service, that message is handled through message mediation. Message mediation
always processes messages according to the mediation sequence defined with
the name 'main'.
</p>
</subsection>
<subsection name="Task Scheduling" id="TaskScheduling">
<p>
In task scheduling, Synapse can execute a predefined task (job) based on a user
specified schedule. This way a task can be configured to run exactly once or
multiple times with fixed intervals. The schedule can be defined by specifying
the number of times the task should be executed and the interval between
executions. Alternatively one may use the Unix Cron syntax to define task
schedules. This mode of operation can be used to periodically invoke a given
service, poll databases and execute other periodic maintenance activities.
</p>
</subsection>
<subsection name="Eventing" id="Eventing">
<p>
In eventing mode, Synapse can be used as an event source and users or systems can
subscribe to receive events from Synapse. Synapse can also act as an event broker
which receives events from other systems and delivers them to the appropriate
subscribers with or without mediation. The set of subscribers will be selected
by applying a predefined filter criteria. This mode enables Synapse to integrate
applications and systems based on the Event Driven Architecture (EDA).
</p>
</subsection>
</section>
<section name="Functional Components Overview" id="Overview">
<p>
As described in the previous section, Synapse engine is comprised of a range of
functional components. Synapse configuration language is used to define, configure
and combine these components so various messaging scenarios and integration
patterns can be realized. Before diving into the specifics of the configuration
language, it is useful to have a thorough understanding of all the functional
components available, their capabilities and features. A good knowledge on Synapse
functional components will help you determine which components should be used to
implement any given scenario or use case. In turns it will allow you to develop
powerful and efficient Synapse configurations thus putting the ESB to maximum use.
</p>
<p>
As of now Synapse mediation engine consists of following functional elements:
</p>
<p>
<ul>
<li>Mediators and sequences</li>
<li>Endpoints</li>
<li>Proxy services</li>
<li>Scheduled tasks</li>
<li>Event sources</li>
<li>Sequence templates</li>
<li>Endpoint templates</li>
<li>Registry adapter</li>
<li>APIs</li>
<li>Priority executors</li>
<li>Message stores and processors</li>
</ul>
</p>
<subsection name="Mediators and Sequences" id="MediatorsAndSequences">
<p>
The Synapse ESB defines a 'mediator' as a component which performs a predefined
action on a message during a message flow. It is the most fundamental message
processing unit in Synapse. A mediator can be thought of as a filter that resides
in a message flow, which processes all the messages passing through it.
</p>
<p>
A mediator gets full access to the messages at the point where it is defined.
Thus they can inspect, validate and modify messages. Further, mediators can take
external action such as looking up a database or invoking a remote service,
depending on some attributes or values in the current message. Synapse ships
with a variety of built-in mediators which are capable of handling an array of
heterogeneous tasks. There are built-in mediators that can log the requests,
perform content transformations, filter out traffic and a plethora of other
messaging and integration activities.
</p>
<p>
Synapse also provides an API using which custom mediators can be implemented
easily in Java. The 'Class' and 'POJO (command)' mediators allow one to plugin a
Java class into Synapse with minimal effort. In addition, the 'Script' mediator
allows one to provide an Apache BSF script (eg: JavaScript, Ruby, Groovy etc)
for mediation.
</p>
<p>
A mediation sequence, commonly called a 'sequence' is a list of mediators. A
sequence may be named for re-use, or defined in-line or anonymously within a
configuration. Sequences may be defined within the Synapse configuration or in
the Registry. From an ESB point of view, a sequence equates to a message flow.
It can be thought of as a pipe consisting of many filters, where individual
mediators play the role of the filters.
</p>
<p>
A Synapse configuration contains two special sequences named 'main' and 'fault'.
These too may be defined in the Synapse configuration, or externally in the
Registry. If either is not found, a suitable default configuration is generated at
runtime by the ESB. The default 'main' sequence will simply send a message without
any mediation, while the default 'fault' sequence would log the message and error
details and stop further processing. The 'fault' sequence executes whenever Synapse
itself encounters an error while processing a message, or when a fault handler has
not been defined to handle exceptions. A sequence can assign another named sequence
as its 'fault' handler sequence, and handover control to the fault handler if an
error is encountered during the execution of the initial sequence.
</p>
</subsection>
<subsection name="Endpoints" id="Endpoints">
<p>
An Endpoint definition within Synapse defines an external service endpoint and
any attributes or semantics that should be followed when communicating with that
endpoint. An endpoint definition can be named for re-use, or defined in-line or
anonymously within a configuration. Typically an endpoint would be based on a
service address or a WSDL. Additionally the Synapse ESB supports Failover and
Load-balance endpoints - which are defined over a group of endpoints. Endpoints
may be defined within the local Synapse configuration or within the Registry.
</p>
<p>
From a more practical stand point, an endpoint can be used to represent any
entity to which Synapse can make a connection. An endpoint may represent a
URL, a mail box, a JMS queue or a TCP socket. The 'send' mediator of Synapse
which is used to forward messages can take an endpoint as an argument. In that
case the 'send' mediator would forward the message to the specified endpoint.
</p>
</subsection>
<subsection name="Proxy Services" id="ProxyServices">
<p>
A proxy service is a virtual service exposed on Synapse. For the external
clients, a proxy service looks like a full fledged web service which has a
set of endpoint references (EPRs), a WSDL and a set of developer specified
policies. But in reality, a proxy service sits in front of a real web service
implementation, acting as a proxy, mediating messages back and forth. The
actual business logic of the service resides in the real back-end web service.
Proxy service simply hides the real service from the consumer and provides
an interface through which the actual service can be reached but with some
added mediation/routing logic.
</p>
<p>
Proxy services have many use cases. A proxy can be used to expose an existing
service over a different protocol or a schema. The mediation logic in the proxy
can take care of performing the necessary content transformations and protocol
switching. A proxy service can act as a load balancer or a lightweight process
manager thereby hiding multiple back-end services from the client. Proxy services
also provide a convenient way of extending existing web services without changing
the back-end service implementations. For an example a proxy service can add logging
and validation capabilities to an existing service without the developer having
to implement such functionality at service level. Another very common usage of
proxy services is to secure an existing service or a legacy system.
</p>
<p>
A proxy service is a composite functional component. It is made of several
sequences and endpoints. Typically a proxy service consists of an 'in sequence',
an 'out sequence' and an endpoint. The 'in sequence' handles all the incoming
requests sent by the client. Mediated messages are then forwarded to the target
endpoint which generally points to the real back-end service. Responses coming
back from the back-end service are processed by the 'out sequence'. In addition
to these a 'fault sequence' can also be associated with a proxy service which
is invoked in case of an error.
</p>
<p>
In addition to the above basic configuration elements, a proxy service can
also define a WSDL file to be published, a set of policies and various other
parameters.
</p>
</subsection>
<subsection name="Scheduled Tasks" id="ScheduledTasks">
<p>
A scheduled task is a job deployed in the Synapse runtime for periodic execution.
Users can program the jobs using the task API (Java) provided by Synapse. Once
deployed, tasks can be configured to run periodically. The execution schedule
can be configured by specifying the delay between successive executions or using
the Unix Cron syntax.
</p>
</subsection>
<subsection name="Templates" id="Templates">
<p>
A Template is an abstract concept in synapse. One way to view a template, is as
a prototype or a function. Templates try to minimize redundancy in synapse
artifacts (ie sequences and endpoints) by creating prototypes that users can
re-use and utilize as and when needed. This is very much analogous to classes
and instances of classes whereas, a template is a class that can be used to
wield instance objects such as sequences and endpoints.
</p>
<p>
Templates is an ideal way to improve re-usability and readability of
ESB configurations (XML). Addition to that users can utilize predefined templates
that reflect commonly used EIP patterns for rapid development of ESB
message/mediation flows.There are two flavours of templates which are Endpoint
and Sequence Templates.
</p>
<p>
An endpoint template is an abstract definition of a synapse endpoint. Users have
to invoke this kind of a template using a special template endpoint. Endpoint
templates can specify various commons parameters of an endpoint that can be reused
across many endpoint definitions (eg: address uri, timeouts, error codes etc).
</p>
<p>
A sequence template defines a functional form of an ESB sequence. Sequence
templates have the ability to parametrize a sequence flow. Generally
parametrization is in the form of static values as well as xpath expressions.
Users can invoke a template of this kind with a mediator named 'call-template'
by passing in the required parameter values.
</p>
</subsection>
<subsection name="Remote Registry and Local Registry (Local Entries)" id="Registry">
<p>
Synapse configuration can refer to an external registry/repository for resources
such as WSDLs, schemas, scripts, XSLT and XQuery transformations etc. One or
more remote registries may be hidden or merged behind a local registry interface
defined in the Synapse configuration. Resources from an external registry are
looked up using 'keys' - which are known to the external registry. The Synapse
ESB ships with a simple URL based registry implementation that uses the file system
for storage of resources, and URLs or fragments as 'keys'.
</p>
<p>
A registry may define a duration for which a resource served may be cached by the
Synapse runtime. If such a duration is specified, the Synapse ESB is capable of
refreshing the resource after cache expiry to support dynamic re-loading of resources
at runtime. Optionally, a configuration could define certain 'keys' to map to locally
defined entities. These entities may refer to a source URL or file, or may be defined
as in-line XML or text within the configuration itself. If a registry contains a
resource whose 'key' matches the key of a locally defined entry, the local entry
shadows the resource available in the registry. Thus it is possible to override
registry resources locally from within the configuration. To integrate Synapse with
a custom/new registry, one needs to implement the org.apache.synapse.registry.Registry
interface to suit the actual registry being used.
</p>
</subsection>
<subsection name="APIs" id="API">
<p>
An API is similar to a web application deployed in Synapse. It provides a
convenient approach for filtering and processing HTTP traffic (specially RESTful
invocations) through the service bus. Each API is anchored at a user defined
URL context (eg: /ws) and can handle all the HTTP requests that
fall within that context. Each API is also comprised of one or more resources.
Resources contain the mediation logic for processing requests and responses.
Resources can also be associated with a set of HTTP methods and header values.
For an example one may define an API with two resources, where one resources is
used to handle GET requests and the other is used to handle POST requests.
Similarly an API can be defined with separate resources for handling XML and JSON
content (by looking at the Content-type HTTP header).
</p>
<p>
Resources bare a strong resemblance to proxy services. Similar to proxy services,
a resource can also define an 'in sequence', an 'out sequence' and a 'fault
sequence'. Just like in the case of proxy services, the 'in sequence' is used
to process incoming requests and the 'out sequence' is used to mediate responses.
</p>
<p>
APIs provide a powerful framework using which comprehensive REST APIs can be
constructed on existing systems. For an example a set of SOAP services can be
hidden behind an API defined in Synapse. Clients can access the API in Synapse
by making pure RESTful invocations over HTTP. Synapse takes care of transforming
the requests and routing them to appropriate back-end services which may or may
not be based on REST.
</p>
</subsection>
<subsection name="Priority Executors" id="PriorityExecutors">
<p>
Priority executors can be used to execute sequences with a given priority.
Priority executors are used in high load scenarios where user wants to execute
different sequences at different priority levels. This allows user to control
the resources allocated to executing sequences and prevent high priority messages
from getting delayed and dropped. A priority has a specific meaning compared to
other priorities specified. For example if we have two priorities with value 10
and 1, messages with priority 10 will get 10 times more resources than messages
with priority 1.
</p>
</subsection>
<subsection name="Message Stores and Processors" id="Stores">
<p>
Message store acts as a unit of storage for messages/data exchanged during synapse
runtime. By default synapse ships with a in-memory message store and the storage
can be plugged in depending on the requirement. There is a specific mediator called
store mediator which is able to direct message traffic to a particular message
store at runtime.
</p>
<p>
On the other hand a Message processor has the ability to connect to a message
store and perform message mediation or required data manipulations. Essentially
a particular message processor will be coupled with a message store and as a
result respective message processor will be inherited with the traits of that
particular message storage.
</p>
<p>
For example in the eye of a message processor, data/messages coming from in-memory
message store will be seen as more volatile compared to a persistent message store.
Nevertheless it will find it can perform operations much faster on the former.
This is in fact a very powerful concept and hence depending on the processor and
store combination users can define limitless number of EI patterns in synapse
that could meet different runtime requirements and SLA's. Synapse by default
support two processors which are scheduled message processor and sampling
processor.
</p>
</subsection>
</section>
<section name="Synapse Configuration Files" id="ConfigFiles">
<p>
All the XML files pertaining to the Synapse configuration are available in the
repository/conf/synapse-config directory of the Synapse installation. This file
hierarchy consists of two files named synapse.xml and registry.xml. In addition to
that, following sub-directories can be found in the synapse-config directory.
</p>
<ul>
<li>api</li>
<li>endpoints</li>
<li>events</li>
<li>local-entries</li>
<li>message-processors</li>
<li>message-stores</li>
<li>priority-executors</li>
<li>proxy-services</li>
<li>sequences</li>
<li>tasks</li>
<li>templates</li>
</ul>
<p>
Each of these sub-directories can contain zero or more configuration items. For
an example the 'endpoints' directory may contain zero or more endpoint definitions
and the 'sequences' directory may contain zero or more sequence definitions. The
registry adapter is defined in the top level registry.xml file. The synapse.xml file
is there mainly for backward compatibility reasons. It can be used to define any
type of configuration items. One may define few endpoints in the 'endpoints' directory
and a few endpoints in the synapse.xml file. However it is recommended to stick to
a single, consistent way of defining configuration elements. So you should either
define everything in synapse.xml file, or not use it at all.
</p>
<p>
The following tree diagram shows the high-level view of the resulting file
hierarchy.
</p>
<div class="consoleOutput">synapse-config
|-- api
|-- endpoints
| `-- foo.xml
|-- events
| `-- event1.xml
|-- local-entries
| `-- bar.xml
|-- message-processors
|-- message-stores
|-- priority-executors
|-- proxy-services
| |-- proxy1.xml
| |-- proxy2.xml
| `-- proxy3.xml
|-- registry.xml
|-- sequences
| |-- custom-logger.xml
| |-- fault.xml
| `-- main.xml
|-- synapse.xml
|-- tasks
| `-- task1.xml
`-- templates</div>
</section>
<section name="Configuration Syntax" id="Syntax">
<p>
Synapse ESB is configured using an XML based configuration language. This is a
Domain Specific Language (DSL) created and maintained by the Synapse community.
The language is designed to be simple, intuitive and easy to learn. All XML
elements (tags) in this language must be namespace qualified with the namespace
URL <strong>http://ws.apache.org/ns/synapse</strong>.
</p>
<p>
As stated earlier, the synapse.xml file can be used to define all kinds of artifacts.
All these different configuration items should be wrapped in a top level 'definitions'
element. A configuration defined in the synapse.xml file looks like this at the
high level.
</p>
<div class="xmlConf">&lt;definitions&gt;
&lt;<a href="#RegistryConfig">registry</a> provider="string"&gt;...&lt;/registry&gt;?
&lt;<a href="#LocalEntryConfig">localEntry</a> key="string"&gt;...&lt;/localEntry&gt;?
&lt;<a href="#SequenceConfig">sequence</a> name="string"&gt;...&lt;/sequence&gt;?
&lt;<a href="#EndpointConfig">endpoint</a> name="string"&gt;...&lt;/endpoint&gt;?
&lt;<a href="#ProxyServiceConfig">proxy</a> name="string" ...&gt;...&lt;/proxy&gt;?
&lt;<a href="#TaskConfig">task</a> name="string" ...&gt;...&lt;/task&gt;?
&lt;<a href="#EventSourceConfig">eventSource</a> name="string" ...&gt;...&lt;/eventSource&gt;?
&lt;<a href="#ExecutorConfig">executor</a> name="string" ...&gt;...&lt;/executor&gt;?
&lt;<a href="#APIConfig">api</a> name="string" ...&gt;...&lt;/api&gt;?
&lt;<a href="#TemplateConfig">template</a> name="string" ...&gt;...&lt;/template&gt;?
&lt;<a href="#StoresConfig">messageStore</a> name="string" ...&gt;...&lt;/messageStore&gt;?
&lt;/definitions&gt;</div>
<p>
The registry adapter definition is defined under the &lt;registry&gt; element. Similarly
&lt;endpoint&gt;, &lt;sequence&gt;, &lt;proxy&gt;, &lt;localEntry&gt;, &lt;eventSource
and &lt;executor&gt; elements are used to define other functional components.
</p>
<p>
As pointed out earlier, the synapse.xml file is there in the synapse-config directory
for backwards compatibility reasons. Any artifact defined in this file can be
defined separately in its own XML file. The registry can be defined in the registry.xml
and other artifacts can be defined in the corresponding sub-directories of the synapse-config
directory. However the XML syntax used to configure these artifacts are always the same.
Next few sections of this document explains the XML syntax for defining various
types of components in the Synapse configuration.
</p>
</section>
<section name="Registry Configuration" id="RegistryConfig">
<p>
The &lt;registry&gt; element is used to define the registry adapter used by the
Synapse runtime. The registry provider specifies an implementation class for the
registry being used, and optionally a number of configuration parameters as may be
required by the particular registry implementation. An outline configuration is given
below.
</p>
<div class="xmlConf">&lt;registry provider="string"/&gt;
&lt;parameter name="string"&gt;text | xml&lt;/parameter&gt;*
&lt;/registry&gt;</div>
<p>
Registry entries loaded from a remote registry may be cached as governed by the
registry, and reloaded after the cache periods expires if a newer version is found.
Hence it is possible to define configuration elements such as (dynamic) sequences and
endpoints, as well as resources such as XSLT's, scripts or XSDs in the registry, and
update the configuration as these are allowed to dynamically change over time.
</p>
<p>
Synapse ships with a built-in URL based registry implementation called the
'SimpleURLRegistry' and this can be configured as follows:
</p>
<div class="xmlConf">&lt;registry provider="org.apache.synapse.registry.url.SimpleURLRegistry"&gt;
&lt;parameter name="root"&gt;file:./repository/conf/sample/resources/&lt;/parameter&gt;
&lt;parameter name="cachableDuration"&gt;15000&lt;/parameter&gt;
&lt;/registry&gt;</div>
<p>
The 'root' parameter specifies the root URL of the registry for loaded resources. The
SimpleURLRegistry keys are path fragments, that when combined with the root prefix
would form the full URL for the referenced resource. The 'cachableDuration' parameter
specifies the number of milliseconds for which resources loaded from the registry
should be cached. More advanced registry implementations allows different cachable
durations to be specified for different resources, or mark some resources as never
expires. (e.g. Check the WSO2 ESB implementation based on Apache Synapse)
</p>
</section>
<section name="Local Entry (Local Registry) Configuration" id="LocalEntryConfig">
<p>
Local entries provide a convenient way to import various external configuration
artifacts into the Synapse runtime. This includes WSDLs, policies, XSLT files,
and scripts. Local entry definitions are parsed at server startup and the referenced
configurations are loaded to the memory where they will remain until the server is
shut down. Other functional components such as sequences, endpoints and proxy services
can refer these locally defined in-memory configuration elements by using the local
entry keys.
</p>
<p>
The &lt;localEntry&gt; element is used to declare registry entries that are local
to the Synapse instance. Following syntax is used to define a local entry in the
Synapse configuration.
</p>
<div class="xmlConf">&lt;localEntry key="string" [src="url"]&gt;text | xml&lt;/localEntry&gt;</div>
<p>
A local entry may contain static text or static XML specified as inline content.
Following examples show how such static content can be included in local entry
definitions.
</p>
<div class="xmlConf">&lt;localEntry key="version"&gt;0.1&lt;/localEntry&gt;
&lt;localEntry key="validate_schema"&gt;
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
...
&lt;/xs:schema&gt;
&lt;/localEntry&gt;</div>
<p>
Note the validate_schema local entry which wraps some static XML schema content. A
mediator such as the validate mediator can refer this local entry to load its XML
schema definition.
</p>
<p>
A local entry may also point to a remote URL (specified using the 'src'
attribute) from which the contents can be loaded. This way the user does not have
to specify all external configurations in the Synapse configuration itself. The
required artifacts can be kept on the file system or hosted on a web server from where
Synapse can fetch them using a local entry definition. Following example shows
how a local entry is configured to load an XSLT file from the local file system.
</p>
<div class="xmlConf">&lt;localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/&gt;</div>
<p>
It is important to note that Synapse loads the local entry contents only during
server start up (even when they are defined with a remote URL). Therefore any
changes done on the remote artifacts will not reflect on Synapse until the server
is restarted. This is in contrast to the behavior with remote registry where
Synapse reloads configuration artifacts as soon as the cache period expires.
</p>
</section>
<section name="Sequence Configuration" id="SequenceConfig">
<p>
As explained earlier a sequence resembles a message flow in Synapse and consists
of an array of mediators. The &lt;sequence&gt; element is used to define a sequence
in the Synapse configuration. Sequences can be defined with names so they can be
reused across the Synapse configuration. The sequences named 'main' and 'fault' have
special significance in a Synapse configuration. The 'main' sequence handles any message
that is accepted for '<a href="#MessageMediation">Message Mediation</a>'. The
'fault' sequence is invoked if Synapse encounters a fault, and a custom fault handler
is not specified for the sequence via its 'onError' attribute. If the 'main' or
'fault' sequences are not defined locally or not found in the Registry, Synapse
auto generates suitable defaults at initialization.
</p>
<p>
A Dynamic Sequence may be defined by specifying a key reference to a registry entry.
As the remote registry entry changes, the sequence will dynamically be updated
according to the specified cache duration and expiration. If tracing is enabled on a
sequence, all messages being processed through the sequence would write tracing
information through each mediation step to the 'trace.log' file configured via the
log4j.properties configuration.
</p>
<p>
The syntax outline of a sequence definition is given below.
</p>
<div class="xmlConf">&lt;sequence name="string" [onError="string"] [key="string"] [trace="enable"] [statistics="enable"]&gt;
mediator*
&lt;/sequence&gt;</div>
<p>
The 'onError' attribute can be used to define a custom error handler sequence.
Statistics collection can be activated by setting the 'statistics' attribute to
'enable' on the sequence. In this mode the sequence will keep track of the number
of messages processed and their processing times. This statistical information can
then be retrieved through the Synapse statistics API.
</p>
<p>
All the immediate child elements of the sequence element must be valid mediators.
Following example shows a sequence configuration which consists of three child
mediators.
</p>
<div class="xmlConf">&lt;sequence name="main" onError="errorHandler"&gt;
&lt;log/&gt;
&lt;property name="test" value="test value"/&gt;
&lt;send/&gt;
&lt;/sequence&gt;</div>
<p>
Sequences can also hand over messages to other sequences. In this sense a sequence
is analogous to a procedure in a larger program. In many programming languages
procedures can invoke other procedures. See the following example sequence
configuration.
</p>
<div class="xmlConf">&lt;sequence name="foo"&gt;
&lt;log/&gt;
&lt;property name="test" value="test value"/&gt;
&lt;sequence key="other_sequence"/&gt;
&lt;send/&gt;
&lt;/sequence&gt;</div>
<p>
Note how the message is handed to a sequence named 'other_sequence' using the
'sequence' element. The 'key' attribute could point to another named sequence, a
local entry or a remote registry entry.
</p>
</section>
<section name="Endpoint Configuration" id="EndpointConfig">
<p>
An &lt;endpoint&gt; element defines a destination for an outgoing message. There
are several types of endpoints that can be defined in a Synapse configuration.
</p>
<ul>
<li>Address endpoint</li>
<li>WSDL endpoint</li>
<li>Load balance endpoint</li>
<li>Fail-over endpoint</li>
<li>Default endpoint</li>
<li>Recipient list endpoint</li>
</ul>
<p>
Configuration syntax and runtime semantics of these endpoint types differ from
each other. However the high level configuration syntax of an endpoint definition
takes the following form.
</p>
<div class="xmlConf">&lt;endpoint [name="string"] [key="string"]&gt;
<a href="#AddressEndpointConfig">address-endpoint</a> | <a href="#DefaultEndpointConfig">default-endpoint</a> | <a href="#WSDLEndpointConfig">wsdl-endpoint</a> |
<a href="#LBEndpointConfig">load-balanced-endpoint</a> | <a href="#FOEndpointConfig">fail-over-endpoint</a> | <a href="#RecipientListEndpointConfig">recipient-list-endpoint</a>
&lt;/endpoint&gt;</div>
<p>
Note how the endpoint definitions always start with an 'endpoint' element. The
immediate child element of this top level 'endpoint' element determines the type of
the endpoint. All above endpoint types can have a 'name' attribute, and such named
endpoints can be referred by other endpoints, through the key attribute. For example
if there is an endpoint named 'foo', the following endpoint can be used in any place,
where 'foo' has to be used.
</p>
<div class="xmlConf">&lt;endpoint key="foo"/&gt;</div>
<p>
This provides a simple mechanism for reusing endpoint definitions within a Synapse
configuration.
</p>
<p>
The 'trace' attribute turns on detailed trace information for messages being sent
to the endpoint. These will be available in the 'trace.log' file configured via the
log4j.properties file.
</p>
<subsection name="Address Endpoint" id="AddressEndpointConfig">
<div class="xmlConf">&lt;address uri="<em>endpoint address</em>" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
[encoding="<em>charset encoding</em>"]
[statistics="enable|disable"] [trace="enable|disable"]&gt;
&lt;enableRM [policy="<em>key</em>"]/&gt;?
&lt;enableSec [policy="<em>key</em>"]/&gt;?
&lt;enableAddressing [version="final|submission"] [separateListener="true|false"]/&gt;?
&lt;timeout&gt;
&lt;duration&gt;<em>timeout duration in milliseconds</em>&lt;/duration&gt;
&lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
&lt;/timeout&gt;?
&lt;markForSuspension&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
&lt;retryDelay&gt;d&lt;/retryDelay&gt;
&lt;/markForSuspension&gt;
&lt;suspendOnFailure&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;initialDuration&gt;n&lt;/initialDuration&gt;
&lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
&lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
&lt;/suspendOnFailure&gt;
&lt;/address&gt;</div>
<p>
Address endpoint is an endpoint defined by specifying the EPR and other
attributes of the endpoint directly in the configuration. The 'uri' attribute
of the address element contains the EPR of the target endpoint. Message format
for the endpoint and the method to optimize attachments can be specified in the
'format' and 'optimize' attributes respectively. Reliable messaging and security
policies for the endpoint can be specified in the policy attribute of the
'enableRM' and 'enableSec' elements respectively. WS-Addressing can be engaged
for the messages sent to the endpoint by using the 'enableAddressing' element.
</p>
<p>
The 'timeout' element of the endpoint configuration is used to set a specific
socket timeout for the endpoint. By default this is set to 1 minute (60 seconds).
When integrating with back-end services which take longer to respond the timeout
duration should be increased accordingly. The 'responseAction' element states
the action that should be taken in case a response is received after the timeout
period has elapsed. Synapse can either 'discard' the delayed response or inject it
into a 'fault' handler.
</p>
<p>
A Synapse endpoint is a state machine. At any given point in time it could be
in one of four states - Active, Timeout, Suspended and Switched Off. How and
when an endpoint changes its state is configurable through the Synapse configuration.
An endpoint in suspended or switched off states cannot be used to send messages.
Such an attempt would generate a runtime error.
</p>
<p>
By default an endpoint is in the 'Active' state. The endpoint will continue to
forward requests as long as its in this state. If an active endpoint encounters
an error while trying to send a message out (eg: a connection failure), the
endpoint may get pushed into the 'Timeout' state or the 'Suspended' state.
Generally most errors will put the endpoint straight into the 'Suspended' state.
Connection timeouts (error code 101504) and connection closed errors (101505)
are the only errors that will not directly suspend an endpoint. Using the
'errorCodes' element in the 'suspendOnFailure' configuration one can explicitly
define the errors for which the endpoint should be suspended. Similarly the
'errorCodes' element in the 'markForSuspension' configuration can be used to
define the errors for which the endpoint should be pushed into the 'Timeout'
state.
</p>
<p>
Endpoints in 'Timeout' state can be used to send messages. But any consecutive
errors while in this state can push the endpoint into the 'Suspended' state.
The number of consecutive errors that can suspend the endpoint can be configured
using the 'retriesBeforeSuspension' element in the 'markForSuspension' configuration.
The 'retryDelay' is used to specify a duration for which an endpoint will not be
available for immediate use after moving it to the 'Timeout' state. This duration
should be specified in milliseconds.
</p>
<p>
An endpoint in 'Suspended' state cannot be used to send messages. However the
suspension is only temporary. The suspend duration can be configured using the
'initialDuration' element. When this time period expires a suspended endpoint
becomes available for use again. However any recurring errors can put the
endpoint back in the 'Suspended' state. Such consecutive suspensions can also
progressively increase the suspend duration of the endpoint as configured by the
'progressionFactor' element. But the suspend duration will never exceed the
period configured in the 'maximumDuration' element. Note that both 'initialDuration'
and 'maximumDuration' should be specified in milliseconds.
</p>
<p>
Some example address endpoint configurations are given below. Note how the
communication protocol is used as a suffix to indicate the outgoing transport.
</p>
<table border="1">
<tbody>
<tr><th>Transport</th><th>Sample address</th></tr>
<tr><td>HTTP</td><td><tt>http://localhost:9000/services/SimpleStockQuoteService</tt></td></tr>
<tr><td>JMS</td><td><tt>jms:/SimpleStockQuoteService?<br/>
&#160;&#160;&#160;transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&amp;<br/>
&#160;&#160;&#160;java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&amp;<br/>
&#160;&#160;&#160;java.naming.provider.url=tcp://localhost:61616&amp;<br/>
&#160;&#160;&#160;transport.jms.DestinationType=topic</tt></td></tr>
<tr><td>Mail</td><td><tt>mailto:guest@host</tt></td></tr>
<tr><td>VFS</td><td><tt>vfs:file:///home/user/directory</tt></td></tr>
<tr><td/><td><tt>vfs:file:///home/user/file</tt></td></tr>
<tr><td/><td><tt>vfs:ftp://guest:guest@localhost/directory?vfs.passive=true</tt></td></tr>
</tbody>
</table>
</subsection>
<subsection name="Default Endpoint" id="DefaultEndpointConfig">
<p>
Default endpoint is an endpoint defined for adding QoS and other configurations
to the endpoint which is resolved from the 'To' address of the message context.
All the configurations such as message format for the endpoint, the method to
optimize attachments, reliable messaging, security policies for the endpoint
can be specified as in the case of Address Endpoint. This endpoint differs from
the address endpoint only in the 'uri' attribute which will not be present in
this endpoint. Following section describes the configuration of a default
endpoint.
</p>
<div class="xmlConf">&lt;default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
[encoding="<em>charset encoding</em>"]
[statistics="enable|disable"] [trace="enable|disable"]&gt;
&lt;enableRM [policy="<em>key</em>"]/&gt;?
&lt;enableSec [policy="<em>key</em>"]/&gt;?
&lt;enableAddressing [version="final|submission"] [separateListener="true|false"]/&gt;?
&lt;timeout&gt;
&lt;duration&gt;<em>timeout duration in milliseconds</em>&lt;/duration&gt;
&lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
&lt;/timeout&gt;?
&lt;markForSuspension&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
&lt;retryDelay&gt;d&lt;/retryDelay&gt;
&lt;/markForSuspension&gt;
&lt;suspendOnFailure&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;initialDuration&gt;n&lt;/initialDuration&gt;
&lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
&lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
&lt;/suspendOnFailure&gt;
&lt;/default&gt;</div>
</subsection>
<subsection name="WSDL Endpoint" id="WSDLEndpointConfig">
<p>
WSDL endpoint is an endpoint definition based on a specified WSDL document. The
WSDL document can be specified either as a URI or as an inline definition within
the configuration. The service and port name containing the target EPR has to be
specified with the 'service' and 'port' (or 'endpoint') attributes respectively.
Elements like 'enableRM', 'enableSec', 'enableAddressing', 'suspendOnFailure' and
'timeout' are same as for an Address endpoint.
</p>
<div class="xmlConf">&lt;wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname"&gt;
&lt;wsdl:definition&gt;...&lt;/wsdl:definition&gt;?
&lt;wsdl20:description&gt;...&lt;/wsdl20:description&gt;?
&lt;enableRM [policy="key"]/&gt;?
&lt;enableSec [policy="key"]/&gt;?
&lt;enableAddressing/&gt;?
&lt;timeout&gt;
&lt;duration&gt;timeout duration in milliseconds&lt;/duration&gt;
&lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
&lt;/timeout&gt;?
&lt;markForSuspension&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
&lt;retryDelay&gt;d&lt;/retryDelay&gt;
&lt;/markForSuspension&gt;
&lt;suspendOnFailure&gt;
[&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
&lt;initialDuration&gt;n&lt;/initialDuration&gt;
&lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
&lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
&lt;/suspendOnFailure&gt;
&lt;/wsdl&gt;</div>
</subsection>
<subsection name="Load Balance Endpoint" id="LBEndpointConfig">
<p>
A Load balanced endpoint distributes the messages (load) among a set of listed
endpoints or static members by evaluating the load balancing policy and any other
relevant parameters. The policy attribute of the load balance element specifies the
load balance policy (algorithm) to be used for selecting the target endpoint or
static member. Currently only the roundRobin policy is supported. The 'failover'
attribute determines if the next endpoint or static member should be selected once
the currently selected endpoint or static member has failed, and defaults to true.
The set of endpoints or static members amongst which the load has to be distributed
can be listed under the 'loadBalance' element. These endpoints can belong to any
endpoint type mentioned in this document. For example, failover endpoints can be
listed inside the load balance endpoint to load balance between failover groups etc.
The 'loadbalance' element cannot have both 'endpoint' and 'member' child elements in
the same configuration. In the case of the 'member' child element, the 'hostName',
'httpPort' and/or 'httpsPort' attributes should be specified.
</p>
<p>
The optional 'session' element makes the endpoint a session affinity based load
balancing endpoint. If it is specified, sessions are bound to endpoints in the
first message and all successive messages for those sessions are directed to their
associated endpoints. Currently there are two types of sessions supported in session
aware load balancing. Namely HTTP transport based session which identifies the
sessions based on http cookies and the client session which identifies the session
by looking at a SOAP header sent by the client with the QName
'{http://ws.apache.org/ns/synapse}ClientID'. The 'failover' attribute mentioned
above is not applicable for session affinity based endpoints and it is always
considered as set to false. If it is required to have failover behavior in session
affinity based load balance endpoints, failover endpoints should be listed as the
target endpoints.
</p>
<div class="xmlConf">&lt;loadBalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"]
[failover="true|false"]&gt;
&lt;endpoint .../&gt;+
&lt;member hostName="host" [httpPort="port"] [httpsPort="port2"]&gt;+
&lt;/loadBalance&gt;
&lt;session type="http|simpleClientSession"/&gt;?</div>
</subsection>
<subsection name="Dynamic Load Balance Endpoint" id="DLBEndpointConfig">
<p>
This is a special variation of the load balance endpoint where instead of
having to specify the child endpoints explicitly, the endpoint automatically
discovers the child endpoints available for load balancing. These child
endpoints will be discovered using the 'membershipHandler' class. Generally, this
class will use a group communication mechanism to discover the application members.
The 'class' attribute of the 'membershipHandler' element should be an
implementation of org.apache.synapse.core.LoadBalanceMembershipHandler.
The 'membershipHandler' specific properties can be specified using the 'property'
elements. The 'policy' attribute of the 'dynamicLoadbalance' element specifies
the load balance policy (algorithm) to be used for selecting the next member to
which the message has to be forwarded. Currently only the 'roundRobin' policy is
supported. 'The failover' attribute determines if the next member should be
selected once the currently selected member has failed, and defaults to true.
</p>
<div class="xmlConf">&lt;dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]&gt;
&lt;membershipHandler class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler"&gt;
&lt;property name="name" value="value"/&gt;+
&lt;/membershipHandler&gt;
&lt;/dynamicLoadBalance&gt;</div>
<p>
Currently Synapse ships with one implementation of the LoadBalanceMembershipHandler
interface. This class is named 'Axis2LoadBalanceMembershipHandler' and its
usage is demonstrated in sample 57.
</p>
</subsection>
<subsection name="Fail-Over Endpoint" id="FOEndpointConfig">
<p>
Failover endpoints send messages to the listed endpoints with the following
failover behavior. At the start, the first listed endpoint is selected as the
primary and all other endpoints are treated as backups. Incoming messages are
always sent only to the primary endpoint. If the primary endpoint fails, next
active endpoint is selected as the primary and failed endpoint is marked as
inactive. Thus it sends messages successfully as long as there is at least one
active endpoint among the listed endpoints.
</p>
<p>
When a previously failed endpoint becomes available again, it will assume
its position as the primary endpoint and the traffic will be routed to that endpoint.
It is possible to disable this behavior by setting the 'dynamic' attribute to false.
</p>
<div class="xmlConf">&lt;failover [dynamic="true|false"]&gt;
&lt;endpoint .../&gt;+
&lt;/failover&gt;</div>
</subsection>
<subsection name="Recipient List Endpoint" id="RecipientListEndpointConfig">
<p>
A recipient list endpoint can be used to send a single message to a list of
recipients (child endpoints). This is used to implement the well-known
integration pattern named 'recipient list'. The same functionality can
be achieved using the 'clone' mediator, but the recipient list provides
a more natural and intuitive way of implementing such a scenario. Configuration
of the recipient list endpoint takes the following general form.
</p>
<div class="xmlConf">&lt;recipientList name="string"&gt;
&lt;endpoint&gt;+
&lt;member hostName="host" [httpPort="port"] [httpsPort="port2"]&gt;+
&lt;/recipientList&gt;</div>
<p>
A recipient list can be named by setting the 'name' attribute on the 'recipientList'
element. Similar to a load balance endpoint, the recipient list endpoint also
wraps a set of endpoint definitions or a set of member definitions. At runtime
messages will be sent to all the child endpoints or members.
</p>
</subsection>
</section>
<section name="Proxy Service Configuration" id="ProxyServiceConfig">
<p>
A &lt;proxy&gt; element is used to define a Synapse Proxy service.
</p>
<div class="xmlConf">&lt;proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"] [serviceGroup="string"]&gt;
&lt;description&gt;...&lt;/description&gt;?
&lt;target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]&gt;
&lt;inSequence&gt;...&lt;/inSequence&gt;?
&lt;outSequence&gt;...&lt;/outSequence&gt;?
&lt;faultSequence&gt;...&lt;/faultSequence&gt;?
&lt;endpoint&gt;...&lt;/endpoint&gt;?
&lt;/target&gt;?
&lt;publishWSDL key="string" uri="string"&gt;
( &lt;wsdl:definition&gt;...&lt;/wsdl:definition&gt; | &lt;wsdl20:description&gt;...&lt;/wsdl20:description&gt; )?
&lt;resource location="..." key="..."/&gt;*
&lt;/publishWSDL&gt;?
&lt;enableAddressing/&gt;?
&lt;enableSec/&gt;?
&lt;enableRM/&gt;?
&lt;policy key="string" [type="(in | out)"]/&gt;? // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies)
&lt;parameter name="string"&gt; // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
string | xml
&lt;/parameter&gt;
&lt;/proxy&gt;</div>
<p>
A proxy service is created and exposed on the specified transports through the
underlying Axis2 engine, exposing service EPRs as per the standard Axis2
conventions (ie based on the service name). Note that currently Axis2 does not allow
custom URI's to be set for services on some transports such as http/s. A proxy
service could be exposed over all enabled Axis2 transports such as http, https,
JMS, Mail and File etc. or on a subset of these as specified by the optional
'transports' attribute. By default, if this attribute is not specified, Synapse
will attempt to expose the proxy service on all enabled transports.
</p>
<p>
In a clustered setup it might be required to deploy a particular proxy service
on a subset of the available nodes. This can be achieved using the 'pinnedServers'
attribute. This attribute takes a list of server names. At server startup Synapse
will check whether the name of the current host matches any of the names given
in this attribute and only deploy the proxy service if a match is found. The
server host name is picked from the system property 'SynapseServerName', failing
which the hostname of the machine would be used or default to 'localhost'. User can
specify a more meaningful name to a Synapse server instance by starting the server
using the following command.
</p>
<div class="command">./synapse.sh -serverName=&lt;ServerName&gt;</div>
<p>
If Synapse is started as a daemon or a service, the above setting should be specified
in the wrapper.conf file.
</p>
<p>
By default when a proxy service is created it is added to an Axis service group
which has the same name as the proxy service. With the 'serviceGroup' attribute
this behavior can be further configured. A custom Axis service group can be specified
for a proxy service using the 'serviceGroup' attribute. This way multiple proxy
services can be grouped together at Axis2 level thus greatly simplifying service
management tasks.
</p>
<p>
Each service could define the target for received messages as a named sequence or a
direct endpoint. Either target inSequence or endpoint is required for the proxy
configuration, and a target outSequence defines how responses should be handled. Any
WS-Policies provided would apply as service level policies, and any service parameters
could be passed into the proxy service's AxisService instance using the 'parameter'
elements (e.g. the JMS destination etc). If the proxy service should enable
WS-Reliable Messaging or Security, the appropriate modules should be engaged, and
specified service level policies will apply. To engage the required modules, one may
use the 'enableSec', 'enableRM' and 'enableAddressing' elements.
</p>
<p>
A dynamic proxy may be defined by specifying the properties of the proxy as dynamic
entries by referring them with the key. For example one could specify the
inSequence or endpoint with a remote key, without defining it in the local
configuration. As the remote registry entry changes, the properties of the proxy
will dynamically be updated accordingly. (Note: proxy service definition itself
cannot be specified to be dynamic; i.e &lt;proxy key="string"/&gt; is wrong)
</p>
<p>
A WSDL for the proxy service can be published using the 'publishWSDL' element.
The WSDL document can be loaded from the registry by specifying the 'key' attribute
or from any other location by specifying the 'uri' attribute. Alternatively the WSDL
can be provided inline as a child element of the 'publishWSDL' element. Artifacts
(schemas or other WSDL documents) imported by the WSDL can be resolved from the
registry by specifying appropriate 'resource' elements.
</p>
<div class="xmlConf">&lt;publishWSDL key="my.wsdl"&gt;
&lt;resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/&gt;
&lt;/publishWSDL&gt;</div>
<p>
In this example the WSDL is retrieved from the registry using the key 'my.wsdl'. It
imports another WSDL from location 'http://www.standards.org/standard.wsdl'. Instead
of loading it from this location, Synapse will retrieve the imported WSDL from the
registry entry 'standard.wsdl'.
</p>
<p>
Some well-known parameters that are useful when writing complex proxy services
are listed below. These can be included in a proxy configuration using 'parameter'
tags.
</p>
<table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table">
<tbody>
<tr>
<th>
Parameter
</th>
<th>
Value
</th>
<th>
Default
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
useOriginalwsdl
</td>
<td>
true|false
</td>
<td>
false
</td>
<td>
Use the given WSDL instead of generating the WSDL.
</td>
</tr>
<tr>
<td>
modifyUserWSDLPortAddress
</td>
<td>
true|false
</td>
<td>
true
</td>
<td>
(Effective only with useOriginalwsdl=true) If true (default) modify
the port addresses to current host.
</td>
</tr>
<tr>
<td>
showAbsoluteSchemaURL
</td>
<td>
true|false
</td>
<td>
false
</td>
<td>
Show the absolute path of the referred schemas of the WSDL without
showing the relative paths.
</td>
</tr>
</tbody>
</table>
<p>
Following table lists some transport specific parameters that can be passed into
proxy service configurations.
</p>
<table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table">
<tbody>
<tr>
<th>
Transport
</th>
<th>
Require
</th>
<th>
Parameter
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
JMS
</td>
<td>
Optional
</td>
<td>
transport.jms.ConnectionFactory
</td>
<td>
The JMS connection factory definition (from axis2.xml) to be used to
listen for messages for this service
</td>
</tr>
<tr>
<td/>
<td>
Optional
</td>
<td>
transport.jms.Destination
</td>
<td>
The JMS destination name (Defaults to a Queue with the service name)
</td>
</tr>
<tr>
<td/>
<td>
Optional
</td>
<td>
transport.jms.DestinationType
</td>
<td>
The JMS destination type. Accept values 'queue' or 'topic' (default:
queue)
</td>
</tr>
<tr>
<td/>
<td>
Optional
</td>
<td>
transport.jms.ReplyDestination
</td>
<td>
The destination where a reply will be posted
</td>
</tr>
<tr>
<td/>
<td>
Optional
</td>
<td>
transport.jms.Wrapper
</td>
<td>
The wrapper element for the JMS message
</td>
</tr>
</tbody>
</table>
</section>
<section name="Scheduled Task Configuration" id="TaskConfig">
<p>
A &lt;task&gt; element is used to define a Synapse task (aka startup).
</p>
<div class="xmlConf">&lt;task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]&gt;
&lt;property name="stringProp" value="String"/&gt;
&lt;property name="xmlProp"&gt;
&lt;somexml&gt;config&lt;/somexml&gt;
&lt;/property&gt;
&lt;trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/&gt;
&lt;/task&gt;</div>
<p>
A task is created and scheduled to run at specified time intervals or as specified
by the cron expression. The 'class' attribute specifies the actual task
implementation class (which must implement org.apache.synapse.task.Task interface)
to be executed at the specified interval/s, and name specifies an identifier for
the scheduled task.
</p>
<p>
Fields in the task class can be set using properties provided as string literals or
XML fragments. For example, if the task implementation class has a field named
'version' with a corresponding setter method, the configuration value which will be
assigned to this field before running the task can be specified using a property with
the name 'version'.
</p>
<p>
There are three different trigger mechanisms to schedule tasks. A simple trigger is
specified with a 'count' and an 'interval', implying that the task will run a
'count' number of times at specified intervals. A trigger may also be specified as
a cron trigger using a cron expression. A one-time trigger is specified using the
'once' attribute in the definition and could be specified as true in which case the
task will be executed only once just after the initialization of Synapse.
</p>
<p>
In clustered deployments sometimes it would be necessary to deploy a particular task
in a selected set of nodes. This can be achieved using the optional 'pinnedServers'
attribute. A list of server names or host names can be specified in this attribute.
At server startup, Synapse will match the current server name or the host name with
the values specified in this attribute to see whether the task should be initialized
or not.
</p>
</section>
<section name="Template Configuration" id="TemplateConfig">
<p>
As explained earlier templates in synapse are defined in two flavors; sequence and
endpoint templates. The configuration, syntax forms and semantics of these are explained
in the following section.
</p>
<p>
A sequence template consist of two parts. As in any kind of a function, it has a
parameter set definition (argument list) and a function body definition. An important
difference is sequence template parameters are not typed (typically these are
string parameters, but can be of any type which is determined at runtime). Also
function body is a typical esb flow or a sequence.
</p>
<p>
The syntax outline of a sequence template definition is given below.
</p>
<div class="xmlConf">&lt;template name=&quot;string&quot;&gt;
&lt;!-- parameters this sequence template will be supporting --&gt;
(
&lt;parameter name=&quot;string&quot;/&gt;
) *
&lt;!--this is the in-line sequence of the template --&gt;
&lt;sequence&gt;
mediator+
&lt;/sequence&gt;
&lt;/template&gt;</div>
<p>
A sequence template is a top level element defined with the 'name' attribute in Synapse
configuration. Both endpoint and sequence templates start with a 'template' element.
Parameters (defined by &lt;parameter&gt; elements) are the inputs supported by a
sequence template. These sequence template parameters can be referred by any xpath
expression defined within the in-lined sequence. For example parameter named 'foo' can
be referred by a property mediator (defined inside the in-line sequence of the template)
in following ways.
</p>
<div class="xmlConf">&lt;property name="PropertyValue" expression="$func:foo"/&gt;
&lt;property name="PropertyValue" expression="get-property('foo', 'func')"/&gt;</div>
<p>
Note the scope variable used in the XPath expression. We use 'function' scope or '$func'
to refer to template parameters.
</p>
<p>
Invoking a sequence template can be done with a mediator named 'call-template' by
passing parameter values. The syntax outline of a call template mediator definition
is given below.
</p>
<div class="xmlConf">&lt;call-template target=&quot;string&quot;&gt;
&lt;!-- parameter values will be passed on to a sequence template --&gt;
(
&lt;!--passing plain static values --&gt;
&lt;with-param name=&quot;string&quot; value=&quot;string&quot; /&gt; |
&lt;!--passing xpath expressions --&gt;
&lt;with-param name=&quot;string&quot; value=&quot;{string}&quot; /&gt; |
&lt;!--passing dynamic xpath expressions where values will be compiled dynamically--&gt;
&lt;with-param name=&quot;string&quot; value=&quot;{{string}}&quot; /&gt; |
) *
&lt;/call-template&gt;</div>
<p>
The 'call-template' mediator should define a target template it should be
invoking, with 'target' attribute.
</p>
<p>
The 'with-param' element is used to parse parameter values to a target
sequence template. Note that parameter names has to be exact matches to the names
specified in the target template. Parameter elements can contain three types of
parameterized values. xpath values are passed in within curly braces ({}) for value
attribute.
</p>
<p>
Endpoint templates are similar to the sequence templates in definition. Unlike
sequence templates, endpoint templates are always parameterized using '$' prefixed
values (NOT xpath expressions). Users can parameterize endpoint configuration elements
with these '$' prefixed values. An example is shown below.
</p>
<div class="xmlConf">&lt;template name=&quot;ep_template&quot;&gt;
&lt;parameter name=&quot;codes&quot;/&gt;
&lt;parameter name=&quot;factor&quot;/&gt;
&lt;parameter name=&quot;retries&quot;/&gt;
&lt;endpoint name=&quot;$name&quot;&gt;
&lt;default&gt;
&lt;suspendOnFailure&gt;
&lt;errorCodes&gt;$codes&lt;/errorCodes&gt;
&lt;progressionFactor&gt;$factor&lt;/progressionFactor&gt;
&lt;/suspendOnFailure&gt;
&lt;markForSuspension&gt;
&lt;retriesBeforeSuspension&gt;$retries&lt;/retriesBeforeSuspension&gt;
&lt;retryDelay&gt;0&lt;/retryDelay&gt;
&lt;/markForSuspension&gt;
&lt;/default&gt;
&lt;/endpoint&gt;
&lt;/template&gt;</div>
<p>
The syntax outline of a endpoint template definition is given below.
</p>
<div class="xmlConf">&lt;template name=&quot;string&quot;&gt;
&lt;!-- parameters this endpoint template will be supporting --&gt;
(
&lt;parameter name=&quot;string&quot;/&gt;
) *
&lt;!--this is the in-line endpoint of the template --&gt;
&lt;endpoint [name=&quot;string&quot;] &gt;
address-endpoint | default-endpoint | wsdl-endpoint |
load-balanced-endpoint | fail-over-endpoint | recipient-list-endpoint
&lt;/endpoint&gt;
&lt;/template&gt;</div>
<p>
As described earlier template endpoint is the artifact that makes a template of an
endpoint type into a concrete endpoint. In other words an endpoint template would
be useless without a template endpoint referring to it. This is semantically similar
to the relationship between a sequence template and a 'call-template' mediator.
</p>
<p>
The syntax outline of a template endpoint definition is as following..
</p>
<div class="xmlConf">&lt;endpoint [name=&quot;string&quot;] [key=&quot;string&quot;] template=&quot;string&quot;&gt;
&lt;!-- parameter values will be passed on to a endpoint template --&gt;
(
&lt;parameter name=&quot;string&quot; value=&quot;string&quot; /&gt;
) *
&lt;/endpoint&gt;</div>
<p>
Template endpoint defines parameter values that can parameterize an endpoint.
The 'template' attribute points to a target endpoint template.
</p>
<p>
As in the case of sequence template, note that parameter names has to be exact match
to the names specified in target endpoint template.
</p>
</section>
<section name="Event Source Configuration" id="EventSourceConfig">
<p>
Event sources enable the user to run Synapse in the eventing mode of operation.
Synapse can act as an event source as well as an event broker. An event source
is defined using the &lt;eventSource&gt; configuration element.
</p>
<div class="xmlConf">&lt;eventSource name="string"&gt;
&lt;subscriptionManager class="mypackage.MyClass"&gt;
&lt;parameter name="string"/&gt;
&lt;/subscriptionManager&gt;
&lt;/eventSource&gt;</div>
<p>
Once an event source is deployed in Synapse, it will provide a service URL (EPR) to
which clients can send WS-Eventing subscription requests. Clients can subscribe,
unsubscribe and renew subscriptions by sending messages to this EPR. The subscription
manager configured inside the event source will be responsible for storing
and managing the subscriptions. The 'class' attribute of the 'subscriptionManager'
element should point to the Java class which provides this subscription management
functionality. Synapse ships with an in-memory subscription manager which
keeps and manages all subscriptions in memory.
</p>
<p>
Any additional parameters required to configure the subscription manager implementation
can be specified using the 'parameter' elements.
</p>
</section>
<section name="API Configuration" id="APIConfig">
<p>
APIs provide a flexible and powerful approach for defining full fledged REST APIs
in Synapse. An API definition starts with the &lt;api&gt; element.
</p>
<div class="xmlConf">&lt;api name="string" context="string" [hostname="string"][port="int"]&gt;
&lt;resource [methods="http-method-list"][inSequence="string"][outSequence="string"]
[faultSequence="string"][content-type="string"][user-agent="str"]&gt;
&lt;inSequence&gt;...&lt;/inSequence&gt;?
&lt;outSequence&gt;...&lt;/outSequence&gt;?
&lt;faultSequence&gt;...&lt;/faultSequence&gt;?
&lt;/resource&gt;+
&lt;handlers&gt;
&lt;handler class="name"/&gt;+
&lt;/handlers&gt;?
&lt;/api&gt;</div>
<p>
Each API definition must be uniquely named using the 'name' attribute. The 'context'
attribute is used to define the URL context at which the REST API will be anchored
(eg: /ws, /foo/bar, /soap). The API will only receive requests that fall in the
specified URL context. In addition to that an API could be bound to a particular
host and a port using the 'hostname' and 'port' attributes.
</p>
<p>
An API must also contain one or more resources. Resources define how messages
are processed and mediated by the API. An API can be associated with a set of HTTP
methods using the 'methods' attribute. This attribute can support a single method name
(eg: GET) or a space separated list of methods (eg: GET PUT DELETE). A resource
can also refer other sequences using the 'inSequence', 'outSequence' and 'faultSequence'
attributes. Alternatively these mediation sequences can be defined inline with the
resource using 'inSequence', 'outSequence' and 'faultSequence' tags.
</p>
<p>
An API can also optionally define a set of handlers. These handlers are invoked
for each incoming API request, before they are dispatched to the appropriate
resources. The 'class' attribute on the 'handler' elements should contain the
ful qualified names of the handler implementation classes.
</p>
</section>
<section name="Priority Executor Configuration" id="ExecutorConfig">
<p>
The priority executor configuration syntax takes the following general form.
</p>
<div class="xmlConf">&lt;priority-executor name=&quot;string&quot;&gt;
&lt;queues isFixed=&quot;true|false&quot; nextQueue=&quot;class implementing NextQueueAlgorithm&quot;&gt;
&lt;queue [size=&quot;size of the queue&quot;] priority=&quot;priority of the messages put in to this queue&quot;/&gt;*
&lt;/queues&gt;
&lt;threads core=&quot;core number of threads&quot; max=&quot;max number of threads&#39; keep-alive=&quot;keep alive time&quot;/&gt;
&lt;/priority-executor&gt;</div>
<p>
A priority executor consists of a thread pool and a set of queues for different
priority levels. Queues can be either bounded on unbounded in terms of capacity.
Each executor must define at least two queues. By default queues are unbounded.
By specifying the attribute 'size' they can be configured to have a limited capacity.
The 'priority' attribute specifies the priority level associated with a particular
queue. As explained earlier, higher the level, higher the priority the messages will
get.
</p>
<p>
The next queue algorithm is used to determine the next message processed. By default
Synapse uses a built-in priority queueing algorithm for this purpose. If required a
custom algorithm can be used by specifying the 'nextQueue' algorithm on the 'queues'
element.
</p>
<p>
The 'threads' element is used to configure the underlying thread pool. The 'core'
and 'max' attributes are used to specify the initial size and the maximum size of the
thread pool. A keep-alive time duration can be specified for idling threads using
the 'keep-alive' attribute where the duration is configured in seconds. If not
specified a default keep-alive duration of 5 seconds will be used.
</p>
<p>
In order to process messages through a priority executor one must use the 'enqueue'
mediator. This mediator can be used in a sequence or a proxy service to get all
requests processed through a pre-configured priority executor.
</p>
<div class="xmlConf">&lt;enqueue priority="10" executor="MyExecutor"/&gt;</div>
<p>
For best results it's recommended to dispatch messages into priority executors
straight from the transport level. This can be achieved by adding an additional
parameter to the NHTTP transport configuration in the axis2.xml file of Synapse.
</p>
<div class="xmlConf">&lt;parameter name="priorityConfigFile"&gt;file path&lt;/parameter&gt;</div>
<p>
The parameter should point to a separate XML configuration which defines the
priority configuration.
</p>
<div class="xmlConf">&lt;Priority-Configuration&gt;
&lt;priority-executor name="priority-executor"&gt;
&lt;queues isFixed="true|false"&gt;
&lt;queue [size=""] priority=""/&gt;*
&lt;/queues&gt;
&lt;threads core="core number of threads" max="max number of threads' keep-alive="keep alive time"/&gt;
&lt;/priority-executor&gt;
&lt;!-- conditions for calculating the priorities based on HTTP message --&gt;
&lt;conditions defaultPriority="default priority as an integer"&gt;
&lt;condition priority="priority value as an integer"&gt;
one evaluator, this evaluator can contain other evaluators
&lt;/condition&gt;
&lt;/conditions&gt;
&lt;/Priority-Configuration&gt;</div>
</section>
<section name="Message Stores and Processors Configuration" id="StoresConfig">
<p>
Both Message Stores and processors are top level configuration of synapse. Following
section tries to describe some of the syntax of the message store/processors
configurations.
</p>
<p>
The syntax outline of a message store definition is given below.
</p>
<div class="xmlConf"> &lt;messageStore name=&quot;string&quot; class=&quot;classname&quot; &gt;
&lt;parameter name=&quot;string&quot; &gt; &quot;string&quot; &lt;/parameter&gt;*
&lt;/messageStore&gt;</div>
<p>
The 'class' attribute value is the fully qualified class name of the underlying message
store implementation. There can be many message store implementations.Users can write
their own message store implementation and use it. Parameters section is used to
configure the parameters that is needed by underlying message store implementation.
</p>
<p>
The syntax outline of a message processor definition is given below.
</p>
<div class="xmlConf"> &lt;messageProcessor name=&quot;string&quot; class=&quot;class name&quot; messageStore=&quot;classname&quot; &gt;
&lt;parameter name=&quot;string&quot; &gt; &quot;string&quot; &lt;/parameter&gt;*
&lt;/messageProcessor&gt;</div>
<p>
The 'class' attribute value is the fully qualified class name of the underlying message
processor implementation. There are two message processor implementations shipped by
default. There can be many message processor implementations.Users can write their
own message processor implementation and use it. Similar to message stores ,parameters
section here as well is used to configure the parameters that is needed by underlying
message processor implementation
</p>
<div class="xmlConf">Message Forwarding Processor : org.apache.synapse.message.processors.forward.ScheduledMessageForwardingProcessor</div>
<div class= "xmlConf">Sampling Processor : org.apache.synapse.message.processors.sampler.SamplingProcessor</div>
<p>
As mentioned earlier, there are several message store/processor implementations
shipped by default. However if users wants to extend these following interfaces are
available.
</p>
<div class="xmlConf">Interface: org.apache.synapse.message.store.MessageStore
Abstract Class: org.apache.synapse.message.store.AbstractMessageStore
Interface: org.apache.synapse.message.processors.MessageProcessor
Abstract Class: org.apache.synapse.message.processors.AbstractMessageProcessor</div>
</section>
</body>
</document>