<?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 8</title>
    </properties>
    <body>
        <section name="Sample 8: Introduction to Static and Dynamic Registry Resources, and Using XSLT Transformations">
            <div class="xmlConf">&lt;definitions xmlns="http://ws.apache.org/ns/synapse"&gt;

    &lt;!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) --&gt;
    &lt;registry provider="org.apache.synapse.registry.url.SimpleURLRegistry"&gt;
        &lt;!-- the root property of the simple URL registry helps resolve a resource URL as root + key --&gt;
        &lt;parameter name="root"&gt;file:repository/conf/sample/resources/&lt;/parameter&gt;
        &lt;!-- all resources loaded from the URL registry would be cached for this number of milli seconds --&gt;
        &lt;parameter name="cachableDuration"&gt;15000&lt;/parameter&gt;
    &lt;/registry&gt;

    &lt;!-- define the request processing XSLT resource as a static URL source --&gt;
    &lt;localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/&gt;

    &lt;sequence name="main"&gt;
        &lt;in&gt;
            &lt;!-- transform the custom quote request into a standard quote requst expected by the service --&gt;
            &lt;xslt key="xslt-key-req"/&gt;
        &lt;/in&gt;
        &lt;out&gt;
            &lt;!-- transform the standard response back into the custom format the client expects --&gt;
            &lt;!-- the key is looked up in the remote registry and loaded as a 'dynamic' registry resource --&gt;
            &lt;xslt key="transform/transform_back.xslt"/&gt;
        &lt;/out&gt;
        &lt;send/&gt;
    &lt;/sequence&gt;

&lt;/definitions&gt;</div>
            <subsection name="Objective">
                <p>
                    Demonstrating the usage of the XSLT mediator for transforming message content
                    and using local registry and remote registry for storing configuration
                    metadata.
                </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 8 (repository/conf/sample/synapse_sample_8.xml)
                            <div class="command">
                                Unix/Linux: sh synapse.sh -sample 8<br/>
                                Windows: synapse.bat -sample 8
                            </div>
                        </li>
                    </ul>
                </p>
            </subsection>
            <subsection name="Executing the Client">
                <p>
                    This example uses the XSLT mediator to perform transformations, and the xslt
                    transformations are specified as registry resources. The first resource
                    'xslt-key-req' is specified as a 'local' registry entry. Local entries do not
                    place the resource on the registry, but simply make it available to the local
                    configuration. If a local entry is defined with a key that already exists in
                    the remote registry, the local entry will get higher precedence over the remote
                    resource.
                </p>
                <p>
                    In this example you will notice the new 'registry' definition. Synapse comes
                    with a simple URL based registry implementation (SimpleURLRegistry). During
                    initialization of the registry, the SimpleURLRegistry expects to find a property
                    named 'root', which specifies a prefix for the registry keys used later.
                    When the SimpleURLRegistry is used, this root is prefixed to the entry keys to
                    form the complete URL of the resource being looked up. The registry caches a
                    resource once requested, and stores it internally for a specified duration.
                    Once this period expires, it will reload the meta information about the resource
                    and reloads its cached copy if necessary, the next time the resource is requested.
                </p>
                <p>
                    Hence the second XSLT resource key 'transform/transform_back.xslt' concatenated
                    with the 'root' of the SimpleURLRegistry 'file:repository/conf/sample/resources/'
                    forms the complete URL of the resource as
                    'file:repository/conf/sample/resources/transform/transform_back.xslt' and caches
                    its value for a period of 15000 ms. 
                </p>
                <p>
                    Execute the custom quote client as follows and analyze the the Synapse debug
                    log output.
                </p>
                <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote</div>
                <p>
                    The incoming message is transformed into a standard stock quote request by the
                    XSLT mediator. The XSLT mediator uses Xalan-J to perform the transformations.
                    It is possible to configure the underlying transformation engine using properties
                    when necessary. The response from the SimpleStockQuoteService is converted back
                    into the custom format as expected by the client during the out message processing.
                </p>
                <p>
                    During the response processing you could see the SimpleURLRegistry fetching the
                    resource as shown by the log message below.
                </p>
                <div class="consoleOutput">[HttpClientWorker-1] DEBUG SimpleURLRegistry ==&gt; Repository fetch of resource with key : transform/transform_back.xslt</div>
                <p>
                    If you run the client again immediately (i.e within 15 seconds of the first
                    request) you will not see the resource being reloaded by the registry as the
                    cached value would be still valid.
                </p>
                <p>
                    However if you leave the system idle for 15 seconds or more and then retry the
                    same request, you will now notice that the registry notices the cached resource
                    has expired and will reload the meta information about the resource to check if
                    the resource has changed and will require a fresh fetch from the source URL.
                    If the meta data / version number indicates that a reload of the cached resource
                    is not necessary (i.e. unless the resource itself actually changed) the updated
                    meta information is used and the cache lease extended as appropriate.
                </p>
                <div class="consoleOutput">[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
[HttpClientWorker-1] DEBUG AbstractRegistry - Expired version number is same as current version in registry
[HttpClientWorker-1] DEBUG AbstractRegistry - Renew cache lease for another 15s</div>
                <p>
                    Thus the SimpleURLRegistry allows resource to be cached, and updates are detected
                    so that the configuration changes could be reloaded without restarting the
                    Synapse instance.
                </p>
            </subsection>
        </section>
        <p><a href="../samples.html">Back to Catalog</a></p>        
    </body>
</document>