<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  ~  Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. 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.
  -->

<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
    <title>
      WSO2 EI - Extending
    </title>
    <link href="css/EI-docs.css" rel="stylesheet"/>
    <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>

  </head>
  <body>
      [ <a href="docs_index.html"> Documentation Index </a> ]
    <h1>
      Extending WSO2 Enterprise Integrator (EI)
    </h1>
    <p>
      This document explains how to write custom mediator implementations and
      custom configuration implementations for mediators by extending Apache
      Synapse through WSO2 EI. It also provides guidelines on how to configure
      these mediators.
    </p>
    <h2>Contents</h2>
    <div class="toc">
      <ul>
        <li>
          <a href="#Writing">Writing Custom Mediator Implementations</a>
          <ul>
            <li>
              <a href="#MessageCon">MessageContext Interface</a>
            </li>
            <li>
              <a href="#Mediator">Mediator Interface</a>
            </li>
          </ul>
          <ul>
            <li>
              <a href="#Leaf">Leaf and Node Mediators, List Mediators and
              Filter Mediators</a>
              <ul>
                <li>
                  <a href="#ListMediat">The ListMediator Interface</a>
                </li>
                <li>
                  <a href="#FilterMedi">FilterMediator Interface</a>
                </li>
              </ul>
            </li>
          </ul>
        </li>
        <li>
          <a href="#Writing1">Writing Custom Configuration Implementations
          for Mediators</a>
          <ul>
            <li>
              <a href="#MediatorFa">The MediatorFactory Interface</a>
            </li>
            <li>
              <a href="#MediatorSe">The MediatorSerializer Interface</a>
            </li>
          </ul>
        </li>
        <li>
          <a href="#Configurin">Configuring Mediators</a>
          <ul>
            <li>
              <a href="#Loading">Loading of Extensions by the Synapse Runtime</a>
            </li>
          </ul>
        </li>
	<li>
          <a href="#synXpathExtensions">Xpath Extension Framework</a>
          <ul>
            <li> <a href="#synXpathExtensions_1">Implementing HELLO_WORLD custom xpath variable</a>
            </li>
          </ul>
	  <ul>
            <li> <a href="#synXpathExtensions_2">Implementing hello-world() custom xpath function</a>
            </li>
          </ul>
          <ul>
            <li><a href="#synXpathExtensions_3">Registering Extensions</a>
            </li>
          </ul>
        </li>
      </ul>
    </div>
    <h2 id="Writing">
      Writing Custom Mediator Implementations
    </h2>
    <p>
      The primary interface of the Synapse API is the MessageContext interface
      defined below. This essentially defines the per-message context passed
      through the chain of mediators, for each and every message received and
      processed by Synapse. Each message instance is wrapped within a
      MessageContext instance, and the message context is set with the
      references to the SynapseConfiguration and SynapseEnvironments. The
      SynapseConfiguration holds the global configuration model that defines
      mediation rules, local registry entries and other configuration, while
      the environment gives access to the underlying SOAP implementation used -
      Apache Axis2. A typical mediator would need to manipulate the
      MessageContext by referring to the SynapseConfiguration. However, it is
      strongly recommended that the SynapseConfiguration is not updated by
      mediator instances as it is shared by all messages, and may be updated by
      Synapse administration or configuration modules. Mediator instances may
      store local message properties into the MessageContext for later retrieval
      by successive mediators. Extending the AbstractMediator class is the
      easiest way to write a new mediator, than implementing the Mediator
      interface.
    </p>
    <h4><a id="MessageCon"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/MessageContext.java?view=markup">MessageContext
      Interface</a>
    </h4>
    <p/>
<pre xml:space="preserve">package org.apache.synapse;

import ...

public interface MessageContext {

    /**
     * Get a reference to the current SynapseConfiguration
     *
     * @return the current synapse configuration
     */
    public SynapseConfiguration getConfiguration();

    /**
     * Set or replace the Synapse Configuration instance to be used. May be used to
     * programmatically change the configuration at runtime etc.
     *
     * @param cfg The new synapse configuration instance
     */
    public void setConfiguration(SynapseConfiguration cfg);

    /**
     * Returns a reference to the host Synapse Environment
     * @return the Synapse Environment
     */
    public SynapseEnvironment getEnvironment();

    /**
     * Sets the SynapseEnvironment reference to this context
     * @param se the reference to the Synapse Environment
     */
    public void setEnvironment(SynapseEnvironment se);

    /**
     * Get the value of a custom (local) property set on the message instance
     * @param key key to look up property
     * @return value for the given key
     */
    public Object getProperty(String key);

    /**
     * Set a custom (local) property with the given name on the message instance
     * @param key key to be used
     * @param value value to be saved
     */
    public void setProperty(String key, Object value);

    /**
     * Returns the Set of keys over the properties on this message context
     * @return a Set of keys over message properties
     */
    public Set getPropertyKeySet();

    /**
     * Get the SOAP envelope of this message
     * @return the SOAP envelope of the message
     */
    public SOAPEnvelope getEnvelope();

    /**
     * Sets the given envelope as the current SOAPEnvelope for this message
     * @param envelope the envelope to be set
     * @throws org.apache.axis2.AxisFault on exception
     */
    public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;

    /**
     * SOAP message related getters and setters
     */
    public ....get/set()...

}</pre>
    <p>
      The MessageContext interface is based on the Axis2 <a>MessageContext</a>
      interface, and it uses the Axis2 <a>EndpointReference</a> and
      SOAPEnvelope classes/interfaces. The purpose of this interface is to
      capture a message as it flows through the system. As you will see the
      message payload is represented using the SOAP infoset. Binary messages can
      be embedded in the Envelope using MTOM (SOAP Message Transmission
      Optimization Mechanism) or SwA (SOAP with Attachments) using the AXIOM
      (AXis Object Model) object model.
    </p>
    <h4><a id="Mediator"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/Mediator.java?view=markup">Mediator
      Interface</a>
    </h4>
    <p>
      The second key interface for mediator writers is the Mediator interface:
    </p>
<pre xml:space="preserve">package org.apache.synapse;

import org.apache.synapse.MessageContext;

/**
 * All Synapse mediators must implement this Mediator interface. As a message passes
 * through the synapse system, each mediator's mediate() method is invoked in the
 * sequence/order defined in the SynapseConfiguration.
 */
public interface <span style="font-weight: bold;">Mediator </span>{

    /**
     * Invokes the mediator passing the current message for mediation. Each
     * mediator performs its mediation action, and returns true if mediation
     * should continue, or false if further mediation should be aborted.
     *
     * @param synCtx the current message for mediation
     * @return true if further mediation should continue
     */
    public boolean mediate(MessageContext synCtx);

    /**
     * This is used for debugging purposes and exposes the type of the current
     * mediator for logging and debugging purposes
     * @return a String representation of the mediator type
     */
    public String getType();

    /**
     * This is used to check whether the tracing should be enabled on the current mediator or not
     * @return value that indicate whether tracing is on, off or unset
     */
    public int getTraceState();

    /**
     * This is used to set the value of tracing enable variable
     * @param traceState Set whether the tracing is enabled or not
     */
    public void setTraceState(int traceState);
}</pre>
    <p>
      A mediator can read and/or modify the <a>SynapseMessage</a> in
      any suitable manner - adjusting the routing headers or changing the
      message body. If the mediate() method returns false, it signals to the
      Synapse processing model to stop further processing of the message. For
      example, if the mediator is a security agent it may decide that this
      message is dangerous and should not be processed further. This is
      generally the exception as mediators are usually designed to co-operate to
      process the message onwards.
    </p>
    <h3 id="Leaf">
      Leaf and Node Mediators, List Mediators and Filter Mediators
    </h3>
    <p>
      Mediators may be Node mediators (i.e. these that can contain child
      mediators) or Leaf mediators (mediators that does not hold any other child
      mediators). A Node mediator must implement the
      org.apache.synapse.api.ListMediator interface listed below, or extend from
      the org.apache.synapse.mediators.AbstractListMediator.
    </p>
    <h4><a id="ListMediat"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/ListMediator.java?view=markup">The
      ListMediator Interface</a>
    </h4>
<pre xml:space="preserve">package org.apache.synapse.mediators;

import java.util.List;

/**
* The List mediator executes a given sequence/list of child mediators
*/
public interface ListMediator extends Mediator {
    /**
    * Appends the specified mediator to the end of this mediator's (children) list
    * @param m the mediator to be added
    * @return true (as per the general contract of the Collection.add method)
    */
    public boolean addChild(Mediator m);

    /**
    * Appends all of the mediators in the specified collection to the end of this mediator's (children)
    * list, in the order that they are returned by the specified collection's iterator
    * @param c the list of mediators to be added
    * @return true if this list changed as a result of the call
    */
    public boolean addAll(List c);

    /**
    * Returns the mediator at the specified position
    * @param pos index of mediator to return
    * @return the mediator at the specified position in this list
    */
    public Mediator getChild(int pos);

    /**
    * Removes the first occurrence in this list of the specified mediator
    * @param m mediator to be removed from this list, if present
    * @return true if this list contained the specified mediator
    */
    public boolean removeChild(Mediator m);

    /**
    * Removes the mediator at the specified position in this list
    * @param pos the index of the mediator to remove
    * @return the mediator previously at the specified position
    */
    public Mediator removeChild(int pos);

    /**
    * Return the list of mediators of this List mediator instance
    * @return the child/sub mediator list
    */
    public List getList();
}</pre>
    <p>
      A ListMediator implementation should call super.mediate(synCtx) to process
      its sub mediator sequence. A FilterMediator is a ListMediator which
      executes its sequence of sub mediators on successful outcome of a test
      condition. The Mediator instance which performs filtering should implement
      the FilterMediator interface.
    </p>
    <h4><a id="FilterMedi"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/FilterMediator.java?view=markup">FilterMediator
      Interface</a>
    </h4>
<pre xml:space="preserve">package org.apache.synapse.mediators;

import org.apache.synapse.MessageContext;

/**
 * The filter mediator is a list mediator, which executes the given (sub) list of mediators
 * if the specified condition is satisfied
 *
 * @see FilterMediator#test(org.apache.synapse.MessageContext)
 */
public interface <span style="font-weight: bold;">FilterMediator </span>extends ListMediator {

    /**
     * Should return true if the sub/child mediators should execute. i.e. if the filter
     * condition is satisfied
     * @param synCtx
     * @return true if the configured filter condition evaluates to true
     */
    public boolean test(MessageContext synCtx);
}</pre>
    <h2 id="Writing1">
      Writing Custom Configuration Implementations for Mediators
    </h2>
    <p>
      You may write your own custom configurator for the Mediator implementation
      you write without relying on the Class mediator or Spring extension for
      its initialization. You could thus write a MediatorFactory implementation
      which defines how to digest a custom XML configuration element to be used
      to create and configure the custom mediator instance. A MediatorSerializer
      implementation defines how a configuration should be serialized back into
      an XML configuration. The custom MediatorFactory and MediatorSerializer
      implementations and the mediator class/es must be bundled as a "Synapse-Core" fragment bundle, 
      which exporting these classes (See the description for Extensions below for more
      details and examples) and placed into the EI_HOME/repository/components/dropins
      folder, so that the Synapse runtime could find and load the definition.
    </p>
	<p>
	For eg: Your MANIFEST.MF file will look like;
	</p>
	<pre>
	Bundle-Name: surcharge-stock-quote-mediator
	Created-By: Apache Maven Bundle Plugin
	DynamicImport-Package: *
	Fragment-Host: synapse-core
	Build-Jdk: 1.6.0_20
	Bundle-Version: 1.0.0
	Bnd-LastModified: 1322212580393
	Bundle-ManifestVersion: 2
	Bundle-Description: Tutorial
	Bundle-SymbolicName: surcharge-stock-quote-mediator
	Import-Package: javax.xml.namespace;version="0.0.0",org.apache.axiom.o
	m;resolution:=optional,org.apache.axiom.om.xpath;resolution:=optional
	,org.apache.axiom.soap;resolution:=optional,org.apache.commons.loggin
	g;resolution:=optional,org.apache.synapse;resolution:=optional,org.ap
	ache.synapse.config.xml;resolution:=optional,org.apache.synapse.media
	tors;resolution:=optional,org.jaxen;resolution:=optional,org.wso2.EI
	.tutorial.mediators;resolution:=optional
	</pre>	
    <p>
      Essentially this means that a custom JAR file must bundle your classes
      implementing the Mediator interface, MediatorSerializer and the MediatorFactory
      interfaces. It should also contain two text files named
      "org.apache.synapse.config.xml.MediatorFactory" and
      "org.apache.synapse.config.xml.MediatorSerializer" which will contain the
      fully qualified name(s) of your MediatorFactory and MediatorSerializer
      implementation classes. Any dependencies should be made available through OSGi
      bundles in the same plugins directory.
    </p>
	
	<p><strong>Note:</strong>
	However there is a limitation with this custom mediators. Currently EI supports them as
	fragments of synapse-core, since that custom mediators can not own their Activator classes.
	So,they can not override the information present in the host bundle, which is the synapse-core.
	</p>
	
    <p>
      The MediatorFactory interface listing is given below, which you should
      implement, and its getTagQName() method must define the fully qualified
      element of interest for custom configuration. The Synapse initialization
      will call back to this MediatorFactory instance through the
      createMediator(OMElement elem) method passing in this XML element, so that
      an instance of the mediator could be created utilizing the custom XML
      specification and returned. See the ValidateMediator and the
      ValidateMediatorFactory classes under modules/extensions in the Synapse
      source distribution for examples.
    </p>
    <h4><a id="MediatorFa"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorFactory.java?view=markup">The
      MediatorFactory Interface</a>
    </h4>
<pre xml:space="preserve">package org.apache.synapse.config.xml;

import ...

/**
 * A mediator factory capable of creating an instance of a mediator through a given
 * XML should implement this interface
 */
public interface MediatorFactory {
    /**
     * Creates an instance of the mediator using the OMElement
     * @param elem
     * @return the created mediator
     */
    public Mediator createMediator(OMElement elem);

    /**
     * The QName of this mediator element in the XML config
     * @return QName of the mediator element
     */
    public QName getTagQName();
}</pre>
    <p/>
    <h4><a id="MediatorSe"></a>
      <a
      href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorSerializer.java?view=markup">The
      MediatorSerializer Interface</a>
    </h4>
<pre xml:space="preserve">package org.apache.synapse.config.xml;

import ...

/**
 * Interface which should be implemented by mediator serializers. Does the
 * reverse of the MediatorFactory
 */
public interface MediatorSerializer {

    /**
     * Return the XML representation of this mediator
     * @param m mediator to be serialized
     * @param parent the OMElement to which the serialization should be attached
     * @return the serialized mediator XML
     */
    public OMElement serializeMediator(OMElement parent, Mediator m);

    /**
     * Return the class name of the mediator which can be serialized
     * @return the class name
     */
    public String getMediatorClassName();
}</pre>
    <h2 id="Configurin">
      Configuring Mediators
    </h2>
    <p>
      Mediators could access the Synapse registry to load resources and
      configure the local behaviour. Refer to the Spring mediator and Script
      mediator implementations for examples on how this could be achieved.
    </p>
    <h3 id="Loading">
      Loading of Extensions by the Synapse Runtime
    </h3>
    <p>
      Synapse loads available extensions from the runtime classpath using the <a
      href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider">J2SE
      Service Provider model</a>. This essentially iterates over the
      available JAR files, for a META-INF/services directory within each file,
      and looks for text files with the name
      org.apache.synapse.config.xml.MediatorFactory and org.apache.synapse.config.xml.MediatorSerializer
      which contains a list of fully qualified class name that implement the above interface, listing each
      class in a separate line. For example, the built-in synapse-extensions.jar
      contains the following structure:
    </p>
<pre xml:space="preserve">synapse-extensions.jar
    /META-INF/services
        org.apache.synapse.config.xml.MediatorFactory
        org.apache.synapse.config.xml.MediatorSerializer
    /... the implementation classes as usual...</pre>
 

<h2>Scheduled Tasks</h2>

<p></p>

<p>Task is a one of method to automatically driving the mediation in the EI.
This is an implementation of EI Startup which allowed adding tasks should run
at EI startup. Task is a Startup and it is based on Quartz, an open source job
scheduling system. Task can be used to create simple or complex schedules. A
simple schedule may be a schedule to run a task periodically. A complex
schedule may be a schedule to run at specific time in future. A complex
schedule can be specified using cron expressions.</p>

<p></p>
<pre>&lt;task class="string" name="string" [group="string"] [pinnedServers="(serverName)+"]&gt;
       &lt;property name="string" value="String"/&gt;
       &lt;property name="string"&gt;&lt;somexml&gt;config&lt;/somexml&gt;&lt;/property&gt;
       &lt;trigger ([[count="int"]? interval="int"] | [cron="string"] | [once=(true | false)])/&gt;
&lt;/task&gt;</pre>

<p></p>

<p>A task is created and scheduled to run at specified time intervals or as
specified by the cron expression. The Task class specifies the actual task
implementation class</p>

<p> (which must implement
<strong>org.apache.synapse.task.Task</strong><strong>interface</strong>) to be
executed at the specified interval/s, and name specifies an identifier for the
scheduled task.</p>

<p> In the current EI , there is only one implementation -
<strong>org.apache.synapse.startup.tasks.MessageInjector</strong>.This can be
used to inject messages at EI startup.</p>

<p></p>

<p>Fields in the task class can be set using properties provided as string
literals or as XML fragments. (For example; if the task implementation class
has a field named "version" with a corresponding setter method, the
configuration value which will be assigned to this field before running the
task can be specified using a property with the name 'version')</p>

<p></p>

<p>There are three different trigger mechanisms to schedule tasks. A simple
trigger is specified specifying a 'count' and an 'interval', implying that the
task will run a 'count' number of times at specified intervals. A trigger may
also be specified as a cron trigger using a cron expression. A one-time trigger
is specified using the 'once' attribute as true in the definition and could be
specified as true in which case this task will be executed only once just after
the initialization of EI. You can give a list of Synapse server names where
this task should be started using pinnedServers attribute. Refer to the
explanation of this attribute under proxy services for more information.</p>

<p></p>

<h3>Extending Task</h3>

<p>A custom Task can be developed by writing a custom Java class that
implements the <strong>org.apache.synapse.task.Task interface</strong>. Task
interface is shown bellow.</p>

<p></p>
<pre>package org.apache.synapse.task;

/*** Represents an executable Task*/

public interface Task {

   /*** Execute method will be invoked by the QuartzJOb.
   */
   public void execute();

}</pre>

<h2 id="synXpathExtensions">
            Xpath Extension Framework
        </h2>
        <p>
            WSO2 EI configuration language is a powerful and flexible tool to perform
            authentication, validation, transformation, logging, routing based on the content etc.
            It could be easily extended, with configuration extensions , mediation extensions and
            even expression level extension. An expression is a lowest level particle in the
            synapase configuration. To be precise , unlike static values ,expressions can be used to
            define dynamically extracted values (using xpath) in a  configuration.
            Mediators extensively uses expressions to extract properties from message context.
            Expression is defined under attribute "expression" of a particular configuration. (see
            property/header/iterator mediator ) .Although expressions can be purely xpath , synapse
            allows extensions to define extended expressions as well. These special xpath expressions
            can be two fold , that is ,
        </p>
        <pre xml:space="preserve">
            1.xpath variable expressions
            2.xpath function expressions
        </pre>
        <p>
            this allows us to access xpath variables with "$" . Currently there are several
            predefined synapse xpath variables avaiable.
        </p>
        <pre xml:space="preserve">
            Ie:- $body - message SOAP body
            $header ? message SOAP header
            $ctxt:SOME_PROPERTY ? a property belonging to synapse meessage context scope
            $axis2:SOME_PROPERTY ? a property belonging to axis2 meessage context scope
            $trp:SOME_TRANSPORT_HEADER ? a transport header
        </pre>
        <p>
            Synapse get-property() is an example xpath function expressions. The get-property()
            function allows any XPath expression used in a configuration to lookup information from
            the current message context. Similar to above , It is possible to retrieve properties
            previously set with the property mediator, and/or information from the Synapse or Axis2
            message contexts or transport header using get-property().
        </p>
        <p>
            see synapse documentation for more details on usage of these expressions.
            Xpath extension framework allows users to further extend xpath expressions to
            suite user requirement. More specifically it allows users to define custom xpath
            expressions and custom xpath functions that is required in a specific usecase
            configuration scenario. Let's see how we can do this. We start by writng our HELLO_WORLD
            custom xpath variable and hello-world() custom xpath function.
        </p>
        <h4 id="synXpathExtensions_1">
            Implementing HELLO_WORLD custom xpath variable
        </h4>
        <p>
            Before going into implementation details , let me first define our final objective here.
            What we need to do is to expose an HELLO_WORLD message in xml format to outside , so
            that users would be able to access it using a xpath expression="$HELLOWORLD/...".
            Following is the HELLO_WORLD mesasge we have.
        </p>
        <pre xml:space="preserve">
            &lt;HELLO_WORLD&gt;
            &lt;name&gt;WSO2-EI&lt;/name&gt;
            &lt;version&gt;4.0.0&lt;/version&gt;
            &lt;release_date&gt;20/12/2010&lt;/release_date&gt;
            &lt;/HELLO_WORLD&gt;
        </pre>
        <p>Every custom xpath extension should implement
            org.apache.synapse.util.xpath.ext.SynapseXpathVariableResolver interface to expose a
            custom xpath variable. This interface consists of two methods , #getResolvingQName ,
            #resolve . First interface method is used to indicate the fully qualified
            variable name that this extesion support (in our case it is HELLO_WORLD). Later method
            should contain what ever resolving logic required to give the desired output.(in our
            case it should return HELLO_WORLD element) . Following is the implementation of our
            custom xpath variable HELLO_WORLD,
        </p>
        <pre xml:space="preserve">
            package org.sample;

            import org.apache.axiom.om.OMAbstractFactory;
            import org.apache.axiom.om.OMElement;
            import org.apache.axiom.om.OMFactory;
            import org.apache.synapse.MessageContext;
            import org.apache.synapse.util.xpath.ext.SynapseXpathVariableResolver;

            import javax.xml.namespace.QName;

            public class HelloWorldXpathVariableResolver implements SynapseXpathVariableResolver {

            public static final QName HELLO_WORLD = new QName("HELLO_WORLD");

            public Object resolve(MessageContext messageContext) {
                //create Hello world message
                OMFactory factory = OMAbstractFactory.getOMFactory();
                OMElement helloWorldElement = factory.createOMElement(HELLO_WORLD);

                OMElement nameElement = factory.createOMElement(new QName("name"));
                nameElement.setText("synapse");
                OMElement versionElem = factory.createOMElement(new QName("version"));
                versionElem.setText("3.1.0");
                OMElement releaseDateElem = factory.createOMElement(new QName("release_date"));
                releaseDateElem.setText("12/12/2010");

                helloWorldElement.addChild(nameElement);
                helloWorldElement.addChild(versionElem);
                helloWorldElement.addChild(releaseDateElem);

                return helloWorldElement;
            }

            public QName getResolvingQName() {
                //to support xpath expression="$HELLO_WORLD"
                return HELLO_WORLD;
            }

            }
        </pre>
        <p>
            with implementation in place mediators can refer version , name , release date on
            HELLO_WORLD message using expression="$HELLO_WORLD/version" , etc
        </p>
        <h4 id="synXpathExtensions_2">
            Implementing hello-world() custom xpath function
        </h4>
        <p>
            Having an xpath function extension is easy as implementing an xpath variable extension.
            In this case Extension class should implement
            org.apache.synapse.util.xpath.ext.SynapseXpathFunctionContextProvider . This interface
            also do have methods , #getResolvingQName and #getInitializedExtFunction . First method
            serves the same purpose as in the previous example. However later method should be
            implementated in such a way that this extension should return a custom jaxen function to
            synapse , initialized with synapse message context. It is extension developers
            responsibility to provide a properly initialized xpath function so that it can be
            resolved at runtime. Our sample implementation is shown below
        </p>
        <pre xml:space="preserve">
            package org.sample;

            import org.apache.synapse.MessageContext;
            import org.apache.synapse.util.xpath.ext.SynapseXpathFunctionContextProvider;
            import org.jaxen.Function;
            import javax.xml.namespace.QName;

            public class HelloWorldXpathFunctionProvider implements SynapseXpathFunctionContextProvider {

            public Function getInitializedExtFunction(MessageContext messageContext) {
                CustomHelloWorldFunction helloWorldFunction = new CustomHelloWorldFunction(messageContext);
                return helloWorldFunction;
            }

            public QName getResolvingQName() {
                //letting know synapse new hello-world extension function
                return new QName("hello-world");
            }
            }

        </pre>
        <p>
            Shown bellow is the custom xpath function returned by our xpath function extension. Note
            that this should implement org.jaxen.Function to resolve xpath .
        </p>
        <pre xml:space="preserve">
            package org.sample;

            import org.apache.axiom.om.OMAbstractFactory;
            import org.apache.axiom.om.OMElement;
            import org.apache.axiom.om.OMFactory;
            import org.apache.commons.logging.Log;
            import org.apache.commons.logging.LogFactory;
            import org.apache.synapse.MessageContext;
            import org.apache.synapse.SynapseConstants;
            import org.jaxen.Context;
            import org.jaxen.Function;
            import org.jaxen.FunctionCallException;
            import org.jaxen.function.StringFunction;

            import javax.xml.namespace.QName;
            import java.util.List;


            public class CustomHelloWorldFunction implements Function {
            private MessageContext synCtx;

            private Log log = LogFactory.getLog(CustomHelloWorldFunction.class);
            private static final Log trace = LogFactory.getLog(SynapseConstants.TRACE_LOGGER);

            private String NULL_STRING = "";
            public static final QName HELLO_WORLD = new QName("HELLO_WORLD");
            private OMElement helloWorld;

            public CustomHelloWorldFunction(MessageContext ctxt) {
                this.synCtx = ctxt;
                //create hello world message
                OMFactory factory = OMAbstractFactory.getOMFactory();
                OMElement helloWorldElement = factory.createOMElement(HELLO_WORLD);

                OMElement nameElement = factory.createOMElement(new QName("name"));
                nameElement.setText("synapse");
                OMElement versionElem = factory.createOMElement(new QName("version"));
                versionElem.setText("3.1.0");
                OMElement releaseDateElem = factory.createOMElement(new QName("release_date"));
                releaseDateElem.setText("12/12/2010");

                helloWorldElement.addChild(nameElement);
                helloWorldElement.addChild(versionElem);
                helloWorldElement.addChild(releaseDateElem);
                this.helloWorld = helloWorldElement;
            }

            /**
            * Returns the string value of the hello world message for the corresponding child
            proeprty
            * arguments are hello-world(name | version | release_date)
            *
            * @param context the context at the point in the expression when the function is called
            * @param args arguments of the functions
            * @return The string value of the property
            * @throws org.jaxen.FunctionCallException
            *
            */
            public Object call(Context context, List args) throws FunctionCallException {

                if (synCtx == null) {
                    if (log.isDebugEnabled()) {
                    log.debug("Synapse message context has not been set for the " +
                    "XPath extension function 'synapse:hello-world(arg_name)'");
                    }
                    return null;
                }

                boolean traceOn = synCtx.getTracingState() == SynapseConstants.TRACING_ON;
                boolean traceOrDebugOn = traceOn || log.isDebugEnabled();

                if (args == null || args.size() == 0) {
                    if (traceOrDebugOn) {
                        traceOrDebug(traceOn, "argument key value for lookup is not specified");
                    }
                    return NULL_STRING;
                } else
                {
                    int size = args.size();
                    if (size == 1) {
                        String argument = StringFunction.evaluate(args.get(0), context.getNavigator());
                    if ("name".equals(argument) || "version".equals(argument) ||
                        "release_date".equals(argument)) {
                         return helloWorld.getFirstChildWithName(new QName(argument));
                    }else{
                        return helloWorld;
                    }
                }
                }
                return NULL_STRING;
            }

            private void traceOrDebug(boolean traceOn, String msg) {
                if (traceOn) {
                    trace.info(msg);
                }
                if (log.isDebugEnabled()) {
                    log.debug(msg);
                }
            }

            }
        </pre>
        <p>
            Here we basically select an child element or the whole Hello World message based on the
            aguments. Please refer to org.jaxen.Function for further details on the implementation.
            With this extension in place synapse configuration can refer to a particular element of
            our Hello World message with expression = "hello-world('name')" ,expression =
            "hello-world('version')" , etc
        </p>
        <h4 id="synXpathExtensions_3">
            Registering Extensions
        </h4>
        <p>
            We need one additional step to make all these extensions integrate into Synapse configuration language.
            Registering extensions is done by declaring them in synapse.properties file.
            synapse.properties can be found $SYNAPSE_HOME/repository/conf . Functions should be
            declared under property synapse.xpath.func.extensions while Variables should be under
            synapse.xpath.var.extensions .
        </p>
        <pre xml:space="preserve">
            synapse.xpath.var.extensions=org.sample.HelloWorldXpathVariableResolver
            synapse.xpath.func.extensions=org.sample. HelloWorldXpathFunctionProvider
        </pre>
        <p>
            If multiple function / variable extesnions are needed comma delimited list can be
            declared. WSO2 EI at startup will register all these declared extensions (defined under
            its CLASSPATH) and our HELLO-WORLD xpath extensions will be ready to roll.
        </p>
</body>
</html>
