Sample 650: File Hierarchy-Based Configuration Builder

Note that WSO2 EI is shipped with the following changes to what is mentioned in this documentation:

<PRODUCT_HOME>/repository/samples/ directory that includes all Integration profile samples is changed to <EI_HOME>/samples/service-bus/.
<PRODUCT_HOME>/repository/samples/resources/ directory that includes all artifacts related to the Integration profile samples is changed to <EI_HOME>/samples/service-bus/resources/.

Objective: Demonstrate the ability to construct the Synapse configuration from a file hierarchy.

      synapse_sample_650.xml
         |-- endpoints
         |   `-- foo.xml
         |-- events
         |   `-- event1.xml
         |-- local-entries
         |   `-- bar.xml
         |-- proxy-services
         |   |-- proxy1.xml
         |   |-- proxy2.xml
         |   `-- proxy3.xml
         |-- registry.xml
         |-- sequences
         |   |-- custom-logger.xml
         |   |-- fault.xml
         |   `-- main.xml
         |-- synapse.xml
         `-- tasks
             `-- task1.xml

Prerequisites:

Deploy the SimpleStockQuoteService in sample Axis2 server and start it on port 9000.
Start ESB with the sample configuration 650 (i.e. wso2esb-samples.sh -sn 650).

Go to the repository/samples directory and locate the subdirectory named synapse_sample_650.xml within it. When ESB is started with the sample configuration 650, ESB will load the configuration from this directory. You will find a number of subdirectories and a set of XML files in each of those directories. Synapse will parse all the XML files in this file hierarchy and construct the full Synapse configuration at startup. As a result when this sample is executed Synapse will start with four proxy services, several sequences, a task, an event source and some endpoint and local entry definitions.

The names of the subdirectories (eg: proxy-services, sequences, endpoints) are fixed and hence cannot be changed. Also the registry definition should go into a file named registry.xml which resides at the top level of the file hierarchy. It can also be specified in the synapse.xml file at top level. This synapse.xml file can include any item that can be normally defined in a synapse.xml file. The files which define proxy services, sequences, endpoints etc can have any name. These configuration files must have the .xml extension at the end of the name. Synapse will ignore any files which do not have the .xml extension.

None of the directories and files in the sample file hierachy are mandatory. You can leave entire directories out if you do not need them. For example if your configuration does not contain any proxy services you can leave the subdirectory named proxy-services out.

To use this feature you should simply pass a path to an existing directory when starting the Synapse server. The SynapseServer class which is responsible for starting the server accepts a file path as an argument from where to load the configuration. Generally we pass the path to the synapse.xml file as the value of this argument. If you pass a directory path instead, Synapse configuration will be loaded from the specified directory. Note the following line on the console when Synapse is loading the configuration from a file hierarchy.

2009-08-04 14:14:42,489 [-] [main] INFO SynapseConfigurationBuilder Loaded Synapse configuration from the directory hierarchy at : /home/synapse/repository/conf/sample/synapse_sample_650.xml

This feature comes in handy when managing large Synapse configurations. It is easier to maintain a well structured file hierarchy than managing one large flat XML file.