Added: synapse/site/3_0_2/userguide/config.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/config.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/config.html (added) +++ synapse/site/3_0_2/userguide/config.html Fri May 12 16:09:34 2023 @@ -0,0 +1,2099 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-04 + | Rendered using Apache Maven Fluido Skin 1.6 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="Date-Revision-yyyymmdd" content="20230504" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse – Apache Synapse - Configuration Language Guide</title> + <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> + <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> + </head> + <body class="topBarDisabled"> + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"><div id="bannerLeft"><h2>Apache Synapse</h2> +</div> +</div> + <div class="pull-right"></div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + <li id="publishDate">Last Published: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</li> + </ul> + </div> + <div class="row-fluid"> + <div id="leftColumn" class="span2"> + <div class="well sidebar-nav"> +<ul class="nav nav-list"> + <li class="nav-header">Main Menu</li> + <li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li> + <li><a href="../download.html" title="Download"><span class="none"></span>Download</a> </li> + <li><a href="../history.html" title="History"><span class="none"></span>History</a> </li> + <li><a href="http://www.apache.org/licenses/LICENSE-2.0"; class="externalLink" title="License"><span class="none"></span>License</a> </li> + <li><a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> + <li><a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> + <li><a href="http://www.apache.org/security/"; class="externalLink" title="Security"><span class="none"></span>Security</a> </li> + <li class="nav-header">Documentation</li> + <li><a href="../userguide/installation.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> + <li><a href="../userguide/quick_start.html" title="Quick Start Guide"><span class="none"></span>Quick Start Guide</a> </li> + <li><a href="../userguide/samples/setup/index.html" title="Samples Setup Guide"><span class="none"></span>Samples Setup Guide</a> </li> + <li><a href="../userguide/samples.html" title="Samples Catalog"><span class="none"></span>Samples Catalog</a> </li> + <li class="active"><a href="#"><span class="none"></span>Configuration Language</a> + </li> + <li><a href="../userguide/mediators.html" title="Mediators Catalog"><span class="none"></span>Mediators Catalog</a> </li> + <li><a href="../userguide/transports.html" title="Transports Catalog"><span class="none"></span>Transports Catalog</a> </li> + <li><a href="../userguide/properties.html" title="Properties Catalog"><span class="none"></span>Properties Catalog</a> </li> + <li><a href="../userguide/xpath.html" title="XPath functions and Variables"><span class="none"></span>XPath functions and Variables</a> </li> + <li><a href="../userguide/extending.html" title="Extending Synapse"><span class="none"></span>Extending Synapse</a> </li> + <li><a href="../userguide/template_library.html" title="Synapse Template Libraries"><span class="none"></span>Synapse Template Libraries</a> </li> + <li><a href="../userguide/upgrading.html" title="Upgrading"><span class="none"></span>Upgrading</a> </li> + <li><a href="../userguide/deployment.html" title="Deployment"><span class="none"></span>Deployment</a> </li> + <li><a href="../apidocs/" title="Javadocs"><span class="none"></span>Javadocs</a> </li> + <li><a href="../userguide/faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> + <li class="nav-header">Developer Resources</li> + <li><a href="../dev/developer-guide.html" title="Developer Guide"><span class="none"></span>Developer Guide</a> </li> + <li><a href="../dev/best-practices.html" title="Development Best Practices"><span class="none"></span>Development Best Practices</a> </li> + <li><a href="../dev/release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> + <li class="nav-header">Project Details</li> + <li><a href="../project-info.html" title="Overview"><span class="none"></span>Overview</a> </li> + <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> + <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a> </li> + <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> + <li><a href="../dependency-management.html" title="Dependencies"><span class="none"></span>Dependencies</a> </li> + <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> + </ul> + <hr /> + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> + </div> + </div> + </div> + <div id="bodyColumn" class="span10" > + + + <a name="Intro"></a> +<div class="section" id="Intro"> +<h2><a name="Introduction"></a>Introduction</h2> + +<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> + </div> + +<div class="section"> +<h2><a name="Contents"></a>Contents</h2> + +<ul> + +<li> + <a href="#SynapseConfig">Synapse Configuration</a> + +<ul> + +<li><a href="#ServiceMediation">Service Mediation (Proxy Services)</a></li> + +<li><a href="#MessageMediation">Message Mediation</a></li> + +<li><a href="#TaskScheduling">Task Scheduling</a></li> + +<li><a href="#Eventing">Eventing</a></li> + </ul> + </li> + +<li> + <a href="#Overview">Functional Components Overview</a> + +<ul> + +<li><a href="#MediatorsAndSequences">Mediators and Sequences</a></li> + +<li><a href="#Endpoints">Endpoints</a></li> + +<li><a href="#ProxyServices">Proxy Services</a></li> + +<li><a href="#ScheduledTasks">Scheduled Tasks</a></li> + +<li><a href="#Templates">Templates</a></li> + +<li><a href="#Registry">Remote Registry and Local Registry</a></li> + +<li><a href="#API">APIs</a></li> + +<li><a href="#PriorityExecutors">Priority Executors</a></li> + +<li><a href="#Stores">Message Stores and Processors</a></li> + </ul> + </li> + +<li><a href="#ConfigFiles">Synapse Configuration Files</a></li> + +<li><a href="#Syntax">Configuration Syntax</a></li> + +<li><a href="#RegistryConfig">Registry Configuration</a></li> + +<li><a href="#LocalEntryConfig">Local Entry (Local Registry) Configuration</a></li> + +<li><a href="#SequenceConfig">Sequence Configuration</a></li> + +<li> + <a href="#EndpointConfig">Endpoint Configuration</a> + +<ul> + +<li><a href="#AddressEndpointConfig">Address Endpoint</a></li> + +<li><a href="#DefaultEndpointConfig">Default Endpoint</a></li> + +<li><a href="#WSDLEndpointConfig">WSDL Endpoint</a></li> + +<li><a href="#LBEndpointConfig">Load Balance Endpoint</a></li> + +<li><a href="#DLBEndpointConfig">Dynamic Load Balance Endpoint</a></li> + +<li><a href="#FOEndpointConfig">Fail-Over Endpoint</a></li> + +<li><a href="#RecipientListEndpointConfig">Recipient List Endpoint"</a></li> + </ul> + </li> + +<li><a href="#ProxyServiceConfig">Proxy Service Configuration</a></li> + +<li><a href="#TaskConfig">Scheduled Task Configuration</a></li> + +<li><a href="#TemplateConfig">Template Configuration</a></li> + +<li><a href="#EventSourceConfig">Event Source Configuration</a></li> + +<li><a href="#APIConfig">API Configuration</a></li> + +<li><a href="#ExecutorConfig">Priority Executor Configuration</a></li> + +<li><a href="#StoresConfig">Message Stores and Processors Configuration</a></li> + </ul> + </div> + <a name="SynapseConfig"></a> +<div class="section" id="SynapseConfig"> +<h2><a name="The_Synapse_Configuration"></a>The Synapse Configuration</h2> + +<p> + A typical Synapse configuration is comprised of sequences, endpoints, proxy services + and local entries. In certain advanced scenarios, Synapse configuration may also + contain scheduled tasks, event sources, messages stores and priority executors. + Synapse configuration may also include a registry adapter through which the mediation + engine can import various resources to the mediation engine at runtime. Following + diagram illustrates different functional components of Synapse and how they interact + with each other. + </p> + <img src="../images/synapse-flow.png" alt="" /> + +<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 class="externalLink" 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> + <a name="ServiceMediation"></a> +<div class="section" id="ServiceMediation"> +<h3><a name="Service_Mediation_Proxy_Services"></a>Service Mediation (Proxy Services)</h3> + +<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> + </div> + <a name="MessageMediation"></a> +<div class="section" id="MessageMediation"> +<h3><a name="Message_Mediation"></a>Message Mediation</h3> + +<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> + </div> + <a name="TaskScheduling"></a> +<div class="section" id="TaskScheduling"> +<h3><a name="Task_Scheduling"></a>Task Scheduling</h3> + +<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> + </div> + <a name="Eventing"></a> +<div class="section" id="Eventing"> +<h3><a name="Eventing"></a>Eventing</h3> + +<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> + </div> + </div> + <a name="Overview"></a> +<div class="section" id="Overview"> +<h2><a name="Functional_Components_Overview"></a>Functional Components Overview</h2> + +<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> + </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> + + <a name="MediatorsAndSequences"></a> +<div class="section" id="MediatorsAndSequences"> +<h3><a name="Mediators_and_Sequences"></a>Mediators and Sequences</h3> + +<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> + </div> + <a name="Endpoints"></a> +<div class="section" id="Endpoints"> +<h3><a name="Endpoints"></a>Endpoints</h3> + +<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> + </div> + <a name="ProxyServices"></a> +<div class="section" id="ProxyServices"> +<h3><a name="Proxy_Services"></a>Proxy Services</h3> + +<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> + </div> + <a name="ScheduledTasks"></a> +<div class="section" id="ScheduledTasks"> +<h3><a name="Scheduled_Tasks"></a>Scheduled Tasks</h3> + +<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> + </div> + <a name="Templates"></a> +<div class="section" id="Templates"> +<h3><a name="Templates"></a>Templates</h3> + +<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> + </div> + <a name="Registry"></a> +<div class="section" id="Registry"> +<h3><a name="Remote_Registry_and_Local_Registry_Local_Entries"></a>Remote Registry and Local Registry (Local Entries)</h3> + +<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> + </div> + <a name="API"></a> +<div class="section" id="API"> +<h3><a name="APIs"></a>APIs</h3> + +<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> + </div> + <a name="PriorityExecutors"></a> +<div class="section" id="PriorityExecutors"> +<h3><a name="Priority_Executors"></a>Priority Executors</h3> + +<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> + </div> + <a name="Stores"></a> +<div class="section" id="Stores"> +<h3><a name="Message_Stores_and_Processors"></a>Message Stores and Processors</h3> + +<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> + </div> + </div> + <a name="ConfigFiles"></a> +<div class="section" id="ConfigFiles"> +<h2><a name="Synapse_Configuration_Files"></a>Synapse Configuration Files</h2> + +<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> + </div> + <a name="Syntax"></a> +<div class="section" id="Syntax"> +<h2><a name="Configuration_Syntax"></a>Configuration Syntax</h2> + +<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 <b>http://ws.apache.org/ns/synapse</b>. + </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="#StoresConfig">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> + </div> + <a name="RegistryConfig"></a> +<div class="section" id="RegistryConfig"> +<h2><a name="Registry_Configuration"></a>Registry Configuration</h2> + +<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> + </div> + <a name="LocalEntryConfig"></a> +<div class="section" id="LocalEntryConfig"> +<h2><a name="Local_Entry_Local_Registry_Configuration"></a>Local Entry (Local Registry) Configuration</h2> + +<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> + </div> + <a name="SequenceConfig"></a> +<div class="section" id="SequenceConfig"> +<h2><a name="Sequence_Configuration"></a>Sequence Configuration</h2> + +<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> + </div> + <a name="EndpointConfig"></a> +<div class="section" id="EndpointConfig"> +<h2><a name="Endpoint_Configuration"></a>Endpoint Configuration</h2> + +<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> + <a name="AddressEndpointConfig"></a> +<div class="section" id="AddressEndpointConfig"> +<h3><a name="Address_Endpoint"></a>Address Endpoint</h3> + +<div class="xmlConf"><address uri="<i>endpoint address</i>" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] + [encoding="<i>charset encoding</i>"] + [statistics="enable|disable"] [trace="enable|disable"]> + <enableSec [policy="<i>key</i>"]/>? + <enableAddressing [version="final|submission"] [separateListener="true|false"]/>? + + <timeout> + <duration><i>timeout duration in milliseconds</i></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. Security + policies for the endpoint can be specified in the policy attribute of the + 'enableSec' element. 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 class="table table-striped" border="1"> + <tbody> + +<tr class="a"> +<th>Transport</th> +<th>Sample address</th></tr> + +<tr class="b"> +<td>HTTP</td> +<td><tt>http://localhost:9000/services/SimpleStockQuoteService</tt></td></tr> + +<tr class="a"> +<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 class="b"> +<td>Mail</td> +<td><tt>mailto:guest@host</tt></td></tr> + +<tr class="a"> +<td>VFS</td> +<td><tt>vfs:file:///home/user/directory</tt></td></tr> + +<tr class="b"> +<td></td> +<td><tt>vfs:file:///home/user/file</tt></td></tr> + +<tr class="a"> +<td></td> +<td><tt>vfs:ftp://guest:guest@localhost/directory?vfs.passive=true</tt></td></tr> + </tbody> + </table> + </div> + <a name="DefaultEndpointConfig"></a> +<div class="section" id="DefaultEndpointConfig"> +<h3><a name="Default_Endpoint"></a>Default Endpoint</h3> + +<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, and 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="<i>charset encoding</i>"] + [statistics="enable|disable"] [trace="enable|disable"]> + <enableSec [policy="<i>key</i>"]/>? + <enableAddressing [version="final|submission"] [separateListener="true|false"]/>? + + <timeout> + <duration><i>timeout duration in milliseconds</i></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> + </div> + <a name="WSDLEndpointConfig"></a> +<div class="section" id="WSDLEndpointConfig"> +<h3><a name="WSDL_Endpoint"></a>WSDL Endpoint</h3> + +<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 '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>? + <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> + </div> + <a name="LBEndpointConfig"></a> +<div class="section" id="LBEndpointConfig"> +<h3><a name="Load_Balance_Endpoint"></a>Load Balance Endpoint</h3> + +<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> + </div> + <a name="DLBEndpointConfig"></a> +<div class="section" id="DLBEndpointConfig"> +<h3><a name="Dynamic_Load_Balance_Endpoint"></a>Dynamic Load Balance Endpoint</h3> + +<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> + </div> + <a name="FOEndpointConfig"></a> +<div class="section" id="FOEndpointConfig"> +<h3><a name="Fail-Over_Endpoint"></a>Fail-Over Endpoint</h3> + +<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> + + </div> + <a name="RecipientListEndpointConfig"></a> +<div class="section" id="RecipientListEndpointConfig"> +<h3><a name="Recipient_List_Endpoint"></a>Recipient List Endpoint</h3> + +<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> + </div> + </div> + <a name="ProxyServiceConfig"></a> +<div class="section" id="ProxyServiceConfig"> +<h2><a name="Proxy_Service_Configuration"></a>Proxy Service Configuration</h2> + +<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/>? + <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', 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 class="a"> + +<th> + Parameter + </th> + +<th> + Value + </th> + +<th> + Default + </th> + +<th> + Description + </th> + </tr> + +<tr class="b"> + +<td> + useOriginalwsdl + </td> + +<td> + true|false + </td> + +<td> + false + </td> + +<td> + Use the given WSDL instead of generating the WSDL. + </td> + </tr> + +<tr class="a"> + +<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 class="b"> + +<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 class="a"> + +<th> + Transport + </th> + +<th> + Require + </th> + +<th> + Parameter + </th> + +<th> + Description + </th> + </tr> + +<tr class="b"> + +<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 class="a"> + +<td></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 class="b"> + +<td></td> + +<td> + Optional + </td> + +<td> + transport.jms.DestinationType + </td> + +<td> + The JMS destination type. Accept values 'queue' or 'topic' (default: + queue) + </td> + </tr> + +<tr class="a"> + +<td></td> + +<td> + Optional + </td> + +<td> + transport.jms.ReplyDestination + </td> + +<td> + The destination where a reply will be posted + </td> + </tr> + +<tr class="b"> + +<td></td> + +<td> + Optional + </td> + +<td> + transport.jms.Wrapper + </td> + +<td> + The wrapper element for the JMS message + </td> + </tr> + </tbody> + </table> + </div> + <a name="TaskConfig"></a> +<div class="section" id="TaskConfig"> +<h2><a name="Scheduled_Task_Configuration"></a>Scheduled Task Configuration</h2> + +<p>
[... 445 lines stripped ...]
