-
Notifications
You must be signed in to change notification settings - Fork 63
Expand file tree
/
Copy pathconfig.xml
More file actions
1628 lines (1602 loc) · 98.2 KB
/
config.xml
File metadata and controls
1628 lines (1602 loc) · 98.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--
~ Licensed to the Apache Software Foundation (ASF) under one
~ or more contributor license agreements. See the NOTICE file
~ distributed with this work for additional information
~ regarding copyright ownership. The ASF licenses this file
~ to you under the Apache License, Version 2.0 (the
~ "License"); you may not use this file except in compliance
~ with the License. You may obtain a copy of the License at
~
~ http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing,
~ software distributed under the License is distributed on an
~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~ KIND, either express or implied. See the License for the
~ specific language governing permissions and limitations
~ under the License.
-->
<document>
<properties>
<title>Apache Synapse - Configuration Language Guide</title>
</properties>
<body>
<section name="Introduction" id="Intro">
<p>
Apache Synapse loads its configuration from a set of XML files. This enables the
user to easily hand edit the configuration, maintain backups and even include the
entire configuration in a version control system for easier management and control.
For an example one may check-in all Synapse configuration files into a version
control system such as Subversion and easily move the configuration files from
development, through QA, staging and into production.
</p>
<p>
All the configuration files related to Synapse are housed in the repository/conf/synapse-config
directory of the Synapse installation. Synapse is also capable of loading certain
configuration elements (eg: sequences, endpoints) from an external SOA registry.
When using a registry to store fragments of the configuration, some configuration
elements such as endpoints can be updated dynamically while Synapse is executing.
</p>
<p>
This article describes the hierarchy of XML files from which Synapse reads its
configuration. It describes the high level structure of the file set and the XML
syntax used to configure various elements in Synapse.
</p>
</section>
<section name="Contents">
<ul>
<li>
<a href="#SynapseConfig">Synapse Configuration</a>
<ul>
<li><a href="#ServiceMediation">Service Mediation (Proxy Services)</a></li>
<li><a href="#MessageMediation">Message Mediation</a></li>
<li><a href="#TaskScheduling">Task Scheduling</a></li>
<li><a href="#Eventing">Eventing</a></li>
</ul>
</li>
<li>
<a href="#Overview">Functional Components Overview</a>
<ul>
<li><a href="#MediatorsAndSequences">Mediators and Sequences</a></li>
<li><a href="#Endpoints">Endpoints</a></li>
<li><a href="#ProxyServices">Proxy Services</a></li>
<li><a href="#ScheduledTasks">Scheduled Tasks</a></li>
<li><a href="#Templates">Templates</a></li>
<li><a href="#Registry">Remote Registry and Local Registry</a></li>
<li><a href="#API">APIs</a></li>
<li><a href="#PriorityExecutors">Priority Executors</a></li>
<li><a href="#Stores">Message Stores and Processors</a></li>
</ul>
</li>
<li><a href="#ConfigFiles">Synapse Configuration Files</a></li>
<li><a href="#Syntax">Configuration Syntax</a></li>
<li><a href="#RegistryConfig">Registry Configuration</a></li>
<li><a href="#LocalEntryConfig">Local Entry (Local Registry) Configuration</a></li>
<li><a href="#SequenceConfig">Sequence Configuration</a></li>
<li>
<a href="#EndpointConfig">Endpoint Configuration</a>
<ul>
<li><a href="#AddressEndpointConfig">Address Endpoint</a></li>
<li><a href="#DefaultEndpointConfig">Default Endpoint</a></li>
<li><a href="#WSDLEndpointConfig">WSDL Endpoint</a></li>
<li><a href="#LBEndpointConfig">Load Balance Endpoint</a></li>
<li><a href="#DLBEndpointConfig">Dynamic Load Balance Endpoint</a></li>
<li><a href="#FOEndpointConfig">Fail-Over Endpoint</a></li>
<li><a href="#RecipientListEndpointConfig">Recipient List Endpoint"</a></li>
</ul>
</li>
<li><a href="#ProxyServiceConfig">Proxy Service Configuration</a></li>
<li><a href="#TaskConfig">Scheduled Task Configuration</a></li>
<li><a href="#TemplateConfig">Template Configuration</a></li>
<li><a href="#EventSourceConfig">Event Source Configuration</a></li>
<li><a href="#APIConfig">API Configuration</a></li>
<li><a href="#ExecutorConfig">Priority Executor Configuration</a></li>
<li><a href="#StoresConfig">Message Stores and Processors Configuration</a></li>
</ul>
</section>
<section name="The Synapse Configuration" id="SynapseConfig">
<p>
A typical Synapse configuration is comprised of sequences, endpoints, proxy services
and local entries. In certain advanced scenarios, Synapse configuration may also
contain scheduled tasks, event sources, messages stores and priority executors.
Synapse configuration may also include a registry adapter through which the mediation
engine can import various resources to the mediation engine at runtime. Following
diagram illustrates different functional components of Synapse and how they interact
with each other.
</p>
<img src="../images/synapse-flow.png"/>
<p>
All the functional components of the Synapse configuration are configured through
XML files. The Synapse configuration language governs the XML syntax used to define
and configure different types of components. This configuration language is now
available as a <a href="https://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="#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>
</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"]>
<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. 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 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, 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="<em>charset encoding</em>"]
[statistics="enable|disable"] [trace="enable|disable"]>
<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 '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>
</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