<?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 - Sample 600</title>
    </properties>
    <body>
        <section name="Sample 600: File Hierarchy Based Configuration Builder">
            <p>
                In this sample we will be looking at how Synapse configuration files can be
                organized into a single rooted file hierarchy. We will be using the following set
                of files and directories.
            </p>
            <div class="consoleOutput">synapse_sample_600.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</div>
            <subsection name="Objective">
                <p>
                    Demonstrate the ability to load the Synapse configuration from a file hierarchy
                </p>
            </subsection>
            <subsection name="Pre-requisites">
                <p>
                    <ul>
                        <li>
                            Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
                        </li>
                        <li>
                            Start Synapse using the configuration numbered 600 (this is available
                            in the directory at repository/conf/sample/synapse_sample_600.xml)
                            <div class="command">
                                Unix/Linux: sh synapse.sh -sample 600<br/>
                                Windows: synapse.bat -sample 600
                            </div>
                        </li>
                    </ul>
                </p>
            </subsection>
            <subsection name="Description">
                <p>
                    Go to the SYNAPSE_HOME/repository/conf/sample directory and locate the subdirectory
                    named synapse_sample_600.xml within it. When Synapse is started with the sample
                    configuration 600, Synapse 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.
                </p>
                <p>
                    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.
                </p>
                <p>
                    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.
                </p>
                <p>
                    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.
                </p>
                <div class="consoleOutput">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_600.xml</div>
                <p>
                    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.
                </p>
            </subsection>
        </section>
        <p><a href="../samples.html">Back to Catalog</a></p>
    </body>
</document>