You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/22 17:16:05 UTC
svn commit: r1222320 [2/13] - in /synapse/branches/2.1/src: ./ site/
site/resources/ site/resources/css/ site/resources/images/ site/xdoc/
site/xdoc/userguide/ site/xdoc/userguide/samples/
site/xdoc/userguide/samples/setup/
Added: synapse/branches/2.1/src/site/xdoc/userguide/config.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/config.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/config.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/config.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,1627 @@
+<?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="Contents">
+ <ul>
+ <li><a href="#Intro">Introduction</a></li>
+ <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="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="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>
+ <!-- Image goes here -->
+ <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"><definitions>
+ <<a href="#RegistryConfig">registry</a> provider="string">...</registry>?
+ <<a href="#LocalEntryConfig">localEntry</a> key="string">...</localEntry>?
+ <<a href="#SequenceConfig">sequence</a> name="string">...</sequence>?
+ <<a href="#EndpointConfig">endpoint</a> name="string">...</endpoint>?
+ <<a href="#ProxyServiceConfig">proxy</a> name="string" ...>...</proxy>?
+ <<a href="#TaskConfig">task</a> name="string" ...>...</task>?
+ <<a href="#EventSourceConfig">eventSource</a> name="string" ...>...</eventSource>?
+ <<a href="#ExecutorConfig">executor</a> name="string" ...>...</executor>?
+ <<a href="#APIConfig">api</a> name="string" ...>...</api>?
+ <<a href="#TemplateConfig">template</a> name="string" ...>...</template>?
+ <<a href="#store">messageStore</a> name="string" ...>...</messageStore>?
+</definitions></div>
+ <p>
+ 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.
+ </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 <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.
+ </p>
+ <div class="xmlConf"><registry provider="string"/>
+ <parameter name="string">text | xml</parameter>*
+</registry></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"><registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+</registry></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 <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.
+ </p>
+ <div class="xmlConf"><localEntry key="string" [src="url"]>text | xml</localEntry></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"><localEntry key="version">0.1</localEntry>
+
+<localEntry key="validate_schema">
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ ...
+ </xs:schema>
+</localEntry></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"><localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/></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 <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 '<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"><sequence name="string" [onError="string"] [key="string"] [trace="enable"] [statistics="enable"]>
+ mediator*
+</sequence></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"><sequence name="main" onError="errorHandler">
+ <log/>
+ <property name="test" value="test value"/>
+ <send/>
+</sequence></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"><sequence name="foo">
+ <log/>
+ <property name="test" value="test value"/>
+ <sequence key="other_sequence"/>
+ <send/>
+</sequence></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 <endpoint> 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"><endpoint [name="string"] [key="string"]>
+ <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>
+</endpoint></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"><endpoint key="foo"/></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"><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"]>
+ <enableRM [policy="<em>key</em>"]/>?
+ <enableSec [policy="<em>key</em>"]/>?
+ <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?
+
+ <timeout>
+ <duration><em>timeout duration in milliseconds</em></duration>
+ <responseAction>discard|fault</responseAction>
+ </timeout>?
+
+ <markForSuspension>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <retriesBeforeSuspension>m</retriesBeforeSuspension>
+ <retryDelay>d</retryDelay>
+ </markForSuspension>
+
+ <suspendOnFailure>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <initialDuration>n</initialDuration>
+ <progressionFactor>r</progressionFactor>
+ <maximumDuration>l</maximumDuration>
+ </suspendOnFailure>
+</address></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/>
+    transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&<br/>
+    java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&<br/>
+    java.naming.provider.url=tcp://localhost:61616&<br/>
+    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"><default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
+ [encoding="<em>charset encoding</em>"]
+ [statistics="enable|disable"] [trace="enable|disable"]>
+ <enableRM [policy="<em>key</em>"]/>?
+ <enableSec [policy="<em>key</em>"]/>?
+ <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?
+
+ <timeout>
+ <duration><em>timeout duration in milliseconds</em></duration>
+ <responseAction>discard|fault</responseAction>
+ </timeout>?
+
+ <markForSuspension>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <retriesBeforeSuspension>m</retriesBeforeSuspension>
+ <retryDelay>d</retryDelay>
+ </markForSuspension>
+
+ <suspendOnFailure>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <initialDuration>n</initialDuration>
+ <progressionFactor>r</progressionFactor>
+ <maximumDuration>l</maximumDuration>
+ </suspendOnFailure>
+</default></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"><wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname">
+ <wsdl:definition>...</wsdl:definition>?
+ <wsdl20:description>...</wsdl20:description>?
+ <enableRM [policy="key"]/>?
+ <enableSec [policy="key"]/>?
+ <enableAddressing/>?
+
+ <timeout>
+ <duration>timeout duration in milliseconds</duration>
+ <responseAction>discard|fault</responseAction>
+ </timeout>?
+ <markForSuspension>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <retriesBeforeSuspension>m</retriesBeforeSuspension>
+ <retryDelay>d</retryDelay>
+ </markForSuspension>
+
+ <suspendOnFailure>
+ [<errorCodes>xxx,yyy</errorCodes>]
+ <initialDuration>n</initialDuration>
+ <progressionFactor>r</progressionFactor>
+ <maximumDuration>l</maximumDuration>
+ </suspendOnFailure>
+
+</wsdl></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"><loadBalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"]
+ [failover="true|false"]>
+ <endpoint .../>+
+ <member hostName="host" [httpPort="port"] [httpsPort="port2"]>+
+</loadBalance>
+<session type="http|simpleClientSession"/>?</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"><dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]>
+ <membershipHandler class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler">
+ <property name="name" value="value"/>+
+ </membershipHandler>
+</dynamicLoadBalance></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"><failover [dynamic="true|false"]>
+ <endpoint .../>+
+</failover></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"><recipientList name="string">
+ <endpoint>+
+ <member hostName="host" [httpPort="port"] [httpsPort="port2"]>+
+</recipientList></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 <proxy> element is used to define a Synapse Proxy service.
+ </p>
+ <div class="xmlConf"><proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"] [serviceGroup="string"]>
+ <description>...</description>?
+ <target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]>
+ <inSequence>...</inSequence>?
+ <outSequence>...</outSequence>?
+ <faultSequence>...</faultSequence>?
+ <endpoint>...</endpoint>?
+ </target>?
+ <publishWSDL key="string" uri="string">
+ ( <wsdl:definition>...</wsdl:definition> | <wsdl20:description>...</wsdl20:description> )?
+ <resource location="..." key="..."/>*
+ </publishWSDL>?
+ <enableAddressing/>?
+ <enableSec/>?
+ <enableRM/>?
+ <policy key="string" [type="(in | out)"]/>? // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies)
+ <parameter name="string"> // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
+ string | xml
+ </parameter>
+</proxy></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=<ServerName></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 <proxy key="string"/> 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"><publishWSDL key="my.wsdl">
+ <resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/>
+</publishWSDL></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 <task> element is used to define a Synapse task (aka startup).
+ </p>
+ <div class="xmlConf"><task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]>
+ <property name="stringProp" value="String"/>
+ <property name="xmlProp">
+ <somexml>config</somexml>
+ </property>
+ <trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/>
+</task></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"><template name="string">
+ <!-- parameters this sequence template will be supporting -->
+ (
+ <parameter name="string"/>
+ ) *
+ <!--this is the in-line sequence of the template -->
+ <sequence>
+ mediator+
+ </sequence>
+</template></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 <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.
+ </p>
+ <div class="xmlConf"><property name="PropertyValue" expression="$func:foo"/>
+<property name="PropertyValue" expression="get-property('foo', 'func')"/></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"><call-template target="string">
+ <!-- parameter values will be passed on to a sequence template -->
+ (
+ <!--passing plain static values -->
+ <with-param name="string" value="string" /> |
+ <!--passing xpath expressions -->
+ <with-param name="string" value="{string}" /> |
+ <!--passing dynamic xpath expressions where values will be compiled dynamically-->
+ <with-param name="string" value="{{string}}" /> |
+ ) *
+</call-template></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"><template name="ep_template">
+ <parameter name="codes"/>
+ <parameter name="factor"/>
+ <parameter name="retries"/>
+ <endpoint name="$name">
+ <default>
+ <suspendOnFailure>
+ <errorCodes>$codes</errorCodes>
+ <progressionFactor>$factor</progressionFactor>
+ </suspendOnFailure>
+ <markForSuspension>
+ <retriesBeforeSuspension>$retries</retriesBeforeSuspension>
+ <retryDelay>0</retryDelay>
+ </markForSuspension>
+ </default>
+ </endpoint>
+</template></div>
+ <p>
+ The syntax outline of a endpoint template definition is given below.
+ </p>
+
+ <div class="xmlConf"><template name="string">
+ <!-- parameters this endpoint template will be supporting -->
+ (
+ <parameter name="string"/>
+ ) *
+ <!--this is the in-line endpoint of the template -->
+ <endpoint [name="string"] >
+ address-endpoint | default-endpoint | wsdl-endpoint |
+ load-balanced-endpoint | fail-over-endpoint | recipient-list-endpoint
+ </endpoint>
+</template></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
[... 208 lines stripped ...]