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.

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.

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.

• Synapse Configuration
  • Service Mediation (Proxy Services)
  • Message Mediation
  • Task Scheduling
  • Eventing
• Functional Components Overview
  • Mediators and Sequences
  • Endpoints
  • Proxy Services
  • Scheduled Tasks
  • Templates
  • Remote Registry and Local Registry
  • APIs
  • Priority Executors
  • Message Stores and Processors
• Synapse Configuration Files
• Configuration Syntax
• Registry Configuration
• Local Entry (Local Registry) Configuration
• Sequence Configuration
• Endpoint Configuration
  • Address Endpoint
  • Default Endpoint
  • WSDL Endpoint
  • Load Balance Endpoint
  • Dynamic Load Balance Endpoint
  • Fail-Over Endpoint
  • Recipient List Endpoint"
• Proxy Service Configuration
• Scheduled Task Configuration
• Template Configuration
• Event Source Configuration
• API Configuration
• Priority Executor Configuration
• Message Stores and Processors Configuration

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.

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 XML schema.

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.

Depending on how functional components are used in the Synapse configuration, Synapse can execute in one or more of the following operational modes.

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.

As of now Synapse mediation engine consists of following functional elements:

• Mediators and sequences
• Endpoints
• Proxy services
• Scheduled tasks
• Event sources
• Sequence templates
• Endpoint templates
• Registry adapter
• APIs
• Priority executors
• Message stores and processors

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.

• api
• endpoints
• events
• local-entries
• message-processors
• message-stores
• priority-executors
• proxy-services
• sequences
• tasks
• templates

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.

The following tree diagram shows the high-level view of the resulting file hierarchy.

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 http://ws.apache.org/ns/synapse.

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.

The registry adapter definition is defined under the <registry> element. Similarly <endpoint>, <sequence>, <proxy>, <localEntry>, <eventSource and <executor> elements are used to define other functional components.

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.

The <registry> 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.

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.

Synapse ships with a built-in URL based registry implementation called the 'SimpleURLRegistry' and this can be configured as follows:

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)

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.

The <localEntry> 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.

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.

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.

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.

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.

As explained earlier a sequence resembles a message flow in Synapse and consists of an array of mediators. The <sequence> 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 'Message Mediation'. 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.

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.

The syntax outline of a sequence definition is given below.

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.

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.

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.

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.

An <endpoint> element defines a destination for an outgoing message. There are several types of endpoints that can be defined in a Synapse configuration.

• Address endpoint
• WSDL endpoint
• Load balance endpoint
• Fail-over endpoint
• Default endpoint
• Recipient list endpoint

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.

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.

This provides a simple mechanism for reusing endpoint definitions within a Synapse configuration.

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.

A <proxy> element is used to define a Synapse Proxy service.

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.

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.

If Synapse is started as a daemon or a service, the above setting should be specified in the wrapper.conf file.

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.

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', and 'enableAddressing' elements.

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 <proxy key="string"/> is wrong)

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.

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'.

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.

Following table lists some transport specific parameters that can be passed into proxy service configurations.

A <task> element is used to define a Synapse task (aka startup).

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.

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'.

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.

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.

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.

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.

The syntax outline of a sequence template definition is given below.

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 <parameter> 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.

Note the scope variable used in the XPath expression. We use 'function' scope or '$func' to refer to template parameters.

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.

The 'call-template' mediator should define a target template it should be invoking, with 'target' attribute.

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.

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.

The syntax outline of a endpoint template definition is given below.

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.

The syntax outline of a template endpoint definition is as following..

Template endpoint defines parameter values that can parameterize an endpoint. The 'template' attribute points to a target endpoint template.

As in the case of sequence template, note that parameter names has to be exact match to the names specified in target endpoint template.

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 <eventSource> configuration element.

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.

Any additional parameters required to configure the subscription manager implementation can be specified using the 'parameter' elements.

APIs provide a flexible and powerful approach for defining full fledged REST APIs in Synapse. An API definition starts with the <api> element.

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. The 'transport' attribute can be used to restrict the API to process either HTTP messages or HTTPS messages only.

An API must also contain one or more resources. Resources define how messages are processed and mediated by the API. A resource 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). The 'url-mapping' and 'uri-template' attributes can be used to specify the type of URL requests that should be handled by any particular resource. The 'url-mapping' attribute accepts any Java servlet style URL mapping (eg: /test/*, *.jsp). The 'uri-template' attribute accepts valid RFC6570 style expressions (eg: /orders/{orderId}). 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.

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.

The priority executor configuration syntax takes the following general form.

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.

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.

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.

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.

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.

The parameter should point to a separate XML configuration which defines the priority configuration.

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.

The syntax outline of a message store definition is given below.

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.

The syntax outline of a message processor definition is given below.

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

As mentioned earlier, there are several message store/processor implementations shipped by default. However if users wants to extend these following interfaces are available.