+
+
+
+
diff --git a/config/wso2server.bat b/config/wso2server.bat
new file mode 100644
index 0000000000..3261136e2a
--- /dev/null
+++ b/config/wso2server.bat
@@ -0,0 +1,173 @@
+@echo off
+
+REM ---------------------------------------------------------------------------
+REM Copyright 2005-2009 WSO2, Inc. http://www.wso2.org
+REM
+REM Licensed under the Apache License, Version 2.0 (the "License");
+REM you may not use this file except in compliance with the License.
+REM You may obtain a copy of the License at
+REM
+REM http://www.apache.org/licenses/LICENSE-2.0
+REM
+REM Unless required by applicable law or agreed to in writing, software
+REM distributed under the License is distributed on an "AS IS" BASIS,
+REM WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+REM See the License for the specific language governing permissions and
+REM limitations under the License.
+
+rem ---------------------------------------------------------------------------
+rem Main Script for WSO2 Carbon
+rem
+rem Environment Variable Prequisites
+rem
+rem CARBON_HOME Home of CARBON installation. If not set I will try
+rem to figure it out.
+rem
+rem JAVA_HOME Must point at your Java Development Kit installation.
+rem
+rem JAVA_OPTS (Optional) Java runtime options used when the commands
+rem is executed.
+rem ---------------------------------------------------------------------------
+
+rem ----- if JAVA_HOME is not set we're not happy ------------------------------
+:checkJava
+
+if "%JAVA_HOME%" == "" goto noJavaHome
+if not exist "%JAVA_HOME%\bin\java.exe" goto noJavaHome
+goto checkServer
+
+:noJavaHome
+echo "You must set the JAVA_HOME variable before running CARBON."
+goto end
+
+rem ----- Only set CARBON_HOME if not already set ----------------------------
+:checkServer
+rem %~sdp0 is expanded pathname of the current script under NT with spaces in the path removed
+if "%CARBON_HOME%"=="" set CARBON_HOME=%~sdp0..
+SET curDrive=%cd:~0,1%
+SET wsasDrive=%CARBON_HOME:~0,1%
+if not "%curDrive%" == "%wsasDrive%" %wsasDrive%:
+
+rem find CARBON_HOME if it does not exist due to either an invalid value passed
+rem by the user or the %0 problem on Windows 9x
+if not exist "%CARBON_HOME%\bin\version.txt" goto noServerHome
+
+set AXIS2_HOME=%CARBON_HOME%
+goto updateClasspath
+
+:noServerHome
+echo CARBON_HOME is set incorrectly or CARBON could not be located. Please set CARBON_HOME.
+goto end
+
+rem ----- update classpath -----------------------------------------------------
+:updateClasspath
+
+setlocal EnableDelayedExpansion
+cd %CARBON_HOME%
+set CARBON_CLASSPATH=
+FOR %%C in ("%CARBON_HOME%\bin\*.jar") DO set CARBON_CLASSPATH=!CARBON_CLASSPATH!;".\bin\%%~nC%%~xC"
+
+set CARBON_CLASSPATH="%JAVA_HOME%\lib\tools.jar";%CARBON_CLASSPATH%;
+
+FOR %%D in ("%CARBON_HOME%\lib\commons-lang*.jar") DO set CARBON_CLASSPATH=!CARBON_CLASSPATH!;".\lib\%%~nD%%~xD"
+
+rem ----- Process the input command -------------------------------------------
+
+rem Slurp the command line arguments. This loop allows for an unlimited number
+rem of arguments (up to the command line limit, anyway).
+
+
+:setupArgs
+if ""%1""=="""" goto doneStart
+
+if ""%1""==""-run"" goto commandLifecycle
+if ""%1""==""--run"" goto commandLifecycle
+if ""%1""==""run"" goto commandLifecycle
+
+if ""%1""==""-restart"" goto commandLifecycle
+if ""%1""==""--restart"" goto commandLifecycle
+if ""%1""==""restart"" goto commandLifecycle
+
+if ""%1""==""debug"" goto commandDebug
+if ""%1""==""-debug"" goto commandDebug
+if ""%1""==""--debug"" goto commandDebug
+
+if ""%1""==""version"" goto commandVersion
+if ""%1""==""-version"" goto commandVersion
+if ""%1""==""--version"" goto commandVersion
+
+shift
+goto setupArgs
+
+rem ----- commandVersion -------------------------------------------------------
+:commandVersion
+shift
+type "%CARBON_HOME%\bin\version.txt"
+type "%CARBON_HOME%\bin\wso2carbon-version.txt"
+goto end
+
+rem ----- commandDebug ---------------------------------------------------------
+:commandDebug
+shift
+set DEBUG_PORT=%1
+if "%DEBUG_PORT%"=="" goto noDebugPort
+if not "%JAVA_OPTS%"=="" echo Warning !!!. User specified JAVA_OPTS will be ignored, once you give the --debug option.
+set JAVA_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=%DEBUG_PORT%
+echo Please start the remote debugging client to continue...
+goto findJdk
+
+:noDebugPort
+echo Please specify the debug port after the --debug option
+goto end
+
+rem ----- commandLifecycle -----------------------------------------------------
+:commandLifecycle
+goto findJdk
+
+:doneStart
+if "%OS%"=="Windows_NT" @setlocal
+if "%OS%"=="WINNT" @setlocal
+
+rem ---------- Handle the SSL Issue with proper JDK version --------------------
+rem find the version of the jdk
+:findJdk
+
+set CMD=RUN %*
+
+:checkJdk16
+"%JAVA_HOME%\bin\java" -version 2>&1 | findstr /r "1.[6|7]" >NUL
+IF ERRORLEVEL 1 goto unknownJdk
+goto jdk16
+
+:unknownJdk
+echo Starting WSO2 Carbon (in unsupported JDK)
+echo [ERROR] CARBON is supported only on JDK 1.6 and 1.7
+goto jdk16
+
+:jdk16
+goto runServer
+
+rem ----------------- Execute The Requested Command ----------------------------
+
+:runServer
+cd %CARBON_HOME%
+
+rem ---------- Add jars to classpath ----------------
+
+set CARBON_CLASSPATH=.\lib;%CARBON_CLASSPATH%
+
+set JAVA_ENDORSED=".\lib\endorsed";"%JAVA_HOME%\jre\lib\endorsed";"%JAVA_HOME%\lib\endorsed"
+
+set CMD_LINE_ARGS=-Xbootclasspath/a:%CARBON_XBOOTCLASSPATH% -Xms256m -Xmx1024m -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath="%CARBON_HOME%\repository\logs\heap-dump.hprof" -Dcom.sun.management.jmxremote -classpath %CARBON_CLASSPATH% %JAVA_OPTS% -Djava.endorsed.dirs=%JAVA_ENDORSED% -Dcarbon.registry.root=/ -Dcarbon.home="%CARBON_HOME%" -Dwso2.server.standalone=true -Djava.command="%JAVA_HOME%\bin\java" -Djava.opts="%JAVA_OPTS%" -Djava.io.tmpdir="%CARBON_HOME%\tmp" -Dcatalina.base="%CARBON_HOME%\lib\tomcat" -Dwso2.carbon.xml=%CARBON_HOME%\repository\conf\carbon.xml -Dwso2.registry.xml="%CARBON_HOME%\repository\conf\registry.xml" -Dwso2.user.mgt.xml="%CARBON_HOME%\repository\conf\user-mgt.xml" -Dwso2.transports.xml="%CARBON_HOME%\repository\conf\mgt-transports.xml" -Djava.util.logging.config.file="%CARBON_HOME%\repository\conf\etc\logging-bridge.properties" -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Dcarbon.config.dir.path="%CARBON_HOME%\repository\conf" -Dcarbon.logs.path="%CARBON_HOME%\repository\logs" -Dcomponents.repo="%CARBON_HOME%\repository\components" -Dconf.location="%CARBON_HOME%\repository\conf" -Dcom.atomikos.icatch.file="%CARBON_HOME%\lib\transactions.properties" -Dcom.atomikos.icatch.hide_init_file_path="true" -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dcom.sun.jndi.ldap.connect.pool.authentication=simple -Dcom.sun.jndi.ldap.connect.pool.timeout=3000 -Dorg.terracotta.quartz.skipUpdateCheck=true -Dcarbon.classpath=%CARBON_CLASSPATH% -Dfile.encoding=UTF8 -DapplyPatches
+
+:runJava
+echo JAVA_HOME environment variable is set to %JAVA_HOME%
+echo CARBON_HOME environment variable is set to %CARBON_HOME%
+"%JAVA_HOME%\bin\java" %CMD_LINE_ARGS% org.wso2.carbon.bootstrap.Bootstrap %CMD%
+if "%ERRORLEVEL%"=="121" goto runJava
+:end
+goto endlocal
+
+:endlocal
+
+:END
diff --git a/config/wso2server.sh b/config/wso2server.sh
new file mode 100644
index 0000000000..6aed64025e
--- /dev/null
+++ b/config/wso2server.sh
@@ -0,0 +1,298 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Copyright 2005-2012 WSO2, Inc. http://www.wso2.org
+#
+# Licensed 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.
+
+# ----------------------------------------------------------------------------
+# Main Script for the WSO2 Carbon Server
+#
+# Environment Variable Prequisites
+#
+# CARBON_HOME Home of WSO2 Carbon installation. If not set I will try
+# to figure it out.
+#
+# JAVA_HOME Must point at your Java Development Kit installation.
+#
+# JAVA_OPTS (Optional) Java runtime options used when the commands
+# is executed.
+#
+# NOTE: Borrowed generously from Apache Tomcat startup scripts.
+# -----------------------------------------------------------------------------
+
+# OS specific support. $var _must_ be set to either true or false.
+#ulimit -n 100000
+
+cygwin=false;
+darwin=false;
+os400=false;
+mingw=false;
+case "`uname`" in
+CYGWIN*) cygwin=true;;
+MINGW*) mingw=true;;
+OS400*) os400=true;;
+Darwin*) darwin=true
+ if [ -z "$JAVA_VERSION" ] ; then
+ JAVA_VERSION="CurrentJDK"
+ else
+ echo "Using Java version: $JAVA_VERSION"
+ fi
+ if [ -z "$JAVA_HOME" ] ; then
+ JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/${JAVA_VERSION}/Home
+ fi
+ ;;
+esac
+
+# resolve links - $0 may be a softlink
+PRG="$0"
+
+while [ -h "$PRG" ]; do
+ ls=`ls -ld "$PRG"`
+ link=`expr "$ls" : '.*-> \(.*\)$'`
+ if expr "$link" : '.*/.*' > /dev/null; then
+ PRG="$link"
+ else
+ PRG=`dirname "$PRG"`/"$link"
+ fi
+done
+
+# Get standard environment variables
+PRGDIR=`dirname "$PRG"`
+
+# Only set CARBON_HOME if not already set
+[ -z "$CARBON_HOME" ] && CARBON_HOME=`cd "$PRGDIR/.." ; pwd`
+
+# Set AXIS2_HOME. Needed for One Click JAR Download
+AXIS2_HOME=$CARBON_HOME
+
+# For Cygwin, ensure paths are in UNIX format before anything is touched
+if $cygwin; then
+ [ -n "$JAVA_HOME" ] && JAVA_HOME=`cygpath --unix "$JAVA_HOME"`
+ [ -n "$CARBON_HOME" ] && CARBON_HOME=`cygpath --unix "$CARBON_HOME"`
+ [ -n "$AXIS2_HOME" ] && CARBON_HOME=`cygpath --unix "$CARBON_HOME"`
+fi
+
+# For OS400
+if $os400; then
+ # Set job priority to standard for interactive (interactive - 6) by using
+ # the interactive priority - 6, the helper threads that respond to requests
+ # will be running at the same priority as interactive jobs.
+ COMMAND='chgjob job('$JOBNAME') runpty(6)'
+ system $COMMAND
+
+ # Enable multi threading
+ QIBM_MULTI_THREADED=Y
+ export QIBM_MULTI_THREADED
+fi
+
+# For Migwn, ensure paths are in UNIX format before anything is touched
+if $mingw ; then
+ [ -n "$CARBON_HOME" ] &&
+ CARBON_HOME="`(cd "$CARBON_HOME"; pwd)`"
+ [ -n "$JAVA_HOME" ] &&
+ JAVA_HOME="`(cd "$JAVA_HOME"; pwd)`"
+ [ -n "$AXIS2_HOME" ] &&
+ CARBON_HOME="`(cd "$CARBON_HOME"; pwd)`"
+ # TODO classpath?
+fi
+
+if [ -z "$JAVACMD" ] ; then
+ if [ -n "$JAVA_HOME" ] ; then
+ if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+ # IBM's JDK on AIX uses strange locations for the executables
+ JAVACMD="$JAVA_HOME/jre/sh/java"
+ else
+ JAVACMD="$JAVA_HOME/bin/java"
+ fi
+ else
+ JAVACMD=java
+ fi
+fi
+
+if [ ! -x "$JAVACMD" ] ; then
+ echo "Error: JAVA_HOME is not defined correctly."
+ echo " CARBON cannot execute $JAVACMD"
+ exit 1
+fi
+
+# if JAVA_HOME is not set we're not happy
+if [ -z "$JAVA_HOME" ]; then
+ echo "You must set the JAVA_HOME variable before running CARBON."
+ exit 1
+fi
+
+if [ -e "$CARBON_HOME/wso2carbon.pid" ]; then
+ PID=`cat "$CARBON_HOME"/wso2carbon.pid`
+fi
+
+# ----- Process the input command ----------------------------------------------
+for c in $*
+do
+ if [ "$c" = "--debug" ] || [ "$c" = "-debug" ] || [ "$c" = "debug" ]; then
+ CMD="--debug"
+ continue
+ elif [ "$CMD" = "--debug" ]; then
+ if [ -z "$PORT" ]; then
+ PORT=$c
+ fi
+ elif [ "$c" = "--stop" ] || [ "$c" = "-stop" ] || [ "$c" = "stop" ]; then
+ CMD="stop"
+ elif [ "$c" = "--start" ] || [ "$c" = "-start" ] || [ "$c" = "start" ]; then
+ CMD="start"
+ elif [ "$c" = "--version" ] || [ "$c" = "-version" ] || [ "$c" = "version" ]; then
+ CMD="version"
+ elif [ "$c" = "--restart" ] || [ "$c" = "-restart" ] || [ "$c" = "restart" ]; then
+ CMD="restart"
+ elif [ "$c" = "--test" ] || [ "$c" = "-test" ] || [ "$c" = "test" ]; then
+ CMD="test"
+ fi
+done
+
+if [ "$CMD" = "--debug" ]; then
+ if [ "$PORT" = "" ]; then
+ echo " Please specify the debug port after the --debug option"
+ exit 1
+ fi
+ if [ -n "$JAVA_OPTS" ]; then
+ echo "Warning !!!. User specified JAVA_OPTS will be ignored, once you give the --debug option."
+ fi
+ CMD="RUN"
+ JAVA_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=$PORT"
+ echo "Please start the remote debugging client to continue..."
+elif [ "$CMD" = "start" ]; then
+ if [ -e "$CARBON_HOME/wso2carbon.pid" ]; then
+ if ps -p $PID >&- ; then
+ echo "Process is already running"
+ exit 0
+ fi
+ fi
+ export CARBON_HOME=$CARBON_HOME
+# using nohup bash to avoid erros in solaris OS.TODO
+ nohup bash $CARBON_HOME/bin/wso2server.sh > /dev/null 2>&1 &
+ exit 0
+elif [ "$CMD" = "stop" ]; then
+ export CARBON_HOME=$CARBON_HOME
+ kill -term `cat $CARBON_HOME/wso2carbon.pid`
+ exit 0
+elif [ "$CMD" = "restart" ]; then
+ export CARBON_HOME=$CARBON_HOME
+ kill -term `cat $CARBON_HOME/wso2carbon.pid`
+ process_status=0
+ pid=`cat $CARBON_HOME/wso2carbon.pid`
+ while [ "$process_status" -eq "0" ]
+ do
+ sleep 1;
+ ps -p$pid 2>&1 > /dev/null
+ process_status=$?
+ done
+
+# using nohup bash to avoid erros in solaris OS.TODO
+ nohup bash $CARBON_HOME/bin/wso2server.sh > /dev/null 2>&1 &
+ exit 0
+elif [ "$CMD" = "test" ]; then
+ JAVACMD="exec "$JAVACMD""
+elif [ "$CMD" = "version" ]; then
+ cat $CARBON_HOME/bin/version.txt
+ cat $CARBON_HOME/bin/wso2carbon-version.txt
+ exit 0
+fi
+
+# ---------- Handle the SSL Issue with proper JDK version --------------------
+jdk_16=`$JAVA_HOME/bin/java -version 2>&1 | grep "1.[6|7]"`
+if [ "$jdk_16" = "" ]; then
+ echo " Starting WSO2 Carbon (in unsupported JDK)"
+ echo " [ERROR] CARBON is supported only on JDK 1.6 and 1.7"
+fi
+
+CARBON_XBOOTCLASSPATH=""
+for f in "$CARBON_HOME"/lib/xboot/*.jar
+do
+ if [ "$f" != "$CARBON_HOME/lib/xboot/*.jar" ];then
+ CARBON_XBOOTCLASSPATH="$CARBON_XBOOTCLASSPATH":$f
+ fi
+done
+
+JAVA_ENDORSED_DIRS="$CARBON_HOME/lib/endorsed":"$JAVA_HOME/jre/lib/endorsed":"$JAVA_HOME/lib/endorsed"
+
+CARBON_CLASSPATH=""
+if [ -e "$JAVA_HOME/lib/tools.jar" ]; then
+ CARBON_CLASSPATH="$JAVA_HOME/lib/tools.jar"
+fi
+for f in "$CARBON_HOME"/bin/*.jar
+do
+ if [ "$f" != "$CARBON_HOME/bin/*.jar" ];then
+ CARBON_CLASSPATH="$CARBON_CLASSPATH":$f
+ fi
+done
+for t in "$CARBON_HOME"/lib/commons-lang*.jar
+do
+ CARBON_CLASSPATH="$CARBON_CLASSPATH":$t
+done
+# For Cygwin, switch paths to Windows format before running java
+if $cygwin; then
+ JAVA_HOME=`cygpath --absolute --windows "$JAVA_HOME"`
+ CARBON_HOME=`cygpath --absolute --windows "$CARBON_HOME"`
+ AXIS2_HOME=`cygpath --absolute --windows "$CARBON_HOME"`
+ CLASSPATH=`cygpath --path --windows "$CLASSPATH"`
+ JAVA_ENDORSED_DIRS=`cygpath --path --windows "$JAVA_ENDORSED_DIRS"`
+ CARBON_CLASSPATH=`cygpath --path --windows "$CARBON_CLASSPATH"`
+ CARBON_XBOOTCLASSPATH=`cygpath --path --windows "$CARBON_XBOOTCLASSPATH"`
+fi
+
+# ----- Execute The Requested Command -----------------------------------------
+
+echo JAVA_HOME environment variable is set to $JAVA_HOME
+echo CARBON_HOME environment variable is set to $CARBON_HOME
+
+cd "$CARBON_HOME"
+
+START_EXIT_STATUS=121
+status=$START_EXIT_STATUS
+
+#To monitor a Carbon server in remote JMX mode on linux host machines, set the below system property.
+# -Djava.rmi.server.hostname="your.IP.goes.here"
+
+while [ "$status" = "$START_EXIT_STATUS" ]
+do
+ $JAVACMD \
+ -Xbootclasspath/a:"$CARBON_XBOOTCLASSPATH" \
+ -Xms256m -Xmx1024m -XX:MaxPermSize=256m \
+ -XX:+HeapDumpOnOutOfMemoryError \
+ -XX:HeapDumpPath="$CARBON_HOME/repository/logs/heap-dump.hprof" \
+ $JAVA_OPTS \
+ -Dcom.sun.management.jmxremote \
+ -classpath "$CARBON_CLASSPATH" \
+ -Djava.endorsed.dirs="$JAVA_ENDORSED_DIRS" \
+ -Djava.io.tmpdir="$CARBON_HOME/tmp" \
+ -Dcatalina.base="$CARBON_HOME/lib/tomcat" \
+ -Dwso2.server.standalone=true \
+ -Dcarbon.registry.root=/ \
+ -Djava.command="$JAVACMD" \
+ -Dcarbon.home="$CARBON_HOME" \
+ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \
+ -Djava.util.logging.config.file="$CARBON_HOME/repository/conf/etc/logging-bridge.properties" \
+ -Dcarbon.config.dir.path="$CARBON_HOME/repository/conf" \
+ -Dcomponents.repo="$CARBON_HOME/repository/components/plugins" \
+ -Dconf.location="$CARBON_HOME/repository/conf"\
+ -Dcom.atomikos.icatch.file="$CARBON_HOME/lib/transactions.properties" \
+ -Dcom.atomikos.icatch.hide_init_file_path=true \
+ -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true \
+ -Dcom.sun.jndi.ldap.connect.pool.authentication=simple \
+ -Dcom.sun.jndi.ldap.connect.pool.timeout=3000 \
+ -Dorg.terracotta.quartz.skipUpdateCheck=true \
+ -Djava.security.egd=file:/dev/./urandom \
+ -Dfile.encoding=UTF8 \
+ -DapplyPatches \
+ org.wso2.carbon.bootstrap.Bootstrap $*
+ status=$?
+done
diff --git a/design-docs/data-model/iteration1/1-entities-with-cardinality.jpg b/design-docs/data-model/iteration1/1-entities-with-cardinality.jpg
new file mode 100644
index 0000000000..64afd725df
Binary files /dev/null and b/design-docs/data-model/iteration1/1-entities-with-cardinality.jpg differ
diff --git a/design-docs/data-model/iteration1/2-mapped-to-tree-hierarchy.jpg b/design-docs/data-model/iteration1/2-mapped-to-tree-hierarchy.jpg
new file mode 100644
index 0000000000..0b53204dda
Binary files /dev/null and b/design-docs/data-model/iteration1/2-mapped-to-tree-hierarchy.jpg differ
diff --git a/design-docs/data-model/iteration1/3-consumers_and_APIs.jpg b/design-docs/data-model/iteration1/3-consumers_and_APIs.jpg
new file mode 100644
index 0000000000..b23c3eba5a
Binary files /dev/null and b/design-docs/data-model/iteration1/3-consumers_and_APIs.jpg differ
diff --git a/design-docs/data-model/iteration1/4-storage-for-search-terms.jpg b/design-docs/data-model/iteration1/4-storage-for-search-terms.jpg
new file mode 100644
index 0000000000..719de2cb2c
Binary files /dev/null and b/design-docs/data-model/iteration1/4-storage-for-search-terms.jpg differ
diff --git a/design-docs/data-model/iteration1/5-birds-eye.jpg b/design-docs/data-model/iteration1/5-birds-eye.jpg
new file mode 100644
index 0000000000..16793b56b5
Binary files /dev/null and b/design-docs/data-model/iteration1/5-birds-eye.jpg differ
diff --git a/design-docs/data-model/iteration1/compressed/1-entities-with-cardinality-21-02-2012.jpg b/design-docs/data-model/iteration1/compressed/1-entities-with-cardinality-21-02-2012.jpg
new file mode 100644
index 0000000000..3b7438a13f
Binary files /dev/null and b/design-docs/data-model/iteration1/compressed/1-entities-with-cardinality-21-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration1/compressed/2-mapped-to-tree-hierarchy-21-02-2012.jpg b/design-docs/data-model/iteration1/compressed/2-mapped-to-tree-hierarchy-21-02-2012.jpg
new file mode 100644
index 0000000000..c6ff376de8
Binary files /dev/null and b/design-docs/data-model/iteration1/compressed/2-mapped-to-tree-hierarchy-21-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration1/compressed/3-consumers_and_APIs-21-02-2012.jpg b/design-docs/data-model/iteration1/compressed/3-consumers_and_APIs-21-02-2012.jpg
new file mode 100644
index 0000000000..14a0a3cffb
Binary files /dev/null and b/design-docs/data-model/iteration1/compressed/3-consumers_and_APIs-21-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration1/compressed/4-storage-for-search-terms-21-02-2012.jpg b/design-docs/data-model/iteration1/compressed/4-storage-for-search-terms-21-02-2012.jpg
new file mode 100644
index 0000000000..af7bac3c38
Binary files /dev/null and b/design-docs/data-model/iteration1/compressed/4-storage-for-search-terms-21-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration1/compressed/5-birds-eye-21-02-2012.jpg b/design-docs/data-model/iteration1/compressed/5-birds-eye-21-02-2012.jpg
new file mode 100644
index 0000000000..817e7279cb
Binary files /dev/null and b/design-docs/data-model/iteration1/compressed/5-birds-eye-21-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/1-Tier-22-02-2012.jpg b/design-docs/data-model/iteration2/1-Tier-22-02-2012.jpg
new file mode 100644
index 0000000000..e8b0093770
Binary files /dev/null and b/design-docs/data-model/iteration2/1-Tier-22-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/2-entities-with-cardinality-22-02-2012.jpg b/design-docs/data-model/iteration2/2-entities-with-cardinality-22-02-2012.jpg
new file mode 100644
index 0000000000..a7d5f041ef
Binary files /dev/null and b/design-docs/data-model/iteration2/2-entities-with-cardinality-22-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/3-mapped-to-tree-hierarchy-22-02-2012.jpg b/design-docs/data-model/iteration2/3-mapped-to-tree-hierarchy-22-02-2012.jpg
new file mode 100644
index 0000000000..a8e97cb04e
Binary files /dev/null and b/design-docs/data-model/iteration2/3-mapped-to-tree-hierarchy-22-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/4-Config-Data-Movedout-22-02-2012.jpg b/design-docs/data-model/iteration2/4-Config-Data-Movedout-22-02-2012.jpg
new file mode 100644
index 0000000000..98321ad32d
Binary files /dev/null and b/design-docs/data-model/iteration2/4-Config-Data-Movedout-22-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/5-birds-eye-22-02-2012.jpg b/design-docs/data-model/iteration2/5-birds-eye-22-02-2012.jpg
new file mode 100644
index 0000000000..39e45b658f
Binary files /dev/null and b/design-docs/data-model/iteration2/5-birds-eye-22-02-2012.jpg differ
diff --git a/design-docs/data-model/iteration2/Property_for_Tier.jpg b/design-docs/data-model/iteration2/Property_for_Tier.jpg
new file mode 100644
index 0000000000..26aea9d920
Binary files /dev/null and b/design-docs/data-model/iteration2/Property_for_Tier.jpg differ
diff --git a/design-docs/data-model/iteration3/1-entities-with-cardinality.jpg b/design-docs/data-model/iteration3/1-entities-with-cardinality.jpg
new file mode 100644
index 0000000000..71cc57faaa
Binary files /dev/null and b/design-docs/data-model/iteration3/1-entities-with-cardinality.jpg differ
diff --git a/design-docs/data-model/iteration3/22022012109.jpg b/design-docs/data-model/iteration3/22022012109.jpg
new file mode 100644
index 0000000000..9488dda59b
Binary files /dev/null and b/design-docs/data-model/iteration3/22022012109.jpg differ
diff --git a/design-docs/data-model/iteration3/22022012111.jpg b/design-docs/data-model/iteration3/22022012111.jpg
new file mode 100644
index 0000000000..34e1c76537
Binary files /dev/null and b/design-docs/data-model/iteration3/22022012111.jpg differ
diff --git a/design-docs/data-model/iteration3/22022012113.jpg b/design-docs/data-model/iteration3/22022012113.jpg
new file mode 100644
index 0000000000..c845598cf8
Binary files /dev/null and b/design-docs/data-model/iteration3/22022012113.jpg differ
diff --git a/design-docs/data-model/iteration3/22022012114.jpg b/design-docs/data-model/iteration3/22022012114.jpg
new file mode 100644
index 0000000000..136a3d0217
Binary files /dev/null and b/design-docs/data-model/iteration3/22022012114.jpg differ
diff --git a/design-docs/data-model/iteration3/5-birds-eye.jpg b/design-docs/data-model/iteration3/5-birds-eye.jpg
new file mode 100644
index 0000000000..1bed7aebcb
Binary files /dev/null and b/design-docs/data-model/iteration3/5-birds-eye.jpg differ
diff --git a/design-docs/data-model/iteration3/6-Classification-of-data.jpg b/design-docs/data-model/iteration3/6-Classification-of-data.jpg
new file mode 100644
index 0000000000..6cbc39ca35
Binary files /dev/null and b/design-docs/data-model/iteration3/6-Classification-of-data.jpg differ
diff --git a/design-docs/data-model/iteration4/rdbms_model.dia b/design-docs/data-model/iteration4/rdbms_model.dia
new file mode 100644
index 0000000000..0d36e5b1a5
Binary files /dev/null and b/design-docs/data-model/iteration4/rdbms_model.dia differ
diff --git a/design-docs/data-model/iteration4/rdbms_model.jpg b/design-docs/data-model/iteration4/rdbms_model.jpg
new file mode 100644
index 0000000000..4c6981ca97
Binary files /dev/null and b/design-docs/data-model/iteration4/rdbms_model.jpg differ
diff --git a/design-docs/mockscreens/HomePage.png b/design-docs/mockscreens/HomePage.png
new file mode 100644
index 0000000000..7e0587cc8c
Binary files /dev/null and b/design-docs/mockscreens/HomePage.png differ
diff --git a/design-docs/mockscreens/HomePage.screen b/design-docs/mockscreens/HomePage.screen
new file mode 100644
index 0000000000..9a2ac74552
--- /dev/null
+++ b/design-docs/mockscreens/HomePage.screen
@@ -0,0 +1,139 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/LoggedIn-Application-HomePage.png b/design-docs/mockscreens/LoggedIn-Application-HomePage.png
new file mode 100644
index 0000000000..d2368c3ff0
Binary files /dev/null and b/design-docs/mockscreens/LoggedIn-Application-HomePage.png differ
diff --git a/design-docs/mockscreens/LoggedIn-Application-HomePage.screen b/design-docs/mockscreens/LoggedIn-Application-HomePage.screen
new file mode 100644
index 0000000000..11fbef760a
--- /dev/null
+++ b/design-docs/mockscreens/LoggedIn-Application-HomePage.screen
@@ -0,0 +1,97 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.png b/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.png
new file mode 100644
index 0000000000..015a975c2b
Binary files /dev/null and b/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.png differ
diff --git a/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.screen b/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.screen
new file mode 100644
index 0000000000..b838ca7668
--- /dev/null
+++ b/design-docs/mockscreens/LoggedIn-Application-Services-HomePage.screen
@@ -0,0 +1,70 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/LoggedIn-Service-HomePage.png b/design-docs/mockscreens/LoggedIn-Service-HomePage.png
new file mode 100644
index 0000000000..ab80f9722d
Binary files /dev/null and b/design-docs/mockscreens/LoggedIn-Service-HomePage.png differ
diff --git a/design-docs/mockscreens/LoggedIn-Service-HomePage.screen b/design-docs/mockscreens/LoggedIn-Service-HomePage.screen
new file mode 100644
index 0000000000..5426b6f431
--- /dev/null
+++ b/design-docs/mockscreens/LoggedIn-Service-HomePage.screen
@@ -0,0 +1,119 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/ServiceDetails.png b/design-docs/mockscreens/ServiceDetails.png
new file mode 100644
index 0000000000..a364472b74
Binary files /dev/null and b/design-docs/mockscreens/ServiceDetails.png differ
diff --git a/design-docs/mockscreens/ServiceDetails.screen b/design-docs/mockscreens/ServiceDetails.screen
new file mode 100644
index 0000000000..ad82013e34
--- /dev/null
+++ b/design-docs/mockscreens/ServiceDetails.screen
@@ -0,0 +1,84 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/ServiceListing b/design-docs/mockscreens/ServiceListing
new file mode 100644
index 0000000000..bc2314b129
Binary files /dev/null and b/design-docs/mockscreens/ServiceListing differ
diff --git a/design-docs/mockscreens/ServiceListing.screen b/design-docs/mockscreens/ServiceListing.screen
new file mode 100644
index 0000000000..735ec28928
--- /dev/null
+++ b/design-docs/mockscreens/ServiceListing.screen
@@ -0,0 +1,67 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/0-login.screen b/design-docs/mockscreens/provider/0-login.screen
new file mode 100644
index 0000000000..86ac6dbab8
--- /dev/null
+++ b/design-docs/mockscreens/provider/0-login.screen
@@ -0,0 +1,26 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/1.1-api-add.screen b/design-docs/mockscreens/provider/1.1-api-add.screen
new file mode 100644
index 0000000000..8d47c96303
--- /dev/null
+++ b/design-docs/mockscreens/provider/1.1-api-add.screen
@@ -0,0 +1,121 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/1.2-api-add.screen b/design-docs/mockscreens/provider/1.2-api-add.screen
new file mode 100644
index 0000000000..bcb9a13f8b
--- /dev/null
+++ b/design-docs/mockscreens/provider/1.2-api-add.screen
@@ -0,0 +1,121 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/1.3-api-add.screen b/design-docs/mockscreens/provider/1.3-api-add.screen
new file mode 100644
index 0000000000..a5e1ec7822
--- /dev/null
+++ b/design-docs/mockscreens/provider/1.3-api-add.screen
@@ -0,0 +1,130 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/2.1-api-listing.screen b/design-docs/mockscreens/provider/2.1-api-listing.screen
new file mode 100644
index 0000000000..90b95a488a
--- /dev/null
+++ b/design-docs/mockscreens/provider/2.1-api-listing.screen
@@ -0,0 +1,189 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/2.2-api-listing.screen b/design-docs/mockscreens/provider/2.2-api-listing.screen
new file mode 100644
index 0000000000..09a278420b
--- /dev/null
+++ b/design-docs/mockscreens/provider/2.2-api-listing.screen
@@ -0,0 +1,189 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/2.3-api-listing.screen b/design-docs/mockscreens/provider/2.3-api-listing.screen
new file mode 100644
index 0000000000..88a0130ce6
--- /dev/null
+++ b/design-docs/mockscreens/provider/2.3-api-listing.screen
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/3-api-details.screen b/design-docs/mockscreens/provider/3-api-details.screen
new file mode 100644
index 0000000000..6d5440faa0
--- /dev/null
+++ b/design-docs/mockscreens/provider/3-api-details.screen
@@ -0,0 +1,119 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/4-api-versions.screen b/design-docs/mockscreens/provider/4-api-versions.screen
new file mode 100644
index 0000000000..fd7211c5bd
--- /dev/null
+++ b/design-docs/mockscreens/provider/4-api-versions.screen
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/5-api-edit.screen b/design-docs/mockscreens/provider/5-api-edit.screen
new file mode 100644
index 0000000000..63416e49ae
--- /dev/null
+++ b/design-docs/mockscreens/provider/5-api-edit.screen
@@ -0,0 +1,119 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/6-api-users.screen b/design-docs/mockscreens/provider/6-api-users.screen
new file mode 100644
index 0000000000..e61585b30e
--- /dev/null
+++ b/design-docs/mockscreens/provider/6-api-users.screen
@@ -0,0 +1,74 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/7-api-docs.screen b/design-docs/mockscreens/provider/7-api-docs.screen
new file mode 100644
index 0000000000..c136f81d8e
--- /dev/null
+++ b/design-docs/mockscreens/provider/7-api-docs.screen
@@ -0,0 +1,116 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/APIDetails-SelectPackage.screen b/design-docs/mockscreens/provider/APIDetails-SelectPackage.screen
new file mode 100644
index 0000000000..7194eb698b
--- /dev/null
+++ b/design-docs/mockscreens/provider/APIDetails-SelectPackage.screen
@@ -0,0 +1,69 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/APIDetails.png b/design-docs/mockscreens/provider/APIDetails.png
new file mode 100644
index 0000000000..a761699480
Binary files /dev/null and b/design-docs/mockscreens/provider/APIDetails.png differ
diff --git a/design-docs/mockscreens/provider/APIDetails.screen b/design-docs/mockscreens/provider/APIDetails.screen
new file mode 100644
index 0000000000..e3ed74a657
--- /dev/null
+++ b/design-docs/mockscreens/provider/APIDetails.screen
@@ -0,0 +1,137 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/APIDocumentation.screen b/design-docs/mockscreens/provider/APIDocumentation.screen
new file mode 100644
index 0000000000..3d8d412a25
--- /dev/null
+++ b/design-docs/mockscreens/provider/APIDocumentation.screen
@@ -0,0 +1,114 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/APIs-published-by-a-provider.png b/design-docs/mockscreens/provider/APIs-published-by-a-provider.png
new file mode 100644
index 0000000000..5d817aa423
Binary files /dev/null and b/design-docs/mockscreens/provider/APIs-published-by-a-provider.png differ
diff --git a/design-docs/mockscreens/provider/AddNewAPI.screen b/design-docs/mockscreens/provider/AddNewAPI.screen
new file mode 100644
index 0000000000..acdac9d44d
--- /dev/null
+++ b/design-docs/mockscreens/provider/AddNewAPI.screen
@@ -0,0 +1,105 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/AllAPIProviders.png b/design-docs/mockscreens/provider/AllAPIProviders.png
new file mode 100644
index 0000000000..19c2181204
Binary files /dev/null and b/design-docs/mockscreens/provider/AllAPIProviders.png differ
diff --git a/design-docs/mockscreens/provider/CreateNewAPIVersion.screen b/design-docs/mockscreens/provider/CreateNewAPIVersion.screen
new file mode 100644
index 0000000000..bb5f45524d
--- /dev/null
+++ b/design-docs/mockscreens/provider/CreateNewAPIVersion.screen
@@ -0,0 +1,82 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/KeyMgt-for-API.png b/design-docs/mockscreens/provider/KeyMgt-for-API.png
new file mode 100644
index 0000000000..114bfe2f57
Binary files /dev/null and b/design-docs/mockscreens/provider/KeyMgt-for-API.png differ
diff --git a/design-docs/mockscreens/provider/ListOfProviders.screen b/design-docs/mockscreens/provider/ListOfProviders.screen
new file mode 100644
index 0000000000..85b20be1d1
--- /dev/null
+++ b/design-docs/mockscreens/provider/ListOfProviders.screen
@@ -0,0 +1,170 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/MyPublishedAPIs-Keymanagement.screen b/design-docs/mockscreens/provider/MyPublishedAPIs-Keymanagement.screen
new file mode 100644
index 0000000000..789fd0b25c
--- /dev/null
+++ b/design-docs/mockscreens/provider/MyPublishedAPIs-Keymanagement.screen
@@ -0,0 +1,87 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/MyPublishedAPIs.screen b/design-docs/mockscreens/provider/MyPublishedAPIs.screen
new file mode 100644
index 0000000000..12a313c234
--- /dev/null
+++ b/design-docs/mockscreens/provider/MyPublishedAPIs.screen
@@ -0,0 +1,92 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/RegisterEditProvider.screen b/design-docs/mockscreens/provider/RegisterEditProvider.screen
new file mode 100644
index 0000000000..0ee2430c6d
--- /dev/null
+++ b/design-docs/mockscreens/provider/RegisterEditProvider.screen
@@ -0,0 +1,77 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/UpdateAccessControl.screen b/design-docs/mockscreens/provider/UpdateAccessControl.screen
new file mode 100644
index 0000000000..df9bfbf7de
--- /dev/null
+++ b/design-docs/mockscreens/provider/UpdateAccessControl.screen
@@ -0,0 +1,141 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/API_Package_selection.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/API_Package_selection.png
new file mode 100644
index 0000000000..7fb3b9ee99
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/API_Package_selection.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/APIs_published_by_provider.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/APIs_published_by_provider.png
new file mode 100644
index 0000000000..16e7daea67
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/APIs_published_by_provider.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/AddNewAPI.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/AddNewAPI.png
new file mode 100644
index 0000000000..8493de3d0f
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/AddNewAPI.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/Add_API_Documentation.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/Add_API_Documentation.png
new file mode 100644
index 0000000000..55a276483f
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/Add_API_Documentation.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/All_API_Providers.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/All_API_Providers.png
new file mode 100644
index 0000000000..26b34edfc3
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/All_API_Providers.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/Applications_using_an_API.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/Applications_using_an_API.png
new file mode 100644
index 0000000000..20a067d41f
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/Applications_using_an_API.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/EditAPI.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/EditAPI.png
new file mode 100644
index 0000000000..7adc00c488
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/EditAPI.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/Manage_API_Versions.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/Manage_API_Versions.png
new file mode 100644
index 0000000000..a276b36508
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/Manage_API_Versions.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/Policy_Template_Definition.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/Policy_Template_Definition.png
new file mode 100644
index 0000000000..ddd5487492
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/Policy_Template_Definition.png differ
diff --git a/design-docs/mockscreens/provider/screenshots/16-02-2012/Signup.png b/design-docs/mockscreens/provider/screenshots/16-02-2012/Signup.png
new file mode 100644
index 0000000000..45a71fbfdb
Binary files /dev/null and b/design-docs/mockscreens/provider/screenshots/16-02-2012/Signup.png differ
diff --git a/docs/resources/css/site.css b/docs/resources/css/site.css
new file mode 100644
index 0000000000..12488c5097
--- /dev/null
+++ b/docs/resources/css/site.css
@@ -0,0 +1,192 @@
+/*
+ * Copyright (c) 2005-2010, WSO2 Inc. (http://wso2.com) 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.
+ *
+ */
+
+body {
+ color: #000;
+ font-size: 11px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ background-image: url( ../images/esb-docs-bg.gif );
+ background-repeat: repeat-x;
+ background-attachment: scroll;
+ background-position: left top;
+ text-decoration: none;
+ text-align: left;
+ padding: 0px;
+ list-style-type: square;
+ list-style-position: outside;
+}
+
+div#banner {
+ background-image: url(../images/esb-docs-header.gif);
+ background-repeat: no-repeat;
+ background-position: left top;
+ height: 38px;
+ padding-top: 30px;
+ padding-left: 265px;
+ border-bottom: 0px;
+}
+
+div#banner span#bannerLeft {
+ font-size: 180%;
+ color: #542988;
+}
+
+div#breadcrumbs {
+ background-color: transparent;
+ border-top: solid 0px;
+ border-bottom: solid 0px;
+ height: 23px;
+ padding-top: 5px;
+ padding-left: 20px;
+ padding-right: 20px;
+}
+
+div#leftColumn {
+ margin-left: 0px;
+ margin-top: 0px;
+ border-top: 0px;
+ background-color: #F7F7F7;
+ border-left: solid 0px;
+ border-right: solid 1px #542988;
+ border-bottom: solid 1px #542988;
+}
+
+div#leftColumn div#navcolumn {
+ padding-left: 20px;
+ padding-right: 20px;
+ padding-top: 15px;
+ background-color: #F7F7F7;
+}
+
+
+div#contentBox {
+ margin-top: 10px;
+ margin-bottom: 15px;
+ font-size: 12px;
+}
+
+div#navcolumn h5 {
+ margin-bottom: 2px;
+ padding-bottom: 2px;
+ border-bottom: solid 1px #542988;
+ font-size: 110%;
+}
+
+#navcolumn li {
+ padding-top: 2px;
+ padding-bottom: 2px;
+}
+
+p {
+}
+
+td {
+ background-color: #f8f8f8;
+ padding: 3px 5px;
+ outline-color: gray;
+ outline-width: 0;
+}
+
+a:link {
+ color: #36c;
+}
+
+a:visited {
+}
+
+a:hover {
+ color: #7f7f7f;
+}
+
+a:active {
+}
+
+body, td, select, input, li {
+ line-height: 18px;
+}
+
+h1 {
+ color: #333;
+ font-size: 18px;
+ font-weight: bold;
+ font-style: normal;
+ line-height: normal;
+ background-image: none;
+ background-repeat: no-repeat;
+ background-attachment: scroll;
+ background-position: left top;
+ text-decoration: none;
+ height: 30px;
+ padding-bottom: 2px;
+ border-bottom: 1px solid #663399;
+}
+
+h2 {
+ color: black;
+ font-size: 15px;
+ font-weight: bold;
+ line-height: 24px;
+ border-bottom: 0px;
+ border-left: solid 1px #ccc;
+ border-right: solid 1px #ccc;
+ border-top: 0px;
+ background-color: #B5B5B5;
+ padding-left: 5px;
+ padding-top: 0px;
+ padding-bottom: 0px;
+ color: #fff;
+}
+
+h3 {
+ color: #3a3a3a;
+ font-size: 12px;
+ font-weight: bold;
+ padding-top: 10px;
+ padding-bottom: 4px;
+ padding-left: 10px;
+ border-left: 0px;
+ border-right: 0px;
+ border-top: 0px;
+ border-bottom: 1px solid #ccc;
+ background-image: url(../images/table-header.gif);
+ background-position: left bottom;
+ background-repeat: repeat-x;
+ background-color: transparent;
+}
+
+table {
+ background-color: #cbcbcb;
+ margin: 0;
+ padding: 1px;
+ border-style: solid;
+ border-width: 0;
+}
+
+th {
+ padding-left: 5px;
+}
+
+img {
+ background-color: gray;
+ padding: 1px;
+}
+div#footer {
+ background-color: #ccc;
+ padding-right: 20px;
+}
\ No newline at end of file
diff --git a/docs/resources/images/add-user.png b/docs/resources/images/add-user.png
new file mode 100644
index 0000000000..fc72b127e2
Binary files /dev/null and b/docs/resources/images/add-user.png differ
diff --git a/docs/resources/images/add.gif b/docs/resources/images/add.gif
new file mode 100644
index 0000000000..4bfdd7983e
Binary files /dev/null and b/docs/resources/images/add.gif differ
diff --git a/docs/resources/images/browse-registry.png b/docs/resources/images/browse-registry.png
new file mode 100644
index 0000000000..7671f3c21b
Binary files /dev/null and b/docs/resources/images/browse-registry.png differ
diff --git a/docs/resources/images/delete.gif b/docs/resources/images/delete.gif
new file mode 100644
index 0000000000..471f55c15f
Binary files /dev/null and b/docs/resources/images/delete.gif differ
diff --git a/docs/resources/images/dep-tracking.png b/docs/resources/images/dep-tracking.png
new file mode 100644
index 0000000000..35d2238d21
Binary files /dev/null and b/docs/resources/images/dep-tracking.png differ
diff --git a/docs/resources/images/edit.gif b/docs/resources/images/edit.gif
new file mode 100644
index 0000000000..f44da7badd
Binary files /dev/null and b/docs/resources/images/edit.gif differ
diff --git a/docs/resources/images/editing-registry-entry.png b/docs/resources/images/editing-registry-entry.png
new file mode 100644
index 0000000000..519dedec85
Binary files /dev/null and b/docs/resources/images/editing-registry-entry.png differ
diff --git a/docs/resources/images/endpoint-info.png b/docs/resources/images/endpoint-info.png
new file mode 100644
index 0000000000..f4d395cf06
Binary files /dev/null and b/docs/resources/images/endpoint-info.png differ
diff --git a/docs/resources/images/endpoint-mbean.png b/docs/resources/images/endpoint-mbean.png
new file mode 100644
index 0000000000..3c66dd3820
Binary files /dev/null and b/docs/resources/images/endpoint-mbean.png differ
diff --git a/docs/resources/images/endpoint-off.png b/docs/resources/images/endpoint-off.png
new file mode 100644
index 0000000000..298bf32dc2
Binary files /dev/null and b/docs/resources/images/endpoint-off.png differ
diff --git a/docs/resources/images/endpoint-state.png b/docs/resources/images/endpoint-state.png
new file mode 100644
index 0000000000..51b1e88d60
Binary files /dev/null and b/docs/resources/images/endpoint-state.png differ
diff --git a/docs/resources/images/endpoint-turn-off.png b/docs/resources/images/endpoint-turn-off.png
new file mode 100644
index 0000000000..cadf740568
Binary files /dev/null and b/docs/resources/images/endpoint-turn-off.png differ
diff --git a/docs/resources/images/esb-architecture.png b/docs/resources/images/esb-architecture.png
new file mode 100644
index 0000000000..79344f5fb0
Binary files /dev/null and b/docs/resources/images/esb-architecture.png differ
diff --git a/docs/resources/images/esb-docs-bg.gif b/docs/resources/images/esb-docs-bg.gif
new file mode 100644
index 0000000000..858ed6744a
Binary files /dev/null and b/docs/resources/images/esb-docs-bg.gif differ
diff --git a/docs/resources/images/esb-docs-header.gif b/docs/resources/images/esb-docs-header.gif
new file mode 100644
index 0000000000..2ef5db6e7b
Binary files /dev/null and b/docs/resources/images/esb-docs-header.gif differ
diff --git a/docs/resources/images/help.gif b/docs/resources/images/help.gif
new file mode 100644
index 0000000000..368068d09d
Binary files /dev/null and b/docs/resources/images/help.gif differ
diff --git a/docs/resources/images/installed-features.png b/docs/resources/images/installed-features.png
new file mode 100644
index 0000000000..6e97fa2bd8
Binary files /dev/null and b/docs/resources/images/installed-features.png differ
diff --git a/docs/resources/images/jconsole-mbean.png b/docs/resources/images/jconsole-mbean.png
new file mode 100644
index 0000000000..1b4f0f87d2
Binary files /dev/null and b/docs/resources/images/jconsole-mbean.png differ
diff --git a/docs/resources/images/log_mediator_conf.png b/docs/resources/images/log_mediator_conf.png
new file mode 100644
index 0000000000..7be137b1a9
Binary files /dev/null and b/docs/resources/images/log_mediator_conf.png differ
diff --git a/docs/resources/images/login.png b/docs/resources/images/login.png
new file mode 100644
index 0000000000..ce9c384fd3
Binary files /dev/null and b/docs/resources/images/login.png differ
diff --git a/docs/resources/images/logs.png b/docs/resources/images/logs.png
new file mode 100644
index 0000000000..685554427c
Binary files /dev/null and b/docs/resources/images/logs.png differ
diff --git a/docs/resources/images/main_seq.png b/docs/resources/images/main_seq.png
new file mode 100644
index 0000000000..6f1b35b9ae
Binary files /dev/null and b/docs/resources/images/main_seq.png differ
diff --git a/docs/resources/images/monitoring_jconsole_login.png b/docs/resources/images/monitoring_jconsole_login.png
new file mode 100644
index 0000000000..ed49ae3605
Binary files /dev/null and b/docs/resources/images/monitoring_jconsole_login.png differ
diff --git a/docs/resources/images/monitoring_jconsole_mbeans.png b/docs/resources/images/monitoring_jconsole_mbeans.png
new file mode 100644
index 0000000000..a6c85483a2
Binary files /dev/null and b/docs/resources/images/monitoring_jconsole_mbeans.png differ
diff --git a/docs/resources/images/monitoring_seq.png b/docs/resources/images/monitoring_seq.png
new file mode 100644
index 0000000000..44d4acf9a7
Binary files /dev/null and b/docs/resources/images/monitoring_seq.png differ
diff --git a/docs/resources/images/monitoring_view.png b/docs/resources/images/monitoring_view.png
new file mode 100644
index 0000000000..f31fd8640c
Binary files /dev/null and b/docs/resources/images/monitoring_view.png differ
diff --git a/docs/resources/images/monitoring_view_ps.png b/docs/resources/images/monitoring_view_ps.png
new file mode 100644
index 0000000000..6c7a6e1ef3
Binary files /dev/null and b/docs/resources/images/monitoring_view_ps.png differ
diff --git a/docs/resources/images/monitoring_view_ps_single.png b/docs/resources/images/monitoring_view_ps_single.png
new file mode 100644
index 0000000000..e89feb7149
Binary files /dev/null and b/docs/resources/images/monitoring_view_ps_single.png differ
diff --git a/docs/resources/images/ns-add.png b/docs/resources/images/ns-add.png
new file mode 100644
index 0000000000..142b4c2b20
Binary files /dev/null and b/docs/resources/images/ns-add.png differ
diff --git a/docs/resources/images/nseditor-icon.gif b/docs/resources/images/nseditor-icon.gif
new file mode 100644
index 0000000000..5b4ab69396
Binary files /dev/null and b/docs/resources/images/nseditor-icon.gif differ
diff --git a/docs/resources/images/ot-header-esb-bg.gif b/docs/resources/images/ot-header-esb-bg.gif
new file mode 100644
index 0000000000..a9fe470434
Binary files /dev/null and b/docs/resources/images/ot-header-esb-bg.gif differ
diff --git a/docs/resources/images/perm-tree.png b/docs/resources/images/perm-tree.png
new file mode 100644
index 0000000000..8920240871
Binary files /dev/null and b/docs/resources/images/perm-tree.png differ
diff --git a/docs/resources/images/proxy-service.gif b/docs/resources/images/proxy-service.gif
new file mode 100644
index 0000000000..ffdb8750b5
Binary files /dev/null and b/docs/resources/images/proxy-service.gif differ
diff --git a/docs/resources/images/proxy.png b/docs/resources/images/proxy.png
new file mode 100644
index 0000000000..ff0e5ae937
Binary files /dev/null and b/docs/resources/images/proxy.png differ
diff --git a/docs/resources/images/proxy_service_step1.png b/docs/resources/images/proxy_service_step1.png
new file mode 100644
index 0000000000..85b3aa9c43
Binary files /dev/null and b/docs/resources/images/proxy_service_step1.png differ
diff --git a/docs/resources/images/proxy_templates.png b/docs/resources/images/proxy_templates.png
new file mode 100644
index 0000000000..fa9cdfb848
Binary files /dev/null and b/docs/resources/images/proxy_templates.png differ
diff --git a/docs/resources/images/qs_address.png b/docs/resources/images/qs_address.png
new file mode 100644
index 0000000000..49d33f1dc4
Binary files /dev/null and b/docs/resources/images/qs_address.png differ
diff --git a/docs/resources/images/qs_endpoint_main.png b/docs/resources/images/qs_endpoint_main.png
new file mode 100644
index 0000000000..83325b11f8
Binary files /dev/null and b/docs/resources/images/qs_endpoint_main.png differ
diff --git a/docs/resources/images/qs_out_sequence.png b/docs/resources/images/qs_out_sequence.png
new file mode 100644
index 0000000000..7ca39ea7d7
Binary files /dev/null and b/docs/resources/images/qs_out_sequence.png differ
diff --git a/docs/resources/images/qs_proxy_dashbord.png b/docs/resources/images/qs_proxy_dashbord.png
new file mode 100644
index 0000000000..7719672c7c
Binary files /dev/null and b/docs/resources/images/qs_proxy_dashbord.png differ
diff --git a/docs/resources/images/qs_proxy_dashbord_in.png b/docs/resources/images/qs_proxy_dashbord_in.png
new file mode 100644
index 0000000000..c93b153e6d
Binary files /dev/null and b/docs/resources/images/qs_proxy_dashbord_in.png differ
diff --git a/docs/resources/images/qs_proxy_service.png b/docs/resources/images/qs_proxy_service.png
new file mode 100644
index 0000000000..06476e8c29
Binary files /dev/null and b/docs/resources/images/qs_proxy_service.png differ
diff --git a/docs/resources/images/qs_proxy_service2.png b/docs/resources/images/qs_proxy_service2.png
new file mode 100644
index 0000000000..ca4a8b700f
Binary files /dev/null and b/docs/resources/images/qs_proxy_service2.png differ
diff --git a/docs/resources/images/qs_proxy_wizard3.png b/docs/resources/images/qs_proxy_wizard3.png
new file mode 100644
index 0000000000..e6cd9f351d
Binary files /dev/null and b/docs/resources/images/qs_proxy_wizard3.png differ
diff --git a/docs/resources/images/qs_ps_overall_stats.png b/docs/resources/images/qs_ps_overall_stats.png
new file mode 100644
index 0000000000..8cc9f5eb03
Binary files /dev/null and b/docs/resources/images/qs_ps_overall_stats.png differ
diff --git a/docs/resources/images/qs_ps_stats.png b/docs/resources/images/qs_ps_stats.png
new file mode 100644
index 0000000000..1bd917fa1d
Binary files /dev/null and b/docs/resources/images/qs_ps_stats.png differ
diff --git a/docs/resources/images/registry-entry-types.png b/docs/resources/images/registry-entry-types.png
new file mode 100644
index 0000000000..d5124c1617
Binary files /dev/null and b/docs/resources/images/registry-entry-types.png differ
diff --git a/docs/resources/images/registry_picker.gif b/docs/resources/images/registry_picker.gif
new file mode 100644
index 0000000000..de78940aa4
Binary files /dev/null and b/docs/resources/images/registry_picker.gif differ
diff --git a/docs/resources/images/registrybrowser.png b/docs/resources/images/registrybrowser.png
new file mode 100644
index 0000000000..46fbe4fd2e
Binary files /dev/null and b/docs/resources/images/registrybrowser.png differ
diff --git a/docs/resources/images/sequence_statistics.png b/docs/resources/images/sequence_statistics.png
new file mode 100644
index 0000000000..f253c634c9
Binary files /dev/null and b/docs/resources/images/sequence_statistics.png differ
diff --git a/docs/resources/images/sequences.png b/docs/resources/images/sequences.png
new file mode 100644
index 0000000000..de3f901bfb
Binary files /dev/null and b/docs/resources/images/sequences.png differ
diff --git a/docs/resources/images/set-java-home.jpg b/docs/resources/images/set-java-home.jpg
new file mode 100644
index 0000000000..d23d544990
Binary files /dev/null and b/docs/resources/images/set-java-home.jpg differ
diff --git a/docs/resources/images/simple_address_endpoint.png b/docs/resources/images/simple_address_endpoint.png
new file mode 100644
index 0000000000..0f57ec58db
Binary files /dev/null and b/docs/resources/images/simple_address_endpoint.png differ
diff --git a/docs/resources/images/stat-icon-disabled.gif b/docs/resources/images/stat-icon-disabled.gif
new file mode 100644
index 0000000000..ec24847903
Binary files /dev/null and b/docs/resources/images/stat-icon-disabled.gif differ
diff --git a/docs/resources/images/stat-icon.gif b/docs/resources/images/stat-icon.gif
new file mode 100644
index 0000000000..3f7d61f79d
Binary files /dev/null and b/docs/resources/images/stat-icon.gif differ
diff --git a/docs/resources/images/statistics.png b/docs/resources/images/statistics.png
new file mode 100644
index 0000000000..2836f266e2
Binary files /dev/null and b/docs/resources/images/statistics.png differ
diff --git a/docs/resources/images/synapse-PBX.jpg b/docs/resources/images/synapse-PBX.jpg
new file mode 100644
index 0000000000..53592541dd
Binary files /dev/null and b/docs/resources/images/synapse-PBX.jpg differ
diff --git a/docs/resources/images/synapse-flow.png b/docs/resources/images/synapse-flow.png
new file mode 100644
index 0000000000..f5b6a0352f
Binary files /dev/null and b/docs/resources/images/synapse-flow.png differ
diff --git a/docs/resources/images/synapse-logo-web2.png b/docs/resources/images/synapse-logo-web2.png
new file mode 100644
index 0000000000..0b4fc12f64
Binary files /dev/null and b/docs/resources/images/synapse-logo-web2.png differ
diff --git a/docs/resources/images/table-header.gif b/docs/resources/images/table-header.gif
new file mode 100644
index 0000000000..92283f0911
Binary files /dev/null and b/docs/resources/images/table-header.gif differ
diff --git a/docs/resources/images/templates_call-template-parameters.png b/docs/resources/images/templates_call-template-parameters.png
new file mode 100644
index 0000000000..add4bb3dfb
Binary files /dev/null and b/docs/resources/images/templates_call-template-parameters.png differ
diff --git a/docs/resources/images/templates_endpoint_templ_design.png b/docs/resources/images/templates_endpoint_templ_design.png
new file mode 100644
index 0000000000..8036a73576
Binary files /dev/null and b/docs/resources/images/templates_endpoint_templ_design.png differ
diff --git a/docs/resources/images/templates_sequence_params.png b/docs/resources/images/templates_sequence_params.png
new file mode 100644
index 0000000000..f75e038dd0
Binary files /dev/null and b/docs/resources/images/templates_sequence_params.png differ
diff --git a/docs/resources/images/templates_template_endpoint.png b/docs/resources/images/templates_template_endpoint.png
new file mode 100644
index 0000000000..78a61ec564
Binary files /dev/null and b/docs/resources/images/templates_template_endpoint.png differ
diff --git a/docs/resources/images/trace.png b/docs/resources/images/trace.png
new file mode 100644
index 0000000000..7731046aa4
Binary files /dev/null and b/docs/resources/images/trace.png differ
diff --git a/docs/resources/images/tracer-icon-disabled.gif b/docs/resources/images/tracer-icon-disabled.gif
new file mode 100644
index 0000000000..ddcd94c2d9
Binary files /dev/null and b/docs/resources/images/tracer-icon-disabled.gif differ
diff --git a/docs/resources/images/tracer-icon.gif b/docs/resources/images/tracer-icon.gif
new file mode 100644
index 0000000000..02d399e648
Binary files /dev/null and b/docs/resources/images/tracer-icon.gif differ
diff --git a/docs/resources/images/user-mgt.png b/docs/resources/images/user-mgt.png
new file mode 100644
index 0000000000..813207dddb
Binary files /dev/null and b/docs/resources/images/user-mgt.png differ
diff --git a/docs/site.xml b/docs/site.xml
new file mode 100644
index 0000000000..0d0fdfbf4f
--- /dev/null
+++ b/docs/site.xml
@@ -0,0 +1,124 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ org.apache.maven.skins
+ maven-default-skin
+ 1.0
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/xdoc/admin_guide.xml b/docs/xdoc/admin_guide.xml
new file mode 100644
index 0000000000..e879cd06e7
--- /dev/null
+++ b/docs/xdoc/admin_guide.xml
@@ -0,0 +1,1032 @@
+
+
+
+
+
+
+ WSO2 ESB - System Administration Guide
+
+
+
+
+
+
+ [ Documentation Index ]
+
+ WSO2 Enterprise Service Bus [ESB] System Administration Guide
+
+
+This is a manual on how to maintain and administrate a WSO2 ESB instance. It explains how various
+features of the ESB can be configured using the ESB management console and by modifying the ESB
+configuration files. Descriptions are provided on advanced features like Remote/Embedded
+registry configuration, adding external libraries, managing key stores and user management. It
+also explains how to performance tune the ESB runtime for extreme throughput.
+
+WSO2 ESB is a production grade open source ESB solution based on the lightweight Apache Synapse ESB.
+WSO2 ESB supports service mediation, message mediation, load balancing, clustering and many more
+enterprise integration techniques out of the box. It also supports a range of application and transport
+level protocols such as HTTP, JMS, Mail, VFS, FIX and a variety of industrial messaging standards such as
+Hessian.
+
+
+Starting from version 2.0, WSO2 ESB is based on the revolutionary WSO2 Carbon framework. WSO2 Carbon
+is an OSGi based middleware framework for SOA. Currently all WSO2 Java products are based on WSO2
+Carbon including WSO2 Governance Registry and WSO2 AS. Since ESB is OSGi based some knowledge in
+OSGi would be helpful in administrating the WSO2 ESB.
+
+
+This document explains how to get WSO2 ESB and install it on a server. The latter sections of the
+document illustrates how to setup and configure various features of the WSO2 ESB and how to performance
+tune various aspects of the product.
+
+
+
Document Conventions
+
+
'ESB_HOME' refers to the directory in the file system where WSO2 ESB is installed
+
'ESB_SRC_HOME' refers to the directory in the file system where WSO2 ESB source distribution is installed
+
All file paths follow Unix/Linux conventions but they resemble Windows file paths as well
+
+
+
Getting WSO2 ESB
+
+Binary distributions and source distributions of WSO2 ESB can be downloaded free from the
+WSO2 ESB home page in the WSO2 Oxygen Tank. Before proceeding to the
+downloads page you will be asked to register on the WSO2 Oxygen Tank. Registration is free and optional
+however it is recommended that you sign up for an account right away since registered Oxygen Tank users
+get exclusive access to our support forums and tons of valuable content related to SOA and Web Services.
+
+
+Once you are on the downloads page click on the relevant links to download a binary distribution or a
+source distribution of the latest stable release of the WSO2 ESB. If you are interested in an older
+version of the ESB, scroll down in the downloads page to locate the links to previous releases. You will
+also find links to download developer releases and nightly builds of the WSO2 ESB on the same page. We
+recommend that you always download the latest stable release. If you want to try out a feature that was
+added very recently you can try out a nightly build.
+
+
+If you downloaded a source distribution of the ESB you need to build the source to get the executable
+binary. WSO2 ESB uses an Apache Maven2 based build system and
+therefore you need to first download and install Apache Maven2. Please refer Maven2 documentation on
+installing and configuring Apache Maven2. Also note that Apache Maven2 requires Java to run.
+Once Maven2 is properly configured extract the downloaded source distribution and change your working
+directory to the directory that is created. Then execute the command 'mvn clean install' to run the builder.
+Once the build process is complete you can find the binary distribution archive in ESB_SRC_HOME/modules/distribution/target
+directory.
+
+
+
Installing and Running WSO2 ESB
+
+To install the WSO2 ESB simply extract the downloaded binary distribution archive. If you built WSO2 ESB
+from source extract the archive created by the builder. We recommend installing WSO2 ESB on a Unix/Linux
+system since that will enable you to get the maximum out of the ESB. In order to be able to start WSO2 ESB
+you first need Java 5 or higher. Having installed Java on your system please set the JAVA_HOME environment
+variable to point to the directory in which Java is installed.
+
+
Running WSO2 ESB in Standalone Mode
+
+Now you are all set to start WSO2 ESB in the standalone mode. Go to ESB_HOME/bin directory and if you are
+on Unix/Linux execute the wso2server.sh shell script or if you are on Windows execute the wso2server.bat
+batch file. This will start the ESB and you can see the progress of the startup procedure on the console.
+Please note that server startup may take some time depending on the hardware configuration of your system.
+The very first startup of the ESB can take up a few additional seconds since some first time configuration
+procedure is run by the ESB. If the server started up cleanly you should get an output similar to the following
+on the console.
+
+
+ [2010-03-23 10:34:17,594] INFO - Main Initializing system...
+ [2010-03-23 10:34:25,176] INFO - CarbonCoreActivator Starting WSO2 Carbon...
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Operating System : Linux 2.6.28-16-generic, amd64
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java Home : /opt/jdk1.6.0_16/jre
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java Version : 1.6.0_16
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java VM : Java HotSpot(TM) 64-Bit Server VM 14.2-b01,Sun Microsystems Inc.
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Carbon Home : /home/user/wso2esb-3.0.1
+ [2010-03-23 10:34:25,179] INFO - CarbonCoreActivator Java Temp Dir : /home/user/wso2esb-3.0.1/tmp
+ [2010-03-23 10:34:25,179] INFO - CarbonCoreActivator User : user, en-US, Asia/Colombo
+ [2010-03-23 10:34:29,715] INFO - RegistryCoreServiceComponent Registry Mode : READ-WRITE
+ [2010-03-23 10:34:32,349] INFO - CarbonServerManager Starting Carbon initialization...
+ [2010-03-23 10:34:32,561] INFO - ClusterBuilder Clustering has been disabled
+ [2010-03-23 10:34:32,742] INFO - DeploymentInterceptor Deploying Axis2 module : relay-3.0
+ [2010-03-23 10:34:32,799] INFO - DeploymentInterceptor Deploying Axis2 module : wso2mex-3.0
+ [2010-03-23 10:34:32,818] INFO - DeploymentInterceptor Deploying Axis2 module : rampart-SNAPSHOT
+ [2010-03-23 10:34:32,862] INFO - DeploymentInterceptor Deploying Axis2 module : sandesha2-3.0
+ [2010-03-23 10:34:32,916] INFO - DeploymentInterceptor Deploying Axis2 module : wso2caching-3.0
+ [2010-03-23 10:34:32,989] INFO - DeploymentInterceptor Deploying Axis2 module : wso2xfer-3.0
+ [2010-03-23 10:34:33,001] INFO - DeploymentInterceptor Deploying Axis2 module : rahas-SNAPSHOT
+ [2010-03-23 10:34:33,019] INFO - DeploymentInterceptor Deploying Axis2 module : savan-SNAPSHOT
+ [2010-03-23 10:34:33,034] INFO - DeploymentInterceptor Deploying Axis2 module : wso2throttle-3.0
+ [2010-03-23 10:34:33,125] INFO - DeploymentInterceptor Deploying Axis2 module : addressing-1.6-wso2v1
+ [2010-03-23 10:34:33,202] INFO - HttpCoreNIOSSLSender Loading Identity Keystore from : resources/security/wso2carbon.jks
+ [2010-03-23 10:34:33,228] INFO - HttpCoreNIOSSLSender Loading Trust Keystore from : resources/security/client-truststore.jks
+ [2010-03-23 10:34:33,256] INFO - HttpCoreNIOSender HTTPS Sender starting
+ [2010-03-23 10:34:33,269] INFO - HttpCoreNIOSender HTTP Sender starting
+ [2010-03-23 10:34:33,370] INFO - DeploymentInterceptor Deploying Axis2 service : echo
+ [2010-03-23 10:34:33,899] INFO - DeploymentInterceptor Deploying Axis2 service : version
+ [2010-03-23 10:34:37,698] INFO - DeploymentInterceptor Deploying Axis2 service : wso2carbon-sts
+ [2010-03-23 10:34:38,273] INFO - DeploymentInterceptor Deploying Axis2 service : XKMS
+ [2010-03-23 10:34:38,480] INFO - CarbonServerManager Repository : /home/user/wso2esb-3.0.1/repository/deployment/server/
+ [2010-03-23 10:34:38,506] INFO - EmbeddedRegistryBasedSubscriptionManager Connection established with the registry
+ [2010-03-23 10:34:38,530] INFO - ServiceBusInitializer Starting ESB...
+ [2010-03-23 10:34:38,573] INFO - ServiceBusInitializer Initializing Apache Synapse...
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using Synapse home : /home/user/wso2esb-3.0.1/.
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using synapse.xml location : /home/user/wso2esb-3.0.1/./repository/conf/synapse-config
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using server name : localhost
+ [2010-03-23 10:34:38,584] INFO - SynapseControllerFactory The timeout handler will run every : 15s
+ [2010-03-23 10:34:38,634] INFO - Axis2SynapseController Initializing Synapse at : Tue Mar 23 10:34:38 IST 2010
+ [2010-03-23 10:34:38,636] INFO - Axis2SynapseController Loading mediator extensions...
+ [2010-03-23 10:34:38,642] INFO - CarbonSynapseController Loading the mediation configuration from the file system
+ [2010-03-23 10:34:38,645] INFO - MultiXMLConfigurationBuilder Building synapse configuration from the synapse artifact repository at : ./repository/conf/synapse-config
+ [2010-03-23 10:34:38,646] INFO - XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration
+ [2010-03-23 10:34:39,077] INFO - SynapseConfigurationBuilder Loaded Synapse configuration from the artifact repository at : ./repository/conf/synapse-config
+ [2010-03-23 10:34:39,208] INFO - Axis2SynapseController Deploying the Synapse service...
+ [2010-03-23 10:34:39,212] INFO - Axis2SynapseController Deploying Proxy services...
+ [2010-03-23 10:34:39,212] INFO - Axis2SynapseController Deploying EventSources...
+ [2010-03-23 10:34:39,217] INFO - ServerManager Server ready for processing...
+ [2010-03-23 10:34:40,219] INFO - HttpCoreNIOSSLListener Loading Identity Keystore from : resources/security/wso2carbon.jks
+ [2010-03-23 10:34:40,221] INFO - HttpCoreNIOSSLListener Loading Trust Keystore from : resources/security/client-truststore.jks
+ [2010-03-23 10:34:40,237] INFO - HttpCoreNIOListener HTTPS Listener started on port : 8243
+ [2010-03-23 10:34:40,239] INFO - HttpCoreNIOListener HTTP Listener started on port : 8280
+ [2010-03-23 10:34:40,798] INFO - RegistryEventingServiceComponent Successfully Initialized Eventing on Registry
+ [2010-03-23 10:34:43,926] INFO - CarbonUIServiceComponent Mgt Console URL : https://10.100.1.209:9443/carbon/
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent Started Transport Listener Manager
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent Server : WSO2 ESB-3.0.1
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 25 sec
+
+
+To verify that the ESB is up and running fire off your Web browser and go to https://localhost:9443/carbon.
+This will take you to the WSO2 ESB on-line management console.
+
+
+
+You can login to the console using the default user credentials given below.
+
+
+
Username: admin
+
Password: admin
+
+
+If you can get that far then the ESB is properly installed and running.
+
+
+WSO2 ESB startup scripts stated above accept a few useful arguments.
+
+
+--cleanRegistry
+This argument will remove the settings stored in the registry and replace them with factory settings.
+It removes the /_system/config/repository collection and the /_system/local/repository collection in the
+registry which are used to store resources and configurations managed by the ESB and the underlying
+Carbon framework. Therefore the ESB will be forced to start fresh with factory settings. Starting from
+WSO2 ESB 3.0 the mediation configuration (sequences, proxies etc) is read from the file system by default.
+In that case this argument does not have any effect on the mediation configuration used by the ESB.
+
+
+--debug <port>
+Enables remote debugging on the ESB through the specified port.
+
+
+In addition to the above mentioned arguments the ESB startup scripts accept the following VM arguments.
+
+
+-DosgiConsole
+Starts the OSGi console from which you can directly interact with the underlying OSGi framework.
+
+
+-DloadFromRegistry
+This argument was first introduced in ESB 3.0. When set to 'true' it will force the ESB to load the mediation
+configuration from the registry, instead of loading it from the file system. Please note that for this
+argument to work the registry must contain a valid mediation configuration stored in it. Therefore one
+cannot pass this argument to a fresh ESB instance which is starting from a clean registry. However after the
+first startup the registry will contain a mediation configuration and hence subsequent startups can proceed
+with this VM parameter.
+
+
+-DwriteToFile
+Newly added to WSO2 ESB 3.0, this argument takes effect only when the mediation configuration is loaded
+from the registry. When set to 'true' this parameter will force the ESB to save the configuration loaded
+from the registry to the local file system at startup.
+
+
+
Running ESB Samples
+
+WSO2 ESB ships with a large number of sample configurations which enables you to get familiar with the
+product quickly and easily. Please refer the WSO2 ESB samples guide for sample configuration and details
+on how to run them. You may start WSO2 ESB using those sample configuration by executing the
+ESB_HOME/bin/wso2esb-sample.sh (for Unix/Linux) or ESB_HOME/bin/wso2esb-sample.bat (for Windows).
+These launcher scripts take a mandatory argument -sn. Use this argument to specify the sample number.
+
+
+eg: ./wso2esb-sample.sh -sn 250 (This will launch the ESB using the Sample 250 configuration)
+
+
+The sample configuration files can be found in the ESB_HOME/repository/samples directory.
+
+
+When launching the ESB using the wso2esb-sample.sh/wso2esb-sample.bat scripts a new registry context root
+will be created for storing data and configurations related to that sample. Also note that these launcher
+scripts accept the same set of arguments accepted by the wso2server.sh and wso2server.bat.
+
+
+
WSO2 ESB Directory Hierarchy
+
+When you extract a WSO2 ESB binary distribution archive you will find the following directories in the
+top level directory that is created.
+
+
+
+bin -
+ Contains all the necessary scripts to interact with the WSO2 ESB instance. There are shell scripts
+ (with .sh extension) for Unix/Linux users and batch files (with .bat extension) for Windows users.
+ In general you will find the following scripts in this directory.
+
+
+ wso2esb-samples.sh/wso2esb-samples.bat - Launches WSO2 ESB using one of the sample configurations
+
+
+ wsdl2java.sh/wsdl2java.bat - Launches the Java stub generation tool for Web Services
+
+
+ java2wsdl.sh/java2wsdl.bat - Launches the WSDL generation tool for Java Web Services
+
+
+ tcpmon.sh/tcpmon.bat - Launches TCPMon, the TCP connection monitor
+
+
+ chpasswd.sh/chpasswd.bat -Use this script to change the administrator password without signing in to the server
+
+
+ ciphertool.sh/ciphertool.bat -<TODO: Indika>
+
+
+ daemon.sh -Start WSO2 ESB as a daemon on Unix/Linux systems
+
+
+ install.bat - Install WSO2 ESB as a background service on Windows
+
+
+ repowriter.sh/repowriter.bat
+
+
+ carbondump.sh/carbondump.bat - Create a dump file containing runtime information related to the ESB (Dump file is useful in debugging issues)
+
+
+
+ In addition to the above mentioned scripts you will find a subdirectory named 'native' in the bin
+ directory.
+
+
+dbscripts -
+Contains a collection of database scripts required to create the Carbon database on a variety of database
+management systems.
+
+
+lib -
+The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance.
+The log4j.properties file used by the ESB is also stored here. In addition to that, the Carbon webapp
+can be found in the lib/core directory. The lib/core/WEB-INF/classes directory houses some of
+important configuration files of the ESB such as nhttp.properties, synapse.properties and datasources.properties.
+
+
+repository -
+This directory houses all the OSGi bundles, service artifacts, modules, configurations and related resources
+used by the WSO2 ESB instance. The repository/components/plugin directory will contain all the necessary OSGi bundles
+at server runtime. In the components subdirectory you can also find a set of child directories such as lib,
+mediators and extensions which can be used to deploy custom mediators and third party dependencies into the ESB.
+The repository/conf subdirectory contains all the crucial configuration files such as axis2.xml and carbon.xml. The
+mediation configuration is loaded from the repository/deployment/server/synapse-config directory. Also starting from ESB 3.0
+server logs are stored in the repository/logs directory.
+
+
+resources -
+Contains additional resources required by WSO2 ESB. This includes security related resources such as
+keystores.
+
+
+samples -
+The samples directory contains the sample Axis2 server, sample Axis2 client, source code of the sample
+services and clients and the ANT scripts required to build and run them.
+
+
+tmp -
+The temporary files directory used by the ESB
+
+
+
Using the WSO2 ESB Management Console
+
+WSO2 ESB management console is a Web based control panel powered by JSP and AJAX which enables system administrators
+to interact with a running ESB instance, without having to touch any underlying configuration files. The
+management console allows the users to command and control proxy services, sequences, transports, local
+entries, registry, modules, endpoints and much more. ESB management console is a great way to try things
+out without having to edit the actual configuration files or without having to restart the ESB for
+changes to take effect.
+
+
+We recommend using Mozilla Firefox 3 or Internet Explorer 7 to access the WSO2 ESB management console.
+Please note that your browser must be JavaScript enabled to take the full advantage of the management console.
+To access the ESB management console fire off you Web browser and navigate to
+https://<Server Host>:<Server Port>/<Context>. If you are running the Web browser on
+the same machine as the ESB you may use 'localhost' as the server host. The default port and the context
+for the ESB management console are '9443' and 'carbon' respectively. If you entered the URL correctly you
+will be taken to the management console's login page.
+
+
+On the login page enter 'admin' as the username and the password to login to the system. You can change
+user credentials and even add new users once you login. Controls and wizards in the ESB management console
+are pretty much self explanatory. However if you are having trouble finding your way in the management
+console, click on the 'Help' link at the top right corner of any page to access context sensitive help.
+
+
+Please note that the ESB management console makes use of the default HTTPS servlet transport which is
+configured in the ESB_HOME/repository/conf/mgt-transports.xml file. It is important that this transport
+is always properly configured in the mentioned file. Otherwise the management console might be inaccessible
+to the users.
+
+
+
User Management
+
+To access the WSO2 ESB user management features, first sign in to the ESB management console and click on
+'User and Roles' under the 'Configure' menu in the left navigation bar. This will take you to the User
+Management home page which contains the controls illustrated below.
+
+
+
+From here you can manage users and roles. A user is associated with one or more roles (generally specified at
+user creation time) and each role is associated with zero or more permissions (generally specified at
+role creation time). Therefore the set of permissions owned by a user is determined by the roles assigned to
+that user. A user owns the union of all the permissions associated with the roles assigned to that user. By
+default ESB comes with only two roles, the 'admin' role and the 'everyone' role. There is also a third role
+named 'system' which is not visible in the management console. Every user will be assigned the
+'everyone' role. This role does not have any permissions by default. Users with the 'admin' role have full
+access to all the features and controls in the ESB (all permissions). By default the user 'admin' is assigned the
+'admin' role along with the 'everyone' role. Also note that the ESB UI does not allow configuing the permissions
+assigned to the 'admin' role.
+
+
+The permission model of WSO2 ESB is hierarchical. Therefore permissions
+can be assigned in a fine grained manner or a coarse grained manner. For an example one could assign the 'Configure'
+admin permission to a role. The role will be able to configure event sources, scheduled tasks and many other things.
+This is a coarse grained permission allocation. On the other hand one may assign the specific
+'Transport Management', 'Configure Tasks' or 'Configure Data Sources' permission to a role which is a fine grained
+permission allocation. The full ESB permission tree looks as follows.
+
+
+
+Use the 'User Management' page in the UI to add new users, add new roles, assign and withdraw permissions from
+roles and change login credentials of users. To add a new role to the system click on 'Roles' in the User
+Management home page and on the page that appears click the 'Add New Role' link. This will start the 'Add
+Role' wizard. The wizard will guide you though the process of creating a role by specifying a unique name
+for the role and adding the relevant permissions to the new role. Similarly to create a new user, click on
+'Users' in the User Management home page. Then from the next page that appears select 'Create New User' link.
+This will launch the 'Add User' wizard which will enable you to create a new user account with login credentials
+and associate the account with one or more existing roles. The ESB management console also enables you to
+search for and modify existing users and roles.
+
+
Using External User Stores (LDAP/AD)
+
+You can also connect an external user store (database) with WSO2 ESB. Such external stores are configured through
+the user-mgt.xml file which can be found in the repository/conf directory. Settings required to connect an LDAP
+based user store or an Active Directory based user store are provided in the default user-mgt.xml file. Simply
+uncomment the relevant entries in the file and update the required parameters. Also note that the ESB can have
+only one user store at any given moment. Hence when you want to connect to a different user store you also need
+to comment out the default user store settings (LDAP user store manager) in the user-mgt.xml file. Configuration
+settings for the LDAP based user store looks as follows.
+
+For more information on using external user stores please refer User Core Admin
+Guide.
+
+
+
Setting Up Logging
+
+Logging is one of the most important aspects of a production grade server. A properly configured logging system
+is vital in identifying errors, security threats and usage patterns. WSO2 ESB uses a log4j based logging mechanism
+through Apache Commons Logging facade library. The log4j.properties file which governs how logging is performed by
+the server can be found in ESB_HOME/lib directory. However it is recommended not to make any alterations to the
+default log4j.properties file. The recommended way of setting up logging is by using the ESB management console.
+Simply login to the management console and click on 'Logging' under the 'Configure' menu in the left navigation bar.
+From here you can setup various appenders and configure log levels for various loggers. Any changes to the logging
+configuration you make from the management console will get priority over what is defined in the actual
+log4j.properties file.
+
+
+By default WSO2 ESB comes with the following log appenders configured.
+
+
+
+ CARBON_CONSOLE (Logs to the console when the server is running)
+
+
+ CARBON_LOGFILE (Writes the logs to ESB_HOME/repository/logs/wso2-esb.log)
+
+
+ CARBON_MEMORY
+
+
+ CARBON_SYS_LOG
+
+
+ SERVICE_APPENDER (Writes mediation time audit messages to ESB_HOME/repository/logs/wso2-esb-service.log)
+
+
+ TRACE_APPENDER (Writes mediation time tracing/debug messages to the ESB_HOME/repository/logs/wso2-esb-trace.log for tracing enabled services)
+
+
+ TRACE_MEMORYAPPENDER
+
+
+
+Tracing can be enabled for individual mediation sequences and proxy services from the 'Mediation Sequences'
+home page and the 'Service Dashboard' page respectively. Click on the 'Sequences' link under 'Mediation' in
+the 'Manage' menu of the left navigation bar to access the 'Mediation Sequences' page. This page lists all
+the deployed sequences. Each sequence gives you the options to enable/disable tracing. To access the service
+dashboard for a proxy service go to the Services List page and click on the proxy service that you are
+interested in. Once a sequence or a proxy service is tracing enabled you can view the generated log messages
+by visiting the 'Mediation Tracer' page under the 'Monitor' menu. The 'Monitor' menu also gives you access
+to the system logs and the SOAP tracer logs all through the Web interface itself.
+
+
+
+
Configuring the Underlying Axis2 Engine
+
+WSO2 ESB is based on Apache Synapse lightweight ESB which in turns uses the Apache Axis2 SOAP engine. Every
+WSO2 ESB administrator is expected to have at least a basic understanding of Axis2 and Axis2 configuration model.
+The global configuration of the Axis2 engine is specified in a file named axis2.xml. This configuration file can
+be found in the ESB_HOME/repository/conf directory. Any settings configured in the axis2.xml file are directly
+applied to the server at startup time. Generally, one can configure the following settings in the axis2.xml file.
+
+
+
+ Global system parameters (eg: hotdeployment, hotupdate, servicepath etc)
+
+
+ Global Axis2 listeners (Axis2 observer implementations which are notified of Axis2 events)
+
+
+ Deployers
+
+
+ Message receivers, formatters and builders
+
+
+ Transport receivers and senders
+
+
+ Globally engaged modules (eg: addressing)
+
+
+ Clustering
+
+
+ Axis2 phases
+
+
+
+The axis2.xml file which comes with WSO2 ESB contains examples and descriptions illustrating how the above
+can be configured and setup for common deployment scenarios.
+
+
+
Mediation Configuration
+
+Mediation configuration is the most important part of the WSO2 ESB as far as the functionality of the service
+bus is concerned. The mediation configuration consists of following items.
+
+
+
Endpoints
+
Sequences
+
Proxy services
+
Scheduled tasks
+
Event sources
+
Local entries
+
Priority executors (new in ESB 3.0)
+
+
+Each of the above items can be configured through the management console. New instances of above items
+can be added to the ESB, existing items can be modified or removed. The 'Synapse' entry in the 'Configure'
+menu provides a single unified view of the entire mediation configuration and allows the user to make
+modifications to it using the Synapse configuration language.
+
+
+
Persistence
+
+By default the mediation configuration is stored in the file system as well as in the registry. In the file
+system, configuration is saved under the ESB_HOME/repository/conf/synapse-config directory. There are separate
+subdirectories to store different types of configuration items. When you add a new item using the management
+console it will be saved to a new file under the synapse-config directory. For an example, if you add a new
+endpoint named 'foo' from the UI, it will be saved to a file named foo.xml in ESB_HOME/repository/conf/synapse-config/endpoints
+directory. Any further modifications to the endpoint foo will be saved back to the same file. However if you
+add a new item from the Synapse configuration editor in the UI (in Configure menu) it will be saved to
+ESB_HOME/repository/conf/synapse-config/synapse.xml file.
+
+
+You can customize the behavior of mediation configuration persistence by editing the carbon.xml file. You may
+add the following entry to the carbon.xml and tune up the parameter values as appropriate.
+
+Set the LoadFromRegistry to 'true' if you want to load the mediation configuration from the registry instead of the file
+system. SaveToFile option takes effect only when LoadFromRegistry is set to 'true'. If both values are set to 'true'
+the mediation configuration will be loaded from the registry and will also be saved to the local file system at
+startup. If you want to prevent the ESB from saving the mediation configuration to the registry set RegistryPersistence
+to 'disabled'. By default this is enabled. You can turn off all persistence activies by setting Persistence to
+'disabled'. In that case mediation configuration will not be saved to the file system nor the registry. The configuration
+in the disk/registry is effectively frozen. But the changes made from the UI will still take effect in the runtime. But
+such changes will not survive a restart since they are not saved to persistence store.
+
+
+
Dependency Tracking
+
+WSO2 ESB keeps track of the dependencies among various mediation configuration elements. In a typical mediation
+configuration there are often dependencies among sequences, endpoints, proxy services and local entires. A
+sequence can make references to other sequences, local entries and endpoints. A proxy service may also make references to
+sequences and endpoints. The ESB runtime by default keeps track of such dependencies and warns the user, if he
+attempts to remove a particular item from the configuration which is a dependency for another item.
+
+
+
+The dependency tacking process takes up a few CPU cycles and memory to compute and keep track of the
+dependencies at runtime. Therefore it is recommended to turn this feature off in production environments.
+To turn off dependency tracking open up the synapse.properties file which can be found in the
+ESB_HOME/webapps/ROOT/WEB-INF/classes directory and comment out the following line:
+
+You also need to restart the ESB for the change to take effect. Commenting out the above entry will disengage
+the dependency tracker and hence the ESB will stop computing and keeping track of dependencies among
+different configuration items in the mediation configuration.
+
+
+
Hot Deployment of Mediation Artifacts
+
+WSO2 ESB 3.0 introduces the hot deployment feature for mediation artifacts. With this feature you can hot
+deploy artifacts like endpoints, sequences and proxy services into the ESB_HOME/repository/conf/synapse-config
+directory. Simply save the artifact configuration to an XML file and drop it into the relevant subdirectory in
+the synapse-config parent directory. ESB will pick up the newly added file and get it deployed in the server
+runtime. Once deployed you will be able to view it through the management console and make further changes if
+necessary. Similarly you can make changes to an existing file which contains a mediation configuration item
+and the ESB will pick the changes up through the hot update feature.
+
+
+In a production system it is recommended to turn off hot deployment and update for smooth operation of the ESB.
+To turn off hot deployment and hot update open up the axis2.xml file in repository/conf directory and set the
+following two parameter values to 'false'. (These are by default set to 'true')
+
+New features can be easily installed into the ESB by using the 'WSO2 Carbon Component Manager' that comes
+with the ESB. Component manager is powered by Equinox P2 and allows you to connect to a remote or local P2
+repository and get any feature installed into the ESB runtime. You can also uninstall existing features of
+the ESB and come up with a customized version of WSO2 ESB tailored to meet your requirements.
+
+
+To use the component manager, login to the management console and click on 'Features' under the
+'Configure' menu. Go to the 'Settings' tab and click on 'Manage Repositories'. Click 'Add New Repository'
+and specify the P2 repository to which you wish to connect to. The official WSO2 P2 repository is available
+over http://dist.wso2.org/p2.
+
+
+Once the repository is configured go to the 'Available Features' tab to browse through the features and get them
+installed to the ESB. The installation of a feature can take a while depending on the network bandwidth and
+hardware configuration available. Once a feature has been successfully installed you will be prompted to logout
+and restart the ESB.
+
+
+If you wish to uninstall an existing feature go to the 'Installed Features' tab, select the features to be
+uninstalled and click on 'Uninstall' at the bottom of the page.
+
+
+
+
Adding External Dependencies to the System
+
+You would want to deploy external dependency jars into the WSO2 ESB server in many scenarios. Generally one
+would want to add external dependencies in following situations.
+
+
+
+ Enabling and configuring a new transport (Many transport implementations such as JMS and FIX require
+ adding a set of external dependencies to the server)
+
+
+ Adding a custom mediator
+
+
+ Adding a custom handler or a module
+
+
+
+To add an external dependency to the WSO2 ESB you simply need to copy the necessary jar file(s) to
+ESB_HOME/repository/components/lib or ESB_HOME/repository/components/extensions. Jars copied to these
+directories will be automatically converted into OSGi bundles on ESB startup. Jars copied to
+ESB_HOME/repository/components/extensions will be converted into OSGi bundles which are fragments of the
+main system bundle. WSO2 ESB also provides the ESB_HOME/repository/components/mediators directory to deploy
+custom mediators into the ESB.
+
+
+Currently WSO2 ESB does not support deploying external dependencies at runtime. Therefore after copying
+the external dependency jars to the relevant locations the server must be restarted for the server to be
+able to pick them up.
+
+
+
Registry Integration
+
+WSO2 ESB makes use of a WSO2 Governance Registry instance to store various configurations and artifacts
+such as proxy services, sequences and endpoints. Simply put a registry is a content store and a metadata
+repository. Various SOA artifacts such as services, WSDLs and configuration files can be stored in a
+registry keyed by unique paths. A path is similar to a Unix file path. In WSO2 ESB all configurations
+pertaining to modules, logging, security, data sources and other service groups are stored in the registry
+by default. Starting from WSO2 Carbon 2.0 all the transport configurations are also stored in the registry.
+WSO2 ESB 2.1 introduced a feature to directly store endpoints and sequences to the registry with a user
+specified key value.
+
+
+WSO2 ESB accesses the registry in two ways. In many cases it accesses the registry by directly calling the
+registry API from Carbon components. In some special situations it gains access to the registry through the
+underlying Apache Synapse configuration. It is important that Synapse configuration should always include a
+registry definition. That is, the ESB configuration should include the following registry definition.
+
+Starting from ESB 3.0 the registry that comes with WSO2 ESB is actually a combination of 3 registries.
+
+
+
Local repository (Used to store settings/metadata specific to the ESB node - This registry cannot be shared)
+
Configuration registry (Used to store settings/metadata that is shared across a cluster of ESB instances)
+
Governance registry (Used to store user specified metadata and resources and can be shared across an organization)
+
+
+The above registry instances are mounted to a single top level registry to provide a single unified view. Mount points of
+the three registries are /_system/local, /_system/config and /_system/governance respectively. One could browse
+the contents of the registry used by the ESB from the WSO2 ESB management console. To browse the registry, first
+login to the ESB management console and click on 'Registry Browser' link under the 'Registry' menu.
+
+
+
+
Using the Embedded Registry
+
+WSO2 ESB comes with an embedded WSO2 Governance Registry (WSO2 G-Reg) which is used by the ESB to store configurations
+and other deployment artifacts. The embedded registry instance makes use of the embedded ESB database. This is an H2
+database and the data files are by default stored in the directory named ESB_HOME/repository/database. If you are running
+the ESB in the embedded registry mode you should be careful not to manually alter any files stored in this directory as
+that might lead to database corruption or data loss.
+
+
+The embedded registry instance is configured by the registry.xml file which can be found in the ESB_HOME/repository/conf directory.
+In this configuration you could point the embedded registry to a database other than the default embedded H2 database.
+To change the database used by the registry or change the location of the database files edit the following section of the
+registry.xml.
+
+WSO2 Governance Registry can be run in two operational modes, namely the ReadWrite mode and the ReadOnly mode. By default
+it operates in the ReadWrite mode. This mode is set by the following element in the registry.xml file.
+
+
+<readOnly>false</readOnly>
+
+
+When the registry ReadOnly mode is set to true the ESB will not be able to store resources or write values
+to the registry. It will be capable of reading the existing resources only. If you want to make sure that
+the ESB or any of the ESB administrators do not alter the resources already stored in the registry this
+value should be set to true. Also in a clustered deployment it is recommended that only one ESB instance
+accesses the registry in the ReadWrite mode. All other ESB nodes should be accessing the registry in the
+ReadOnly mode to prevent different ESB servers from modifying the same resources at the same time. Any
+configuration updates should be done via the ESB instancce in ReadWrite mode.
+
+
+In addition to configuring the database instance you can configure media type handlers for various media types
+and setup various registry related system parameters by modifying the registry.xml file. The default
+configuration defines the following parameters.
+
+Please refer WSO2 G-Reg documentation for further information on setting up media type handlers and other
+global parameters.
+
+
+
Using the Remote Registry
+
+You can configure the ESB to use a remotely hosted WSO2 Governance Registry instance as the metadata and
+configuration store, instead of using the embedded registry instance. For that you need to edit the
+ESB_HOME/repository/conf/registry.xml file and modify the database configuration to point to the same
+database as the remote registry instance. Edit the dbconfig element in the registry.xml and make sure that
+the ESB is pointed to the same database as your WSO2 Governance Registry instance.
+
+
+
Setting Up Keystores
+
+WSO2 ESB uses several keystores to power the HTTPS transport and encrypt other confidential information
+such as administrator passwords. The keystore of the HTTPS transport is configured in the axis2.xml file
+under the HTTPS transport receiver and HTTPS transport sender configurations.
+
+The default keystores can be found in ESB_HOME/repository/resources/security directory. To change the keystores used
+by the HTTPS transport update the HTTPS transport receiver and sender configurations by specifying the paths
+to keystore files and other attributes of the files such as the keystore passwords. Under the <KeyStore>
+element two password values must be specified. The <Password> element should indicate the password of
+the keystore file. The <KeyPassword> elemenet should point to the password required to access the private key.
+
+
+The keystore used to encrypt administrator passwords and other confidential information in Carbon is configured in
+ESB_HOME/repository/conf/carbon.xml file. This keystore configuration can be found under the <security>
+element of the carbon.xml file. By default this is also used by the security management component when it
+comes to securing deployed Web Services with WS-Security.
+
+The bind address values and HTTP/HTTPS ports used by the ESB server should be configured in the
+ESB_HOME/repository/conf/axis2.xml file. To configure the bind address for the server, define the following
+parameter under the HTTP and HTTPS transport receiver configurations in the axis2.xml file.
+
+
+
+<parameter name="bind-address" locked="false">hostname or IP address</parameter>
+
+
+
+Similarly the HTTP and HTTPS ports used by the ESB HTTP-NIO transport should be configured by specifying the
+following parameter in the HTTP/HTTPS transport receiver configurations in the axis2.xml file.
+
+To change the ports used by the ESB management console you must modify the ESB_HOME/repository/conf/mgt-transports.xml.
+By default the management console would accept HTTPS requests on port 9443. Change the following parameter
+to set the HTTPS port used by the console.
+
+
+
+<parameter name="port">9443</parameter>
+
+
+
+In situations where a bind address is specifically defined in the axis2.xml it is recommended to define a
+WSDL prefix for the HTTP and HTTPS transports. The WSDL prefix value will be added to all the HTTP/HTTPS
+endpoints defined in the auto generated and user published WSDLs. To setup a WSDL prefix define the following
+parameter under the HTTP and HTTPS receiver configurations in the axis2.xml file.
+
+WSO2 ESB also allows you to setup a HTTP proxy port to deploy the ESB behind a proxy server using Apache mod_proxy.
+In such deployments you need to specify the HTTP proxy port in the axis2.xml file's HTTP/HTTPS receiver
+configurations using the following parameter.
+
+
+
+<parameter name="proxyPort">80</parameter>
+
+
+
+Please refer the WSO2 Carbon Transports Catalog for more information on setting up HTTP and HTTPS NIO transports
+and the servlet HTTPS transport for various deployments.
+
+
+
Performance Tuning WSO2 ESB
+
+We recommend that you install WSO2 ESB on Unix/Linux systems for production deployments. This section, for
+the most part, assumes that you have setup the ESB on a server running Unix/Linux. Also keep in mind that
+you should not take performance tuning steps described here lightly. Performance tuning requires you to modify
+some important system files which would effect all the programs running on the server. Hence care must be
+applied and please refer Unix/Linux documentation for more details on the configuration files described here.
+
+
+To optimize the network performance and OS performance for the ESB you will have to modify the /etc/sysctl.conf
+file. We recommend specifying the following entries in this file.
+
+These settings specify a larger port range, a more effective TCP connection timeout value and a number of
+other important parameters at the system level.
+
+
+Also you may specify the following entries in the /etc/security/limits.conf file to alter the number of allowed
+open files for system users.
+
+
+
+* soft nofile 4096
+* hard nofile 65535
+
+
+
+You can tune up the HTTP-NIO transport performance by creating a nhhtp.properties file for the ESB. This
+configuration file should be placed in the ESB_HOME/lib/core/WEB-INF/classes directory. You can change the
+socket timeout values, connection timeout values and HTTP receiver thread pool parameters by specifying them
+in the nhttp.properties file. A sample set of values that can be included in the nhttp.properties file is
+specified below.
+
+When the nhttp.properties file is not provided a set of default values will be used to initialize the
+thread pool of the HTTP-NIO transports. However the default values (mentioned in the above example) are
+suitable for most deployments and it is recommended to leave them unchanged without overriding the values
+using a nhttp.properties configuration file.
+
+ WSO2 Enterprise Service Bus -ESB System Administration Guide
+
+
+This is a manual on how to maintain and administrate a WSO2 ESB instance. It explains how various
+features of the ESB can be configured using the ESB management console and by modifying the ESB
+configuration files. Descriptions are provided on advanced features like Remote/Embedded
+registry configuration, adding external libraries, managing key stores and user management. It
+also explains how to performance tune the ESB runtime for extreme throughput.
+
+WSO2 ESB is a production grade open source ESB solution based on the lightweight Apache Synapse ESB.
+WSO2 ESB supports service mediation, message mediation, load balancing, clustering and many more
+enterprise integration techniques out of the box. It also supports a range of application and transport
+level protocols such as HTTP, JMS, Mail, VFS, FIX and a variety of industrial messaging standards such as
+Hessian.
+
+
+Starting from version 2.0, WSO2 ESB is based on the revolutionary WSO2 Carbon framework. WSO2 Carbon
+is an OSGi based middleware framework for SOA. Currently all WSO2 Java products are based on WSO2
+Carbon including WSO2 Governance Registry and WSO2 AS. Since ESB is OSGi based some knowledge in
+OSGi would be helpful in administrating the WSO2 ESB.
+
+
+This document explains how to get WSO2 ESB and install it on a server. The latter sections of the
+document illustrates how to setup and configure various features of the WSO2 ESB and how to performance
+tune various aspects of the product.
+
+
+
Document Conventions
+
+
'ESB_HOME' refers to the directory in the file system where WSO2 ESB is installed
+
'ESB_SRC_HOME' refers to the directory in the file system where WSO2 ESB source distribution is installed
+
All file paths follow Unix/Linux conventions but they resemble Windows file paths as well
+
+
+
Getting WSO2 ESB
+
+Binary distributions and source distributions of WSO2 ESB can be downloaded free from the
+WSO2 ESB home page in the WSO2 Oxygen Tank. Before proceeding to the
+downloads page you will be asked to register on the WSO2 Oxygen Tank. Registration is free and optional
+however it is recommended that you sign up for an account right away since registered Oxygen Tank users
+get exclusive access to our support forums and tons of valuable content related to SOA and Web Services.
+
+
+Once you are on the downloads page click on the relevant links to download a binary distribution or a
+source distribution of the latest stable release of the WSO2 ESB. If you are interested in an older
+version of the ESB, scroll down in the downloads page to locate the links to previous releases. You will
+also find links to download developer releases and nightly builds of the WSO2 ESB on the same page. We
+recommend that you always download the latest stable release. If you want to try out a feature that was
+added very recently you can try out a nightly build.
+
+
+If you downloaded a source distribution of the ESB you need to build the source to get the executable
+binary. WSO2 ESB uses an Apache Maven2 based build system and
+therefore you need to first download and install Apache Maven2. Please refer Maven2 documentation on
+installing and configuring Apache Maven2. Also note that Apache Maven2 requires Java to run.
+Once Maven2 is properly configured extract the downloaded source distribution and change your working
+directory to the directory that is created. Then execute the command 'mvn clean install' to run the builder.
+Once the build process is complete you can find the binary distribution archive in ESB_SRC_HOME/modules/distribution/target
+directory.
+
+
+
Installing and Running WSO2 ESB
+
+To install the WSO2 ESB simply extract the downloaded binary distribution archive. If you built WSO2 ESB
+from source extract the archive created by the builder. We recommend installing WSO2 ESB on a Unix/Linux
+system since that will enable you to get the maximum out of the ESB. In order to be able to start WSO2 ESB
+you first need Java 5 or higher. Having installed Java on your system please set the JAVA_HOME environment
+variable to point to the directory in which Java is installed.
+
+
Running WSO2 ESB in Standalone Mode
+
+Now you are all set to start WSO2 ESB in the standalone mode. Go to ESB_HOME/bin directory and if you are
+on Unix/Linux execute the wso2server.sh shell script or if you are on Windows execute the wso2server.bat
+batch file. This will start the ESB and you can see the progress of the startup procedure on the console.
+Please note that server startup may take some time depending on the hardware configuration of your system.
+The very first startup of the ESB can take up a few additional seconds since some first time configuration
+procedure is run by the ESB. If the server started up cleanly you should get an output similar to the following
+on the console.
+
+
+ [2010-03-23 10:34:17,594] INFO - Main Initializing system...
+ [2010-03-23 10:34:25,176] INFO - CarbonCoreActivator Starting WSO2 Carbon...
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Operating System : Linux 2.6.28-16-generic, amd64
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java Home : /opt/jdk1.6.0_16/jre
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java Version : 1.6.0_16
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Java VM : Java HotSpot(TM) 64-Bit Server VM 14.2-b01,Sun Microsystems Inc.
+ [2010-03-23 10:34:25,178] INFO - CarbonCoreActivator Carbon Home : /home/user/wso2esb-3.0.1
+ [2010-03-23 10:34:25,179] INFO - CarbonCoreActivator Java Temp Dir : /home/user/wso2esb-3.0.1/tmp
+ [2010-03-23 10:34:25,179] INFO - CarbonCoreActivator User : user, en-US, Asia/Colombo
+ [2010-03-23 10:34:29,715] INFO - RegistryCoreServiceComponent Registry Mode : READ-WRITE
+ [2010-03-23 10:34:32,349] INFO - CarbonServerManager Starting Carbon initialization...
+ [2010-03-23 10:34:32,561] INFO - ClusterBuilder Clustering has been disabled
+ [2010-03-23 10:34:32,742] INFO - DeploymentInterceptor Deploying Axis2 module : relay-3.0
+ [2010-03-23 10:34:32,799] INFO - DeploymentInterceptor Deploying Axis2 module : wso2mex-3.0
+ [2010-03-23 10:34:32,818] INFO - DeploymentInterceptor Deploying Axis2 module : rampart-SNAPSHOT
+ [2010-03-23 10:34:32,862] INFO - DeploymentInterceptor Deploying Axis2 module : sandesha2-3.0
+ [2010-03-23 10:34:32,916] INFO - DeploymentInterceptor Deploying Axis2 module : wso2caching-3.0
+ [2010-03-23 10:34:32,989] INFO - DeploymentInterceptor Deploying Axis2 module : wso2xfer-3.0
+ [2010-03-23 10:34:33,001] INFO - DeploymentInterceptor Deploying Axis2 module : rahas-SNAPSHOT
+ [2010-03-23 10:34:33,019] INFO - DeploymentInterceptor Deploying Axis2 module : savan-SNAPSHOT
+ [2010-03-23 10:34:33,034] INFO - DeploymentInterceptor Deploying Axis2 module : wso2throttle-3.0
+ [2010-03-23 10:34:33,125] INFO - DeploymentInterceptor Deploying Axis2 module : addressing-1.6-wso2v1
+ [2010-03-23 10:34:33,202] INFO - HttpCoreNIOSSLSender Loading Identity Keystore from : resources/security/wso2carbon.jks
+ [2010-03-23 10:34:33,228] INFO - HttpCoreNIOSSLSender Loading Trust Keystore from : resources/security/client-truststore.jks
+ [2010-03-23 10:34:33,256] INFO - HttpCoreNIOSender HTTPS Sender starting
+ [2010-03-23 10:34:33,269] INFO - HttpCoreNIOSender HTTP Sender starting
+ [2010-03-23 10:34:33,370] INFO - DeploymentInterceptor Deploying Axis2 service : echo
+ [2010-03-23 10:34:33,899] INFO - DeploymentInterceptor Deploying Axis2 service : version
+ [2010-03-23 10:34:37,698] INFO - DeploymentInterceptor Deploying Axis2 service : wso2carbon-sts
+ [2010-03-23 10:34:38,273] INFO - DeploymentInterceptor Deploying Axis2 service : XKMS
+ [2010-03-23 10:34:38,480] INFO - CarbonServerManager Repository : /home/user/wso2esb-3.0.1/repository/deployment/server/
+ [2010-03-23 10:34:38,506] INFO - EmbeddedRegistryBasedSubscriptionManager Connection established with the registry
+ [2010-03-23 10:34:38,530] INFO - ServiceBusInitializer Starting ESB...
+ [2010-03-23 10:34:38,573] INFO - ServiceBusInitializer Initializing Apache Synapse...
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using Synapse home : /home/user/wso2esb-3.0.1/.
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using synapse.xml location : /home/user/wso2esb-3.0.1/./repository/conf/synapse-config
+ [2010-03-23 10:34:38,580] INFO - SynapseControllerFactory Using server name : localhost
+ [2010-03-23 10:34:38,584] INFO - SynapseControllerFactory The timeout handler will run every : 15s
+ [2010-03-23 10:34:38,634] INFO - Axis2SynapseController Initializing Synapse at : Tue Mar 23 10:34:38 IST 2010
+ [2010-03-23 10:34:38,636] INFO - Axis2SynapseController Loading mediator extensions...
+ [2010-03-23 10:34:38,642] INFO - CarbonSynapseController Loading the mediation configuration from the file system
+ [2010-03-23 10:34:38,645] INFO - MultiXMLConfigurationBuilder Building synapse configuration from the synapse artifact repository at : ./repository/conf/synapse-config
+ [2010-03-23 10:34:38,646] INFO - XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration
+ [2010-03-23 10:34:39,077] INFO - SynapseConfigurationBuilder Loaded Synapse configuration from the artifact repository at : ./repository/conf/synapse-config
+ [2010-03-23 10:34:39,208] INFO - Axis2SynapseController Deploying the Synapse service...
+ [2010-03-23 10:34:39,212] INFO - Axis2SynapseController Deploying Proxy services...
+ [2010-03-23 10:34:39,212] INFO - Axis2SynapseController Deploying EventSources...
+ [2010-03-23 10:34:39,217] INFO - ServerManager Server ready for processing...
+ [2010-03-23 10:34:40,219] INFO - HttpCoreNIOSSLListener Loading Identity Keystore from : resources/security/wso2carbon.jks
+ [2010-03-23 10:34:40,221] INFO - HttpCoreNIOSSLListener Loading Trust Keystore from : resources/security/client-truststore.jks
+ [2010-03-23 10:34:40,237] INFO - HttpCoreNIOListener HTTPS Listener started on port : 8243
+ [2010-03-23 10:34:40,239] INFO - HttpCoreNIOListener HTTP Listener started on port : 8280
+ [2010-03-23 10:34:40,798] INFO - RegistryEventingServiceComponent Successfully Initialized Eventing on Registry
+ [2010-03-23 10:34:43,926] INFO - CarbonUIServiceComponent Mgt Console URL : https://10.100.1.209:9443/carbon/
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent Started Transport Listener Manager
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent Server : WSO2 ESB-3.0.1
+ [2010-03-23 10:34:43,940] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 25 sec
+
+
+To verify that the ESB is up and running fire off your Web browser and go to https://localhost:9443/carbon.
+This will take you to the WSO2 ESB on-line management console.
+
+
+
+You can login to the console using the default user credentials given below.
+
+
+
Username: admin
+
Password: admin
+
+
+If you can get that far then the ESB is properly installed and running.
+
+
+WSO2 ESB startup scripts stated above accept a few useful arguments.
+
+
+--cleanRegistry
+This argument will remove the settings stored in the registry and replace them with factory settings.
+It removes the /_system/config/repository collection and the /_system/local/repository collection in the
+registry which are used to store resources and configurations managed by the ESB and the underlying
+Carbon framework. Therefore the ESB will be forced to start fresh with factory settings. Starting from
+WSO2 ESB 3.0 the mediation configuration (sequences, proxies etc) is read from the file system by default.
+In that case this argument does not have any effect on the mediation configuration used by the ESB.
+
+
+--debug <port>
+Enables remote debugging on the ESB through the specified port.
+
+
+In addition to the above mentioned arguments the ESB startup scripts accept the following VM arguments.
+
+
+-DosgiConsole
+Starts the OSGi console from which you can directly interact with the underlying OSGi framework.
+
+
+-DloadFromRegistry
+This argument was first introduced in ESB 3.0. When set to 'true' it will force the ESB to load the mediation
+configuration from the registry, instead of loading it from the file system. Please note that for this
+argument to work the registry must contain a valid mediation configuration stored in it. Therefore one
+cannot pass this argument to a fresh ESB instance which is starting from a clean registry. However after the
+first startup the registry will contain a mediation configuration and hence subsequent startups can proceed
+with this VM parameter.
+
+
+-DwriteToFile
+Newly added to WSO2 ESB 3.0, this argument takes effect only when the mediation configuration is loaded
+from the registry. When set to 'true' this parameter will force the ESB to save the configuration loaded
+from the registry to the local file system at startup.
+
+
+
Running ESB Samples
+
+WSO2 ESB ships with a large number of sample configurations which enables you to get familiar with the
+product quickly and easily. Please refer the WSO2 ESB samples guide for sample configuration and details
+on how to run them. You may start WSO2 ESB using those sample configuration by executing the
+ESB_HOME/bin/wso2esb-sample.sh (for Unix/Linux) or ESB_HOME/bin/wso2esb-sample.bat (for Windows).
+These launcher scripts take a mandatory argument -sn. Use this argument to specify the sample number.
+
+
+eg: ./wso2esb-sample.sh -sn 250 (This will launch the ESB using the Sample 250 configuration)
+
+
+The sample configuration files can be found in the ESB_HOME/repository/samples directory.
+
+
+When launching the ESB using the wso2esb-sample.sh/wso2esb-sample.bat scripts a new registry context root
+will be created for storing data and configurations related to that sample. Also note that these launcher
+scripts accept the same set of arguments accepted by the wso2server.sh and wso2server.bat.
+
+
+
WSO2 ESB Directory Hierarchy
+
+When you extract a WSO2 ESB binary distribution archive you will find the following directories in the
+top level directory that is created.
+
+
+
+bin -
+ Contains all the necessary scripts to interact with the WSO2 ESB instance. There are shell scripts
+ (with .sh extension) for Unix/Linux users and batch files (with .bat extension) for Windows users.
+ In general you will find the following scripts in this directory.
+
+
+ wso2esb-samples.sh/wso2esb-samples.bat - Launches WSO2 ESB using one of the sample configurations
+
+
+ wsdl2java.sh/wsdl2java.bat - Launches the Java stub generation tool for Web Services
+
+
+ java2wsdl.sh/java2wsdl.bat - Launches the WSDL generation tool for Java Web Services
+
+
+ tcpmon.sh/tcpmon.bat - Launches TCPMon, the TCP connection monitor
+
+
+ chpasswd.sh/chpasswd.bat -Use this script to change the administrator password without signing in to the server
+
+
+ ciphertool.sh/ciphertool.bat -<TODO: Indika>
+
+
+ daemon.sh -Start WSO2 ESB as a daemon on Unix/Linux systems
+
+
+ install.bat - Install WSO2 ESB as a background service on Windows
+
+
+ repowriter.sh/repowriter.bat
+
+
+ carbondump.sh/carbondump.bat - Create a dump file containing runtime information related to the ESB (Dump file is useful in debugging issues)
+
+
+
+ In addition to the above mentioned scripts you will find a subdirectory named 'native' in the bin
+ directory.
+
+
+dbscripts -
+Contains a collection of database scripts required to create the Carbon database on a variety of database
+management systems.
+
+
+lib -
+The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance.
+The log4j.properties file used by the ESB is also stored here. In addition to that, the Carbon webapp
+can be found in the lib/core directory. The lib/core/WEB-INF/classes directory houses some of
+important configuration files of the ESB such as nhttp.properties, synapse.properties and datasources.properties.
+
+
+repository -
+This directory houses all the OSGi bundles, service artifacts, modules, configurations and related resources
+used by the WSO2 ESB instance. The repository/components/plugin directory will contain all the necessary OSGi bundles
+at server runtime. In the components subdirectory you can also find a set of child directories such as lib,
+mediators and extensions which can be used to deploy custom mediators and third party dependencies into the ESB.
+The repository/conf subdirectory contains all the crucial configuration files such as axis2.xml and carbon.xml. The
+mediation configuration is loaded from the repository/deployment/server/synapse-config directory. Also starting from ESB 3.0
+server logs are stored in the repository/logs directory.
+
+
+resources -
+Contains additional resources required by WSO2 ESB. This includes security related resources such as
+keystores.
+
+
+samples -
+The samples directory contains the sample Axis2 server, sample Axis2 client, source code of the sample
+services and clients and the ANT scripts required to build and run them.
+
+
+tmp -
+The temporary files directory used by the ESB
+
+
+
Using the WSO2 ESB Management Console
+
+WSO2 ESB management console is a Web based control panel powered by JSP and AJAX which enables system administrators
+to interact with a running ESB instance, without having to touch any underlying configuration files. The
+management console allows the users to command and control proxy services, sequences, transports, local
+entries, registry, modules, endpoints and much more. ESB management console is a great way to try things
+out without having to edit the actual configuration files or without having to restart the ESB for
+changes to take effect.
+
+
+We recommend using Mozilla Firefox 3 or Internet Explorer 7 to access the WSO2 ESB management console.
+Please note that your browser must be JavaScript enabled to take the full advantage of the management console.
+To access the ESB management console fire off you Web browser and navigate to
+https://<Server Host>:<Server Port>/<Context>. If you are running the Web browser on
+the same machine as the ESB you may use 'localhost' as the server host. The default port and the context
+for the ESB management console are '9443' and 'carbon' respectively. If you entered the URL correctly you
+will be taken to the management console's login page.
+
+
+On the login page enter 'admin' as the username and the password to login to the system. You can change
+user credentials and even add new users once you login. Controls and wizards in the ESB management console
+are pretty much self explanatory. However if you are having trouble finding your way in the management
+console, click on the 'Help' link at the top right corner of any page to access context sensitive help.
+
+
+Please note that the ESB management console makes use of the default HTTPS servlet transport which is
+configured in the ESB_HOME/repository/conf/mgt-transports.xml file. It is important that this transport
+is always properly configured in the mentioned file. Otherwise the management console might be inaccessible
+to the users.
+
+
+
User Management
+
+To access the WSO2 ESB user management features, first sign in to the ESB management console and click on
+'User and Roles' under the 'Configure' menu in the left navigation bar. This will take you to the User
+Management home page which contains the controls illustrated below.
+
+
+
+From here you can manage users and roles. A user is associated with one or more roles (generally specified at
+user creation time) and each role is associated with zero or more permissions (generally specified at
+role creation time). Therefore the set of permissions owned by a user is determined by the roles assigned to
+that user. A user owns the union of all the permissions associated with the roles assigned to that user. By
+default ESB comes with only two roles, the 'admin' role and the 'everyone' role. There is also a third role
+named 'system' which is not visible in the management console. Every user will be assigned the
+'everyone' role. This role does not have any permissions by default. Users with the 'admin' role have full
+access to all the features and controls in the ESB (all permissions). By default the user 'admin' is assigned the
+'admin' role along with the 'everyone' role. Also note that the ESB UI does not allow configuing the permissions
+assigned to the 'admin' role.
+
+
+The permission model of WSO2 ESB is hierarchical. Therefore permissions
+can be assigned in a fine grained manner or a coarse grained manner. For an example one could assign the 'Configure'
+admin permission to a role. The role will be able to configure event sources, scheduled tasks and many other things.
+This is a coarse grained permission allocation. On the other hand one may assign the specific
+'Transport Management', 'Configure Tasks' or 'Configure Data Sources' permission to a role which is a fine grained
+permission allocation. The full ESB permission tree looks as follows.
+
+
+
+Use the 'User Management' page in the UI to add new users, add new roles, assign and withdraw permissions from
+roles and change login credentials of users. To add a new role to the system click on 'Roles' in the User
+Management home page and on the page that appears click the 'Add New Role' link. This will start the 'Add
+Role' wizard. The wizard will guide you though the process of creating a role by specifying a unique name
+for the role and adding the relevant permissions to the new role. Similarly to create a new user, click on
+'Users' in the User Management home page. Then from the next page that appears select 'Create New User' link.
+This will launch the 'Add User' wizard which will enable you to create a new user account with login credentials
+and associate the account with one or more existing roles. The ESB management console also enables you to
+search for and modify existing users and roles.
+
+
Using External User Stores (LDAP/AD)
+
+You can also connect an external user store (database) with WSO2 ESB. Such external stores are configured through
+the user-mgt.xml file which can be found in the repository/conf directory. Settings required to connect an LDAP
+based user store or an Active Directory based user store are provided in the default user-mgt.xml file. Simply
+uncomment the relevant entries in the file and update the required parameters. Also note that the ESB can have
+only one user store at any given moment. Hence when you want to connect to a different user store you also need
+to comment out the default user store settings (LDAP user store manager) in the user-mgt.xml file. Configuration
+settings for the LDAP based user store looks as follows.
+
+For more information on using external user stores please refer User Core Admin
+Guide.
+
+
+
Setting Up Logging
+
+Logging is one of the most important aspects of a production grade server. A properly configured logging system
+is vital in identifying errors, security threats and usage patterns. WSO2 ESB uses a log4j based logging mechanism
+through Apache Commons Logging facade library. The log4j.properties file which governs how logging is performed by
+the server can be found in ESB_HOME/lib directory. However it is recommended not to make any alterations to the
+default log4j.properties file. The recommended way of setting up logging is by using the ESB management console.
+Simply login to the management console and click on 'Logging' under the 'Configure' menu in the left navigation bar.
+From here you can setup various appenders and configure log levels for various loggers. Any changes to the logging
+configuration you make from the management console will get priority over what is defined in the actual
+log4j.properties file.
+
+
+By default WSO2 ESB comes with the following log appenders configured.
+
+
+
+ CARBON_CONSOLE (Logs to the console when the server is running)
+
+
+ CARBON_LOGFILE (Writes the logs to ESB_HOME/repository/logs/wso2-esb.log)
+
+
+ CARBON_MEMORY
+
+
+ CARBON_SYS_LOG
+
+
+ SERVICE_APPENDER (Writes mediation time audit messages to ESB_HOME/repository/logs/wso2-esb-service.log)
+
+
+ TRACE_APPENDER (Writes mediation time tracing/debug messages to the ESB_HOME/repository/logs/wso2-esb-trace.log for tracing enabled services)
+
+
+ TRACE_MEMORYAPPENDER
+
+
+
+Tracing can be enabled for individual mediation sequences and proxy services from the 'Mediation Sequences'
+home page and the 'Service Dashboard' page respectively. Click on the 'Sequences' link under 'Mediation' in
+the 'Manage' menu of the left navigation bar to access the 'Mediation Sequences' page. This page lists all
+the deployed sequences. Each sequence gives you the options to enable/disable tracing. To access the service
+dashboard for a proxy service go to the Services List page and click on the proxy service that you are
+interested in. Once a sequence or a proxy service is tracing enabled you can view the generated log messages
+by visiting the 'Mediation Tracer' page under the 'Monitor' menu. The 'Monitor' menu also gives you access
+to the system logs and the SOAP tracer logs all through the Web interface itself.
+
+
+
+
Configuring the Underlying Axis2 Engine
+
+WSO2 ESB is based on Apache Synapse lightweight ESB which in turns uses the Apache Axis2 SOAP engine. Every
+WSO2 ESB administrator is expected to have at least a basic understanding of Axis2 and Axis2 configuration model.
+The global configuration of the Axis2 engine is specified in a file named axis2.xml. This configuration file can
+be found in the ESB_HOME/repository/conf directory. Any settings configured in the axis2.xml file are directly
+applied to the server at startup time. Generally, one can configure the following settings in the axis2.xml file.
+
+
+
+ Global system parameters (eg: hotdeployment, hotupdate, servicepath etc)
+
+
+ Global Axis2 listeners (Axis2 observer implementations which are notified of Axis2 events)
+
+
+ Deployers
+
+
+ Message receivers, formatters and builders
+
+
+ Transport receivers and senders
+
+
+ Globally engaged modules (eg: addressing)
+
+
+ Clustering
+
+
+ Axis2 phases
+
+
+
+The axis2.xml file which comes with WSO2 ESB contains examples and descriptions illustrating how the above
+can be configured and setup for common deployment scenarios.
+
+
+
Mediation Configuration
+
+Mediation configuration is the most important part of the WSO2 ESB as far as the functionality of the service
+bus is concerned. The mediation configuration consists of following items.
+
+
+
Endpoints
+
Sequences
+
Proxy services
+
Scheduled tasks
+
Event sources
+
Local entries
+
Priority executors (new in ESB 3.0)
+
+
+Each of the above items can be configured through the management console. New instances of above items
+can be added to the ESB, existing items can be modified or removed. The 'Synapse' entry in the 'Configure'
+menu provides a single unified view of the entire mediation configuration and allows the user to make
+modifications to it using the Synapse configuration language.
+
+
+
Persistence
+
+By default the mediation configuration is stored in the file system as well as in the registry. In the file
+system, configuration is saved under the ESB_HOME/repository/conf/synapse-config directory. There are separate
+subdirectories to store different types of configuration items. When you add a new item using the management
+console it will be saved to a new file under the synapse-config directory. For an example, if you add a new
+endpoint named 'foo' from the UI, it will be saved to a file named foo.xml in ESB_HOME/repository/conf/synapse-config/endpoints
+directory. Any further modifications to the endpoint foo will be saved back to the same file. However if you
+add a new item from the Synapse configuration editor in the UI (in Configure menu) it will be saved to
+ESB_HOME/repository/conf/synapse-config/synapse.xml file.
+
+
+You can customize the behavior of mediation configuration persistence by editing the carbon.xml file. You may
+add the following entry to the carbon.xml and tune up the parameter values as appropriate.
+
+Set the LoadFromRegistry to 'true' if you want to load the mediation configuration from the registry instead of the file
+system. SaveToFile option takes effect only when LoadFromRegistry is set to 'true'. If both values are set to 'true'
+the mediation configuration will be loaded from the registry and will also be saved to the local file system at
+startup. If you want to prevent the ESB from saving the mediation configuration to the registry set RegistryPersistence
+to 'disabled'. By default this is enabled. You can turn off all persistence activies by setting Persistence to
+'disabled'. In that case mediation configuration will not be saved to the file system nor the registry. The configuration
+in the disk/registry is effectively frozen. But the changes made from the UI will still take effect in the runtime. But
+such changes will not survive a restart since they are not saved to persistence store.
+
+
+
Dependency Tracking
+
+WSO2 ESB keeps track of the dependencies among various mediation configuration elements. In a typical mediation
+configuration there are often dependencies among sequences, endpoints, proxy services and local entires. A
+sequence can make references to other sequences, local entries and endpoints. A proxy service may also make references to
+sequences and endpoints. The ESB runtime by default keeps track of such dependencies and warns the user, if he
+attempts to remove a particular item from the configuration which is a dependency for another item.
+
+
+
+The dependency tacking process takes up a few CPU cycles and memory to compute and keep track of the
+dependencies at runtime. Therefore it is recommended to turn this feature off in production environments.
+To turn off dependency tracking open up the synapse.properties file which can be found in the
+ESB_HOME/webapps/ROOT/WEB-INF/classes directory and comment out the following line:
+
+You also need to restart the ESB for the change to take effect. Commenting out the above entry will disengage
+the dependency tracker and hence the ESB will stop computing and keeping track of dependencies among
+different configuration items in the mediation configuration.
+
+
+
Hot Deployment of Mediation Artifacts
+
+WSO2 ESB 3.0 introduces the hot deployment feature for mediation artifacts. With this feature you can hot
+deploy artifacts like endpoints, sequences and proxy services into the ESB_HOME/repository/conf/synapse-config
+directory. Simply save the artifact configuration to an XML file and drop it into the relevant subdirectory in
+the synapse-config parent directory. ESB will pick up the newly added file and get it deployed in the server
+runtime. Once deployed you will be able to view it through the management console and make further changes if
+necessary. Similarly you can make changes to an existing file which contains a mediation configuration item
+and the ESB will pick the changes up through the hot update feature.
+
+
+In a production system it is recommended to turn off hot deployment and update for smooth operation of the ESB.
+To turn off hot deployment and hot update open up the axis2.xml file in repository/conf directory and set the
+following two parameter values to 'false'. (These are by default set to 'true')
+
+New features can be easily installed into the ESB by using the 'WSO2 Carbon Component Manager' that comes
+with the ESB. Component manager is powered by Equinox P2 and allows you to connect to a remote or local P2
+repository and get any feature installed into the ESB runtime. You can also uninstall existing features of
+the ESB and come up with a customized version of WSO2 ESB tailored to meet your requirements.
+
+
+To use the component manager, login to the management console and click on 'Features' under the
+'Configure' menu. Go to the 'Settings' tab and click on 'Manage Repositories'. Click 'Add New Repository'
+and specify the P2 repository to which you wish to connect to. The official WSO2 P2 repository is available
+over http://dist.wso2.org/p2.
+
+
+Once the repository is configured go to the 'Available Features' tab to browse through the features and get them
+installed to the ESB. The installation of a feature can take a while depending on the network bandwidth and
+hardware configuration available. Once a feature has been successfully installed you will be prompted to logout
+and restart the ESB.
+
+
+If you wish to uninstall an existing feature go to the 'Installed Features' tab, select the features to be
+uninstalled and click on 'Uninstall' at the bottom of the page.
+
+
+
+
Adding External Dependencies to the System
+
+You would want to deploy external dependency jars into the WSO2 ESB server in many scenarios. Generally one
+would want to add external dependencies in following situations.
+
+
+
+ Enabling and configuring a new transport (Many transport implementations such as JMS and FIX require
+ adding a set of external dependencies to the server)
+
+
+ Adding a custom mediator
+
+
+ Adding a custom handler or a module
+
+
+
+To add an external dependency to the WSO2 ESB you simply need to copy the necessary jar file(s) to
+ESB_HOME/repository/components/lib or ESB_HOME/repository/components/extensions. Jars copied to these
+directories will be automatically converted into OSGi bundles on ESB startup. Jars copied to
+ESB_HOME/repository/components/extensions will be converted into OSGi bundles which are fragments of the
+main system bundle. WSO2 ESB also provides the ESB_HOME/repository/components/mediators directory to deploy
+custom mediators into the ESB.
+
+
+Currently WSO2 ESB does not support deploying external dependencies at runtime. Therefore after copying
+the external dependency jars to the relevant locations the server must be restarted for the server to be
+able to pick them up.
+
+
+
Registry Integration
+
+WSO2 ESB makes use of a WSO2 Governance Registry instance to store various configurations and artifacts
+such as proxy services, sequences and endpoints. Simply put a registry is a content store and a metadata
+repository. Various SOA artifacts such as services, WSDLs and configuration files can be stored in a
+registry keyed by unique paths. A path is similar to a Unix file path. In WSO2 ESB all configurations
+pertaining to modules, logging, security, data sources and other service groups are stored in the registry
+by default. Starting from WSO2 Carbon 2.0 all the transport configurations are also stored in the registry.
+WSO2 ESB 2.1 introduced a feature to directly store endpoints and sequences to the registry with a user
+specified key value.
+
+
+WSO2 ESB accesses the registry in two ways. In many cases it accesses the registry by directly calling the
+registry API from Carbon components. In some special situations it gains access to the registry through the
+underlying Apache Synapse configuration. It is important that Synapse configuration should always include a
+registry definition. That is, the ESB configuration should include the following registry definition.
+
+Starting from ESB 3.0 the registry that comes with WSO2 ESB is actually a combination of 3 registries.
+
+
+
Local repository (Used to store settings/metadata specific to the ESB node - This registry cannot be shared)
+
Configuration registry (Used to store settings/metadata that is shared across a cluster of ESB instances)
+
Governance registry (Used to store user specified metadata and resources and can be shared across an organization)
+
+
+The above registry instances are mounted to a single top level registry to provide a single unified view. Mount points of
+the three registries are /_system/local, /_system/config and /_system/governance respectively. One could browse
+the contents of the registry used by the ESB from the WSO2 ESB management console. To browse the registry, first
+login to the ESB management console and click on 'Registry Browser' link under the 'Registry' menu.
+
+
+
+
Using the Embedded Registry
+
+WSO2 ESB comes with an embedded WSO2 Governance Registry (WSO2 G-Reg) which is used by the ESB to store configurations
+and other deployment artifacts. The embedded registry instance makes use of the embedded ESB database. This is an H2
+database and the data files are by default stored in the directory named ESB_HOME/repository/database. If you are running
+the ESB in the embedded registry mode you should be careful not to manually alter any files stored in this directory as
+that might lead to database corruption or data loss.
+
+
+The embedded registry instance is configured by the registry.xml file which can be found in the ESB_HOME/repository/conf directory.
+In this configuration you could point the embedded registry to a database other than the default embedded H2 database.
+To change the database used by the registry or change the location of the database files edit the following section of the
+registry.xml.
+
+WSO2 Governance Registry can be run in two operational modes, namely the ReadWrite mode and the ReadOnly mode. By default
+it operates in the ReadWrite mode. This mode is set by the following element in the registry.xml file.
+
+
+<readOnly>false</readOnly>
+
+
+When the registry ReadOnly mode is set to true the ESB will not be able to store resources or write values
+to the registry. It will be capable of reading the existing resources only. If you want to make sure that
+the ESB or any of the ESB administrators do not alter the resources already stored in the registry this
+value should be set to true. Also in a clustered deployment it is recommended that only one ESB instance
+accesses the registry in the ReadWrite mode. All other ESB nodes should be accessing the registry in the
+ReadOnly mode to prevent different ESB servers from modifying the same resources at the same time. Any
+configuration updates should be done via the ESB instancce in ReadWrite mode.
+
+
+In addition to configuring the database instance you can configure media type handlers for various media types
+and setup various registry related system parameters by modifying the registry.xml file. The default
+configuration defines the following parameters.
+
+Please refer WSO2 G-Reg documentation for further information on setting up media type handlers and other
+global parameters.
+
+
+
Using the Remote Registry
+
+You can configure the ESB to use a remotely hosted WSO2 Governance Registry instance as the metadata and
+configuration store, instead of using the embedded registry instance. For that you need to edit the
+ESB_HOME/repository/conf/registry.xml file and modify the database configuration to point to the same
+database as the remote registry instance. Edit the dbconfig element in the registry.xml and make sure that
+the ESB is pointed to the same database as your WSO2 Governance Registry instance.
+
+
+
Setting Up Keystores
+
+WSO2 ESB uses several keystores to power the HTTPS transport and encrypt other confidential information
+such as administrator passwords. The keystore of the HTTPS transport is configured in the axis2.xml file
+under the HTTPS transport receiver and HTTPS transport sender configurations.
+
+The default keystores can be found in ESB_HOME/repository/resources/security directory. To change the keystores used
+by the HTTPS transport update the HTTPS transport receiver and sender configurations by specifying the paths
+to keystore files and other attributes of the files such as the keystore passwords. Under the <KeyStore>
+element two password values must be specified. The <Password> element should indicate the password of
+the keystore file. The <KeyPassword> elemenet should point to the password required to access the private key.
+
+
+The keystore used to encrypt administrator passwords and other confidential information in Carbon is configured in
+ESB_HOME/repository/conf/carbon.xml file. This keystore configuration can be found under the <security>
+element of the carbon.xml file. By default this is also used by the security management component when it
+comes to securing deployed Web Services with WS-Security.
+
+The bind address values and HTTP/HTTPS ports used by the ESB server should be configured in the
+ESB_HOME/repository/conf/axis2.xml file. To configure the bind address for the server, define the following
+parameter under the HTTP and HTTPS transport receiver configurations in the axis2.xml file.
+
+
+
+<parameter name="bind-address" locked="false">hostname or IP address</parameter>
+
+
+
+Similarly the HTTP and HTTPS ports used by the ESB HTTP-NIO transport should be configured by specifying the
+following parameter in the HTTP/HTTPS transport receiver configurations in the axis2.xml file.
+
+To change the ports used by the ESB management console you must modify the ESB_HOME/repository/conf/mgt-transports.xml.
+By default the management console would accept HTTPS requests on port 9443. Change the following parameter
+to set the HTTPS port used by the console.
+
+
+
+<parameter name="port">9443</parameter>
+
+
+
+In situations where a bind address is specifically defined in the axis2.xml it is recommended to define a
+WSDL prefix for the HTTP and HTTPS transports. The WSDL prefix value will be added to all the HTTP/HTTPS
+endpoints defined in the auto generated and user published WSDLs. To setup a WSDL prefix define the following
+parameter under the HTTP and HTTPS receiver configurations in the axis2.xml file.
+
+WSO2 ESB also allows you to setup a HTTP proxy port to deploy the ESB behind a proxy server using Apache mod_proxy.
+In such deployments you need to specify the HTTP proxy port in the axis2.xml file's HTTP/HTTPS receiver
+configurations using the following parameter.
+
+
+
+<parameter name="proxyPort">80</parameter>
+
+
+
+Please refer the WSO2 Carbon Transports Catalog for more information on setting up HTTP and HTTPS NIO transports
+and the servlet HTTPS transport for various deployments.
+
+
+
Performance Tuning WSO2 ESB
+
+We recommend that you install WSO2 ESB on Unix/Linux systems for production deployments. This section, for
+the most part, assumes that you have setup the ESB on a server running Unix/Linux. Also keep in mind that
+you should not take performance tuning steps described here lightly. Performance tuning requires you to modify
+some important system files which would effect all the programs running on the server. Hence care must be
+applied and please refer Unix/Linux documentation for more details on the configuration files described here.
+
+
+To optimize the network performance and OS performance for the ESB you will have to modify the /etc/sysctl.conf
+file. We recommend specifying the following entries in this file.
+
+These settings specify a larger port range, a more effective TCP connection timeout value and a number of
+other important parameters at the system level.
+
+
+Also you may specify the following entries in the /etc/security/limits.conf file to alter the number of allowed
+open files for system users.
+
+
+
+* soft nofile 4096
+* hard nofile 65535
+
+
+
+You can tune up the HTTP-NIO transport performance by creating a nhhtp.properties file for the ESB. This
+configuration file should be placed in the ESB_HOME/lib/core/WEB-INF/classes directory. You can change the
+socket timeout values, connection timeout values and HTTP receiver thread pool parameters by specifying them
+in the nhttp.properties file. A sample set of values that can be included in the nhttp.properties file is
+specified below.
+
+When the nhttp.properties file is not provided a set of default values will be used to initialize the
+thread pool of the HTTP-NIO transports. However the default values (mentioned in the above example) are
+suitable for most deployments and it is recommended to leave them unchanged without overriding the values
+using a nhttp.properties configuration file.
+
The mediation engine of WSO2 ESB is driven off a set of XML configuration files.
+This allows the mediation configuration to be easily
+hand edited, backed up from the file system, or even included into version
+control for easier management and administration (e.g. moving a configuration from
+development, through QA, staging and into production). The configuration files
+that drives the mediation engine are stored in the ESB_HOME/repository/conf/synapse-config
+directory. These configuration files are written using the Synapse configuration language
+which is a simple and easy to learn domain specific language based on XML.
+
+
It is always recommended to use the graphical wizards and tools provided in the
+WSO2 ESB management console to setup the mediation configuration, thus avoiding having to
+write XML configurations manually. The ESB management console offers a rich set of tools
+that allows you to build mediation configurations easily without writing a single line of XML.
+However it is helpful to have a basic understanding
+on the Synapse configuration language as well as on how the mediation configuration is
+physically stored on the disk. A decent knowledge on the Synapse configuration language
+will enable you to develop efficient and concise mediation configurations. Understanding
+how the files are stored will allow you to use third party tools and scripts for configuration
+management activities.
+
+
This guide walks you through the Synapse configuration language and how various
+configuration files are stored under the synapse-config directory of the ESB. It starts
+off with a breif introduction to the high level concepts associated with mediation and then
+explores into how such concepts can be implemented using the Synapse configuration
+language in WSO2 ESB.
+
+
The Mediation Engine and Modes of Operation
+
As the diagram below depicts, the mediation engine consists of Proxy
+services, Endpoints, Sequences and Startup jobs managed by the ESB. It
+also contains the interface to the Registry/Repository being used by the mediation engine.
+Items like sequences, endpoints and proxy services could be made to
+reference different configuration elements that
+are served through the Registry. When using the Registry to hold
+pieces of the configuration, certain elements such as endpoint definitions,
+sequences and local entries could be updated dynamically while the ESB
+is executing, and the Registry could trigger a re-load as configured.
+
+
+
+
Typically the ESB is deployed between the actual client and a backend
+service implementation to mediate the message flow in between. Thus WSO2
+ESB can accept a message on behalf of the actual service, perform
+authentication, validation, transformation, logging, routing based on the
+content etc. and then decide the destination target endpoint for the message
+and direct it to an actual service implementation. The ESB can also
+detect timeouts, transport failures during communication or introduce load
+balancing, throttling or caching where necessary. For fault scenarios such as
+authentication failure, or schema validation failure, the WSO2 ESB can be
+configured to return a custom message or a SOAP fault to the requesting client
+without forwarding the request to the actual service.
+
+
WSO2 ESB can operate in four modes of operation:
+
+
Service mediation (Proxy services)
+
+
In Service mediation, the ESB exposes a service endpoint on the ESB,
+that accepts messages from clients. Typically these services acts as proxies
+for existing (external) services, and the role of the ESB would be to "mediate"
+these messages before they are proxied to the actual service. In this mode,
+WSO2 ESB 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 etc. 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 through
+the proxy service. A proxy service maybe a SOAP or 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 - e.g. CSV content being the payload
+
+
Message mediation (Sequences)
+
+
In Message mediation, WSO2 ESB can act as a transparent proxy for clients -
+if they are directed to point to WSO2 ESB as a http proxy. This way,
+WSO2 ESB could be configured to filter all messages on a network for logging,
+access control etc, and could "mediate" messages without the explicit knowledge
+of the original client. If the ESB receives a message that is not accepted by
+any proxy service, this message is handled through message mediation as well.
+Message mediation always processes messages according to the mediation sequence
+defined as "main".
+
+
Task Scheduling (Startup jobs)
+
With the task scheduling capabilities of WSO2 ESB, one or more tasks can be
+configured to execute in a periodic manner in the ESB runtime. Tasks are
+custom developed Java code which are deployed into the ESB by the user. Tasks
+could be written to inject messages into the service bus periodically, poll
+databases and message queues, cleanup the environment and ping backend services
+to check availability.
+
+
Eventing (Event Sources)
+
With event sources and the event publisher mediator, WSO2 ESB can act as an
+event broker. It can receive and manage subscription requests from client applications
+and then dispatch events to the subscribers based on a pre configured criteria.
+Also if required events can be mediated through sequences before delivering them
+to the subscribers. The subscription manager implementation is pluggable and WSO2
+ESB ships with a registry based subscription manager and an in memory subscription
+manager.
+
+
Concepts and Configuration Elements
+
The following section explaing the high level concepts associated with the WSO2
+ESB mediation engine and how they map to various configuration elements in the ESB
+configuration. It is very important to understand these high level concepts regardless
+of how you are planning to develop mediation configuration. Even if you are using
+the graphical tools to develop configuration it is still necessary to understand these
+concepts.
WSO2 ESB defines a 'mediator' as a component that performs some
+mediation action on a message during the process flow. Thus a mediator gets
+full access to a message at the point where it is defined to gain control, and
+could inspect the message, modify it or take an external action depending on
+some attributes or values of the current message. A mediation sequence,
+commonly called a 'sequence' is a list of such 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.xml configuration or within the
+Registry. Writing a custom mediator in Java is easy and the supplementary
+documentation provides more details on this. The 'Class' and 'POJO (command)"
+mediators allows one to plugin a Java class easily into the mediation engine with
+minimal effort. In addition, the Script mediator allows one to provide an
+Apache BSF script (e.g. Javascript, Ruby, Groovy etc) for mediation.
+
+
A mediation configuration holds two special sequences named "main" and
+"fault". These may be defined within the synapse.xml, or externally via the
+Registry. If either is not found, a suitable default is generated at runtime by
+the ESB. The default "main" sequence will simply send a message without
+mediation, while the default "fault" sequence would log the message including
+the payload and any error/exception encountered and stop further processing.
+The 'fault' sequence executes whenever WSO2 ESB 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 control branches to the fault handler if an error is encountered
+during the execution of the initial sequence.
An Endpoint definition within the mediation configuration 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 WSO2 ESB supports
+Failover and Load-balance endpoints - which are defined over a group of
+endpoints. Endpoints may be defined within the synapse-config configuration or
+within the Registry.
+
+
Proxy Services
+
+
A proxy service is a virtual services hosted in the ESB runtime. For a service client it
+appears to be a real Web Service which accepts service requests. The proxy service mediates
+any accepted requests and forwards them to a specified endpoint, most of the time to an
+actual Web Service. The responses coming back from the target endpoint are mediated back to
+the client which sent the original service request. Proxy services often make references to
+sequences, endpoints and local entries. A proxy service can enforce various QoS requirements
+on a request and can be exposed over a user specified transport. Therefore they are often used
+to expose existing Web Services over a different transport or a QoS configuration. For an
+example a proxy service can be used to expose an HTTP service over JMS or it can be used to
+expose an unsecured service in a secured manner using WS-Security standards.
+
+
Unlike sequences and endpoints which can be stored and loaded from the registry, proxy
+services cannot be loaded from the registry. However a proxy service can make references
+to sequences and endpoints stored in the registry.
A Task is a custom Java class that implements the
+org.apache.synapse.startup.Task interface that defines a single "public void
+execute()" method. Such a task can be scheduled and managed via the
+ESB. The scheduling information for a task can be specified in the cron format
+or a simple format by the user. A task may also be specified as a one-time task
+where required, and can be used to trigger a callout or inject a message into
+the ESB.
A mediation configuration can refer to an external Registry / Repository for
+resources used such as WSDL's, Schemas, Scripts, XSLT or XQuery transformations
+etc. One or more remote registries may be hidden or merged behind a local
+Registry interface defined to a Synapse configuration. Resources from an
+external registry are looked up using "keys" - which are known to the external
+registry. WSO2 ESB ships with a simple URL based registry implementation
+that uses the file system for storage of resources, and URL's or fragments as
+"keys".
+
+
A Registry may define a duration for which a resource served may be cached
+by the ESB runtime. If such a duration is specified, WSO2 ESB is
+capable of refreshing the resource after cache expiry to support dynamic
+re-loading of resource 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 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 a configuration. To integrate WSO2 ESB with a custom / new Registry
+or repository, one needs to implement the org.apache.synapse.registry.Registry
+interface to suit the actual Registry being used.
+
+
Event Sources
+
An event source is used to define the event source and the subscription manager
+configuration used in the eventing implementation of WSO2 ESB. An event source provides
+a service URL that can be used to the send subscriptions and events (events that are
+not required to go through a mediation flow).
+
Prioriy executors can be used to execute sequences with a given priority. Priority executors are
+ used in high load scenarios where user wants to execute differrent sequences with different
+ priorities. 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 valid meaning
+ comparing to other priorities specified. For example if we have two priorities with value 10
+ and 1, message with priority 10 will get 10 times more resources than messages with priority 1.
+
+
+
The Contents of the synapse-config Directory
+
+
The synapse-config directory which houses the mediation configuration (Synapse configuration)
+of WSO2 ESB contains several files and subdirectories. Usually the following set of child
+directories are available in the synapse-config directory.
+
+
+
endpoints
+
event-sources
+
local-entries
+
priority-executors
+
proxy-services
+
sequences
+
tasks
+
+
+
Each of the above subdirectories can house multiple XML configuration files that define
+specific configuration elements of the Synapse configuration. For an example the 'endpoints'
+subdirectory can house zero or more XML files that contain endpoint configurations.
+
+
Inaddition to the above mentioned subdirectories, there can be files named synapse.xml and
+registry.xml at the top level of the synapse-config directory. The registry.xml contains
+the registry definition for the ESB. The synapse.xml can contain any type of configuration
+elements wrapped in a top level <definitions> element. This file is mainly there for backward
+compatibility reasons. Older versions of WSO2 ESB had only a single flat XML file named synapse.xml
+to load the entire Synapse configuration from. The synapse.xml file in the synapse-config directory
+resembles this flat configuration file so that a user could easily port an old configuration
+to a new ESB distribution. Basically a user can get the content of the old synapse.xml file and
+put it in the synapse-config/synapse.xml file.
+
+
A Synapse configuration looks like the following at the top level synapse.xml file:
The <definitions> elements in the synapse.xml holds the ESB
+configuration. While the <registry>, <sequence>, <endpoint>,
+<proxy>, <task> and <localEntry> elements refer to those
+discussed above, the built-in mediator elements names are already registered
+with the Synapse engine. Custom mediators written by a user may be included
+into the library directory, and would be dynamically picked up in a Sun JDK
+environment. A list of mediators found directly as children under the
+<definitions> element would be treated as the "main" sequence, if a named
+sequence with the name "main" cannot be found.
+
+
Registry
+
+
The <registry> element is used to define the remote registry used by
+the configuration. The registry provider specifies an implementation class for
+the registry implementation used, and optionally a number of configuration
+parameters as may be required for the configuration of the connection to the
+registry.
Registry entries loaded from a remote registry may be cached as dictated 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 off the registry, and update the configuration as these are allowed to
+dynamically change over time.
+
+
WSO2 ESB ships with a built-in file system based registry implementation called the
+"FileSystemRegistry" and this can be configured as follows:
+
e.g.
+<registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <parameter name="root">file:./repository/samples/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+</registry>
+
+
The "root" parameter specifies the root directory of the Registry for loaded
+resources. The FileSystemBasedRegistry 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. By default WSO2 ESB
+uses the WSO2 Governance Registry for storing resources. It is configured as
+follows:
+
e.g.
+<registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
+ <parameter name="cachableDuration">15000</parameter>
+</registry>
+
+
By default you will find the above bit of configuration in the top level
+registry.xml file in the synapse-config directory.
+
+
Local Registry / Local Entries
+
+
The <localEntry> element is used to declare registry entries that are
+local to the ESB instance, as shown below
These entries are top level entries which are globally visible within the
+entire system. Values of these entries can be retrieved via the extension XPath
+function "synapse:get-property(prop-name)" and the keys of these entries could
+be specified wherever a registry key is expected within the configuration.
+
+
An entry can be static text specified as inline text or static XML specified
+as an inline XML fragment or specified as a URL (using the src attribute). A
+local entry shadows any entry with the same name from a remote Registry.
Local entries can be defined in the top level synapse.xml file or in the
+synapse-config/local-entries directory.
+
+
Sequences
+
+
A <sequence> element is used to define a sequence of mediators that
+can be invoked later by name. The sequences named "main" and "fault" has
+special significance in a Synapse configuration. The "main" sequence handles
+any message that is accepted for 'Message
+Mediation', and 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, the Synapse ESB defines suitable defaults at
+initialization.
+
+
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.
+Setting the trace log level to TRACE would additionally dump the message and
+detailed trace information at each mediation step. A tracing enabled sequence
+propagates this setting to invoked sub-sequences.
e.g.
+<sequence name="main" onError="errorHandler">
+ .. <!-- a 'main' sequence that invokes the sequence named 'errorHandler' on a fault --> ..
+</sequence>
+
<sequence key="sequence/dynamic_seq_1.xml"/>
+where "sequence/dynamic_seq_1.xml" refers to the following sequence definition from the registry:
+
+<sequence name="dynamic_sequence" xmlns="http://ws.apache.org/ns/synapse">
+ ..
+</sequence>
+
+
Sequences can be defined in the top level synapse.xml file or in the
+synapse-config/sequences directory. The default main sequence and the fault
+sequence that ships with WSO2 ESB can be found in the sequences directory
+in two files named main.xml and fault.xml respectively.
+
+
Endpoints
+
+
Endpoints can be defined in the top level synapse.xml file or in the
+synapse-config/endpoints directory.
+
+
An <endpoint> element defines a destination for an outgoing message.
+An endpoint may be specified as an address endpoint, WSDL based endpoint, a
+load balancing endpoint or a fail-over endpoint as follows:
All above endpoint types can have a name attribute, and such named endpoints
+can be reffered by other endpoints, through the key attribute. For example if
+there is an endpoint named as "foo", the following endpoint can be used in any
+place, where "foo" has to be used.
+
<endpoint key="foo"/>
+
+
The "trace" attribute turns on detailed trace information for messages being
+sent to the endpoint. These are available in the trace.log configured via the
+log4j.properties file. Setting the trace log level to TRACE will dump detailed
+trace information including message payloads.
+
+
Address Endpoint
+
+
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. Reliable messaging and security
+policies for the endpoint can be specified in the policy attribute of the
+enableRM and enableSec elements respectively. WS-Addressing can be engaged for
+the messaging going to the endpoint by the enableAddressing element.
+suspendDurationOnFailure attribute specifies the time duration in seconds to
+suspend this endpoint, if it is detected as failed. If this attribute is not
+specified, endpoint will never be recovered after a failure.
+
+
Address endpoints can timeout if responses fail to arrive at Synapse by a
+predefined timeout-duration specified in seconds. The timeout action specifies
+whether to discard responses that arrives late, or to trigger a fault. Synapse
+has a periodic timeout handler that triggers itself at each 15 second interval.
+Thus endpoint timeouts will have a +/- error on actual trigger time. Though
+this can be minimized by setting a System property
+"synapse.timeout_handler_interval" to a millisecond duration below the desired
+endpoint timeout, care must be taken as a lesser value may have a higher
+overhead on the system.
+
+
An endpoint that fails may be suspended for a specified duration after such
+a failure, during which new messages will not be processed through the
+endpoint. The 'suspendDurationOnFailure' could specify an optional value in
+seconds for which this endpoint should be suspended.
+
+
QoS aspects such as WS-RM and WS-Security and WS-Addressing may be enabled
+on messages sent to an endpoint using the enableRM, enableSec and
+enableAddressing elements. Optionally, the WS-RM and WS-Security policies could
+be specified using the 'policy' attributes.
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, reliable messaging, security
+policies for the endpoint can be specified as in the 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
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 inlined 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. enableRM, enableSec, enableAddressing, suspendDurationOnFailure
+and timeout elements are same as for an Address endpoint.
A Load balanced endpoint distributes the messages (load) arriving at it
+among a set of listed endpoints by evaluating the load balancing policy and any
+other relevant parameters. Policy attribute of the load balance element
+specifies the load balance policy (algorithm) to be used for selecting the
+target endpoint. Currently only the roundRobin policy is supported. failover
+attribute determines if the next endpoint should be selected once the currently
+selected endpoint has failed, and defaults to true. The set of endpoints among
+which the load is distributed can be listed under the 'loadBalance' element.
+Those 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 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 SAL endpoints. 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, list failover
+endpoints as the target endpoints.
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.
+
<failover>
+ <endpoint .../>+
+</failover>
+
+
Indirect Endpoint
+
Indirect Endpoint refers an actual endpoint by a key. This endpoint fetches
+ the actual endpoint at runtime. Then it delegates the message sending to
+ the actual endpoint. When Endpoints are stored in the registry and referred,
+ this endpoint can be used. The key is a static value for this endpoint.
+
<endpoint key="" name="" />
+
+
Resolving Endpoint
+
Resolving Endpoint refers an actual endpoint using a dynamickey. The key is a XPath expression.
+ The XPath is evaluated against the current message and key is calculated at run time. Then resolving endpoint fetches
+ the actual endpoint using the calculated key. Then it delegates the message sending to
+ the actual endpoint. When Endpoints are stored in the registry and referred,
+ this endpoint can be used.
+
<endpoint name="" key-expression="" />
+
+
Proxy Services
+
+
A <proxy> element is used to define a Synapse Proxy service.
A proxy service is created and exposed on the specified transports through
+the underlying Axis2 engine, exposing service EPR's as per the standard Axis2
+conventions - based on the service name. (Note: that currently Axis2 does not
+allow custom URI's to be set for services on some transports such as http/s)
+The Proxy service could be exposed over all enabled Axis2 transports such as
+http, https, JMS, Mail and File etc. or on a subset of these as specified with
+the optional 'transports' attribute.
+
+
You can give a list of Synapse server names where this proxy service should
+be deployed using 'pinnedServers' attribute. It takes the server names
+separated by comma or space character. If there is no pinned server list then
+proxy service will be started in all server instances. If a pinned server names
+list is given it will only start in the given named Synapse server instances.
+The Synapse server name is picked up either from the system property
+'SynapseServerName' or through the axis2.xml parameter 'SynapseConfig.ServerName',
+failing which the hostname of the machine would be used or
+default to 'localhost'. You can give a name to a Synapse server instance by
+specifiying -DSynapseServerName=<ServerName> property when you execute
+the startup script, i.e. wso2server.bat or wso2server.sh. You can also edit the
+wrapper.conf to do this where Synapse is started as a service.
+
+
Each service could define the target for received messages as a named
+sequence or a direct endpoint. Target inSequence or endpoint is required for
+the proxy configuration, and a target outSequence defines how responses should
+be handled. Any supplied WS-Policies would apply as service level policies, and
+any service parameters could be passed into the proxy services' AxisService
+instance using the parameter elements (e.g. the JMS destination etc). If the
+proxy service should enable WS-Reliable Messaging or Security, the appropriate
+modules could be engaged, and specified service level policies will apply.
+
+
A Dynamic Proxy may be defined by specifying the properties of the proxy as
+dynamic entries by refering them with the key. (For example one could specify
+the inSequence or endpoint with a remote key, without defining it in the local
+configuration) As the remote registry entry changes, the properties of the
+proxy will dynamically be updated accordingly. (Note: proxy service definition
+itself can not be specified to be dynamic; i.e <proxy key="string"/> is
+wrong)
+
+
A WSDL for the proxy service can be published using the <publishWSDL>
+element. The WSDL document can be loaded from the registry by specifying the
+'key' attribute or from any other location by specifying the 'uri' attribute.
+Alternatively the WSDL can be provided inline as a child element of
+<publishWSDL>. Artifacts (schemas or other WSDL documents) imported by
+the WSDL can be resolved from the registry by specifying appropriate
+<resource> elements:
In this example the WSDL is retrieved from the registry using the key
+'my.wsdl'. It imports another WSDL from location
+'http://www.standards.org/standard.wsdl'. Instead of loading it from this
+location, Synapse will retrieve the imported WSDL from the registry entry
+'standard.wsdl'.
+
+
You can give the following as service parameters:
+
+
+
+
+
+
Parameter
+
Value
+
Default
+
Description
+
+
+
useOriginalwsdl
+
true|false
+
false
+
Use the given WSDL instead of generating the WSDL.
+
+
+
modifyUserWSDLPortAddress
+
true|false
+
true
+
(Effective only with useOriginalwsdl=true) If true (default) modify
+ the port addresses to current host.
+
+
+
+
+
Transport specific parameters that may be set as service parameters:
+
+
+
+
+
+
Transport
+
Require
+
Parameter
+
Description
+
+
+
JMS
+
Optional
+
transport.jms.ConnectionFactory
+
The JMS connection factory definition (from axis2.xml) to be used to
+ listen for messages for this service
+
+
+
+
Optional
+
transport.jms.Destination
+
The JMS destination name (Defaults to the service name)
+
+
+
+
Optional
+
transport.jms.DestinationType
+
The JMS destination type. Accept values 'queue' or 'topic'
+
+
+
+
Optional
+
transport.jms.ReplyDestination
+
The destination where a reply will be posted
+
+
+
+
Optional
+
transport.jms.Wrapper
+
The wrapper element for the JMS message
+
+
+
VFS
+
Required
+
transport.vfs.FileURI
+
The primary File (or Directory) URI in the vfs* transport format, for
+ this service
+
+
+
+
Required
+
transport.vfs.ContentType
+
The expected content type for files retrieved for this service. The
+ VFS transport uses this information to select the appropriate message
+ builder.
+ Examples:
+
+
text/xml for plain XML or SOAP
+
text/plain; charset=ISO-8859-1 for text files
+
application/octet-stream for binary data
+
+
+
+
+
+
Optional
+
transport.vfs.FileNamePattern
+
A file name regex pattern to match files against a directory
+ specified by the FileURI
+
+
+
+
Optional
+
transport.PollInterval
+
The poll interval (in seconds)
+
+
+
+
Optional
+
transport.vfs.ActionAfterProcess
+
DELETE or MOVE
+
+
+
+
Optional
+
transport.vfs.MoveAfterProcess
+
The directory to move files after processing (i.e. all files process
+ successfully)
+
+
+
+
Optional
+
transport.vfs.ActionAfterErrors
+
DELETE or MOVE
+
+
+
+
Optional
+
transport.vfs.MoveAfterErrors
+
The directory to move files after errors (i.e. some of the files
+ succeed but some fail)
+
+
+
+
Optional
+
transport.vfs.ActionAfterFailure
+
DELETE or MOVE
+
+
+
+
Optional
+
transport.vfs.MoveAfterFailure
+
The directory to move after failure (i.e. all files fail)
+
+
+
+
Optional
+
transport.vfs.ReplyFileURI
+
Reply file URI
+
+
+
+
Optional
+
transport.vfs.ReplyFileName
+
Reply file name (defaults to response.xml)
+
+
+
+
Optional
+
transport.vfs.MoveTimestampFormat
+
Timestamp prefix format for processed file name.
+ java.text.SimpleDateFormat compatible string. e.g. yyMMddHHmmss'-'
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 (which must implement org.apache.synapse.startup.Task
+interface) to be executed at the specified interval/s, and name specifies an
+identifier for the scheduled task.
+
+
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')
+
+
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 Synapse
+
+
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.
+
+
Event Sources
+
+A <eventSource> element is used to define an event source.
+
+An event source is required to implement eventing in WSO2 ESB. Event sources are
+used to inject subscription messages into the ESB and provide a service URL for the
+users to send subscription requests. User can send messages to manage the subscriptions
+(unsubscribe, renew, get-status) in the event source as well.
+
+
+Subscription manager configured inside the event source will be responsible for
+keeping track of the subscriptions, and provide operations to manage the
+subscriptions. Subscription storage will be decided based on the implementation of
+the subscription manager , e.g. Registry, memory, database. Additional information
+required to setup the subscription manager can be set as parameters.
+
+
+
Priority Executors
+
Below is the Priority Executor Configuration
+
<priority-executor name="priority-executor">
+ <queues isFixed="true|false" nextQueue="class implementing NextQueueAlgorithm">
+ <queue [size="size of the queue"] priority="priority of the messages put in to this queue"/>*
+ </queues>
+ <threads core="core number of threads" max="max number of threads' keep-alive="keep alive time"/>
+</priority-executor>
+
+ An executor is a Thread Pool Executor with separate queues for different priorities.
+
+
+ The queues can have a fixed depths or they can have un-bounded capacities. This is controlled by
+ the isFixed attribute.
+
+
+ An executor should have at least two or more queues. If only one queue is used there is no
+ point in using a priority executor. It only adds some overhead.
+
+
+ A Queue can have a size and a priority. If the queues has unlimited length, no more than
+ core threads will be used.
+
+
+ A Priority Executor has a core number of threads. When ESB is started with the priority
+ executor, this number of threads will be created. Max is the maximum number of threads this
+ executor will have. If the number of threads in the executor exceeds the core threads, they
+ will be in active for the keep-alive time only. After the keep-alive time those threads will
+ be be removed from the system.
+
+
+
+
Mediators
+
+
A mediator token refers to any of the following tokens:
In addition to the above, Synapse will be able to load custom mediators via
+the J2SE Service Provider model. Mediator extensions must implement the
+MediatorFactory interface. The Class and POJO Command mediators allow custom
+Java code to be easily invoked during mediation, while the Script mediator
+allows Apache BSF scripts such as Javascript, Ruby, Groovy etc to be used for
+mediation.
The send token represents a <send> element, used to send messages out
+of Synapse to some endpoint. The send mediator also copies any message context
+properties from the current message context to the reply message received on
+the execution of the send operation so that the response could be correlated
+back to the request. Messages may be correlated by WS-A MessageID, or even
+simple custom text labels (see the property mediator and samples)
+
+
In the simplest case shown below, the destination to send a message is
+implicit in the message via the 'To' address. Thus a request message will be
+sent to its 'To' address, and a response message would be sent back to the
+client. Removing the 'To' address of a message targets it back to the client,
+and thus a request message received may be returned to the client after
+changing its direction. (Note: to mark a message as a response set the property
+RESPONSE to true)
+
+
Note: A send operation may be blocking or non-blocking
+depending on the actual transport implementation used. As the default NIO based
+http/s implementation does not block on a send, care must be taken if the same
+message must be sent and then further processed (e.g. transformed). In such a
+scenario, it maybe required to first clone the message into two copies and then
+perform processing to avoid conflicts.
+
<send/>
+
+
If the message is to be sent to one or more endpoints, then the following is
+used:
+
<send>
+ (endpointref | endpoint)+
+ </send>
+
+
where the endpointref token refers to the following:
+
<endpoint key="name"/>
+
+
and the endpoint token refers to an anonymous endpoint definition.
The property token refers to a <property> element which is a mediator
+that has no direct impact on the message but rather on the message context
+flowing through Synapse. The properties set on a message can be later retrieved
+through the synapse:get-property(prop-name) XPath extension function. If a
+scope is specified for a property, the property could be set as a transport
+header property or an (underlying) Axis2 message context property, or as a
+Axis2 client option. If a scope is not specified, it will default to the
+Synapse message context scope. Using the property element with action specified
+as "remove" you can remove any existing message context properties.
+
+
With the type attribute, we can set properties with specific data types
+into the message context. When this attribute is not used the specified property value
+will be set as a string. Currently the following data type names are recognized
+by the property mediator's type attribute:
+
+
BOOLEAN
+
DOUBLE
+
FLOAT
+
INTEGER
+
LONG
+
OM
+
SHORT
+
STRING
+
+
When the type attribute is assigned one of the above mentioned values, the
+specified property value will be converted to the specified type before setting
+it into the message context. The type OM can be used to convert the property value
+into an AXIOM OMElement. Please note that all type names mentioned above are case
+sensitive.
+
+
There are some well-defined properties that you can get/set on the Synapse
+message context scope:
+
+
RESPONSE - 'true' means the message is to be marked as a response message
+
+
OUT_ONLY - 'true' means the message is to be marked as an out-only
+ message that does not expect a response
+
ERROR_CODE - this is set to any error message code encountered during a
+ fault
+
ERROR_MESSAGE - this is set to any error message text encountered during
+ a fault
+
ERROR_DETAIL - this is set to any error message detail text encountered
+ during a fault
+
+
ERROR_EXCEPTION - this is set to any Java Exception encountered during a
+ fault
+
+
+
There are some Axis2 and module properties that are useful which are set at
+scope="axis2"
+
+
MercurySequenceKey - can be an identifier specifying an Mercury internal
+ sequence key, and
+
MercuryLastMessage - 'true' will make this the last message and terminate
+ the sequence
+
+
+
There are some Axis2 client side properties/options that are useful which
+are set at scope="axis2-client"
+
+
FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0 (instead
+ of the default 1.1)
+
+
+
The synapse:get-property() XPath extension function
+
+
The get-property() function allows any XPath expression used in a
+configuration to lookup information from the current message context. 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. The function accepts the scope as an optional parameter as shown below:
+
Some useful properties from the Synapse message context follows:
+
+
SYSTEM_DATE - Returns the current date as a String. Optionally a date
+ format as per standard date format may be supplied. e.g.
+ synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or
+ get-property('SYSTEM_DATE')
+
SYSTEM_TIME - Returns the current time in milliseconds. (i.e. the
+ difference, measured in milliseconds, between the current time and
+ midnight, January 1, 1970 UTC)
+
To, From, Action, FaultTo, ReplyTo, MessageID the message To and Action
+ and WS-Addressing properties
+
MESSAGE_FORMAT - returns the message format - i.e. returns pox, get,
+ soap11 or soap12
+
OperationName - returns the operation name for the message
+
+
+
In addition to the above, one may use the get-property() function to
+retrieve Axis2 message context properties or transport headers. e.g.
+synapse:get-property('transport', 'USER_AGENT')
+
+
SynapseXpath variables
+
+
There are a set of predefined XPath variables when writing XPaths in the
+Synapse Configuration. Those are as follows;
+
+
body - The SOAP 1.1 or 1.2 body element
+ For example; expression="$body/getQuote" refers to the first getQuote element
+ in the SOAP body regardless of whether the message is SOAP-11 or SOAP-12
+
header - The SOAP 1.1 or 1.2 header element
+ For example; expression="$header/wsa:To" refers to the addressing To header
+ regardless of whether this message is SOAP-11 or SOAP-12
+
+
Further there are some variable prefixes defined in Synapse XPaths which can
+be usefull in writing the configurations;
+
+
ctx - Prefix for Synapse MessageContext properties
+ For example; expression="$ctx:RESPONSE" gives the value of the Synapse
+ message context property with name 'RESPONSE'
+
axis2 - Prefix for Axis2 MessageContext properties
+ For example; expression="$axis2:messageType" gives the value of the axis2
+ message context property with name 'messageType'
+
trp - Prefix for the transport headers
+ For example; expression="$trp:Content-Type" gives the value of the
+ 'Content-Type' transport header, which is going to be the Content-Type of the
+ current message
The <validate> mediator validates the result of the evaluation of the
+source xpath expression, against the schema specified. If the source attribute
+is not specified, the validation is performed against the first child of the
+SOAP body of the current message. If the validation fails, the on-fail sequence
+of mediators is executed. Properties could be used to turn on/off some of the
+underlying features of the validator (See http://xerces.apache.org/xerces2-j/features.html)
+
The fault mediator transforms the current message into a fault message, but
+does NOT send it. The <send> mediator needs to be invoked to send a fault
+message created this way. The fault message "To" header is set to the
+"Fault-To" of the original message if such a header exists on the original
+message. If a 'version' attribute is specified, the created fault message will
+be created as a selected SOAP 1.1, SOAP 1.2 or POX fault.
The <callout> mediator performs a blocking external service invocation
+during mediation. The serviceURL and the optional action specifies the
+parameters for this external call. The source element specifies the payload for
+the request message using an XPath expression; or a registry key that will be
+used. The target element specifies a node, at which the resulting payload will
+be attached into the current message, or the name of a key/property using which
+the response would be attached to the current message context as a property.
+
+
+
As the callout mediator performs a blocking call, it cannot use the default
+non-blocking http/s transports based on Java NIO, and thus defaults to using
+the samples/axis2Client/client_repo/conf/axis2.xml as the Axis2 configuration,
+and samples/axis2Client/client_repo as the client repository unless these are
+specified separately
The <xslt> mediator applies the specified XSLT transformation to the
+selected element of the current message payload. If the source element is not
+specified, it defaults to the first child of the soap body. Optionally
+parameters (XSLT) could be passed into the transformations through the
+'property' elements. The 'feature' element defines any features which should be
+explicitly set to the TransformerFactory. The feature
+'http://ws.apache.org/ns/synapse/transform/feature/dom' turns on DOM based
+transformations instead of serializing elements into Byte streams and/or
+temporary files. Though this would be better in performance than using byte
+streams, sometimes it may not work for all transformations.
+
+
Finally, the 'resource' element can be used to resolve XSLT imports and
+includes from the repository. It works in exactly the same way as the
+corresponding element in a <proxy> definition.
The XQuery mediator can be used to perform an XQuery transformation. The
+'key' attribute specifies the XQuery transformation, and the optional 'target'
+attribute specifies the node of the message that should be transformed. This
+defaults to the first child of the SOAP body of the payload. The 'variable'
+elements define a variable that could be bound to the dynamic context of the
+XQuery engine in order to access those variables through the XQuery script .
+
+
+
It is possible to specify just a literal 'value', or an XPath expression
+over the payload, or even specify a registry key or a registry key combined
+with an XPath expression that selects the variable. The name of the variable
+corresponds to the name of variable declaration in the XQuery script. The
+'type' of the variable must be a valid type defined by the JSR-000225 (XQJ
+API).
The <header> mediator sets or removes a specified header from the
+current soap infoset. Currently the set header only supports simple valued
+headers. In the future we may extend this to have XML structured headers by
+embedding the XML content within the element itself. The optional action
+attribute specifies whether the mediator should set or remove the header. If
+omitted, it defaults to a set-header.
The <smooks> mediator can be used to perform complex content transformation efficiently
+using the Smooks framework for XML processing. The key attribute should point to a local entry
+or a registry resource which contains a Smooks configuration file. For more information on Smooks
+transformation please visit the Smooks website.
The <filter> mediator either test the given xpath expression as a
+boolean expression, or match the evaluation result of a source xpath expression
+as a String against the given regular expression. If the test succeeds, the
+filter mediator will execute the enclosed mediators in sequence.
+
+
One could also use this mediator to handle the failure case as well, in
+which case the configuration would be as follows
In this case the filter condition remains as earlier and the succeeded
+messages will be mediated using the the set of mediators enclosed in the 'then'
+element in sequence, while failed messages will be mediated using the set of
+mediators enclosed in the else element in sequence
The <switch> mediator will evaluate the given source xpath expression
+into its string value, and match it against the given regular expressions. If
+the specified cases does not match and a default case exists, it will be
+executed.
The In and Out mediators will execute the child mediators over the current
+message if the message matches the direction of the mediator. Hence all
+incoming messages would pass through the "<in>" mediators and vice versa.
+
Router mediator is represented by the 'router' root tag and it can contain
+any number of routes which are represented with the 'route' tags. Router
+mediator can be configured to continue or to stop the mediation after the
+routing by setting the 'continueAfter' attribute value to be 'true' and 'false'
+respectively. Each and every route must contain an 'expression' attribute which
+is to specify the XPath over which the routing condition is evaluated. Apart
+from that there can be an optional 'match' attribute as well. If both
+expression and the match attirbutes are specified in a particualr route, the
+evaluated string value of the XPath over the current message will be campared
+with the reular expression provided as the value of the match attribute to see
+whether this route is matching for the current message. Where as if only the
+expression is specified, presence of the element specified by this XPath is
+considered as the routing condition.
+
+
One can configure a route to break routing or continue evaluating further
+routes to see any further matchings by setting the 'breakRouter' attribute to
+'true' or 'false' respectively. For all the routes there has to be a 'target'
+element which contains the information about the routing path as a sequence or
+an endpoint both can be inlined as well as refered. If both an endpoint and a
+sequence is specified message will be first mediated through the sequence and
+sent to the endpoint after mediation. Particular target cannot contain an
+inline sequence and a refered sequence at the same time. The same applies to
+endpoit of the target as well.
The dblookup mediator is capable of executing an arbitrary SQL select
+statement, and then set some resulting values as local message properties on
+the message context. The DB connection used maybe looked up from an external
+DataSource or specified in-line, in which case an Apache DBCP connection pool
+is established and used. Apache DBCP connection pools support the following
+properties:
More than one statement may be specified, and the SQL statement may specify
+parameters which could be specified as values or XPath expressions. The types
+of parameters could be any valid SQL types. Only the first row of a result set
+will be considered and any others are ignored. The single <result>
+element contains the 'name' and the column' attributes. The 'name' attribute
+defines the name under which the result is stored in the Synapse message
+context, and the column attribute specifies a column number or name .
The <RMSequence> mediator can be used to create a sequence of messages
+to communicate via WS-Reliable Messaging with an WS-RM enabled endpoint
+(<enableRM>). The simple use case of this mediator is to specify a
+single="true" property, because this means that only one message is involved in
+the same sequence. However if multiple messages should be sent in the same
+sequence, the correlation property should be used with a XPath expression that
+selects an unique element value from the incoming message. With the result of
+the XPath expression, Synapse can group messages together that belong to the
+same sequence. To close the sequence neatly, for the last message of the
+sequence also an XPath expression should be specified. With the version
+attribute the WS-RM specification version to be used can be specified, 1.0 or
+1.1.
The Throttle mediator can be used for rate limiting as well as concurrency
+based limiting. A WS-Policy dictates the throttling configuration and may be
+specified inline or loaded from the registry. Please refer to the samples
+document for sample throttling policies. The Throttle mediator could be added
+in the request path for rate limiting and concurrent access limitation. When
+using for concurrent access limitation, the same throttle mediator 'id' must be
+triggered on the response flow so that completed responses are deducted from
+the available limit. (i.e. two instances of the throttle mediator with the same
+'id' attribute in the request and response flows). The 'onReject' and
+'onAccept' sequence references or inline sequences define how accepted and
+rejected messages are to be handled.
The <cache> mediator will evaluate the hash value of an incoming
+message as described in the optional hash generator implementation (which
+should be a class implementing the org.wso2.caching.digest.DigestGenerator
+interface). The default hash generator is
+'org.wso2.caching.digest.DOMHashGenerator'. If the generated hash value has
+been found in the cache then the cache mediator will execute the onCacheHit
+sequence which can be specified inline or referenced. The cache mediator must
+be specified with an 'id' and two instances with this same 'id' that correlates
+the response message into the cache for the request message hash. The optional
+'timeout' specifies the valid duration for cached elements, and the scope
+defines if mediator instances share a common cache per every host instance, or
+per every cache mediator pair (i.e. 'id') instance. The 'collector' attribute
+'true' specifies that the mediator instance is a response collection instance,
+and 'false' specifies that its a cache serving instance. The maximum size of a
+message to be cached could be specified with the optional 'maxMessageSize'
+attributes in bytes and defaults to unlimited. Finally the 'implementation'
+element may define if the cache is disk or memory based, and the 'maxSize'
+attribute defines the maximum number of elements to be cached.
The clone mediator closely resembles the Message Splitter EIP and will split
+the message into number of identical messages which will be processed in
+parallel. They can also be set to process sequentially by setting
+the value of the optional 'sequential' attribute to 'true'.
+The original message cloned can be continued or dropped depending on
+the boolean value of the optional 'continueParent' attribute. Optionally a
+custom 'To' address and/or a 'Action' may be specified for cloned messages
+The optional 'id' attribute can be used to identify the clone mediator which
+created a particular splitted message when nested clone mediators are used.
+This is particularly useful when aggregating responses of messages that are
+created using nested clone mediators.
+
The iterate mediator implements another EIP and will split the message into
+number of different messages derived from the parent message by finding
+matching elements for the XPath expression specified. New messages will be
+created for each and every matching element and processed in parallel(default
+behavior) using either the specified sequence or endpoint.
+Created messages can also be set to process sequentially by setting the optional 'sequential'
+attribute to 'true'. Parent message can be continued or
+dropped in the same way as in the clone mediator. The 'preservePayload'
+attribute specifies if the original message should be used as a template when
+creating the splitted messages, and defaults to 'false', in which case the
+splitted messages would contain the split elements as the SOAP body. The optional 'id' attribute
+can be used to identify the iterator which created a particular splitted message when nested iterate
+mediators are used. This is particularly useful when aggregating responses of messages that are
+created using nested iterate mediators.
The aggregate mediator implements the Message Aggregator EIP and will
+aggregate the messages or responses for splitted messages using either the
+clone or iterate mediators. At the same time it can aggregate messages on the
+presence of matching elements specified by the correlateOn XPATH expression.
+Aggregate will collect the messages coming into it until the messages collected
+on the aggregation satisfies the complete condition. The completion condition
+can specify a minimum or maximum number of messages to be collected, or a
+timeout value in seconds, after which the aggregation terminates. On completion
+of the aggregation it will merge all of the collected messages and invoke the
+onComplete sequence on it. The merged message would be created using the XPath
+expression specified by the attribute 'expression' on the 'onComplete' element.
+The optional 'id' attribute can be used to aggregate only responses for splitted messages that
+are created by a specific clone/iterate mediator. Aggregate ID should be same as the ID of the
+corresponding clone/iterate mediator that creates splitted messages. This is particularly useful
+when aggregating responses of messages that are created using nested clone/iterate mediators.
+
Event mediator publishes events to the given event source. Thus, the
+presence of defined event sources are necessary prior to the usage of this
+mediator.
The Entitlement Mediator by passes the requests and evaluates the actions performed by the user
+against the XACML policy defined at the Policy Decision Point [WSO2 Identity Server]
Transaction mediator can provide transaction facility for a set of mediators
+defined as its child mediators. A transaction mediator with the action "new"
+indicates the entry point for the transaction. A transaction is marked
+completed by a transaction mediator with the action "commit". The suspend and
+resume actions are used to pause a transaction at some point and start it again
+later. Additionally, the transaction mediator supports three other actions,
+i.e. use-existing-or-new, fault-if-no-tx, rollback.
<class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+ </class>
+
+
The class mediator creates an instance of a custom specified class and sets
+it as a mediator. The class must implement the org.apache.synapse.api.Mediator
+interface. If any properties are specified, the corresponding setter methods
+are invoked on the class, once, during initialization.
The pojoCommand mediator creates an instance of the specified command class
+- which may implement the org.apache.synapse.Command interface or should have a
+public void method "public void execute()". If any properties are specified,
+the corresponding setter methods are invoked on the class before each message
+is executed. It should be noted that a new instance of the POJO Command class
+is created to process each message processed. After execution of the POJO
+Command mediator, depending on the 'action' attribute of the property, the new
+value returned by a call to the corresponding getter method is stored back to
+the message or to the context. The 'action' attribute may specify whether this
+behaviour is expected or not via the Read, Update and ReadAndUpdate properties.
+
+
+
Scripting language mediators
+
+
Synapse supports Mediators implemented in a variety of scripting languages
+such as JavaScript, Python or Ruby. There are two ways of defining script
+mediators, either with the script program statements stored in a separate file
+which is referenced via the local or remote registry entry, or with the script
+program statements embedded in-line within the Synapse configuration. A script
+mediator using a script off the registry (local or remote) is defined as
+follows:
The property key is the registry key to load the script. The language
+attribute specifies the scripting language of the script code (e.g. "js" for
+Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python..). The
+function is an optional attribute defining the name of the script function to
+invoke, if not specified it defaults to a function named 'mediate'. The
+function is passed a single parameter - which is the Synapse MessageContext.
+The function may return a boolean, if it does not, then true is assumed, and
+the script mediator returns this value. An inline script mediator has the
+script source embedded in the configuration as follows:
The execution context environment of the script has access to the Synapse
+MessageContext predefined in a script variable named 'mc' . An example of an
+inline mediator using JavaScript/E4X which returns false if the SOAP message
+body contains an element named 'symbol' which has a value of 'IBM' would be:
+
Synapse uses the Apache Bean
+Scripting Framework for the scripting language support, any script language
+supported by BSF may be used to implement a Synapse Mediator.
+
+
Implementing a Mediator with a script language can have advantages over
+using the built in Synapse Mediator types or implementing a custom Java class
+Mediator. Script Mediators have all the flexibility of a class Mediator with
+access to the Synapse MessageContext and SynapseEnvironment APIs, and the ease
+of use and dynamic nature of scripting languages allows rapid development and
+prototyping of custom mediators. An additional benefit of some scripting
+languages is that they have very simple and elegant XML manipulation
+capabilities, for example JavaScript E4X or Ruby REXML, so this makes them well
+suited for use in the Synapse mediation environment. For both types of script
+mediator definition the MessageContext passed into the script has additional
+methods over the standard Synapse MessageContext to enable working with the XML
+in a way natural to the scripting language. For example when using JavaScript
+getPayloadXML and setPayloadXML, E4X XML objects, and when using Ruby, REXML
+documents.
+
+
Extensibility of WSO2 ESB
+
+
The Synapse configuration language could be easily extended, with
+configuration extensions as well as mediation extensions. The Spring mediator
+is such an example.
+
+
Spring Configuration
+
+
A Spring configuration could be created as a localEntry or remote registry
+entry providing a URL or a key reference to a Registry. The configuration is
+then created on first use or as necessary (as per registry lookup semantics) by
+the mediators which reference this configuration.
The name attribute specifies a unique name for the configuration, and the
+src, key or inlined XML references to the Spring configuration
+
+
Spring mediator
+
<spring:spring bean="exampleBean1" key="string"/>
+
+
The <spring> element creates an instance of a mediator, which is
+managed by Spring. This Spring bean must implement the Mediator interface for
+it to act as a Mediator. The key will reference the Spring
+ApplicationContext/Configuration used for the bean
+
+
The <spring> element creates an instance of a mediator, which is
+managed by Spring. This Spring bean must implement the Mediator interface for
+it to act as a Mediator. The key will reference the Spring
+ApplicationContext/Configuration used for the bean
+
+
+
Rule Mediator - Java Rule mediator
+
+
Rule mediator is to integrate the WSO2 Rules component to the WSO2 ESB in
+order to define dynamic integration decisions in terms of rules.
The source is the only mandatory element of the ruleset. However, the
+properties required for the creation of the ruleset can also be specified
+within ruleset. The key attribute is a registry key, which is to lookup the
+rule script from the registry if the rule script is in the registry. The rule
+set can be given as a child node of source elemenent. If the rule set is
+non-XML, you may need to wrap it with a CDATA section inside a XML tag ex:
+<X><![CDATA[ native code]]></X>
+
+
Note : The key or in-lined rule script must be defined. Otherwise, the rule
+mediator configuration is invalid.
+
+
RuleSession
+
+
Rule Session specify the stateful or stateless behavior of the rule engine.
+If this has value ‘stateful’, then the rule engine will execute
+rules in a stateful manner, for any other value , it assumes as stateless.
+There are optional properties, which are used when creating the rule session.
+Rule session is optional and the default one is stateful.
+
+
Facts / Results
+
+
name - the unique name
+
value - Represents any static value
+
expression - XPath expression for extracting data from the message being
+ passed between ESB components. The default value is the first child of the
+ SOAP Body.
+
type - Defines the type of the input data. There are a few built in types
+ such as Message, Context, Map, POJO and Mediator and there are samples
+ using these. Using the rule-component.conf, you can register new types
+ along with adapters, which are responsible for formulating specified types
+ from the data. If there is no registered adapter for a given type, then, we
+ assume the given type as a valid java class name and uses POJO adapter to
+ formulate the POJO instance whose class is the given type.
+
+
+
Facts specify the facts being used in rule set. It also defines how to
+formulate facts from the message, etc. Results define how to handle results
+from the rule set execution. Usually, results adapters enrich the message with
+results. For example, If you are using POJO adapter (i.e. a java class as the
+type – the class name of a result), then we transform POJO into an XML
+and attached to the SOAP message.
+
+
UI Integration
+
As mentioned earlier the ESB management console provides tools that can be
+used to construct mediation configurations. When these tools are used to create
+endpoints, sequences, proxy services and other configuration elements they are
+also saved under the appropriate child directory under the synapse-config
+directory. For an example if you add an endpoint named 'foo' from the UI it will
+be saved to a file named 'foo.xml' in the synapse-config/endpoints directory.
+Further modifications to the endpoint 'foo' will be saved to the same configuration
+file.
+
However there is a slight exception with the Synapse configuration editor in the
+ESB management console (available under the 'Configure' menu). New elements add
+through this editor will be saved to the top level synapse.xml file in the
+synapse-config directory. Anyway, if an existing item is modified through the Synapse
+configuration editor it will be still saved back to the original file where it was
+loaded from.
+ WSO2 Enterprise Service Bus (ESB) Deployment Guide
+
+
+ Deploying the WSO2 ESB correctly on your infrastructure is a vital task for the success
+ of the usage of the ESB. You should first analyze the requirement and then select the
+ best matching deployment mode. There are different set of possible deployment modes with
+ different configurations.
+
+ Webapp Deployment Guide :
+ Contains the information on deploying the ESB on an Application Server, this particular guide
+ explains the deployment of an existing Tomcat Servlet Container.
+
+
+
Clustered Deployment Guide
+
+ This document describes the steps you need to follow to setup a working WSO2 ESB cluster in your environment.
+
The configuration sharing is done using the WSO2 Governance Registry. All the ESB nodes in the
+ cluster are pointed to one instance of WSO2 G-Reg and through this registry configuration is shared.
+
+
+ WSO2 G-Reg consists of three registry spaces.
+
+
+
Local Registry - Per running instance of every product
+
Configuration Registry - Shared among all the instance of a cluster of one product
+
Governance Registry - Centrally managed & shared across multiple products and multiple
+ instances of those
+
+
So, when it comes to ESB clustering, we will be using local registry per each instance,
+ mounting the configuration registry of each ESB instance to the same config registry and
+ sharing the governance space among GReg and 2-ESB instances.
+
+
First lets see how to set up ESB instances pointing to a single G-Reg.
+
+ WSO2 ESB Cluster Deployment Diagram
+
+
+
Setting UP WSO2 ESB cluster with GReg
+
+
Extract the WSO2 ESB 4.0.0 distribution and as the first step we need to configure the database configuration.
+
Both GReg and ESB are shipped embedded H2 registry. However, for clustering purposes we will be using MySQL instead.
+
In the following setup, we have GReg running on mysql database which means it's local/config/governance registries are store in a mysql database and it's user-manager tables are also inside the same database.
+
In ESB instances,
+
+
Both master and slave ESBs are using unique local registries.
+
Both configuration registries mounted to the same directory of GReg.
+
Governance registry is mounted to the governance registry of GReg
+
+
+
All the ESB instances in the cluster are sharing a common database for user-manager. (if you are using an LDAP you do not have to use a database for user-manager.)
+
+
+ (This documentation http://wso2.org/project/registry/3.5.0/docs/user_guide/registry_config.html contains database
+ configurations with different databases and we recommend you to go through it if you are using a
+ different database server other than mysql.)
+
+
+
ESB cluster database configuration
+
+
+
+
Instance Name
+
Registry Space
+
Instance Name Registry Space Mysql database name/mounted path (x.x.x.x)
+
+
+
ESB Master (x.x.x.x)
+
local
+
amamaster
+
+
+
+
config
+
amagregdb /_system/esbConfig
+
+
+
+
governance
+
amagregdb /_system/governance
+
+
+
+
user-manager
+
amausermgtdb
+
+
+
ESB Slave1 (x.x.x.x)
+
local
+
amaslave1
+
+
+
+
+
config
+
amagregdb /_system/esbConfig
+
+
+
+
governance
+
amagregdb /_system/governance
+
+
+
+
user-manager
+
amausermgtdb
+
+
+
GREG (x.x.x.x)
+
All
+
amagregdb
+
+
+
+
In the above table there are 5 separate databases with following names
Running Multiple instance of the WSO2 Carbon Servers in the same machine
+
If you are running multiple instance same or different WSO2 Product Instances, then you need to
+ configure ports for each instance. You can configure $CARBON_HOME/repository/conf/carbon.xml by using portOffset
+
+
+ <Offset>0</Offset>
+
+
Please provide + Offset value
+
E.g: If Offset=2 and HTTPS port=9443, will be set the effective HTTPS port to 9445
+
+
+
Settings for Governance Registry
+
+ If you see the table above you can see that we are using a single database
+ for all the queries in GREG instance. So we need to change the configuration in registry.xml and user-mgt.xml.
+
+
+
Go to GREG_HOME/repository/conf/registry.xml file remove the original dbConfig element and add the
+ database configuration below. (IP addresses and database urls have to be changed acccording to your setup).
+ Go to GREG_HOME/repository/conf/user-mgt.xml file and change the database configuration as below(IP addresses and urls have to be changed according to your setup).
+
Copy mysql jdbc driver library to GREG_HOME/repository/components/lib direcotry since by default we do not ship the mysql drivers in GREG.
+
If we examine the above configuration we can see that we are pointing the same database (amagregdb)for registry and user store .
+
Start the GREG instance with -Dsetup
+ (This will create tables for user manager database and registry database(pick the database configuration from currentDBConfig element in registry.xml
+ since there might be number of database configurations in your registry.xml which we put
+ to perform mounting from other databases but only one database configuration is configured as currentDBConfig)).
+
+
+
After successfully starting GREG instance create following directory from GREG's management console. Go to
+ management console-->Registry browser and create "esbConfig" collection under "system" path.
+ Configurations will be mounted by ESB instances running in the cluster to this directory.( /_system/esbConfig)
+
+
Settings for ESB Master Node
+
+
Here we are changing the default database configuration to point master node's local registry to amamaster and will be poinetd the user manager database
+ to amausermgtdb . Here ESB master node's configuration and Governance registriy's configuration also will be mounted from GREG database.
+
+
Let's first add local registry configuration and user-manager configuration.
+
Open the ESB_HOME/repository/conf/registry.xml file remove the original dbConfig element and add the database configuration below.
+ (IP addresses and database urls have to be changed according to your setup).
Open the ESB_HOME/repository/conf/user-mgt.xml file and change the database configuration as below(IP addresses and urls have to be changed according to your setup).
Now let's configure the mounting configuration. For that we need to add more parameters to registry.xml file.
+
Open the ESB_HOME/repository/conf/registry.xml file and add the following mount database configuration below. (IP addresses and database urls have to be changed acccording to your setup).
Please change the "remoteInstance URL" according to the configuration of the GREG instance. Please note that "InstanceIds", "id" and "dbConfig" elements should be mapped properly if you are using different
+ names for them.
+
+
Copy mysql jdbc driver library to ESB_HOME/repository/components/lib direcotry since by default we do not ship the mysql drivers in ESB.
+
+
Settings for ESB Slave Node
+
+
Here we are changing the default database configuration, to point slvae node's local registry to amaslave1 and will be pointed the user manager
+ database to amausermgtdb . Here ESB slave node's configuration and Governance registriy's configuration also will be mounted from GREG database.
+
+
Let's first add local registry configuration and user-manager configuration.
+
Open the ESB_SLAVE_HOME/repository/conf/registry.xml file , remove the original dbConfig element and add the database configuration below. (IP addresses and database
+ urls have to be changed acccording to your setup).
Open the ESB_SLAVE_HOME/repository/conf/user-mgt.xml file and change the database configuration as below(IP addresses and urls have to be changed according to your setup).
+
Note : Here we are changing the mode to 'readOnly' in database configuration.
Now let's configure the mounting configuration. For that we need to add more parameters to registry.xml file.
+
Open the ESB_SLAVE_HOME//repository/conf/registry.xml file and add the following mount database configuration below. (IP addresses and database urls have to be changed acccording to your setup).
+ Please change the remoteInstance URL according to the configuration of the GREG running machine. Please note that "InstanceIds", "id" and "dbConfig" elements
+ should be mapped properly if you are using different names for them.
+
+
+ Note: If you compare the configuration with master node, we are only changing the configuration of local registry
+ and all the other configurations are same with the master node, but the registry access mode in mounting is readonly but the local registry
+ configuration should be read-write since it is specific for each node.
+
+
+
Copy mysql jdbc driver library to ESB_SLAVE_HOME/repository/components/lib direcotry since by default we do not ship the mysql drivers in ESB.
+
Before starting the slave ESB node you need to load registry database schema to amaslave1 database.
+ You can find the required SQL script at ESB_SLAVE_HOME/dbscripts directory.
+
+
Running the setup
+
+
After successful configurations, run the wso2server.sh or wso2server.bat of master node based on your platform with '-Dsetup' option for the first time start up
+ to create the database tables, and after creating database tables, do not use '-Dsetup' option when run the server.
+
sh CARBON_HOME/bin/wso2server.sh -Dsetup
+
+
You don't need to specify the -Dsetup option for ESB slave node because we have created DB schema in the previous step.
+
Note: -Dsetup doesn't work with ESB slave node because we share a same database for user manager and -Dsetup option will try to
+ create user manager tables at the startup if you use -Dsetup option.
+
+
After setting up the ESB's pointing to a single Registry we have two options for sharing the configuration.
+
+
+
+
Manual configuration sharing
+
In this mode ESB's can be configured to load the configuration from the Registry instead of the file system. The configuration loading happens only when the ESB starts up. So if a change is made to the master ESB node, other ESB's has to be restarted to get the new configuration.
+
+ Lot of users prefer this mode because it guarantees a consistent configuration at the start up and configuration is not changed while the ESB is running.
+ By default ESB loads the configuration from the File System. If the configuration has to be loaded from the Registry following configuration has to be uncommented and changed in the carbon.xml
LoadFromRegistry parameter has to be changed to true in the slave nodes.
+
+
+
Deployment Synchronizer
+
The next approach is to use the Deployment Synchronizer shipped with the ESB. With the deployment
+ synchronizer, configurations can be updated in the slave nodes at the runtime.
+
+
Configuration has to be changed in the master node.
WSO2 ESB flows are stateless for the most part. But in very rare deployments users have requested to share some of the runtime information among the cluster nodes. For example Caching can be used with runtime state sharing.
+
+
Runtime state replication is based on the Tribes group management system. It
+ provides group membership handling and group communication for clustered Carbon Server
+ instances. Although ESB ships with this built in Tribes based
+ implementation, other clustering implementations based on different group
+ management systems can be plugged in easily. The only thing you have to do is
+ to implement a set of clustering interfaces provided by Carbon Server.
+
+
+
+
ESB clustering currently does not support distributed locking for session
+ data replication. Therefore, we have to deploy primary backup clusters for
+ stateful services. This restriction does not apply to
+ stateless services and you can direct client requests to any node in the
+ cluster for such services.
NWe can enable clustering by changing the configuration in the axis2.xml. By default, clustering is
+ turned off to avoid additional overhead for individual deployments. Open
+ the axis2.xml and set the value 'true' for the "enable" attribute
+ of the "clustering" element as follows.
You may also change clustering properties to suit your deployment as explianed
+ in the above article. However, the default configuration is sufficient for
+ the demonstration.
+
+
+ Other Resources
+
+
+
+ The WSO2 Oxygen Tank
+ Library : The Library contains articles, tutorials,
+ presentations, and other knowledge base items published on The Oxygen
+ Tank on different styles of deployments.
+
+ WSO2 Enterprise Service Bus (ESB) Documentation Index
+
+
+ Getting Started
+
+
+ Installation Guide : Gives
+ basic steps on how to download, install, and run WSO2 ESB using the binary
+ distribution, and how to build WSO2 ESB using the source distribution.
+
+
+ Quick Start Guide :
+ Demonstrates two sample applications covering the basic and the most
+ common usage scenarios of the WSO2 ESB - Message mediation and Service
+ mediation.
+
+
+ User Guide : A
+ manual on how to run and configure the WSO2 ESB through the management
+ console. Descriptions include how to manage the underlying Synapse
+ configuration elements and the integrated registry, and how to interpret
+ statistics generated by the system.
+
+
+ Administrator Guide : A
+ manual on how to administrate and configure the WSO2 ESB through the management
+ console. Descriptions on advanced configurations like Remote/Embedded Registry
+ configuration, adding external libraries, Key store & User management. Briefly
+ describes the performance tunning the ESB as well.
+
+
+ Deployment Guide : A
+ manual on how to deploy the WSO2 ESB on different Application Servers, including the
+ configuration that are required to setup the ESB on those Application Servers.
+
+
+ Samples
+
+
+ Samples Setup Guide :
+ Provides step-by-step instructions on how to install the prerequisites,
+ and set up the samples given in this distribution - generic instructions
+ on how to start the sample server, deploy a service, and run the client.
+
+
+ How to Run the WSO2 ESB Samples :
+ While the document above gives you a generic description on how to set up
+ and and run the WSO2 ESB samples, this document takes each sample, one by
+ one and discusses the objective of the sample, its prerequisites, and its
+ expected behavior when the sample is built.
+
+
+ Advanced Topics
+
+
+ Extending Synapse : Explains how
+ to write custom mediator implementations and custom configuration
+ implementations for mediators by extending Apache Synapse through WSO2
+ ESB. It also provides guidelines on how to configure these mediators.
+
+
+ Synapse Configuration
+ Language : Describes the configuration language used by the
+ underlying Synapse mediation engine. This document is provided only as a
+ reference, as the WSO2 ESB management console allows users to configure
+ the underlying engine graphically, through the management console
+
+
+ Secure Vault : Describes how you can
+ keep the secret information securely within the WSO2 ESB. You can secure any secret
+ including the passwords, keys or pass phrases.
+
+
+ Transactions : Describes the transaction support in WSO2
+ ESB. This guide contains information on using transaction mediator(which adds the distributed transaction
+ support) and also JMS transactions(local and distributed JMS transactions support) in WSO2 ESB.
+
+
Catalogs
+
+ Mediator Catalog : Comprehensive catalog of all the
+ available default mediators in the WSO2 ESB 4.0.0.
+
+
+ Endpoint Catalog : Comprehensive catalog of all the
+ available default endpoints in the WSO2 ESB 4.0.0.
+
+
+ Transport Catalog : Comprehensive catalog of
+ all the available default transports in the WSO2 ESB 4.0.0.
+
+
+ Other Resources
+
+
+ Frequently Asked Questions : Contains a set of FAQ's on WSO2 ESB, and
+ the related Axis2, Synapse components.
+
+
+ WSO2 ESB Features : Gives a high
+ level overview of the features pf the WSO2 ESB.
+
+
+ Java Docs : Application
+ Programing Interface of the Apache Synapse version used underneath the WSO2 ESB. If you want
+ to write advanced custom mediators, you will need this API.
+
+
+ External articles : A collection of external articles published on WSO2
+ ESB.
+
+
+ The WSO2 Oxygen Tank
+ Library : The Library contains articles, tutorials,
+ presentations, and other knowledge base items published on The Oxygen
+ Tank.
+
WSO2 Enterprise Service Bus (ESB) Endpoint Catalog
+
The endpoints catalog wlks you through the endpoints which are there inside the WSO2 ESB.
+This will cover the very basics of the endpoints and dive deeper in to the configurtion details and
+the technical implementation details as well
An endpoint
+defines an external destination for an outgoing message through WSO2
+ESB. An <endpoint> element defines an endpoint in the
+configuration. An endpoint may be specified as an address endpoint, WSDL based endpoint, a load
+balancing endpoint or a fail-over endpoint as follows:
+
+All the types of endpoints can have a name attribute which specify the name of the endpoint and such named endpoints
+ can be referred by other endpoints using a key attribute. For example if there is an endpoint named as "foo",
+the following endpoint can be used in any place, where "foo" has to be used.
+
+
+
+ <endpoint key="foo"/>
+
+
This let the users to reuse the already defined endpoints in several places.
+
The endpoints also have a trace attribute which turns on detailed trace information for messages being sent to the
+ endpoint. These are available in the trace.log configured via the log4j.properties file(which can be found within
+ lib folder once you unzip wso2 ESB zip). Setting the trace log level to TRACE will dump detailed trace information
+ including message payloads.
+
+
+At any given time an endpoint can be one of the following four states.
+
+
[1] Active - Endpoint is active and running.
+
[2] TimeOut - The endpoint can be in TimeOut state if
+ we get a timeout error when invoking the endpoint (because the endpoint is currently unavailable or due to a
+ network failure) or if it returns a previously defined error code for timeout state, the endpoint said to be in
+ TimeOut state. The possible error codes can be found in the SynapseConstant class (under the endpoint failure section). A timed out endpoint is a candidate for a suspenstion.
+ The configuration related to marking an endpoint for suspension is given by markForSuspension.If the configuration
+ does have a positive retrieve count (see the configuration section below) the endpoint will be retrieve again
+ (the number of time to retrieve can be configured using the same configuration element) and if it fails in further attempts it will transfer
+ into Suspended state.
+
[3] Suspended - When invoking the endpoint if a previously defined error code for Suspended state is returned
+ or a if a TimeOut endpoint fails in further attempts the endpoint is said to be in Suspended state.
+ The endpoint can goes into Active state once the suspend duration is over. The configuration section
+ called suspendOnFailure.
+
[4] Switch Off - The endpoint is moved into maintains mode.
+
+
+
+A state transfer between any state to Switch off state can be done only manually using JMX based API.
+ And also an endpoint which is in SwitchOff state can only transfer into Active state again using
+ the JMX based API. See section on using JMX based API to learn how to do this.
+
+
+
+The state transition between states can be shown as follows.
+
+
+
+
Figure1: The state transition between states in an endpoint
+
+
Using jconsole to manage state transition between states
+
+
The jconsole tool is a JMX-compliant graphical tool for monitoring a Java virtual machine. If you have installed
+ java you'll automatically get this tool. We'll add an endpoint (name 'ep1') and monitor the states transition
+ between states in ep1
+
+
+
1. Add an address endpoint called 'ep1'. Refer endpoint userguide to see how this can be done.
+
2. Start jconsole by typing jconsole at your termnial, if you encounter any problem please consult your operatying
+ system guide. You'll see the following console once you select Mbeans tab.
+
+
+
+
Figure2: Jconsole Mbeans tab
+
3.Go to org.apache.synpase menu from left hand and expand it. You'll see the following figure with the
+ endpoint ep1 that we just added.
+
+
+
+
Figure3: Endpoint Mbean is selected
+
+
4. Select the ep1 endpoint and you'll see the information related to this endpoint and please note that the state
+ is given as active as the first entry and value is set to true. The endpoint is in active state.
+
+
+
Figure4: The ep1 endpoint attributes. The endpoint is active.
+
+
5. Now go to the Operations tab and switch off the endpoint. You'll see a message saying the
+ operation was successful.
+
+
+
Figure5: Switching off the endpoint.
+
+
You'll also see a INFO level log message saying that the endpoint was switched off manually.
+
+
[2009-06-23 12:18:21,149] INFO - EndpointContext Manually switching off endpoint : ep1
+
+
6. Next again switch back to Attributes tab and see the state of the endpoint after refreshing it. You'll see
+ endpoint is inactive and the endpoint is in switch off state. At this point if you try to use a client which
+ use this endpoint you'll see it fails since the endpoint is down. You can use a similar approach activate the
+ endpoint back.
+
+
+
+
Figure6: Endpoint is in Switch off state.
+
+
Address Endpoint
+
Address endpoint is an endpoint defined by specifying the EPR (Endpoint Reference) and other attributes
+ of the configuration.
EPR of the target endpoint.
+ See the table below for a possible list of transports.
+
format
Message format for the endpoint.
+
optimize
Method to optimize the attachments.
+
encoding
The charset encoding to use for the endpoint.
+
statistics
This enables statistics for the endpoint.
+
trace
This enables trace for the endpoint.
+
+
+
QoS for the endpoint
+
QoS (Quility of service) aspects such as WS-RM(WS-Reliable messaging), WS-Security and WS-Addressing may be
+ enabled on messages send to an endpoint using enableRM, enableSec and enableAddressing
+ elements. Optionally, the WS-RM and WS-Security policies could be specified using policy attribute.
+
+
QoS configuration
+
+
+
+
enableRM [policy="key"]
This enables WS-Reliable messaging
+ for the message which goes for the endpoint. The optional policy attribute specify the WS-RM
+ policy.
+
enableSec [policy="key"]
This enables WS-Security for
+ the message which goes for the endpoint. The optional policy attribute specify the WS-Security
+ policy.
This enables WS-Addressing for the message which goes for the endpoint. User can specify
+ to have seperate listener with version final or submission.
+
+
+
Endpoint timeout
+
Address(and also WSDL) endpoints can timeout if the response fails to arrive at Synapse by a predefined
+ timeout duration specified in seconds. The timeout action specifies whether to discard reponse that arives
+ later, or to trigger a fault. Synapse has a periodic timeout handler that triggers itself at each 15 seconds
+ interval. Thus endpoint timeout will have a +/- erroce on trigger time. Though this can be minimized by
+ setting a System property "synapse.timeout_handler_interval"(This property can be set in synapse.properties
+ synpase property file which is located in conf directory inside repository once you unzipped WSO2 ESB )
+ to a millisecond duration below the desired endpoint timeout, care must be taken as a lesser value may have a
+ higher overhead on the system.
+
+
timeout configuration
+
+
+
duration
Timeout duration in millisecond.
+
action
Once a timeout occurs the action to perform, avilable
+ options are discard (discard the response which arrives late) or fault (trigger a fault)
+ .
+
+
+
Marking endpoint for suspension
+
As described before (see description on Timeout state above) this configuration element describes the configuration
+ for a timeout endpoint.
+
+
markForSuspension configuration
+
+
errorCodes
A comma separated error code list which can be
+ returned by the endpoint. See SynpaseConstant class for a possible list of error codes.
+
retriesBeforeSuspension
Number of retries before go into suspended
+ state.
+
retryDelay
The delay between each try.
+
+
Suspending endpoint on failure
+
Leaf endpoints(Address and WSDL) endpoint can be put into suspended state if it is detected as failed. An endpoint that
+ fails may be suspended for a specified duration after such a failure, during which new messages will not be
+ processed through the endpoint. The amount of time waiting before next attempt follows the following formula.
+
+ next suspension time period = Max (Initial Suspension duration * (progression factor try count), Maximum Duration)
+
+ All the variables in the above formula are configuration values used to calculate the try count. Try count means,
+ how many tries occurred after the endpoint is SUSPENDED. As the try count increases, the next SUSPENSION time
+ period will also increase. This increase is bound to a maximum duration.
+
+
+
suspendOnFailure configuration
+
+
+
+
+
errorCode
+
+
A comma separated error code list which can be returned by the endpoint. See SynpaseConstant class for a possible list of error codes.
+
+
+
+
+initialDuration
+
+
Initial duration(in milliseconds) to suspend the endpoint.
+
+
+
+
+progressionFactor
+
+
The progression factor for the geometric series. See above for a more detailed description.
+
+
+
+
+maximumDuration
+
+
Maximum duration(in milliseconds) to suspend the endpoint.
+
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, reliable messaging, security policies for the endpoint
+ can be specified as in the 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.
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 inlined 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. enableRM, enableSec, enableAddressing, suspendDurationOnFailure and timeout elements are same
+ as for an Address endpoint.
A Load balanced endpoint distributes the messages (load) arriving at it
+ 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 & member child
+ elements in the same configuration. In the case of the member child element, the hostName,
+ httpPort and/or httpsPort attributes could be specified.
+
+ 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 SAL endpoints. 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, list failover endpoints as the target endpoints.
+
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.
+
+
Failover endpoint configuration
+
+<failover>
+ <endpoint .../>+
+</failover>
+
+
+
Dynamic Load balance Endpoint
+
A Dynamic Load balanced endpoint distributes the messages (load) arriving at it among a application members by
+ evaluating the load balancing policy and any other relevant parameters. These application members 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. 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
+ forwaded to. 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.
+
+
+
\ No newline at end of file
diff --git a/docs/xdoc/extensions_guide.xml b/docs/xdoc/extensions_guide.xml
new file mode 100644
index 0000000000..08ba706a71
--- /dev/null
+++ b/docs/xdoc/extensions_guide.xml
@@ -0,0 +1,890 @@
+
+
+
+
+
+
+
+
+
+ WSO2 ESB - Extending
+
+
+
+
+
+
+ [ Documentation Index ]
+
+ Extending WSO2 Enterprise Service Bus (ESB)
+
+
+ This document explains how to write custom mediator implementations and
+ custom configuration implementations for mediators by extending Apache
+ Synapse through WSO2 ESB. It also provides guidelines on how to configure
+ these mediators.
+
+ 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.
+
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()...
+
+}
+
+ The MessageContext interface is based on the Axis2 MessageContext
+ interface, and it uses the Axis2 EndpointReference 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.
+
+ The second key interface for mediator writers is the Mediator interface:
+
+
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 Mediator {
+
+ /**
+ * 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);
+}
+
+ A mediator can read and/or modify the SynapseMessage 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.
+
+
+ Leaf and Node Mediators, List Mediators and Filter Mediators
+
+
+ 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.
+
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();
+}
+
+ 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.
+
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 FilterMediator 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);
+}
+
+ Writing Custom Configuration Implementations for Mediators
+
+
+ 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 ESB_HOME/repository/components/dropins
+ folder, so that the Synapse runtime could find and load the definition.
+
+ 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.
+
+
+
Note:
+ However there is a limitation with this custom mediators. Currently ESB 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.
+
+
+
+ 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.
+
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();
+}
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();
+}
+
+ Configuring Mediators
+
+
+ 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.
+
+
+ Loading of Extensions by the Synapse Runtime
+
+
+ Synapse loads available extensions from the runtime classpath using the J2SE
+ Service Provider model. 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:
+
+
synapse-extensions.jar
+ /META-INF/services
+ org.apache.synapse.config.xml.MediatorFactory
+ org.apache.synapse.config.xml.MediatorSerializer
+ /... the implementation classes as usual...
+
+
+
Scheduled Tasks
+
+
+
+
Task is a one of method to automatically driving the mediation in the ESB.
+This is an implementation of ESB Startup which allowed adding tasks should run
+at ESB 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.
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
+
+
(which must implement
+org.apache.synapse.task.Taskinterface) to be
+executed at the specified interval/s, and name specifies an identifier for the
+scheduled task.
+
+
In the current ESB , there is only one implementation -
+org.apache.synapse.startup.tasks.MessageInjector.This can be
+used to inject messages at ESB startup.
+
+
+
+
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')
+
+
+
+
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 ESB. 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.
+
+
+
+
Extending Task
+
+
A custom Task can be developed by writing a custom Java class that
+implements the org.apache.synapse.task.Task interface. Task
+interface is shown bellow.
+
+
+
package org.apache.synapse.task;
+
+/*** Represents an executable Task*/
+
+public interface Task {
+
+ /*** Execute method will be invoked by the QuartzJOb.
+ */
+ public void execute();
+
+}
+
+
+ Xpath Extension Framework
+
+
+ WSO2 ESB 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 ,
+
+
+ 1.xpath variable expressions
+ 2.xpath function expressions
+
+
+ this allows us to access xpath variables with "$" . Currently there are several
+ predefined synapse xpath variables avaiable.
+
+
+ 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
+
+
+ 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().
+
+
+ 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.
+
+ 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.
+
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,
+
+ with implementation in place mediators can refer version , name , release date on
+ HELLO_WORLD message using expression="$HELLO_WORLD/version" , etc
+
+
+ Implementing hello-world() custom xpath function
+
+
+ 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
+
+
+ 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");
+ }
+ }
+
+
+
+ Shown bellow is the custom xpath function returned by our xpath function extension. Note
+ that this should implement org.jaxen.Function to resolve xpath .
+
+
+ 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);
+ }
+ }
+
+ }
+
+
+ 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
+
+
+ Registering Extensions
+
+
+ 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 .
+
+ If multiple function / variable extesnions are needed comma delimited list can be
+ declared. WSO2 ESB at startup will register all these declared extensions (defined under
+ its CLASSPATH) and our HELLO-WORLD xpath extensions will be ready to roll.
+
WSO2 Enterprise Service Bus (ESB) Frequently Asked Questions
+
+ This article provides answers to most commonly asked questions regarding WSO2 ESB,
+ its underlying Carbon framework, ESB deployment and configuration.
+
+ WSO2 ESB is a fast, lightweight, open source Enterprise Service Bus implementation. It supports
+ message routing, inter-mediation, transformation, logging, load balancing, fail over routing,
+ task scheduling, eventing and much more.
+
+
+
+
+ What makes WSO2 ESB unique?
+
+
+ WSO2 ESB is fast and able to handle thousands of concurrent connections with constant memory usage.
+ It comes with a rich set of mediators to support almost any integration scenario out of the box.
+ It is also easily extensible and highly customizable. The feature rich admin console makes it
+ so easy to configure, control and monitor the ESB runtime.
+
+ WSO2 ESB is distributed completely free and all the distribution packs can be downloaded from the
+ WSO2 Oxygen Tank. WSO2 ESB can be downloaded as a binary distribution or a source distribution and
+ if required one can even checkout the complete source code from the
+ WSO2 SVN repository.
+
+
+
+
+ Does WSO2 ESB has performance comparison with other popular ESBs?
+
+
+ Yes, several rounds of performance comparison has been carried out and the results are available
+ in WSO2 Oxygen Tank
+
+
+
+
+ Is their commercial support available for WSO2 ESB?
+
+
+ We are committed to ensuring that your enterprise middleware deployment is completely supported
+ from evaluation to production. Our unique approach ensures that all support leverages our open
+ development methodology and is provided by the very same engineers who build the technology. For
+ more details and to take advantage of this unique opportunity please visit
+ WSO2 Support.
+
+
+
+
+
+ Can I get involved with the ESB development activities?
+
+
+ Not only you are allowed, but it is encouraged. You can start by subscribing to carbon-dev@wso2.org
+ and architecture@wso2.org mailing lists. Feel free to provide ideas, feed back and help us make our
+ code better. You can also report bugs on our issue tracker and you can even submit patches. Visit
+ WSO2 Oxygen Tank for more information about our mailig lists.
+
+
+
+
+
Core (Questions related to the Carbon core and underlying framework)
+
+
+
+ What are the technologies used underneath WSO2 ESB?
+
+
+ WSO2 ESB is built on top of WSO2 Carbon, an OSGi based components framework for SOA. It uses
+ Apache Synapse as the underlying mediation engine.
+ Java is the primary programming language used to develop WSO2 ESB.
+
+
+
+
+ What are the minimum requirements to run WSO2 ESB?
+
+
+
+ Hardware Requirements:
+
+
Pentium 800MHz or equivalent processor
+
256 MB of memory
+
The extracted binary distribution of WSO2 ESB takes up about 130 MB of disk space
+ (WSO2 ESB will require more disk space at runtime to keep temporary files,
+ server logs etc)
+
+
+
+
+ Software Requirements:
+
+
Java Runtime Environment 1.5 or above
+
+
+
+
+
+
+ What makes WSO2 ESB so fast?
+
+
+ The mediation core of WSO2 ESB is designed to be completely asynchronous, non-blocking and
+ streaming. It comes with a non-blocking HTTP transport adapter based on Apache HTTP Core-NIO which
+ is capable of handling a large number of concurrent connections. WSO2 ESB also uses Apache AXIOM, a
+ StAX based XML infoset model, to process XML and SOAP. This enables WSO2 ESB to stream messages
+ through the mediation engine without having to invoke slow XML processing routines for each and
+ every message.
+
+
+
+
+
+ Does WSO2 ESB support clustering?
+
+
Yes, it supports clustered deployment. WSO2 ESB uses the Apache Axis2 clustering framework to
+ support the following two clustering schemes:
+
+
Multicast based clustering
+
Well known addressing based clustering
+
+
+
+
+
+ In what occasions do I have to deploy a third party library into WSO2 ESB?
+
+
+
When enabling a new transport you will have to deploy the libraries required by the
+ transport implementation (eg: When enabling JMS you need to deploy the client libraries required
+ to connect to your JMS broker)
+
+
When adding a custom mediator or a task you might have to deploy the dependencies required
+ by the custom code
+
+
+
+
+
+ How do I deploy a third party library into the ESB?
+
+
+ You can deploy any third party jar into the repository/components/lib directory. You also need to
+ restart the server for the newly deployed jars to be picked up by the server runtime. WSO2 ESB will
+ convert any jar files copied into the above location into OSGi bundles. These OSGi bundles are
+ placed in the repository/components/dropins directory.
+
+
+
+
+
+ Can I extend the management console UI to add custom UIs ?
+
+
+ Yes, you can extend the management console easily by writing a custom UI component.
+
+
+
+
+
+ Can I use an external user store to manage and authenticate WSO2 ESB users?
+
+
+ Yes you can. You can connect WSO2 ESB with any external user store implementation.
+ The user store could be LDAP based, JDBC based or a custom developed user store. Please
+ refer user core documentation for more details.
+
+
+
+
+
+ Does WSO2 ESB interop with a .net client/service?
+
+
+ Yes, it does with both. WSO2 ESB can be easily configured to bridge Java services with .NET clients
+ and .NET services with Java clients.
+
+
+
+
+
+ Does WSO2 ESB support hessian binary web service protocol
+
+
+ Yes, it does
+
+
+
+
+
+ I don't want some of the features that come with WSO2 ESB. Can I get rid of them?
+
+
+ Yes you can. Login to the ESB management console and browse to the Feature Manager. Open the
+ 'Installed Features' tab. From here you can uninstall any unwanted features.
+
+
+
+
+
+ Can I add support for other language for the management console ?
+
+
+ Yes, WSO2 ESB comes with a UI framework which supports i18n (internationalization) which lets you
+ to use a language of your choice for the management console.
+
+
+
+
+
+
Mediation (Questions related to sequences, endpoints, proxies etc)
+
+
+
+ What is a proxy service?
+
+
+ A proxy service is a virtual service hosted on the ESB. It can accept requests from service clients,
+ just like a real Web Service. A proxy service can process requests and forward them to an actual
+ Web Service (back end service) to be further processed. The responses coming back from the back
+ end service can be routed back to the original client. Proxy services are mostly used
+ to expose an existing service over a different transport, format or QoS configuration.
+
+
+
+
+
+ Does WSO2 ESB has support for transactions ?
+
+
+ Yes it does. It has support for distributed transaction, local JMS transactions and distributed JMS
+ transactions.
+
+
+
+
+ Does WSO2 ESB has support for PEPPOL?
+
+
+ Yes it does. You can use WSO2 ESB in an Access point.
+
+
+
+
+ Where do I have to put my custom mediators in WSO2 ESB?
+
+
+ In version 3.0.1 you can place your non-OSGi custom mediators and class mediators in
+ $ESB_HOME/repository/components/mediators and OSGi bundles
+ in $ESB_HOME/repository/components/dropins.
+
+
+
+
+ Where does WSO2 ESB load its configuration from?
+
+
+ WSO2 ESB reads its mediation configuration from a set of XML files located at
+ repository/conf/synapse-config directory. XML files are written in the Synapse configuration
+ language. Any changes done to the configuration through the UI are saved back to the configuration
+ files. (Configuration is also written to the registry by default)
+
+
+
+
+ Can I get the ESB to load mediation configuration from the registry?
+
+ A mediator is the basic message processing unit in the ESB. A mediator can take a message, carry
+ out some predefined actions on it and output the modified message. WSO2 ESB ships with a range of
+ mediators capable of carrying out various tasks on input messages.
+
+
+
Log mediator - Logs the input message
+
Send mediator - Sends the input message to a given endpoint
+
XSLT mediator - Transforms the input message using a given XSLT
+
+
+
+
+
+ What is a sequence?
+
+
+ A sequence is an ordered list of mediators (a mediator chain). When a sequence is given a message,
+ it will go through all the mediators in the sequence. A sequence can also handover messages to
+ other sequences.
+
+
+
+
+
+ What is an Endpoint?
+
+
+ Endpoint is a target or collection of targets that a message can deliver.
+
+
+
+
+
+ Can Endpoint perform error handling?
+
+
+ Yes. Endpoints can do error handling. User can configure the behavior of an endpoints when it
+ faced to a erroneous situation. You can find detailed article about endpoint error handling
+
+ here.
+
+
+
+
+
+
+ What are local entries?
+
+
+ Local entries can be used to hold various configuration elements required by sequences and proxy
+ services. Usually they are used to hold WSDLs, XSDs, XSLT files etc. A local entry can contain XML
+ content as well as plain text content. A local entry can be configured to load content from a
+ remote file too.
+
+
+
+
+
+ How can a sequence refer to another sequence?
+
+
+ To refer to a sequence named foo use the sequence mediator as follows:
+
+
+<sequence key="foo"/>
+
+
+ You can also refer to dynamic sequences saved in the registry by specifying the registry key to the
+ sequence resource as follows:
+
+
+<sequence key="gov:/dev/sequences/foo"/>
+
+
The above sequence mediator will load the sequence configuration from the resource at
+ /dev/sequences/foo in the governance registry.
+
+
+
+
+ How does dynamic endpoints and sequences work?
+
+
+ Dynamic endpoints and sequences are just XML configuration bits saved in the registry. These
+ configurations are loaded to the mediation configuration at runtime. Once loaded they will be cached
+ for a specified duration in the memory. Once the cache is expired it will be loaded again from the
+ registry. Therefore changes done to dynamic sequences and endpoints at runtime will take effect
+ once the ESB reloads them after a cache timeout.
+
+
To use dynamic sequences and endpoints the mediation registry must be included in the
+ mediation configuration as follows:
+
+ This configuration can be found in a file named registry.xml in the repository/conf/synapse-config
+ directory by default. Note how the cache duration is set to 15000 ms (15s). This duration can be
+ reduced or extended as necessary by editing the registry.xml file or through the configuration
+ source editor in the UI.
+
+
+
+
+
+ How can I change the endpoint dynamically?
+
+
+ If you want to change the endpoint dynamically per each message, you can use a header mediator to
+ calculate the new 'To' address.
+
+
+<header name="To" expression="XPath to create the address dynamically"/>
+
+
+
+
+
+ I have heard of dynamic sequences and endpoints. Are there also dynamic proxy services?
+
+
+ WSO2 ESB does not support dynamic proxy services. But a proxy service may use a dynamic
+ endpoint as the target endpoint and dynamic sequences as the in sequence and the out sequence.
+ This effectively makes the entire proxy service dynamic.
+
+
+
+
+
+ I want to mediate messages containing binary content through the ESB. What are the features
+ available in WSO2 ESB to support my requirement?
+
+
+
+
+
+
+
+ How can I implement a persistence mechanism within my mediation chain?
+
+
+ You have two options. One option is to use dbreport and dblookup mediators to
+ persist the message into a database and lookup it later from the database. The other option is
+ to use JMS transport in which you can use a JMS broker to persist the message.
+
+
+
+
+
+ I have some dynamic sequences which are loaded from the registry. What will happen to my ESB if
+ the registry goes down or registry becomes unusable for a while?
+
+
+ If the dynamic sequences are loaded to the memory at least once, the ESB will continue to use the
+ cached version of the sequence, as long as the registry is unreachable. A warning will be logged
+ every time ESB attempts to load the sequence from the registry and fails. As soon as the registry
+ comes back on-line, ESB will load the sequence from the registry.
+
+
+
+
+
Transports (Transport related questions)
+
+
+
+ What are the transports supported by the WSO2 ESB?
+
+ Do I need an external JMS broker for the JMS transport?
+
+
+ Yes, WSO2 ESB requires an external JMS broker like
+ Apache ActiveMQ.
+
+
+
+
+
+ Does WSO2 ESB support AMQP?
+
+
+ WSO2 ESB supports AMQP through its JMS transport. The JMS transport can be configured to
+ connect to an AMQP broker as if it was connecting to a JMS broker. This functionality has been
+ tested with Apache Qpid and RabbitMQ.
+
+
+
+
+
+ How to change the host name in WSO2 ESB?
+
+
+ You can edit parameter bind-address in http/https transport receiver to change the host name of WSO2
+ ESB. This hostname will be displayed on service endpoints and generated WSDLs.
+
+
+
+
+
+ I have several JMS connection factories defined under the JMS transport receiver in the axis2.xml.
+ How can I get a particular proxy service to receive messages from one of those connection factories?
+
+
+ You can specify the preferred connection factory by adding the following parameter to the proxy
+ service configuration.
+
Replace 'MyConnectionFactory' with the name of the appropriate connection factory.
+ If the above parameter is not specified, proxy service will bind to the connection
+ factory named 'default'.
+
+
+
+
+
+ Does WSO2 ESB support two way JMS scenario (request/response) ?
+
+
+ Yes, you can refer sample 264
+ which demonstrates exactly the JMS request/response scenario.
+
+
+
+
+
+ What are the JMS brokers that work with WSO2 ESB?
+
+
+ Any JMS broker that provides JNDI support can be integrated with WSO2 ESB. The default
+ configurations are for Apache ActiveMQ. WSO2 ESB has also been tested with IBM Websphere MQ,
+ Swift MQ and JBOSS MQ.
+
+
+
+
+ What is the NHTTP transport?
+
+
+ This is the default HTTP transport used by WSO2 ESB. NHTTP stands for non-blocking HTTP.
+ NHTTP transport uses the Java Non-blocking I/O API. This allows the NHTTP transport to scale into
+ handling hundreds of connections without blocking the threads. The server worker threads used
+ by the NHTTP transport do not get blocked on I/O until the ESB receives responses for the already
+ forwarded requests. Therefore WSO2 ESB can accept more concurrent connections and requests than
+ most HTTP server products.
+
+
+
+
+
+ What is the underlying HTTP library used by the NHTTP transport?
+
+
+ NHTTP transport uses the
+ Apache Http Core NIO library underneath. This library provides low level
+ I/O handling and HTTP level detail handling.
+
+
+
+
+
+ How can I tune up the NHTTP transport?
+
+
+ There is a file called nhttp.properties in the webapps/ROOT/WEB-INF/classes directory. User can
+ change various configuration parameters like number of threads, keep alive connections through
+ this file. More information can be found in the ESB Administrator Guide.
+
+
+
+
+
+ Where is the general configuration of NHTTP transport?
+
+
+ The NHTTP transport configuration has two parts and they are transportReceiver and transportSender.
+ Both configuration are located axis2.xml file.
+
+
+
+
+
+
+
Production (Questions related to production environments)
+
+
+
+
+ Where do I keep the WSDLs required by my proxy services?
+
+
+ You can keep them as local entries. But it is recommended to keep them in the registry instead, for
+ easier and better management.
+
+
+
+
+
+ What is a graceful shut down?
+
+
+ When a graceful shut down is initiated ESB will serve the accepted requests but stops processing
+ new requests
+
+
+
+
+
+ What are the implications of hot deployment/hot update in a production environment?
+
+
+ Hot deployment/hot update may take the system to inconsistent states if the updates are not properly
+ coordinated. Therefore it is recommended to turn hot deployment and hot update off for
+ production deployments.
+
+
+
+
+
+ I already have a WSO2 Governance Registry instance that contains my organization's SOA metadata.
+ Can I get WSO2 ESB to use that registry instance as the metadata store?
+
+
+ WSO2 ESB integrates with WSO2 Governance Registry out of the box. Refer the administrator
+ guide for the necessary steps involved in remote registry configuration.
+
+
+
+
+
+ I need to setup a cluster of ESB instances. How can I share the same configuration
+ among all the ESB nodes?
+
+
+ You just need to put the configuration into the registry and point all ESB instances to that
+ registry instance.
+
+
+
+
+
Deployment (Questions related to ESB deployments)
+
+
+
+ What are the versions of Java supported by the ESB?
+
+
+ It is tested on JDK 1.5 and JDK 1.6. Sun JDK and IBM JDK are supported.
+
+
+
+
+
+ What are the minimum artifacts required to deploy WSO2?
+
+
+ When deploying you can remove, $ESB_HOME/samples and $ESB_HOME/repository/samples from the
+ standard distribution.
+
+
+
+
+
+ How can I disable the management console ?
+
+
+ You can uninstall all the UI components using the feature manager which will disable the
+ management console.
+
+
+
+
+
+ Does WSO2 ESB supports application server deployments?
+
+
+ Yes it has been tested on the following app servers. JBoss, Weblogic, Websphere and Tomcat.
+
+
+
+
+
+ What are the recommended hardware and software configurations for a typical WSO2 ESB deployment?
+
+
+
+ Hardware configuration:
+
+
2 GHz Multicore processor
+
2 GB of memory
+
The extracted binary distribution of WSO2 ESB takes up about 130 MB of disk space
+ (WSO2 ESB will require more disk space at runtime to keep temporary files,
+ server logs etc)
+
+
+
+
+ Software Requirements:
+
+
Java Runtime Environment 1.6
+
+
+
+
+
+
+
+ How can I deploy a custom task?
+
+
+ See the documentation to see how to write a custom task. Put your non-OSGi task jar
+ into $esbhome/repository/components/lib directory. WSO2 ESB will automatically deploy
+ your custom task.
+
+
+
+
+
+ How do I embed a third party registry with WSO2 ESB?
+
+
+ You need to write a class implementing the org.apache.synapse.registry.Registry interface to
+ integrate the third party registry to WSO2 ESB.
+
+
+
+
+
+ What is the database management system used in WSO2 ESB?
+
+
+ WSO2 ESB ships with an embedded H2 database. However any database management system can be plugged
+ into the ESB via JDBC. The relevant database configurations are available in
+ repository/conf/registry.xml and repository/cong/user-mgt.xml files. WSO2 ESB has been tested
+ with MySQL, Oracle, MSSQL and PostgreSQL databases.
+
+
+
+
+
+ How can I change the memory allocation for the WSO2 ESB?
+
+
+ The memory allocation setting are in the wso2server.sh. The user can change the memory allocation
+ settings by changing the following configuration.
+
+
+ -Xms256m -Xmx512m -XX:MaxPermSize=128m
+
+
+
+
+
+
+
+
Monitoring
+
+
+
+ Does ESB supports JMX monitoring?
+
+
+ Yes it support JMX monitoring. Users can use the JConsole for simple monitoring and use
+ JMX clients for
+ custom monitoring
+
+
+
+
+ Does ESB allows custom statistics collection?
+
+
+ Users can write and plug their own statistics collection mechanisms to the ESB. This allows users
+ to report statistics to their own statistics collection systems.
+
+
+
+
+
+ What is logging framework used in WSO2 ESB?
+
+
+ WSO2 ESB uses Apache Log4/J over Apache Commons Logging as the logging framework.
+ Logging configuration is loaded from the log4j.properties file in the lib directory.
+ The UI also allows configuring logging at runtime. The generated server logs can be found in
+ the repository/logs directory.
+
+
+
+
+
+ I have a sequence which does not behave the way I want it to. How can I find out what's
+ wrong with it?
+
+
+ Login to the ESB management console and go to the sequence management page. Enable tracing for the
+ sequence you want to debug. Send a few messages to the sequence and go to the system logs viewer in
+ the UI (or open the wso2-esb.log file in repository/logs). Go through the generated trace logs and
+ locate the problem.
+
+
+
+
+
+ My WSO2 ESB instance is receiving messages. But why I don't see any statistics on the
+ mediation statistics page?
+
+
+ You need to enable statistics on sequences, endpoints, proxy services for the ESB to collect
+ statistics on them. By default WSO2 ESB does not collect statistics on anything to keep the overhead
+ at a minimum. Simply enable statistics for the items you are interested in using the UI and
+ mediation statistics page will start to get updated.
+
+
+
+
+
+ My ESB instance is behaving weird for certain input messages. What are the tools provided
+ in the ESB to help me debug the issue?
+
+
+ You can use the SOAP tracer in the UI to capture and monitor actual content of the incoming
+ messages. Enable tracing on the appropriate sequences to trace the flow of messages through
+ the ESB. ESB also comes with Apache TCPMon which is a simple but extremely useful too for
+ monitoring message flows.
+
WSO2 Carbon is an OSGi-based component framework allows the complete set of products to leverage
+ shared components, ensuring a consistent set of features between products, a consistent user
+ experience, and reusing of identical components.WSO2 Carbon provides the core capabilities
+ for security, clustering, logging,statistics, and management, and through a technology
+ called OSGi, higher level capabilities can be readily added as components to this core.
+ WSO2 ESB can be considered as WSO2 Carbon and bunch of features related to ESB.
+ With the power of componentized architecture of WSO2 Platform, user can add/remove various
+ features from all WSO2 product.
+
+
+
Introduction
+
This documentation provides guideline on feature management related to WSO2 ESB.
+
+
Installing various features in WSO2 ESB?
+
+
Using the Feature Manager (Configure > Feature in the tabbed pane) you can install any feature
+available in the feature repository(p2-repo). Please refer
+Feature Manager Documentation.
+
+
+
+
+
+
Installing ESB features on other WSO2 Products
+
+ Also there can be cases where we need to install the ESB related features inside other WSO2 Products.
+ For instance, we might have to install the ESB Features on raw Carbon Server. For such cases, ESB provides
+ a single feature which install all the ESB Related features. Using the Feature Manager
+ (Configure > Feature in the tabbed pane) you can install 'ESB Mediation' feature to get the functionality
+ of ESB in to any other WSO2 Product.
+
+
+
+
+
+
+
+
+
In addition to that you have to modify some configuration files to get the complete functionality of the
+ ESB.
+ Welcome to WSO2 Enterprise Service Bus (ESB) v4.0.0
+
+
+
+ WSO2 ESB is a lightweight and easy-to-use Open Source Enterprise Service Bus (ESB)
+ available under the Apache
+ Software License v2.0. WSO2 ESB allows system administrators and SOA architects to
+ simply and easily configure message routing, virtualization, intermediation,
+ transformation, logging, task scheduling, load balancing, fail-over routing, event
+ brokering and much more. The runtime has been designed to be completely asynchronous, non-blocking
+ and streaming based on the Apache Synapse mediation
+ engine.
+
+
+
+ WSO2 ESB 4.0.0 is developed on top of the revolutionary
+ WSO2 Carbon platform (Middleware a' la carte),
+ and is based on OSGi to provide better modularity and componentization
+ to your Service Oriented Architecture (SOA). This release also contains a number of
+ new features and many other optional components to customize the behavior of the server.
+ Further, if you do not want any built-in features, you can uninstall those
+ features without any trouble. In other words, WSO2 ESB can be customized and tailored to
+ suit your exact SOA requirements.
+
+
+
+ You can download WSO2 ESB 4.0.0 distribution from Project
+ Download Page and give it a try.
+
+
+
Getting Started
+
Getting your integration project off the ground with WSO2 ESB is simple.
+ WSO2 ESB supports many application layer protocols and messaging standards (collectively known
+ as transports), including HTTP/S, E-mail, Java Message Service (JMS) and Virtual File System
+ (VFS). It also supports a range of domain specific protocols such as Financial Information
+ eXchange (FIX), Advanced Message Queueing Protocol (AMQP) and Health Layer 7 (HL7). New
+ transports can be easily plugged into the server thanks to the seamless extensibility offered
+ by the Axis2 transports framework.
+
+
+ ESB uses message builder components to parse the messages
+ arriving via different transports. A message builder is usually associated with a content type.
+ Depending on the actual content type of an incoming message, the ESB will select a suitable
+ message builder, which will then parse the message content and convert it into the Apache AXIOM
+ based XML infoset. WSO2 ESB ships with message builders for handling text messages (plain text,
+ SOAP, POX etc) as well as binary messages. Message formatters are the opposite partners of the
+ builders. A formatter converts the message back to its original format by referring the content
+ type just before the message is handed over to the transports again for routing. Similar to the
+ transports, user can implement new message builders and formatters by using the Axis2 API.
+
+
+ Endpoints stay as a logical component with the transports. There are three types of top level
+ endpoints, namely Address endpoints, WSDL endpoints and Default endpoints. In addition to these
+ there are secondary endpoint types such as load balanced endpoints and fail over endpoints which
+ are composed of one or more top level endpoints. An endpoint can use any available transport
+ to dispatch the messages and they can even enforce various QoS constraints (security, RM etc)
+ on outgoing messages.
+
+
+ Proxy services are virtual services hosted in WSO2 ESB. These are implemented using Axis2 message
+ receivers and hence can be opened up to accept incoming messages. A proxy service can be accessed
+ using a URL similar to a regular web service address. Proxy services allow publishing a WSDL as
+ well so that a client can connect to a proxy service just like connecting to an actual Web Service.
+ Any available transport can be use to receive and send messages through the proxy services. Proxy
+ services are a great way for exposing existing services over different transports, schemas and QoS
+ configurations.
+
+
+ The power of WSO2 ESB lies in the comprehensive mediator library that provides various message
+ processing and inter-mediation capabilities. Using the mediator library we can implement all widely
+ used Message Exchange Patterns (MEP) and Enterprise Integration Patterns (EIP). There are simple
+ mediators which provide fundamental message processing capabilities such as logging and content
+ transformation as well as advanced mediators which can be used to access databases, add security to
+ message flows and so on. In situations where the built-in mediators are not sufficient to implement
+ a given scenario one can write a custom mediator on top of the simple but powerful API provided
+ by WSO2 ESB. Mediators can be implemented using various technologies including Java, scripting and
+ Spring, all of which are considered as extension points to the WSO2 ESB.
+
+
+ Sequences are special mediators that act as the configuration component for the mediators. Sequences
+ allow organizing the mediators to implement ordered pipes and filters pattern to achieve actual
+ message processing and mediation.
+
+
+ Tasks provide the ability to configure scheduled jobs in WSO2 ESB and they allow executing
+ internal and external commands for mediation. QoS components that implement reliable messaging
+ and security for the proxy services and for mediation come with the Apache implementations of
+ those two modules for Axis2, namely Rampart and Sandesha.
+
+
+ WSO2 ESB has an in-built registry/repository to store the configuration and configuration
+ metadata and it provides the facility to use a remote repository as well. Components like
+ clustering, load balancing and high availability makes WSO2 ESB a production ready server.
+ Finally the GUI components provide comprehensive management, configuration
+ and monitoring capabilities to the ESB. GUI is built on a layered architecture by separating the
+ backend and frontend concerns. This allow the user to connect to multiple servers using a single
+ GUI console. The component based architecture of the WSO2 ESB has enhanced its loosely coupled
+ nature with the usage of OSGi. All the components are built as OSGi bundles.
+
+ WSO2 Enterprise Service Bus (ESB) Installation Guide
+
+
+
+
This installation guide provides information on,
+
+
Prerequisites for installing WSO2 ESB
+
Installation instructions
+
Starting up WSO2 ESB
+
Accessing the management console
+
+
+
+ This document describes the distribution packages available in WSO2 ESB -
+ the binary distribution and the source distribution for more advanced
+ users. It is followed by simple instructions on how to install and run
+ WSO2 ESB using the binary distribution and how to build WSO2 ESB using the
+ source distribution.
+
+ The following distribution packages are available for download.
+
+
+ 1. Binary Distribution : Includes binary files for both MS Windows and
+ Linux operating systems, compressed into a single a zip file. Recommended
+ for normal users.
+
+
+ 2. Source Distribution : Includes the source code for both MS Windows and Linux
+ operating systems, compressed into a single zip file which can be used to build the binary files.
+ Recommended for more advanced users.
+
+
+ Installing and Running WSO2 ESB using the Binary Distribution
+
+ Apache ActiveMQ 5.0.0 or higher is required to enable the WSO2 ESB JMS
+ transport and try out JMS samples. The ActiveMQ client libraries must
+ be installed in the ESB classpath before you can enable the JMS transport.
+ Alternatively you may use the built-in Qpid broker that comes with
+ WSO2 ESB.
+
+
+ If you are using any other JMS provider (eg: IBM Websphere), you will need
+ to install necessary libraries.
+
+ To build the WSO2 ESB from its source distribution, you will need
+ Maven 2.2.0 or later
+
+
+
+
+ Web browser - To start the ESB Management Console
+
+
+ Mozilla Firefox 3.0 or higher at a resolution of 1024x768 is recommended. MS
+ Internet Explorer 7 or Google Chrome may be used as well. Once
+ the WSO2 ESB is started with the default settings, point the browser to
+ https://localhost:9443/carbon in order to access your Management Console.
+ See the WSO2 ESB User Guide for more details.
+
+
+
+
+ Memory
+
+
+ No minimum requirement - A heap size of 1GB is generally
+ sufficient to process typical SOAP messages. Requirements may vary
+ with larger message size and on the number of messages processed
+ concurrently
+
+
+
+
+ Disk
+
+
+ No minimum requirement. The installation will require ~125 MB
+ excluding space allocated for log files and Databases.
+
+
+
+
+ Operating System
+
+
+ Linux, Solaris, MS Windows - XP/2003/2008 (Not fully tested on Windows
+ Vista or Windows 7). Since WSO2 ESB is a Java application, it will generally
+ be possible to run it on other operating systems with a JDK 1.6.x
+ runtime. Linux/Solaris is recommended for a production deployment.
+
+
+
+
+
+
+
Installing on Linux/Unix
+
+ The following steps will take you through the binary distribution
+ installation on Unix/Linux systems.
+
+ Extract the zip archive where you want the WSO2 ESB installed (e.g. into /opt)
+
+
+ Set the JAVA_HOME environment variable to your
+ Java home using the export command or by editing /etc/profile, and add the Java /bin
+ directory to your PATH
+
+
+ Execute the WSO2 ESB start script or the daemon script from the bin
+ directory. e.g. ./wso2server.sh OR ./daemon.sh start OR
+ ./wso2server.sh --console
+
+
+ Check your WSO2 ESB instance using the URL https://localhost:9443/carbon
+ which will take you to the WSO2 ESB Management Console. (Note that server
+ start up may take time)
+
+
+ Login as "admin" using the default password "admin"
+
+
+
+
+ Installing on MS Windows
+
+
+ The following steps will take you through the installation for the MS
+ Windows operating system.
+
+ To build the WSO2 ESB from its source distribution, you will need
+ Maven 2.2.0 or later
+
+
+
+
+ Operating System
+
+
+ Linux, Solaris, MS Windows - XP/2003/2008 (Not fully tested on Windows
+ Vista)
+
+
+
+
+
+
+ Setting up the Environment and Tools
+
+
+
+ Maven:
+
+
+ The WSO2 ESB build is based on Apache
+ Maven 2. Hence, it is a prerequisite to have Maven (version 2.2.0 or later)
+ and JDK (version 1.6.x) installed in order to build WSO2 ESB from the
+ source distribution. Extensive instructions on using Maven 2 are available
+ on the Maven website.
+
+ Download Apache Maven tar ball or the zip archive.
+
+
+ Expand it to a directory of choice.
+
+
+ Set the environment variable M2_HOME and add M2_HOME/bin to the
+ path as well.
+
+
+ Run mvn --version to verify that it is correctly installed.
+
+
+
+
+ MS Windows
+
+
+
+
+ Download and run the Apache Maven Windows installer package.
+
+
+ Set the 'Environment Variables' (create the system variable M2_HOME
+ and edit the path. e.g., "C:\Program Files\Apache Software
+ Foundation\maven-2.2.1"; path %M2_HOME%\bin)
+
+
+ Make sure that the system variable
+ JAVA_HOME
+ is set to the location of your JDK, e.g., C:\Program Files\Java\jdk1.6
+
+
+ Run mvn --version to verify that it is correctly installed.
+
+
+
+ Once Maven is properly installed, you can start building the WSO2 ESB.
+
+
+ Building WSO2 ESB
+
+
+
+ Download
+ the source distribution, which is available as a zip archive.
+
+
+ Extract the source archive to a directory of your choice.
+
+
+ All the necessary build scripts are included with the source distribution.
+
+
+ You can run the following command inside that directory to build the
+ WSO2 ESB. Note that you will require a connection to the Internet for the Maven build
+ to download dependencies required for the build.
+
+
+ Command: mvn clean install
+
+
+
+
+ This will create the complete release artifacts including the binary and
+ source distributions in the modules/distribution/target/ directory which can be installed using
+ the above instructions.
+
+
+ Note: The first time you run Maven it will automatically download the
+ dependency jar files. Therefore, the first run will take more time. It is also
+ recommended to allocate for memory for Maven since the ESB build process takes up
+ a significant amount of resources. More memory can be allocated for Maven by setting
+ the MAVEN_OPTS environment variable.
+
WSO2 Enterprise Service Bus (ESB) Mediator Catalog
+
Mediators are the basic component of a mediation framework and the WSO2 ESB has a
+ comprehensive set of mediators. This guide will walk you through the genral concept of
+ mediation inside the WSO2 ESB and will also describe each and every mediator shipped with
+ WSO2 ESB, one by one
Message mediation is a fundamental part of any ESB. WSO2 ESB achieves
+message mediation through it's mediators. ESB comes with a rich set of 30 plus
+mediators to support the most common mediation functionalities as well as
+advanced functionalities.
+
+
Built in mediator capabilities of ESB provide functionality to match
+incompatible protocols, data formats and interaction patterns across different
+resources. Data can be split, cloned, aggregated and enriched, allowing ESB to
+match the different capabilities of services. XQuery and XSLT allows rich
+transformations on the messages. Rule based message mediation allows user to
+cope with the uncertainty of business logic. Content based routing using XPath
+filtering is supported in different flavors, allowing users to get the most
+convenient configuration experience. Built in capability to handle transactions
+allows message mediation to be done transactionally inside the ESB. With the
+Eventing capabilities of ESB, EDA based components can be easily
+interconnected. With features like throttling and caching integrated in to the
+message mediation, powerful interconnections can be made, allowing ESB to be
+used in the front end of organizations SOA infrastructure.
+
+
ESB mediation framework is designed from the ground up to be extensible.
+Everyday users write their own custom mediators to facilitate their custom
+requirements.
+
+
Now let's briefly look at how the mediation framework works.
+
+
How does a mediator work?
+
+
A mediator is a full powered processing unit in ESB. In run-time it has
+access to all the parts of ESB along with the current message. Usually a
+mediator is configured using XML. Different mediators have their own XML
+configurations.
+
+
At the run-time a Message is injected in to the mediator with the ESB
+run-time information. Then this mediator can do virtually anything with the
+message. Here are some examples of mediator functionalities.
+
+
Drop Mediator : Drops a message, stopping further processing of the
+ message
+
Send Mediator : Send the message out, using information inside the
+ message or according to some external configuration
+
Script Mediator : Executes a scripting language with the message
Wide range usage of mediators is visible through the above few examples.
+
+
Also mediators are considered as one of the main mechanisms for extending
+ESB. A user can write a mediator and put it in to ESB. This custom mediator and
+any other built in mediator will be exactly same from the API and the
+privileges.
+
+
Sequences
+
+
Sequence is a List Mediator of the ESB. That means it can hold other
+mediators and execute them. It is a part of the core of ESB and message
+mediation cannot live without this mediator. When a message is delivered to a
+sequence, it sends the message through all it's child mediators.
In-line sequences has their child mediators defined inside the sequence
+itself.
+
+
Named Sequences
+
+
<sequence key="name"/>
+
+
Named sequences refer other sequences using a key. This allows re-using of
+sequences.
+
+
There are two predefined sequences. They are called "main" and "fault". If a
+user doesn't specify these two sequences in the configuration, default
+sequences will be created automatically.
+
+
Here are the default configurations for main and fault
All the messages that are not for proxy services, will be sent through the
+Main Sequence.
+
+
A sequence can have an error handler. Error handler is again another
+sequence. If an error occurs while executing a sequence, its error handler will
+be called. Every sequence has an error handler. If one isn't explicitly
+specified, fault sequence will be treated as the error handler.
+
+
How does a message comes to a mediator?
+
+
There are two operational modes in the ESB. They are message mediation and
+proxy services. Message mediation is all about mediators. Proxy services can
+use message mediation as well.
+
+
Message Mediation
+
+
A message comes to the main sequence of the ESB if the message is not for
+any of the proxy services defined in the ESB.
+
+
Then this message goes through each of the mediators inside the main
+sequence.
+
+
If the message is sent to an Endpoint from the main sequence, response
+message will also comes to the main sequence.
+
+
Response message will also go through every child mediator of main
+sequence
+
+
If an error occurs in a sequence, message will go through sequence's fault
+sequence.
+
+
Proxy Services
+
+
Proxy service can have 3 sequences. Depending on the message path these
+three sequences can be executed. All the three sequences are optional.
+
+
In Sequence : A request message coming to a proxy service will go through
+ this sequence if the sequence is specified.
+
Out Sequence : A response message coming from the actual endpoint will go
+ through this sequence if the sequence is specified.
+
Fault Sequence : If an error occurs withing the proxy service operation,
+ message will go through this sequence
+
+
+
As mentioned earlier, every sequence is a collection of mediators. A message
+delivered to a sequence will go through all its child mediators.
+
+
WSO2 ESB has a built in sequence editor which helps user to develop/edit
+sequences. The Sequence Editor Guide gives
+an introduction to the usage of the sequence editor. Following is the catalog
+of the built in mediators of WSO2 ESB.
The aggregate mediator implements the Message Aggregator EIP and will
+aggregate the messages or responses for splitted messages using either the
+clone or iterate mediators. At the same time it can aggregate messages on the
+presence of matching elements specified by the correlateOn XPATH expression.
+Aggregate will collect the messages coming into it until the messages collected
+on the aggregation satisfies the complete condition. The completion condition
+can specify a minimum or maximum number of messages to be collected, or a
+timeout value in seconds, after which the aggregation terminates. On completion
+of the aggregation it will merge all of the collected messages and invoke the
+onComplete sequence on it. The merged message would be created using the XPath
+expression specified by the attribute 'expression' on the 'onComplete' element.
+
This optional attribute can be used to aggregate only responses for splitted messages that
+ are created by a specific clone/iterate mediator. Aggregate ID should be same as the ID of the
+ corresponding clone/iterate mediator that creates splitted messages. This is particularly useful
+ when aggregating responses of messages that are created using nested clone/iterate mediators.
+
+
+
+
Aggregation Expression
+
An XPath expression specifying based on which elements to aggregate.
+ Set of messages that's taken for aggregation is determined through
+ Correlation Expression .
+
+
+
Completion Timeout
+
Time that the aggregator waits for messages.
+
+
+
Completion Max-messages
+
Maximum number of messages that can exist in an aggregation.
+
+
+
Completion Min-messages
+
Minimum number of messages required for the aggregation to complete.
+
+
+
+
Correlation Expression
+
An XPath expression specifying the pattern messages will be collected
+ for aggregation. Specific aggregation condition will be set through
+ Aggregation Expression .
When a message comes to the Cache mediator, it checks weather an equivalent message is
+seen before. If the message is seen before it will execute a specified
+sequence. It uses message hashes for checking the equivalence of messages. Once the Cache
+meditor finds that the message is a cached message, it will fetch
+the cached response and prepare ESB for sending the response. If a
+sequence is specified for a cache hit, user can send back the response message
+within this sequence using a send mediator. If a sequence is not specified
+cached response is sent back to the requestor.
The cache mediator will evaluate the hash value of an incoming message as
+described in the optional hash generator implementation (which should be a
+class implementing the org.wso2.caching.digest.DigestGenerator interface). The
+default hash generator is 'org.wso2.caching.digest.DOMHashGenerator'. If the
+generated hash value has been found in the cache then the cache mediator will
+execute the onCacheHit sequence which can be specified inline or referenced.
+The cache mediator must be specified with an 'id' and two instances with this
+same 'id' that correlates the response message into the cache for the request
+message hash. The optional 'timeout' specifies the valid duration for cached
+elements, and the scope defines if mediator instances share a common cache per
+every host instance, or per every cache mediator pair (i.e. 'id') instance. The
+'collector' attribute 'true' specifies that the mediator instance is a response
+collection instance, and 'false' specifies that its a cache serving instance.
+The maximum size of a message to be cached could be specified with the optional
+'maxMessageSize' attributes in bytes and defaults to unlimited. Finally the
+'implementation' element may define if the cache is disk or memory based, and
+the 'maxSize' attribute defines the maximum number of elements to be cached.
+
+
+
+
+
UI Configuration
+
+
+
Cache Id: Id for the cache configuration. You should have same id for a
+ cache mediator instance in incoming path and the corresponding mediator
+ instance in outgoing message path.
+
Cache Scope: Scope of the cache. This is important if the service is
+ deployed in a cluster.
+
+
Per-Host: The cache is kept only for the current host in a cluster.
+
+
Per-Mediator: The cache is kept once for the whole cluster.
+
+
+
Cache Type: Whether the mediator is in the incoming path (check request)
+ or the outgoing path (cache the response).
+
+
Finder: Set if the message is incoming path. This indicate the
+ mediator find for the request hash of each incoming message.
+
Collector: Set if the message is in outgoing path. This indicate the
+ mediator collect the response message in the cache.
+
+
+
Hash Generator: The logic for finding the hash which check against each
+ incoming message. Default to org.wso2.caching.digest.DOMHASHGenerator
+
Cache Timeout: The cache timeout(The time to keep the cache before
+ expiring) in seconds.
+
Maximum Message Size: The limit of the message to cache in bytes.
+
Implementation Type: Currently only "In-Memory" is available.
+
On Cache Hit: Specify the sequence to follow when the cache mediator is
+ hit. You can either specify it as anonymous where you can define child
+ mediators for the Cache mediator or you can refer a named sequence of
+ mediators from the registry.
In this example, first message will be sent to the endpoint specified as
+cache is not hit. The responce will come to the cache mediator inside the out
+meduator and this will cache the response. The second equal message will match
+the cache and response will be directly fetch from the cache and sent to the
+requestor. This happens because no onCacheHit sequence is defined.
+ The <callout> mediator performs a blocking external service invocation
+ during mediation. The serviceURL and the optional action specifies the
+ parameters for this external call. The source element specifies the payload for
+ the request message using an XPath expression; or a registry key that will be
+ used. The target element specifies a node, at which the resulting payload will
+ be attached into the current message, or the name of a key/property using which
+ the response would be attached to the current message context as a property.
+
+
+
+ As the callout mediator performs a blocking call, it cannot use the default
+ non-blocking http/s transports based on Java NIO, and thus defaults to using
+ the samples/axis2Client/client_repo/conf/axis2.xml as the Axis2 configuration,
+ and samples/axis2Client/client_repo as the client repository unless these are
+ specified separately
+
In this scenario, Callout mediator does the direct service invocation to the StockQuoteService using the client
+ request, get the response and set it as the first child of the SOAP message body. Then using the send mediator,
+ the message is sent back to the client.
The class mediator creates an instance of a custom specified class and sets it as a mediator. The class must
+ implement the org.apache.synapse.api.Mediator interface. If any properties are specified, the corresponding
+ setter methods are invoked on the class, once, during initialization.
+
+
Syntax
+
<class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+ </class>
+
+
+
UI Configuration
+ Figure 1: Adding a Class mediator
+
+
+ Clicking on the 'Class' mediator option as shown in above figure, will open
+ up the 'Class' mediator specific options. You can specify the specific implementaion class and load it by
+ clicking 'LoadClass' button. Once you load the class, you'll see the configuration options
+ as in figure2.
+
+
+ Class mediator configuration descriptions
+
+
+
+ Class Name: The class name of the class. You have to give the qualified name of the class and click
+ "Load Class" button.
+
+
+ Properties defined for Class mediator: This list the properties with setter functions of the uploaded class.
+ Following fields are listed for each property.
+
+
+ Property Name - Name of the property.
+
+
+ Property Value - The value to be set to the property.
+
+
+ Action - Link to delete the unused properties, from the list.
+
In this configuration, ESB hands over the request message to the specified endpoint, which sends it to the
+ Axis2 server running on port 9000. But the response message is passed through the class mediator before sending it
+ back to the client. Two parameters named "varible1" and "varible2" are passed to the instance mediator
+ implementation class(SimpleClassMediator). Look at the following sample class mediator. Note how the
+ SynapseMessageContext and to the full Synapse API in there.
+
A simple class mediator implementaion.
+
+
package samples.mediators;
+
+ import org.apache.synapse.MessageContext;
+ import org.apache.synapse.Mediator;
+ import org.apache.axiom.om.OMElement;
+ import org.apache.axiom.om.OMAbstractFactory;
+ import org.apache.axiom.om.OMFactory;
+ import org.apache.axiom.soap.SOAPFactory;
+ import org.apache.commons.logging.Log;
+ import org.apache.commons.logging.LogFactory;
+
+ import javax.xml.namespace.QName;
+
+ public class SimpleClassMediator implements Mediator {
+
+ private static final Log log = LogFactory.getLog(DiscountQuoteMediator.class);
+
+ private String varible1="10";
+
+ private String varible2="10";
+
+ private int varible3=0;
+
+ public DiscountQuoteMediator(){}
+
+ public boolean mediate(MessageContext mc) {
+ // Do somthing useful..
+ // Note the access to the Synapse Message context
+ return true;
+ }
+
+ public String getType() {
+ return null;
+ }
+
+ public void setTraceState(int traceState) {
+ traceState = 0;
+ }
+
+ public int getTraceState() {
+ return 0;
+ }
+
+ public void setvarible1(String newValue) {
+ varible1=newValue;
+ }
+
+ public String getvarible1() {
+ return varible1;
+ }
+
+ public void setvarible2(String newValue){
+ varible2=newValue;
+ }
+
+ public String getvarible2(){
+ return varible2;
+ }
+ }
+
+
A fully working sample is availble. See synapase configuration lanaguge guide for detailed(under
+ section called class mediator) working sample.
As the name suggests clone meditor can be used to clone a message in to
+several messages.
+
+
The clone mediator closely resembles the Message Splitter EIP and will split
+the message into number of identical messages which will be processed in
+parallel. They can also be set to process sequentially by setting
+the value of the optional 'sequential' attribute to 'true'.
+The original message cloned can be continued or dropped depending on
+the boolean value of the optional 'continueParent' attribute. Optionally a
+custom 'To' address and/or a 'Action' may be specified for cloned messages.
+The optional 'id' attribute can be used to identify the clone mediator which
+created a particular splitted message when nested clone mediators are used.
+This is particularly useful when aggregating responses of messages that are
+created using nested clone mediators.
+
Clone ID - This can be used to identify messages created by this clone mediator. This is
+ particularly useful when aggregating responses of messages that are created using nested
+ iterate mediators.
+
+
Sequential Mediation - If "Yes" created messages will be processed sequentially, otherwise
+ they will be processed in parallel.
+
+
Continue Parent - If "Yes" the original message will be continued. If
+ "No" the original message will be dropped.
+
Number of clones - Number of clones created. This can be controlled by
+ adding one or more clone targets by clicking Add Clone Target.Targets can then have it's own set of mediators.
Conditional Router mediator is used to route messages based on 'Condition' provided by user.
+
+
+The Conditional Router mediator can be used to specify the routing of the message according to given conditions. Mediator checks whether the
+ 'Condition' evaluates to true and mediates using the target sequence.
+ Matching route will break the router if the 'Break after route' is set to true.
+
User can define any number of routes. Each and every route must contain a 'condition' which is to be evaluated and a predefined
+ 'Target' sequence, which will be used to mediate further.
+
+
+
+
Figure 2: Route Configuration
+
+
+
+Continue after routing: (Yes/No), Whether to continue the routing if any of the child routes are executed. The default value is No.
+
+
+Break after route : If set to true, matching route will break the router.
+
+
+Evaluator Expression : Route condition .
+
+
+Target Sequence : Target sequence need to be provided as registry key/local entry to do further mediate processing.
+
The dblookup mediator is capable of executing an arbitrary SQL select
+statement, and then set some resulting values as local message properties on
+the message context. The DB connection used maybe looked up from an external
+DataSource or specified in-line, in which case an Apache DBCP connection pool
+is established and used.
+
+
In-lined Data Source
+
+
driver - Database driver class name
+
url - Database URL
+
user - User name for access Database
+
password Password for access Database
+
+
+
This new Datasource is based on Apache DBCP connection pools. This
+connection pool support the following configuration properties:
dsName - The name of the Datasource to be looked up
+
icClass - Initial context factory class. The
+ corresponding java environment property is
+ java.naming.factory.initial
+
url - The naming service provider url . The
+ corresponding java environment property is
+ java.naming.provider.url
+
user - This is corresponding to the java environment
+ property java.naming.security.principal
+
password - This is corresponding to the java environment
+ property This is corresponding to the java environment property
+ java.naming.security.principal
+
+
+
SQL Statements
+
+
sql - One or more SQL Statements
+
parameter - Specify how the values of parameter in the
+ SQL would be calculated. A value can be static literal text and can be
+ calculated at runtime based on the given expression.
+
result - Specify how to deal with rerun result from
+ Database query execution.
+
+
+
More than one statement may be specified, and the SQL statement may specify
+parameters which could be specified as values or XPath expressions. The types
+of parameters could be any valid SQL types. Only the first row of a result set
+will be considered and any others are ignored. The single
+<result> element contains the 'name'
+and the 'column' attributes. The 'name'
+attribute defines the name under which the result is stored in the Synapse
+message context, and the column attribute specifies a column number or name .
+
In this example, when a message arrives at dblookup mediator, it opens a connection to the database and executes the
+ SQL query. The SQL query use '?' character for attributes that will be filled at runtime. The parameters define how
+ to calculate the value of those attributes at runtime. In this sample a dblookup mediator has been used
+ to extract 'id' of the company from the company database using the symbol which is evaluated using an xpath against
+ the SOAP envelope.
The dbreport mediator is very similar to the dblookup mediator, but writes
+information to a Database, using the specified insert SQL statement. For
+configuration information about db mediators , refer dblookup mediator guide
This sample demonstrate simple database write operations. The dbreport mediator writes
+ to a table using the message details. It works the same as the dblookup mediator. In this sample , dbreport
+ mediator is used for updating the stock price of the company using the last quote value which is calculated by
+ evaluating an XPath against the response message.
+
Enqueue mediator works with priority mediation. It can be used to process a message
+ using a priority executor with a priority defined in priority executor.
+
Enrich Mediator can process a message based on a given source configuration
+and then perform the specified action on the message by using the target configuration.
+It basically gets an OMElement using the configuration specified in the source and
+then modify the message by putting it on the current message using the configuration
+in the target.
+
You have the following configuration under the Enrich mediator.
+
+
+
Source Configuration
+
+
Clone : By setting the clone configuration, the message can be cloned or
+ else use as a reference during the enriching. The default value for
+ clone is false.
+
+
True/False
+
+
+
Type : Specifies that the type that the mediator use from the original message to enrich the modified
+ message that pass through the mediator.
+
+
Custom : Custom XPath value
+
If there are any namespaces involved in the XPath expression, you
+ can specify it in the Namespace Editor.
+
+
Namespace Editor Screenshot
+
+
Envelope : Envelope of the original message will be used for enriching.
+
+
Body : Body of the original message will be used for enriching.
+
Property : Specifies a property.
+
Inline : Specifies an inline XML value
+
+
+
+
+
Target Configuration
+
+
Action : By specifying the action type the relevant action can be applied to outgoing message.
+
+
Replace : Replace the xml message based on the target type specified on the target configuration.
+
Child : Adding as a child of specified target type.
+
Sibling : Adding as a sibling of specified target type.
+
+
+
Type : Specifies that the type of enriching the outgoing message.
+
+
Custom : Custom XPath value.
+
If there are any namespaces involved in the XPath expression, you
+ can specify it in the Namespace Editor as in the Source Configuration.
+
+
Envelope : Envelope of the original message will be used for enriching.
+
+
Body : Body of the original message will be used for enriching.
The Entitlement Mediator by passes the requests and evaluates the actions performed by the user against the XACML
+ policy defined at the Policy Decision Point [WSO2 Identity Server]
+
Event mediator publishes events to the given event source. Thus, the
+presence of defined event sources are necessary prior to the usage of this
+mediator. User can apply any mediation before sending the message to the event
+source. This allows features like transformation, logging, filtering to be
+applied to a message coming to an Event Source.
Event Source: Select a source from currently available event sources. You
+ can define event sources from the "Event Sources" panel which can be
+ accessed from Configure-> Event Sources menu of the right hand side menu
+ bar.
In this scenario user has defined an event topic called SampleEventSource.
+When a event notification comes to the EventingProxy proxy service, the
+messages will be logged and then sent to the event topic.
The fault mediator transforms the current message into a fault message, but
+does NOT send it. The <send> mediator needs to be invoked to send a fault
+message created this way. The fault message "To" header is set to the
+"Fault-To" of the original message if such a header exists on the original
+message. If a 'version' attribute is specified, the created fault message will
+be created as a selected SOAP 1.1, SOAP 1.2 or POX fault.
You can select the version of the SOAP fault message that you want to
+create. Options are SOAP 1.1 and SOAP 1.2.
+
+
Fault Code
+
+
You can specify a fault code
+
+
versionMismatch: SOAP version mismatch error
+
mustUnderstand: A soap error regarding must understand error
+
Client: Client side error
+
Server: Server side error
+
+
+
Fault String
+
+
The detailed fault string of the fault code can specify here. It can be give
+either as a string value or as an expression. NSEditor: You can click this link
+to add namespaces if you are providing an expression. You will be provided
+another panel named 'Namespace Editor' where you can provide any number of
+namespace prefixes and url that you have used in the xpath expression. Here is
+an example of the use of namespaces in an expression.
+
+
Fault Actor
+
+
SOAP 1.1 fault actor(if you select SOAP 1.1)
+
+
+
+
Figure2: SOAP 1.1 with fault expression selected
+
+
Detail
+
+
Some information about the fault can be added here
+
+
If you select SOAP 1.2, you can see the followings
+
+
+
+
Figure2: SOAP 1.2 with fault expression selected
+
+
Reason
+
+
Reason is the fault reason describing the fault code
The <filter> mediator either test the given xpath expression as a
+Boolean expression, or match the evaluation result of a source xpath expression
+as a String against the given regular expression. If the test succeeds, the
+filter mediator will execute the enclosed mediators in sequence.
+
+
One could also use this mediator to handle the failure case as well, in
+which case the configuration would be as follows
In this case the filter condition remains as earlier and the succeeded
+messages will be mediated using the the set of mediators enclosed in the 'then'
+element in sequence, while failed messages will be mediated using the set of
+mediators enclosed in the else element in sequence
+
+
UI Configuration
+
+
+
+
Here are the configuration options related to Filter Mediator.
+
+
Specify As: Specify whether you give the condition as an XPath or a
+ Regular expression.
+
XPath: XPath expression if you selected the "Specify As" option to
+ "XPath". Note that you can define the namespaces used in the xpath by
+ clicking the "Namespaces" link
+
Source: XPath expression to locate the value which is going match with
+ the reguilar expression that you can define below.
+
Regex: Regular expression to match with the source value.
In this example, filter will get the To header value and match it against
+the given regular expression. If this evaluation returns true, it will send the
+message. If the evaluation returns false it will drop the message.
ESB receives a non reliable message and it forward it to an endpoint that
+supports reliable messaging. In this example when ESB recieves a message we
+send it using Reliable messaging. So the response ESB receives is having
+Reliable messaging headers. We don't want to send these headers to the client
+who doesn't support reliable messaging. So we remove the reliable messaging
+headers before sending the reponse to the client.
These mediators act as predefined filters. Messages which are in the in path
+of the ESB will traverse through the child mediators of the in mediator.
+Messages which are in the out path of ESB will traverse through the child
+mediators of out mediator.
Main sequence with in and out mediators. Messages coming to the ESB will be
+sent using wsa:to address and responses will be sent back to the requester.
+
+
Remarks
+
+
These mediators are pointless to be used in proxy service sequences. Proxy
+services has predefined sequences for in messages and out message.
The iterate mediator implements another EIP and will split the message into
+number of different messages derived from the parent message by finding
+matching elements for the XPath expression specified. New messages will be
+created for each and every matching element and processed in parallel (default behavior) using
+either the specified sequence or endpoint.
+Created messages can also be set to process sequentially by setting the optional 'sequential'
+attribute to 'true'. Parent message can be continued or
+dropped in the same way as in the clone mediator. The 'preservePayload'
+attribute specifies if the original message should be used as a template when
+creating the splitted messages, and defaults to 'false', in which case the
+splitted messages would contain the split elements as the SOAP body.
+The optional 'id' attribute can be used to identify the iterator which created a particular
+splitted message when nested iterate mediators are used. This is particularly useful when
+aggregating responses of messages that are created using nested iterate mediators.
+
Iterate Mediator can be configured with the following options.
+
+
Iterate ID: (Optional) This can be used identify messages created by this iterate mediator, useful
+ when nested iterate mediators are used.
+
+
Sequential Mediation: (True/False), Specify whether splitted messages should be processed sequentially
+ or in parallel. Default value is 'false' (parallel processing).
+
+
Continue Parent: (True/False), Specify whether the original message
+ should be continued or dropped, this is default to 'false'.
+
Preserve Payload: (True/False), Specify whether the original message
+ should be used as a template when creating the splitted messages or not,
+ this is default to 'false'.
+
Iterate Expression: Xpath expression that matches the elements which you
+ want to split the message from. You can specify the namespaces that you
+ used in the xpath expression by clicking the namespace link in the right
+ hand side.
+
Attach Path: (Optional), You can specify an xpath expression for elements
+ that the splitted elements (as expressed in Iterate expression) are
+ attached to, to form new messages
+
+
+
For more information about target please refer Target.
With the log mediator, you can log messages being mediated.
+
+
Log Category
+
Log Mediator supports following log categories.Log messages will be logged in log4j with
+selected log category. The default log category is INFO
+
+
TRACE
+
DEBUG
+
INFO
+
WARN
+
ERROR
+
FATAL
+
+
+
+
Log Levels
+
Log mediator has four log levels
+
+
simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any
+ properties
+
headers = All SOAP header blocks and any properties
+
full = all attributes included in log level 'simple' and the SOAP
+ envelope and any properties
+
custom = Only properties specified to the Log mediator
+
+
+
Log Separator
+
+
A separator if defined will be used to separate the attributes being logged.
+The default separator is the ',' comma
+
+
Log Properties
+
With properties, user can choose any other attributes that they want to log.
+Imagine there is an element carrying the transaction id in the SOAP body. User
+can use a XPath expression to extract out this transaction id element and log
+it using the log mediator. It is possible to define several such properties to
+be logged.
+
+
If properties are specified with any of the first three log levels, custom
+properties will be logged along with the default ones.
You can select the log category to be one of following values.
+
+
TRACE
+
DEBUG
+
INFO
+
WARN
+
ERROR
+
FATAL
+
+
+
Log Level
+
You can select the log level to be one of following values.
+
+
Simple: To, From, WSAction, SOAPAction, ReplyTo, MessageID and any
+ properties
+
Headers: All SOAP header blocks and any properties
+
Full: All attributes included in log level 'simple' and the SOAP envelope
+ and any properties
+
Custom: Only properties specified to the Log mediator
+
+
+
Log Separator
+
+
The log separator is used to separate the attributes being logged. The
+default separator is ',' (comma).
+
+
Adding Properties
+
+
You can add custom messages to log as the messages mediate thorough the log
+mediator.
+
+
+
+
Figure2: Log Mediator Properties
+
+
Property Name: Name for the property
+
Property Value: The type of the property value, possible candidates are
+ Value/Expression
+
+
Value - A static text message
+
Expression - An xpath expression executed on each mediating message
+
+
+
+
Value: The text or an expression you want to log
+
NSEditor: You can click this link to add namespaces if you are providing
+ an expression. You will be provided another panel named 'Namespace Editor'
+ where you can provide any number of namespace prefixes and url that you
+ have used in the xpath expression. Here is an example of the use of
+ namespaces in an expression.
The pojoCommand(or command) mediator creates an instance of the specified command class - which may implement the
+ org.apache.synapse.Command interface or should have a public void method "public void execute()". If any
+ properties are specified, the corresponding setter methods are invoked on the class before each message is
+ executed. It should be noted that a new instance of the POJO Command class is created to process each
+ message processed. After execution of the POJO Command mediator, depending on the 'action' attribute of
+ the property, the new value returned by a call to the corresponding getter method is stored back to the
+ message or to the context. The 'action' attribute may specify whether this behaviour is expected or not via
+ the Read, Update and ReadAndUpdate properties.
+ Clicking on the command mediator created as shown in figure 1 will open
+ up the command mediator specific options. You can specify the command mediator implementaion class and load it by
+ clicking LoadClass button. Once you load the pojo command class you'll see the command mediator configuration options
+ as in figure2.
+ Class Name: The class name of the Pojo class. You have to give the fully qualified name of the class and click
+ "Load Class" button.
+
+
+ Properties of the POJOCommand mediator: After you click the "Load Class" and if it is a valid Pojo Class
+ you will see the properties in the POJO class in a table with following fields.
+
+
+ Property Name - Name of the property. This will be automatically loaded from the class.
+
+
+ Read Info - The value to set for the property. You can choose the value from eaither of following sources
+
+
Value - A Static value
+
Message - Read a value from the incomming message. You can provide the xpath expression to
+ execute on the message in the 'Value' text field.
+
Context - Read a value from the Message context properties. You can provide the property key
+ in the 'Value' text field.
+
+
+
+ Update Info - Specify the action to do with reading the property value. You can choose following actions.
+
+
NONE - No activitly
+
Message - Update the message. You can provide the xpath expression of the element you want to
+ update in the "Value" text field.
+
Context - Update the properties (Message context). You can give the property key in the 'Value' text field.
Properties are name value pairs. Properties are a way to convey information
+across different processing units. For example user may need to set a transport
+property from the message mediation. Or user may need to remove a property
+which is set by the transport. This mediator sets or removes properties for a
+particular message.
+
+
Property mediator has no direct impact on the message but rather on the
+message context flowing through Synapse. The properties set on a message can be
+later retrieved through the synapse:get-property(prop-name) XPath extension
+function. If a scope is specified for a property, the property could be set as
+a transport header property or an (underlying) Axis2 message context property,
+or as a Axis2 client option. If a scope is not specified, it will default to
+the Synapse message context scope. Using the property element with action
+specified as "remove" you can remove any existing message context properties.
+
+
+
There are some well-defined properties that you can get/set on the Synapse
+message context scope:
+
+
+
+
+
+
+
+
+
+
+
Name
+
Values
+
Meaning
+
+
+
RESPONSE
+
true
+
'true' means the message is to be marked as a response message
+
+
+
OUT_ONLY
+
true
+
'true' means the message is to be marked as an out-only message that
+ does not expect a response
+
+
+
ERROR_CODE
+
String
+
this is set to any error message code encountered during a fault
+
+
+
ERROR_MESSAGE
+
String
+
this is set to any error message text encountered during a fault
+
+
+
ERROR_DETAIL
+
String
+
this is set to any error message detail text encountered during a
+ fault
+
+
+
ERROR_EXCEPTION
+
String
+
this is set to any Java Exception encountered during a fault
+
+
+
+
+
+
+
There are some Axis2 and module properties that are useful which are set at
+scope="axis2"
+
+
+
+
+
+
+
+
+
Name
+
Values
+
Meaning
+
+
+
MercurySequenceKey
+
integer
+
can be an identifier specifying an Mercury internal sequence key,
+ and
+
+
+
MercuryLastMessage
+
true
+
'true' will make this the last message and terminate the sequence
+
+
+
+
+
+
+
There are some Axis2 client side properties/options that are useful which
+are set at scope="axis2-client"
+
+
+
+
+
+
+
+
+
Name
+
Values
+
Meaning
+
+
+
FORCE_HTTP_1.0
+
true
+
forces outgoing http/s messages to use HTTP 1.0 (instead of the
+ default 1.1)
+
+
+
+
+
+
+
The synapse:get-property() XPath extension
+function
+
+
The get-property() function allows any XPath expression used in a
+configuration to look-up information from the current message context. 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. The function accepts the scope as an optional parameter as shown
+below:
Some useful properties from the Synapse message context follows:
+
+
+
+
+
+
+
+
Name
+
Meaning
+
+
+
SYSTEM_DATE
+
Returns the current date as a String. Optionally a date format as per
+ standard date format may be supplied. e.g.
+ synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or
+ get-property('SYSTEM_DATE')
+
+
+
SYSTEM_TIME
+
Returns the current time in milliseconds. (i.e. the difference,
+ measured in milliseconds, between the current time and midnight,
+ January 1, 1970 UTC)
+
+
+
To, From, Action, FaultTo, ReplyTo, MessageID
+
the message To and Action and WS-Addressing propertie
+
+
+
MESSAGE_FORMAT
+
returns the message format - i.e. returns pox, get, soap11 or
+ soap12
+
+
+
OperationName
+
returns the operation name for the message
+
+
+
+
+
+
+
In addition to the above, one may use the get-property() function to
+retrieve Axis2 message context properties or transport headers. e.g.
+synapse:get-property('transport', 'USER_AGENT')
+
+
+
+
SynapseXpath variables
+
+
There are a set of predefined XPath variables when writing XPaths in the
+Synapse Configuration. Those are as follows;
+
+
+
+
+
+
+
+
Name
+
Meaning
+
+
+
body
+
The SOAP 1.1 or 1.2 body element For example;
+ expression="$body/getQuote" refers to the first getQuote element in the
+ SOAP body regardless of whether the message is SOAP-11 or SOAP-12
+
+
+
header
+
The SOAP 1.1 or 1.2 header element For example;
+ expression="$header/wsa:To" refers to the addressing To header
+ regardless of whether this message is SOAP-11 or SOAP-12Further there
+ are some variable prefixes defined in Synapse XPaths which can be
+ usefull in writing the configurations;
+
+
+
ctx
+
Prefix for Synapse MessageContext properties For example;
+ expression="$ctx:RESPONSE" gives the value of the Synapse message
+ context property with name 'RESPONSE'
+
+
+
axis2
+
Prefix for Axis2 MessageContext properties For example;
+ expression="$axis2:messageType" gives the value of the axis2 message
+ context property with name 'messageType'
+
+
+
trp
+
Prefix for the transport headers For example;
+ expression="$trp:Content-Type" gives the value of the 'Content-Type'
+ transport header, which is going to be the Content-Type of the current
+ message
The relayTransformer mediator applies the specified XSLT transformation
+to the selected element of the current message payload. The source
+attribute specifies which element to be selected to apply
+the given XSLT transfomation. In the case where the
+source element is not specified, it uses the first child of the soap body as the
+selected element. Optionally parameters could be passed into
+the transformations through the 'property' elements. These
+properties are corresponding to the XSL parameters and can be accessed during
+transformation by <xsl:param name="{the name of the property}"
+/>. The 'feature' element defines any features
+which should be explicitly set to the TransformerFactory. The
+feature
+'http://ws.apache.org/ns/synapse/transform/feature/dom' turns
+on DOM based transformations instead of serializing elements into Byte streams
+and/or temporary files. Though this would be better in performance than using
+byte streams, sometimes it may not work for all transformations.
+
+
Finally, the 'resource' element can be used to resolve
+XSLT imports and includes from the repository. It works in
+exactly the same way as the corresponding element in a <proxy> definition
+(Proxy Service).
+
+
The Relay Transformer Mediator supports all the features provided by the XSLT
+mediator. In addition to those features, it supports streaming transformation,
+where the incoming stream is given directly to the underlying XSLT processor to
+do the XSLT transformation. When using the Relay Transformer mediator in streaming
+mode, the ESB should be started in Message Relay mode. This will give high
+performance numbers.
In this scenario the xslt can be picked by the key transform/example.xslt and the XSLT would be applied
+to a part of the message that is specified as a XPath expression.In this case it is applied to s11:Body/child
+the message
URL rewrite mediator is used to modify and transform the URL values available in the message
+
+
Properties
+
By default the mediator will take the 'To' header of the message and apply the provided rewrite rules on it.
+ Alternatively one can specify a property name in the 'inProperty' attribute, in which case the mediator will take the value of
+ the specified property as the input URL. Similarly the mediator by default sets the transformed URL as the 'To' header of the message.
+ Alternatively you can use the 'outProperty' attribute to instruct the mediator to set the resulting URL as a property.
+
+
In Property
+
>Out Property
+
+
+
+
Rules
+
The rewrite mediator applies URL transformations by evaluating a set of rules on the message.
+Rules are specified using the 'rewriterule' element. Rules are evaluated in the order they are specified.
+A rule can consist of an optional condition and one or more rewrite actions. If the condition is provided
+it will be evaluated first. If it evaluates to 'true' all the specified rewrite actions will be executed.
+ Otherwise the set of actions will be skipped. If no condition is specified, the provided rewrite actions will be always executed.
+ The condition should be wrapped in a 'condition' element within the 'rule' element.
+ Rewrite actions are specified using 'action' elements.
+
+
Condition:- A rule can consist of an optional condition. If the condition is provided it will be evaluated first
+
Action:- It states which type of action should be executed on the URL. This defaults to 'set' value
+
Fragment:- This attribute can be used to specify the URL fragment on which the action should be executed.
+ If not specified this will be taken as 'full' URL, which is the complete URL
+
Value/Expression:- The value to 'set', 'append' or 'prepend' must be specified using either the 'value' attribute or the 'xpath' attribute.
+ One of these two attributes are always needed unless the value of the 'type' attribute is set to 'remove'
+
Regex:- When user set action to 'replace' an additional 'regex'
+ attribute must be specified which indicates the portion that should be replaced with the given value.
+ By default 'rewrite' mediator will take the 'To' header of the message and will apply the provided rewrite rules on it.
+ If user specify a 'inProperty' attribute, the mediator will take the value of the specified property as the input URL.
+
+
+
Out Property :
+
+ Similarly the mediator by default sets the transformed URL as the 'To' header of the message.
+ Alternatively user can use the 'outProperty' attribute to instruct the mediator to set the resulting URL as a property.
+
+
+
+
+
Rules
+
The rewrite mediator applies URL transformations by evaluating a set of rules on the message
+
+
Figure2: Rules
+
+
Condition:- A rule can consist of an optional condition. If the condition is provided it will be evaluated first
+
Action:- It states which type of action should be executed on the URL. This defaults to 'set' value
+
Fragment:- This attribute can be used to specify the URL fragment on which the action should be executed
+
Value/Expression:- The value to 'set', 'append' or 'prepend' must be specified using either the 'value' attribute or the 'xpath' attribute.
+ One of these two attributes are always needed unless the value of the 'type' attribute is set to 'remove'
+
Regex:- When user set action to 'replace' an additional 'regex'
+ attribute must be specified which indicates the portion that should be replaced with the given value.
the address URL of the request contains the context 'soap'.
+In ESB server all the services are deployed under a context named 'services' by default. So,'To' header will be re written by replacing the 'soap' context with 'services'.
+ Hence the requests will be delivered to the server successfully.
+
The <RMSequence> mediator can be used to create a sequence of messages
+to communicate via WS-Reliable Messaging with an WS-RM enabled endpoint
+(<enableRM>). The simple use case of this mediator is to specify a
+single="true" property, because this means that only one message is involved in
+the same sequence. However if multiple messages should be sent in the same
+sequence, the correlation property should be used with a XPath expression that
+selects an unique element value from the incoming message. With the result of
+the XPath expression, Synapse can group messages together that belong to the
+same sequence. To close the sequence neatly, for the last message of the
+sequence also an XPath expression should be specified. With the version
+attribute the WS-RM specification version to be used can be specified, 1.0 or
+1.1.
Message Sequence: Whether to use a single message or a multiple
+ correlated messages
+
+
Single Message - Making single message reliable.
+
Correlated Sequence - Make multiple correlated message reliable. When
+ you select this option you have to provide the following two fields
+ appears in the panel.
+
+
Sequence XPath: The xpath expression that selects an unique
+ element value from the incoming message
+
Last Message XPath: The xpath expression that identify the last
+ message
+
+ NOTE: You can define prefixes for the namespaces used in these
+ expression from the right hand side link named "Namespaces".
In the above scenario, WS-RM is engaged to the endpoint using the <enableRM/>
+ tag. It is possible to engage WS-RM to both Address and WSDL endpoints using this tag. In addition
+ to the RM enabled endpoint, RMSequence mediator is specified before the send mediator. This mediator is
+ used to specify the set of messages to be sent using a single RM sequence. In this sample it is specified as
+ single message per sequence. It also specifies the version of the WS-RM to be used.
Router is specifically designed for what it name suggests. Routing
+messages.
+
+
Router mediator can contain any number of routes. Router mediator can be
+configured to continue or to stop the mediation after the routing by setting
+the 'continueAfter' attribute value to be 'true' and 'false' respectively. Each
+and every route must contain an 'expression' attribute which is to specify the
+XPath over which the roting condition is evaluated. Apart from that there can
+be an optional 'match' attribute as well. If both expression and the match
+attributes are specified in a particular route, the evaluated string value of
+the XPath over the current message will be compared with the regular expression
+provided as the value of the match attribute to see whether this route is
+matching for the current message. Where as if only the expression is specified,
+presence of the element specified by this XPath is considered as the routing
+condition.
+
+
One can configure a route to break routing or continue evaluating further
+routes to see any further matching by setting the 'breakRoute' attribute to
+'true' or 'false' respectively. For all the routes there has to be a 'target'
+element which contains the information about the routing path as a sequence or
+an endpoint both can be inline as well as referred. If both an endpoint and a
+sequence is specified message will be first mediated through the sequence and
+sent to the endpoint after mediation. Particular target cannot contain an
+inline sequence and a referred sequence at the same time. The same applies to
+endpoint of the target as well.
The router mediator has the following configuration options.
+
+
Continue after routing: (Yes/No), Whether to continue the routing if any
+ of the child routes are executed. The default value is No.
+
Number of clones: Show you the number of child routes that router
+ mediator has. You can add child routes by clicking the 'Add Route' link in
+ the right hand side of the text field.
+
+
+
Route
+
+
+
+
Route Mediator
+
+
Here are the options available in the Route mediator configurations.
+
+
Break After Route: (Yes/No) Specify whether to continue with the sibling
+ routes or stop from the current route, if the routing condition is
+ successful.
+
Route Expression: An xpath expression to execute on the message
+
Route Pattern: A regular expression to compare with the value retrieved
+ from the above xpath expression.
The source is the only mandatory element of the ruleset. However, the
+properties required for the creation of the ruleset can also be specified
+within ruleset. The key attribute is a registry key, which is to lookup the
+rule script from the registry if the rule script is in the registry. The rule
+set can be given as a child node of source elemenent. If the rule set is
+non-XML, you may need to wrap it with a CDATA section inside a XML tag ex:
+<X><![CDATA[ native code]]></X>
+
+
Note : The key or in-lined rule script must be defined. Otherwise, the rule
+mediator configuration is invalid.
+
+
RuleSession
+
+
Rule Session specify the stateful or stateless behavior of the rule engine.
+If this has value 'stateful', then the rule engine will execute rules in a
+stateful manner, for any other value, it assumes as stateless. There are
+optional properties, which are used when creating the rule session. Rule
+session is optional and the default one is stateful.
+
+
Facts / Results
+
+
name - the unique name
+
value - Represents any static value
+
expression - XPath expression for extracting data from the message being
+ passed between ESB components. The default value is the first child of the
+ SOAP Body.
+
type - Defines the type of the input data. There are a few built in types
+ such as Message, Context, Map, POJO and Mediator and there are samples
+ using these. Using the rule-component.conf, you can register new types
+ along with adapters, which are responsible for formulating specified types
+ from the data. If there is no registered adapter for a given type, then, we
+ assume the given type as a valid java class name and uses POJO adapter to
+ formulate the POJO instance whose class is the given type.
+
+
+
Facts specify the facts being used in rule set. It also defines how to
+formulate facts from the message, etc. Results define how to handle results
+from the rule set execution. Usually, results adapters enrich the message with
+results. For example, If you are using POJO adapter (i.e. a java class as the
+type; the class name of a result), then we transform POJO into an XML and
+attached to the SOAP message.
+
+
UI Configuration
+
+
+
+
+
Figure1: Rule Mediator
+
+
Each of configuration elements is described in following section
+
+
RuleSource
+
+
Rule script can be given as a registry key or an in-lined script. To give
+rule script as in-lined, you can use editor.
+
+
The format (language) of the rule script . If it is a XML, then this
+attribute should be 'xml'. Any other value, rule mediator assumes that the rule
+script is in native format. If the rule script is in native format, it should
+be given by wrapping as a CDATA section inside a XML tag ex:
+<X><![CDATA[ native code]]></X>.
+
+
Note: The key or in-lined rule script must be defined. Otherwise, rule
+mediator is invalid.
+
+
RuleSession
+
+
Session Type - Indicates the stateful or stateless behavior of the rule
+engine. If this has value ' stateful ' , then rule engine will executes rules
+in a state full manner , for any other value , it assumes as stateless.
+
+
property - Those are used when creating rule session.
+
+
RuleSet
+
+
It is possible to exists properties for rules set creation, registration,
+deregistration and there are add property options for each.
+
+
Example Usage: When using Drool native language (.drl) for rule script, it
+is needed to provide .dsl file .This can be done using attribute named 'source'
+and value 'drl'.
+
+
<ruleSet>
+
+
<creation>
+
+
<property name="source" value="drl"/>
+
+
</creation>
+
+
</ruleSet>
+
+
Facts / Results
+
+
Input defines what are the facts that should injected to Rule Engine in
+order to fire rules whereas Output describes what should do with return value
+form rule engine.
+
+
Adding Facts / Results
+
+
Figure 2 shows a one senario of addting input
+
+
width="1319"
+height="122">
+
+
Figure 2 Inputs of the Rule Mediator
+
+
Type : According to current implementation valid types are
+as bellow.
+
+
Name : Value Type Static Value or XPath expression
+
+
Value / Expression :value - Represents any static
+value. expression- XPath expression is used to extract data from
+either external XML source or SOAP envelope. There is no default value.
+
+
Registry Key : The registry or Message context key .This is
+used for getting data from either registry or message context
+
+
Registry Browser : If the key is registry resource, the
+browser to select the resource.
+
+
NS Editor : You can click this link to add namespaces if
+you are providing an expression. You will be provided another panel named
+'Namespace Editor' where you can provide any number of namespace prefixes and
+url
+
+
Action : Delete the input out put
+
+
Adding Properties
+
+
Adding properties option is in RuleServiceProvider , RuleSet and
+RuleSession. Figure 3 shows UI on adding property.
+ In the above configuration, Rule script is picked from the registry with
+ key rule/sample.xml. There is a one fact
+ and it is a string variable. Its value is calculated from the current SOAP
+ message using an expression. Rule engine uses these facts to decide what
+ rules should fire.
Synapse supports Mediators implemented in a variety of scripting languages
+such as JavaScript, Python or Ruby. There are two ways of defining script
+mediators, either with the script program statements stored in a separate file
+which is referenced via the local or remote registry entry, or with the script
+program statements embedded in-line within the Synapse configuration. Synapse
+uses the Apache Bean Scripting
+Framework for the scripting language support, any script language
+supported by BSF may be used to implement a Synapse Mediator. With the script
+mediator, you can invoke a function in the corresponding script. With in these
+functions, it is possible to access the Synapse predefined in a script variable
+named 'mc’. This ‘mc’ represents an
+implementation of the MessageContext, named
+ScriptMessageContext.java. That contains following additional
+methods that can be accessed within the script by
+mc.methodName.
+
+
public Object getPayloadXML() - getting the XML representation of
+ SOAP Body payload
+
public void setPayloadXML(Object payload) - Set the SOAP body payload
+ from XML
+
public void addHeader(boolean mustUnderstand, Object content) - Add a
+ new SOAP header to the message.
+
public Object getEnvelopeXML() - Get the XML representation of the
+ complete SOAP envelope
+
public void setTo(String reference)
+
public void setFaultTo(String reference)
+
public void setFrom(String reference)
+
public void setReplyTo(String reference)
+
+
+
Implementing a Mediator with a script language can have advantages over
+using the built in Synapse Mediator types or implementing a custom Java class
+Mediator. Script Mediators have all the flexibility of a class Mediator with
+access to the Synapse MessageContext and SynapseEnvironment APIs, and the ease
+of use and dynamic nature of scripting languages allows rapid development and
+prototyping of custom mediators. An additional benefit of some scripting
+languages is that they have very simple and elegant XML manipulation
+capabilities, for example JavaScript E4X or Ruby REXML, so this makes them well
+suited for use in the Synapse mediation environment. For both types of script
+mediator definition the MessageContext passed into the script has additional
+methods over the standard Synapse MessageContext to enable working with the XML
+in a way natural to the scripting language. For example when using JavaScript
+getPayloadXML and setPayloadXML, E4X XML objects, and when using Ruby, REXML
+documents.
+
+
+
+
Syntax
+
+
Script mediator using a script off the registry
+
+
The attribute key is the registry key to load the
+ script. The language attribute specifies the scripting
+ language of the script code (e.g. "js" for Javascript, "rb" for ruby,
+ "groovy" for Groovy, "py" for Python..). The function is
+ an optional attribute defining the name of the script function to invoke,
+ if not specified it defaults to a function named
+ 'mediate'. The function is passed a single parameter -
+ which is the Synapse MessageContext. The function may
+ return a boolean, if it does not, then true is assumed, and the script
+ mediator returns this value.
The above configuration is an example of an inline mediator using
+ JavaScript/E4X which returns false if the SOAP message body contains an
+ element named 'symbol' which has a value of 'IBM' would be:
In the above example, script is loaded from the registry by using the
+ key repository/conf/sample/resources/script/test.js. The
+ script is written in java script. The function to be invoked is
+ testFunction . As example for test.js shown in the bellow.
+
+
function testFunction(mc) {
+ var symbol = mc.getPayloadXML()..*::Code.toString();
+ mc.setPayloadXML(
+ <m:getQuote xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>{symbol}</m:symbol>
+ </m:request>
+ </m:getQuote>);
+}
Send is considered as one of the most widely used mediators in ESB. It is
+built in to the core of the ESB. It performs a fundamental task of any ESB.
+This fundamental task is to send a message out from ESB.
+
+
There are two modes of operation in a send mediator.
+
+
Sending the message using message level information
+
Sending the message to a predefined endpoint
+
+
+
If we don't provide an Endpoint it will try to send the message using the
+wsa:to address of the message. Also if we use a send mediator in the out path
+of the ESB, without specifying an Endpoint it will send the message as a
+reply.
+
+
If we provide an Endpoint, it will send the message according to the
+information in the Endpoint. Have a look at the endpoint guide for more
+details.
+
+
Send mediator is the only way to send a message out from the ESB. If you
+want to forward the message to an Endpoint or to send the reply back this
+mediator must be used.
+
+
The send mediator copies any message context properties from the current
+message context to the reply message received on the execution of the send
+operation so that the response could be correlated back to the request.
+Messages may be correlated by WS-A Message-ID, or even simple custom text
+labels (see the property mediator and samples).
+
+
Note: A send operation may be blocking or non-blocking depending on the
+actual transport implementation used. As the default NIO based http/s
+implementation does not block on a send, care must be taken if the same message
+must be sent and then further processed (e.g. transformed). In such a scenario,
+it maybe required to first clone the message into two copies and then perform
+processing to avoid conflicts.
+
+
Syntax
+
<send/>
+
+
If the message is to be sent to one or more endpoints, then the following is
+used:
+
<send>
+ (endpointref | endpoint)+
+ </send>
+
+
where the endpointref token refers to the following:
+
<endpoint key="name"/>
+
+
and the endpoint token refers to an anonymous endpoint definition.
+
+
If the response message is to be sent to a sequence, then the following is used:
You can select the endpoint to be one of the following value.
+
+
None
+
Anonymous
+
Pick from Registry
+
Import
+
Receiving Sequence, this can be a static sequence or can be calculated using a XPath
+
+Note: You can manage endpoints from the "Manage Endoint" panel which can be
+accessed from the Manage-> Mediation-> Endpoints menu from the left hand
+side bar.
+
+
In this configuration first send is used inside a in mediator. As I have
+mentioned earlier, both request and response will go through the main sequence.
+But only request messages will go through the child mediators of in and only
+response messages will go through the out mediator. So the request will be
+forward to the endpoint with the given address. Response will go through the
+second send and this send mediator will send it back to the requester.
+ A sequence mediator refers to a predefined sequence element which is used to
+ invoke a named sequence of mediators.
+
+
+
Syntax
+
+
<sequence key="name"/>
+
+
UI Configuration
+
+
+
+
+
+
+ Figure 1: Sequence Mediator
+
+
+
+ In the Sequence Mediator panel, there are two options available to select a sequence.
+
+
+
Static way :- In staic manner, User can provide a registry key which refers a predefined sequence
+
Dynamic way :- Where user can define a 'XPath' expression to point the exact sequence name, which
+ is present in the message. So, ESB will look into the system for that particular sequence and will do further processing.
+
+
+
+
\ No newline at end of file
diff --git a/docs/xdoc/mediators/smooks.xml b/docs/xdoc/mediators/smooks.xml
new file mode 100644
index 0000000000..90283b7c0e
--- /dev/null
+++ b/docs/xdoc/mediators/smooks.xml
@@ -0,0 +1,90 @@
+
+
+
+
+
+ WSO2 ESB - Smooks Mediator
+
+
+
+
+
+
Smooks Mediator
+
+
Smooks mediator can be used to apply lightweight transformations on messages in an efficient manner.
+ Smooks is a powerful framework for processing, manipulating and transforming XML. More information
+ about Smooks can be obtained from the official Smooks website.
+
+
+
Configurations
+
The Smooks mediator requires the transformation definition to be passed in as an external resource.
+ This transformation can be specified as a local entry or be stored in the registry. The mediator UI
+ enables you to point the mediator to an existing local entry or a registry resource.
+
+
+
+
Smooks transformation configuartion : Smooks mediator requires the transformation definition to be passed in as an external resource.
+
+
+
Input : User can define an 'input' as a 'Text' or 'XML' and need to provide a 'xpath' expression to pick exact
+ message block, else by default whole 'message body' will be selected by default.
+
Output : Same like in input, user can define how his output should be
+ Smooks transformation definition to can be specified as a local entry or be stored in the registry.
+
+
+
Input :
+
+ User can define an 'input' as a 'Text' or 'XML' and need to provide a 'xpath' expression to pick exact
+ message block, else by default whole 'message body' will be selected by default.
+
+
Output :
+
+ Same like in input, user can define how his output should be. When user defines an 'output' expression there are
+ additional operations can be performed.
+
+
+
+
+ Add : Selected node will be added as a child to the message.
+
+
+ Replace : Selected node will be replaced in the message.
+
+
+ Sibling : Selected node will be added as a sibling.
+
+
+
+
+ When user defines an 'output' as a 'Property', property will be saved in the messagecontext for the future uses.
+
The Spring mediator exposes a spring bean as a mediator. The spring mediator
+creates an instance of a mediator, which is managed by Spring. This Spring bean
+must implement the Mediator interface for it to act as a Mediator.
+
+
Syntax
+
<spring:spring bean="exampleBean" key="string"/>
+
+
+
+
The key will reference the Spring
+ApplicationContext/Configuration (i.e. spring configuration XML) used for the
+bean. This key can be a registry key or local entry key. The
+bean attribute is used for looking up a Spring bean from the
+spring Application Context. Therefore, a bean with same name must be in the
+given spring configuration. In additions, that bean must implement the Mediator
+interface.
+
+
+
+
UI Configuration
+
+
+
+
Figure1: Spring Mediator
+
+
Bean: The name of the bean
+
Key: The registry reference to the spring
+ Application-Context/Configuration used for the bean. You can select it by
+ clicking the "Registry Keys".
+
In the above configuration, spring XML is in the registry and it can be
+ looked up using the registry key
+ conf/sample/resources/spring/springsample.xml . This
+ spring XML (i.e springsample.xml) must contain a bean with the name
+ springtest. The following figure shows an example can be
+ used as the registry resource - springsample.xml.
Switch mediator is another XPath filter. The XPath will be evaluated and
+will return a string. This string is matched against the regular expression in
+each of cases in the specified order. If a matchig case is found it will be
+executed. Further proccessing of the case statements won't happen after a
+matching is found. If none of the case statements are matching and default case
+is specified, it will be executed.
The <switch> mediator will evaluate the given source XPath expression
+into its string value, and match it against the given regular expressions. If
+the specified cases does not match and a default case exists, it will be
+executed.
+
+
UI Configuration
+
+
Switch
+
+
+
+
Here are the options to configure the Switch Mediator.
+
+
Source XPath: Here you can specify the source xpath to be evaluated.
+
Number of cases: The number of cases specified. You can add cases by
+ clicking the "Add Case" link.
+
Specify default case: The link to add the default case. (This case is to
+ execute when all the other cases are failed.)
+
+
+
Case
+
+
+
+
Switch Case Mediator
+
+
Here are the options to configure the Switch Case Mediator.
+
+
Case Value (Regular Expression): A regular expression to match with
+ switching value.
+
+
+
Default
+
+
The Switch Default Mediator will be a child mediator for the Switch
+Mediator. It is to define a defalut case for the current routing switch. If all
+the cases were not matched with the switch value, the sequence defined as
+children to the default mediator will be taken as the route of the message.
+
+
+
+
Example
+
<switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples/xsd">
+ <case regex="IBM">
+ <!-- the property mediator sets a local property on the *current* message -->
+ <property name="symbol" value="Great stock - IBM"/>
+ </case>
+ <case regex="MSFT">
+ <property name="symbol" value="Are you sure? - MSFT"/>
+ </case>
+ <default>
+ <!-- it is possible to assign the result of an XPath expression as well -->
+ <property name="symbol"
+ expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"
+ xmlns:m0="http://services.samples/xsd"/>
+ </default>
+ </switch>
+
+
+
In this scenario it will get the text of symbol element and match it against
+values MSFT and IBM.
Target is a common configuration used across many ESB conofugrations. Some
+mediators that uses this configuration are Clone, Iterate and Router.
+
+
A target specifies a mediation sequence, and endpoint or both. If a sequnce
+is specified it will be executed. If a endpoint is specified message will be
+sent to the endpoint. If both sequence and endpoint are specified, first
+sequence will be executed and then endpoint will be executed.
Here you can prepare a message to send to an endpoint or mediate through
+some more sequences.
+
+
SOAP Action: The SOAP action of the message.
+
To Address: Then target endpoint address.
+
Sequence: Mediate the message through a sequence. You can either pick a
+ named sequence from the registry or define an anonymous sequence by adding
+ mediators to the current Target mediator as children.
+
Endpoint: Send the message to an endpoint. Here you can pick a named
+ endpoint from the registry (which you can add in the Endpoint panel that
+ can be accessed from the Manage-> Mediation-> Endpoints menu in the
+ left hand side menu bar.) or keep the endpoint as anonymous.
+ The Throttle mediator can be used for rate limiting as well as concurrency
+ based limiting. A WS-Policy dictates the throttling configuration and may be
+ specified inline or loaded from the registry. Please refer to the samples
+ document for sample throttling policies. The Throttle mediator could be added
+ in the request path for rate limiting and concurrent access limitation. When
+ using for concurrent access limitation, the same throttle mediator 'id' must be
+ triggered on the response flow so that completed responses are deducted from
+ the available limit. (i.e. two instances of the throttle mediator with the same
+ 'id' attribute in the request and response flows). The 'onReject' and
+ 'onAccept' sequence references or inline sequences define how accepted and
+ rejected messages are to be handled.
+
+ Throttle Group ID: The id for the throttle group. Note you would have two throttle mediator configuration in
+ request and response paths with the same group id.
+
+
+ Referring Policy: The policy for the throttling. You can specify it inline or refer from the regsitry
+
+
+ On Acceptance Referring Sequence: The sequence to act on accpetance
+
+
+ On Rejection Referring Sequence: The sequence to act on rejection
+
+ Above example specifies a throttle mediator inside the in mediator. Therefore, all request messages
+ directed to the main sequence will be subjected to throttling. Throttle mediator has 'policy', 'onAccept' and
+ 'onReject' tags at top level. The 'policy' tag specifies the throttling policy for throttling messages. This
+ sample policy only contains a component called "MaximumConcurrentAccess" .This indicates the maximum number of
+ concurrent requests that can pass through Synapse on a single unit of time.
+
+ Transaction mediator can provide transaction facility for a set of mediators
+ defined as its child mediators. A transaction mediator with the action "new"
+ indicates the entry point for the transaction. A transaction is marked
+ completed by a transaction mediator with the action "commit". The suspend and
+ resume actions are used to pause a transaction at some point and start it again
+ later. Additionally, the transaction mediator supports three other actions,
+ i.e. use-existing-or-new, fault-if-no-tx, rollback.
+
This mediator is used for schema validation of messages.
+
+
The portion of the message that needs to be validated is chooses by
+evaluating the XPath expression. Then this message is validated against the
+schema spcecified. User can specify a sequence to be executed in case of a
+validation failure. This mediator provide an extension point by providing
+properties to configure the underline validation engine.
The validate mediator validates the result of the evaluation of the source
+xpath expression, against the schema specified. If the source attribute is not
+specified, the validation is performed against the first child of the SOAP body
+of the current message. If the validation fails, the on-fail sequence of
+mediators is executed. Properties could be used to turn on/off some of the
+underlying features of the validator (See
+http://xerces.apache.org/xerces2-j/features.html)
+
+ The <resource> can be used to specify external schema resources, which can be used to
+ validate the messages. External schema resources can be defined as localentries and with <resource>
+ user could point the specified localentries.
+
+
UI Configuration
+
+
+
+
Key
+
+
Schema location
+
+
Source
+
+
XPath expression to extract the XML that need to be validated. If not
+specified validation is performed against the first child of the SOAP body
+
+
Features
+
+
Here is the only mandatory feature supported by the validator, "http://javax.xml.XMLConstants/feature/secure-processing".
+ For more information please refer this.
+
+ In the above validate mediator configuration, the required schema for
+ validating message going through the validate mediator has been given as a
+ registry key, schema\sample.xsd. In this sample
+ configuration, there is no source attribute. Therefore, in
+ this case, validate mediator takes source as the first child of SOAP Body.
+ Within on-fail, it is possible to specify mediation logic
+ that should to be happened if the validation is failed. In the above
+ configuration, it creates a SOAP fault using makefault
+ mediator and send back that to requested party.
+
+
Note: If user configure WSO2 ESB with WSO2 Governance Registry and if he uploads all the required files as *.gar file (described in WSO2 GREG documentation),
+ uer can provide only the base schema when he provides schemas.
+There is no need to provide all required imported schemas since ESB is able to resolve the imported resources using only the base schema.
+Please note that for the above function user needs to uncomment the following lines @ synapse.properties file which is avilable in ESB_HOME/lib/core/WEB_INF/classes folder.
+
The XQuery mediator can be used to perform an XQuery transformation. The
+'key' attribute specifies the registry key for looking up
+XQuery script that going to be used for define transformation. The optional
+'target' attribute specifies the node of the SOAP message that
+should be transformed. In case where the target value is not specified, then
+the first child of the SOAP body is selected. The 'variable'
+elements define a variable that could be bound to the dynamic context of the
+XQuery engine in order to access those
+variables during the XQuery script invocation .
+
+
In the variable definition , it is possible to specify just a
+literal value, or an XPath expression over
+the payload, or even specify a registry key or a registry key
+combined with an XPath expression that selects the value of the variable.Using
+key attribute of the variable, it is possible to bind an XML
+document located in the registry so that in the transformation that too can be
+used.The name of the variable corresponds to the name of variable declaration
+in the XQuery script. The type of the variable must be a valid
+type defined by the JSR-000225 (XQJ API).
Key: The key that represent the xquery transformation.
+
Target: (optional) Specify the node of the message that should be
+ transformed using an xpath expression. ( default to the first child of the
+ SOAP body ) The namespace prefixes used in the expression can be defined by
+ clicking the namespaces link in front of the 'Target' input field.
+
+
+
Variables for the XQuery Mediator: Defines values/expressions that could be
+bound to the dynamic context of the XQuery engine in order to access those
+variables through the XQuery script.
+
+
+
+
Figure2: XQuery Mediator - Adding Variables
+You have the following option in a variable.
+
+
Variable Type: The 'type' of the variable must be a valid type defined by
+ the JSR-000225 (XQJ API).
+
The supported types are defined in the Supported Types
+ section
+
+
Variable Name: The name of the variable should correspond to the name of
+ variable declaration in the XQuery script.
+
Value Type: Whether the value of the variable is a static value or an
+ expession.
+
Value/Expression: Static value or the expression.
+
Registry Key: Key, if the value is retrieved from the registry.
+
NSEditor: Defines the namespaces for the prefixes used in the xpath
+ query.
In the above configuration, XQuery script is in the registry and that
+ script can be picked by key xquery\example.xq. There is a
+ one variable name payload and type as
+ ELEMENT. As there is no expression in the variable
+ definitions, default value - the first child of SOAP Body is used as the
+ value of variable payload. . Within XQuery script, you can
+ access this variable by defining declare variable $payload as
+ document-node() external; . Refer sample 390 and 391 for more
+ information.
A variable definitions that pick a XML resource from the registry using
+ key misc/commission.xml and bind in to XQuery Runtime so that it can be
+ accessed with in XQuery script. Refer sample 391 for more information.
The xslt mediator applies the specified XSLT transformation
+to the selected element of the current message payload. The source
+attribute specifies which element to be selected to apply
+the given XSLT transfomation. In the case where the
+source element is not specified, it uses the first child of the soap body as the
+selected element. Optionally parameters could be passed into
+the transformations through the 'property' elements. These
+properties are corresponding to the XSL parameters and can be accessed during
+transformation by <xsl:param name="{the name of the property}"
+/>. The 'feature' element defines any features
+which should be explicitly set to the TransformerFactory. The
+feature
+'http://ws.apache.org/ns/synapse/transform/feature/dom' turns
+on DOM based transformations instead of serializing elements into Byte streams
+and/or temporary files. Though this would be better in performance than using
+byte streams, sometimes it may not work for all transformations.
+
+
Finally, the 'resource' element can be used to resolve
+XSLT imports and includes from the repository. It works in
+exactly the same way as the corresponding element in a <proxy> definition
+(Proxy Service).
In this scenario the xslt can be picked by the key transform/example.xslt and the XSLT would be applied
+to a part of the message that is specified as a XPath expression.In this case it is applied to s11:Body/child
+the message
+ Message processors can be used to implement different messaging and integration patters along with message stores.
+
+ Message processors can consume the messages in message stores and perform some processing on them.
+
+
For example think of a scenario where we have a back-end service that can only accept messages at a given rate and incoming traffic to the ESB has
+ a different message rate. So to serve that inbound traffic using the available back-end services we can have a message store that
+ temporarily stores the messages and a message processor that will consume those messages and send to the back end service at a predefined rate.
+
+ Users can write their own message processor implementations and plug them using the Synapse configuration. WSO2 ESB ships two message processors implementations
+ that can be used out of the box.
+
Maximum re delivery attempts before deactivating the processor
+
NO
+
+
+
axis2.repo
+
Axis2 Client repository to be use to send messages
+
NO
+
+
+
axis2.config
+
Axis2 Configuration to be use to send messages
+
NO
+
+
+
message.processor.reply.sequence
+
Name of the Sequence that reply of the message should be sent to
+
NO
+
+
+
message.processor.fault.sequence
+
Name of the sequence that fault message should be sent to in case of a SOAP
+ fault
+
+
NO
+
+
+
quartz.conf
+
Quartz configuration file path
+
NO
+
+
+
+
cronExpression
+
Cron Expression to be used to configure the re try pattern
+
NO
+
+
+
+
+
Message Context properties to be used with Message Forwarding Processor
+
+
+
+
+
Property Name
+
Value
+
Required
+
+
+
+
+
target.endpoint
+
Name of the Address Endpoint which message should be delivered to
+
YES.
+
+
+
OUT_ONLY
+
true if this is a out only message
+
Required for out only scenarios
+
+
+
+
+
Message Sampling Processor
+
Message Sampling Processor consumes messages in message store and send it to a configured sequence.
+
This process happens in a pre-configured interval. Therefore this message processor implementation is useful in implementing delivery channels with fixed delivery rate.
+
+
Message Sampling Processor Parameters
+
+
+
+
Parameter Name
+
Value
+
Required
+
+
+
+
+
sequence
+
SequenceID, which defines mediation flow
+
YES
+
+
+
+
interval
+
Message retry interval in milli seconds
+
Default value is 1000ms
+
+
+
quartz.conf
+
Quartz configuration file path
+
NO
+
+
+
+
cronExpression
+
Cron Expression to be used to configure the re try pattern
+
NO
+
+
+
+
+
Note: When using the "SamplingProcessor" as a Message processor implementation, we must provide the "sequence" parameter (which contains 'endpoint' URI).
+ Message Relay is a Message Pass through mechanism for ESB. Message relay enables ESB to pass the messages
+ without building or processing the message.
+
+
+ When message relay is configured incoming requests to the ESB are not built and processed unless
+ specifically requested to do so. A incoming message is wrapped inside a default SOAP envelope as
+ binary content and sent through the ESB.
+
+
+ Some of the ESB scenarios doesn't require the full message to be built. Instead ESB can work on other
+ message properties like request URLs or transport headers.
+
+
+ With message relay ESB can achieve a very high throughput.
+
+
+
+ Message Relay Building blocks
+
+
+ Message relay has two main parts.
+
+
+
Axis2 Message Builder
+
Axis2 Message Formatter
+
+
A message builder is used to build an incoming message to the ESB. A message formatter is used to build the
+ out going stream from the message inside ESB.
+
+ So in a typical ESB routing scenario here is the flow
+
+ When Relay Message builder and formatter are specified for a content type, message
+ coming with that content type will not be built by the ESB. Instead they will pass
+ through the ESB as it is.
+
+
+ Message builders and formatters are specified in the axis2.xml under messageBuilders
+ and messageFormatters configuration section. Message builders and formatters are
+ chosen based on the content type of the message.
+
+
+ ESB has few default Message message builders. Even if the user doesn't specify them
+ in the axis2.xml they will take effect. These can be overridden using the message
+ builder configurations in the axis2.xml.
+
+
+ ESB doesn't have default Message formatters. So it is important to specify all of
+ them in the axis2.xml configuration.
+
+
+ Here are the default message builders.
+
+
+
+
application/soap+xml
+
org.apache.axis2.builder.SOAPBuilder
+
+
+
multipart/related
+
org.apache.axis2.builder.MIMEBuilder
+
+
+
text/xml
+
org.apache.axis2.builder.SOAPBuilder
+
+
+
application/xop+xml
+
org.apache.axis2.builder.MTOMBuilder
+
+
+
application/xml
+
org.apache.axis2.builder.ApplicationXMLBuilder
+
+
+
application/x-www-form-urlencoded
+
org.apache.axis2.builder.XFormURLEncodedBuilder
+
+
+
+ Configuring the message relay
+
+
In the axis2.xml file there are two configuration sections called messageBuilders and
+ messageFormatters. User can replace the expected content types with the relay message
+ builder and formattter to pass these messages through the ESB without building them.
+
Builder mediator can be used to build the actual SOAP message from a message coming in
+ to ESB through the message relay. One usage is to use this before trying to log the
+ actual message in case of a error. Also with the builder mediator ESB can be configured
+ to build some of the messages while passing the others along.
+ By default builder mediator uses the axis2 default message builders for the content types
+ specified in Table 1. User can override those by using the optional messageBuilder configuration.
+
+ Like in axis2.xml user has to specify the content type and the implementation class of
+ the message builder. Also user can specify the message formatter for this content type. This is used by the
+ ExpandingMessageFormatter to format the message before sending to the destination.
+
+
Message Relay Module
+
Now message relay has a axis2 module as well. This is an optional feature. This module can be used
+ to build the actual SOAP message from the messages that went through the Message relay.
+
+ To enable this module user has to enable the relay module globally in the axis2.xml
+
<module ref="relay"/>
+
Also user has to put the following phase in to the InFlow of axis2.
+
<phase name="BuildingPhase"/>
+
This module is designed to be used by Admin Services that runs inside the ESB.
+ All the admin services are running with content type: application/soap+xml. So if
+ a user wants to use admin console and use the ESB for receiving message with content
+ type application/soap+xml, this module should be used.
+
+ User can configure the module by going to the modules section in admin console and then
+ going to the relay module. The module configuration is specified as a module policy.
+ After changing the policy user has to restart the ESB for changes to take effect.
+ includeHiddenServices: If this is true message going to the services with hiddenService parameter will be built
+
wsmr:services: Messages going to these services will be built
+
wsmr:service: Name of the service
+
+
wsmr:builders: Message builders to be used for building the message
+
wsmr:builder: A message builder to be used for a content type
+
+
Message Relay Limitations
+
+ If the message relay is enabled for particular content type, there cannot be Services with
+ security enabled for that content type. This applies to services with reliable messaging as well.
+
+ An ESB can be used to implement different kind of messaging and integration patterns. To support these patters sometimes we need a storage to store messages.
+
+ Message Store is the storage for ESB messages.
+
+
For Example In a scenario where we have a back end service that can only accept messages at a given rate and incoming traffic to ESB will have
+ different message rates.
+ So to serve that traffic utilizing the backend services there should be a temporary storage for messages.
+
+ Message Store can be used as this temporary storage.
+
+ Incoming message traffic can be stored using the store mediator.
+ And Message processors associated with message store can be used to deliver messages to the backend services at a give rate.
+
+
+
Users can implement their own message store by implementing the MessageStore interface and plug them using the configuration.ESB ships two message store implementations.
+ Message Store is a top level ESB configuration element where it should have a unique name.
+
+
+ class attribute value is the fully qualified class name of the underlying message store implementation.
+
+ There can be many message store implementations.Users can write their own message store implementation and use it.
+
+ Parameters section is used to configure the parameters that is needed by underlying message store implementation
+
+
Message Store Operations
+
+
When you click on Message Store section of Manage/Service Bus.It will direct you to
+ a page
+ where Listed
+ Messages appears. You can view and delete messages from that page.
+
This is the default Message Store that will be created if user does not specify any implementation from the configuration.
+ Messages will be stored in an In-memory queue.So in case of a ESB restart all the messages stored will be lost.
+
In Memory message store is lot more faster than any persistence message store implementations.
+
So it can be used as a temporary storage of messages for use cases such as implementation of
+ high speed store and forwarded patterns where message persistence is not a requirement.
+
+
JMS Message Store
+
JMS Message Store can be configured using configuration by giving class value as org.wso2.carbon.message.store.persistence.jms.JMSMessageStore
+ and messages will be stored in a configured JMS queue in the underlying JMS Broker
+
Since this will persistent messages in a JMS queue in a ordered way, JMS message store can be used to implement store and forward patters that have QoS parameters like in order delivery and reliability
+
Configuration to connect to a broker is provided as parameter values
+
JMS Message Store parameters
+
+
+
+
Parameter Name
+
Value
+
Required
+
+
+
+
+
java.naming.factory.initial
+
Initial Context Factory to use to connect to the JMS broker
+
YES
+
+
+
java.naming.provider.url
+
Url of the naming provider to be used by the context factory
+
YES
+
+
+
store.jms.destination
+
JNDI Name of the Queue Name that message store is connecting
+
NO but for some JMS clients this will be needed
+
+
+
store.jms.connection.factory
+
JNDI name of the Connection factory which is used to create jms connections
+
NO but for some JMS clients this will be needed
+
+
+
store.jms.username
+
User Name that is used to create the connection with the broker
+
NO
+
+
+
store.jms.password
+
Password that is used to create the connection with the broker
+
NO
+
+
+
store.jms.JMSSpecVersion
+
1.1 or 1.0 JMS API specification to be used (Default 1.1)
+ This guide describes how to monitor WSO2 ESB using Mediation Statistics component and
+ Java Management Extensions (JMX). WSO2 ESB provides convenient, yet powerful mechanisms for
+ monitoring an ESB deployment. Results provided by ESB Monitoring can be used to tune up
+ message flows, detect mediation faults and track usage patterns.
+
+ WSO2 ESB provides variety of options to monitor and manage the server runtime. While it
+ provides number of monitoring tools through the Web-based Management Console, WSO2 ESB also
+ supports Java Management Extensions (JMX) way of monitoring.
+
+
+
+
+ Mediation Statistics
+
+
+ Out of monitoring capabilities of WSO2 ESB, the Mediation Statistics feature stands out as
+ one of the most useful and widely used features. From functional components of the ESB,
+ sequences, proxy services and endpoints directly get involved in processing messages. The
+ Mediation Statistics feature enables a server administrator to collect runtime statistical
+ information on these three types of functional components and view them through the
+ Management Console. This feature provides a simple but effective way of determining the
+ runtime performance of the ESB. The collected statistical data can be used to analyze network
+ traffic patterns and draw rough estimates on how the service bus will be used in the future.
+ Perhaps the most enticing attribute of the mediation statistics feature is that it can be
+ configured in a fine grained manner. In other words, it allows a user to collect data on only
+ a specified set of sequences, proxy services and endpoints.
+
+
+ Mediation Statistics component of WSO2 ESB uses an in-memory data store to keep the
+ collected data. The memory usage of the data store is restricted by the total number of
+ statistics collecting proxy services, sequences and endpoints. If the number of proxy
+ services, sequences and endpoints is constant, the memory usage of the mediation statistics
+ component stays constant.
+
+ Mediation Statistics component also supports persistence as an optional feature. That is,
+ one may configure the ESB to save statistics to the WSO2 Governance Registry instance that
+ comes embedded with the ESB. Mediation Statistics API allows easy sharing of collected
+ data, among Carbon components. Currently WSO2 Business Activity Monitor (BAM) makes use of
+ this API to access data collected by the service bus. Users can also develop custom data
+ consumers to retrieve mediation statistics from the in-memory data store and process them
+ further, using this API.
+
+
+
+ Enabling Mediation Statistics
+
+
+ Mediation Statistics feature is available with WSO2 ESB out of the box. You do not have to
+ configure anything to use this feature. Simply sign-in to the Management Console and enable
+ statistics on the sequences, proxy services and endpoints you want to monitor, and the service
+ bus will start collecting data on them. For an example, in order to enable statistics for a
+ sequence, click on Service Bus > Sequences in the left menu and simply click
+ on the Enable Statistics icon corresponding to that sequence.
+
+
+
+
+
+
+
Figure 1: Enabling mediation statistics for a sequence
+
+
+
+ To enable statistics for a mediation component using the Synapse configuration language, set
+ the value of the "statistics" attribute to "enabled" on the sequence, proxy or endpoint
+ configuration.
+
+
+
+ Viewing Mediation Statistics
+
+
+ To view the gathered statistics, click Monitor > Mediation Statistics.
+ You will be shown a graphical summary of all collected statistics.
+
+
+
+
+
+
Figure 2: Viewing mediation statistics
+
+
+
+ Starting from this view, you can drill down to see more fine grained data such as statistics
+ pertaining to a single sequence or a proxy service. You can even get statistics for different
+ operations on the same endpoint. Click Proxy Service Statistics link in the
+ upper right corner box of the UI shown in Figure 2 to view a summary of Proxy Service Statistics
+ (Figure 3)
+
+
+
+
+
+
Figure 3: Mediation statistics of all proxy services
+
+
+
+ Select a proxy service from the "Proxy Services" list shown above to view statistics of that
+ proxy service.
+
+
+
+
+
+
Figure 4: Mediation statistics of a proxy service
+
+
+
Transport Statistics, System Statistics and System Logs
+ WSO2 ESB exposes number of management resources as JMX MBeans that can be used for managing
+ and monitoring the running server. These MBeans can be accessed remotely using a JMX client
+ such as JConsole. When WSO2 ESB is starting up, it will display the JMX Service URL in the
+ console as follows.
+
+
+ INFO - JMXServerManager JMX Service URL : service:jmx:rmi://localhost:11111/jndi/rmi://localhost:9999/jmxrmi
+
+
+ This URL can be used to remotely access the JMX Service exposed by WSO2 ESB. In this guide,
+ we will use JConsole as the JMX client to access this service.
+
+
+ Using JConsole for JMX Monitoring
+
+
+ Start JConsole and enter the above URL as the JMX Service URL. Type "admin" in both
+ username and password fields and click "Connect".
+
+
+
+
+
Figure 5: Connecting to the JMX service using JConsole
+
+
+
+ After successfully connecting to the JMX service, click on "MBeans" tab of JConsole to view
+ MBeans exposed by the ESB. As shown in Figure 6, these are listed under org.apache.axis2
+ and org.apache.synapse nodes. The following section summarizes the attributes and operations
+ available in MBeans exposed by the WSO2 ESB.
+
+
+
+
+
Figure 6: Viewing MBeans exposed by WSO2 ESB
+
+
+ Attributes and Operations of MBeans
+
+
+
+
Transport related MBeans: For each transport listener and sender enabled in the
+ ESB, there will be an MBean under org.apache.axis2/Transport node which has following
+ attributes and operations. For example, when http and https transports are enabled following
+ MBeans will be exposed.
+
+
org.apache.axis2/Transport/nio-http-listener
+
org.apache.axis2/Transport/nio-http-sender
+
org.apache.axis2/Transport/nio-https-listener
+
org.apache.axis2/Transport/nio-https-sender
+
+
+
+
+
+
+ Attribute/Operation Name
+
+
+ Description
+
+
+
+
+
+
ActiveThreadCount
+
Threads active in this transport listener/sender.
+
+
+
AvgSizeReceived
+
Average size of received messages.
+
+
+
AvgSizeSent
+
Average size of sent messages.
+
+
+
MaxSizeReceived
+
Maximum message size of received messages.
+
+
+
MaxSizeSent
+
Maximum message size of sent messages.
+
+
+
MinSizeReceived
+
Minimum message size of received messages.
+
+
+
MinSizeSent
+
Minimum message size of sent messages.
+
+
+
MessagesReceived
+
Total number of messages received through this transport.
+
+
+
MessagesSent
+
Total number of messages sent through this transport.
+
+
+
FaultsReceiving
+
Number of faults encountered while receiving.
+
+
+
FaultsSending
+
Number of faults encountered while sending.
+
+
+
BytesReceived
+
Number of bytes received through this transport.
+
+
+
BytesSent
+
Number of bytes sent through this transport.
+
+
+
QueueSize
+
Number of messages currently queued. Messages get queued if all the worker threads
+ in this transport thread pool are busy.
+
+
+
+
ResponseCodeTable
+
Number of messages sent against their response codes.
+
+
+
+
TimeoutsReceiving
+
Message receiving timeout.
+
+
+
TimeoutsSending
+
Message sending timeout.
+
+
+
LastResetTime
+
Last time transport listener/sender statistic recording was reset.
+
+
+
+
MetricsWindow
+
Time difference between current time and last reset time in milliseconds.
+
+
+
resetStatistics()
+
Clear recorded transport listener/sender statistics and restart recording.
+
+
+
start()
+
Start this transport listener/sender.
+
+
+
stop()
+
Stop this transport listener/sender.
+
+
+
pause()
+
Pause this transport listener/sender which has been started.
+
+
+
resume()
+
Resume this transport listener/sender which is currently paused.
+
+
+
maintenenceShutdown(long gracePeriod)
+
Stop processing new messages, and wait the specified maximum time for in-flight
+ requests to complete before a controlled shutdown for maintenence.
+
+
+
+
+
+
+
Latency related MBeans:
+
+
+
org.apache.synapse/NHTTPLatencyView/nio-http
+
org.apache.synapse/NHTTPLatencyView/nio-https
+
org.apache.synapse/NHTTPS2SLatencyView/nio-http
+
org.apache.synapse/NHTTPS2SLatencyView/nio-https
+
+
+
+
+
+
+ Attribute/Operation Name
+
+
+ Description
+
+
+
+
+
+
AllTimeAvgLatency
+
Average latency since latency recording was last reset.
+
+
+
LastXxxAvgLatency
+
Average latency for last Xxx time period. For example,
+ LastHourAvgLatency return the average latency for last hour.
+
+
+
+
LastResetTime
+
Last time latency statistic recording was reset.
+
+
+
reset()
+
Clear recorded latency statistics and restart recording.
+ An ESB can be deployed as a front end for various services with a very high load passing through it. The traffic passing through it may be of different priorities and can have different load charasterisitcs. Also in some situations load of different types of messages can vary dramatically over time.
+
+ The goal is to serve high priority traffic when there are resources available in the system regardless of the low priority traffic. The serving of different priority messages should be independent as much as possible. For example an ESB can be bombarded with very high volume of low priority traffic. Even in this case ESB should obey its contract to serve high priority traffic.
+
Usually a person deploying an ESB expects a certain guarantee of message deliverance from the ESB. ESB should be able to honor that.
+
+ Here is a possible scenario with a high volume of traffic.
+
+ Lets assume ESB is configured to serve two types of messages with different priorities. Message type m1 has the priority p1 and message type m2 has priority p2. p1 is about ten times the priority of p2. In a very high volume traffic scenario the services can afford to loose some amount of m2 messages. But it cannot afford to loose any of m1 messages.
+
+ In normal operation mode, volume of m2 is about twice as m1. But in some situations m1 can be higher and m2 can be low.
+
+ The expectation is to serve the m1 traffic no matter what the volume of m2 traffic is.
+
Priority Based Mediation Configuration Model
+
+
Priority based mediation can be configured at two levels.
+
+
HTTP transport level
+
Mediation level
+
+
+ At both configuration levels priority-executor configuration is present.
+
Priority Executor
+
<priority-executor name="priority-executor">
+ <queues isFixed="true|false" nextQueue="class implementing NextQueueAlgorithm">
+ <queue [size="size of the queue"] priority="priority of the messages put in to this queue"/>*
+ </queues>
+ <threads core="core number of threads" max="max number of threads' keep-alive="keep alive time"/>
+</priority-executor>
+
+
+ An executor is a Thread Pool Executor with separate queues for different priorities.
+
+
+ The queues can have a fixed depths or they can be un-bounded queues. This is controlled by the isFixed attribute.
+
+ A executor should have at least two or more queues. If only one queue is used there is no point in using a priority executor. It only adds some overhead.
+
+ A Queue can have a size and a priority. If the queues has unlimited length, no more than core threads will be used.
+
+ A Priority Executor has a core number of threads. When ESB is started with the priority executor, this number of threads will be created. Max is the maximum number of threads this executor will have. If the number of threads in the executor exceeds the core threads, they will be in active for the keep-alive time only. After the keep-alive time those threads will be be removed from the system.
+
+
HTTP Level Configuration
+
+ HTTP level configuration is done by using a separate xml configuration file.
+
+ This configuration file should be referred from the Nhttp transport receiver configuration in the axis2.xml.
Here is the syntax of the priority configuration at the HTTP level.
+
<Priority-Configuration>
+ <priority-executor name="priority-executor">
+ <queues isFixed="true|false">
+ <queue [size=""] priority=""/>*
+ </queues>
+ <threads core="core number of threads" max="max number of threads' keep-alive="keep alive time"/>
+ </priority-executor>
+
+ <!-- conditions for calculating the priorities based on HTTP message -->
+ <conditions defaultPriority="default priority as an integer">
+ <condition priority="priority value as an integer">
+ one evaluator, this evaluator can contain other evaluators
+ </condition>
+ </conditions>
+</Priority-Configuration>
+
+ Priority executor configuration is explained in the previous section.
+
+ A priority configuration can have multiple conditions. A condition is evaluated over a HTTP message. A condition return true or false. If a condition evaluates to true, message will be executed with the priority associated with the condition.
+
+ A condition can have a single boolean expression. Here are the supported boolean operators and expressions.
+
+
equal
+
match
+
not
+
and
+
or
+
+
+ eqaul and match are leaf level expressions. 'not', 'and' and 'or' can contain other expressions.
Match is similar to equal. Only difference is instead of just trying to see weather the two values are equal, it uses a regular expression to match the source. If the regular expression matches the source it will return true
+
not
+
<not>
+ any boolean operator or boolean expression
+</not>
+
+
Not can have another boolean expression inside of it. Not negates the boolean value returned by the boolean expression inside.
+
and
+
<and>
+ two or more boolean boolean expressions
+</and>
+
And can have two or more boolean expressions. It does the boolean and for the enclosing expressions.
+
or
+
<or>
+ any boolean operator or boolean expression
+</or>
+
+
"or" is same as "and" configuration except it gets the boolean 'or' for the enclosing expressions.
+
Mediation level Configurations
+
+ At mediation level multiple priority executors can be defined at the top level of the sypase configuration. These executors should have a unique name.
+
<priority-executor name="priority-executor">
+ <queues isFixed="true|false">
+ <queue [size=""] priority=""/>*
+ </queues>
+ <threads core="core number of threads" max="max number of threads' keep-alive="keep alive time"/>
+</priority-executor>
+
+
Executor configuration is same as the one described earlier.
+
+ To execute a sequence using a priority-executor enqueue mediator should be used. Here is the syntax of the enqueue mediator.
+
Enqueue Mediator
+
<enqueue priority="priority as an integer" executor="executor name to submit the responses" sequence="sequence name to be executed with the given priority"/>
+
+
Enqueue mediator should be pointing to an priority-executor. Message coming in to the enqueue mediator will be executed using this priority-executor. Also it specifies a priority. This priority is applied to the messages. sequence attribute specifies the sequence to be executed with the given priority.
Properties provide the means of accessing various information regarding a message
+ passing through the ESB. Also properties can be used to control the behaviour of the
+ ESB for a particular message as well.
+
Generic Properties
+
Property: synapse.isresponse
+
+
+
Name
+
synapse.isresponse
+
+
+
Possible Values
+
"true", "false"
+
+
+
Default Behavior
+
none
+
+
+
Scope
+
axis2
+
+
+
Description
+
+ Once this property is set to 'true' on a message, the ESB will start treating it
+ as a response message. It is generally used to route a request message back to its
+ source as the response.
+
+ By default the ESB adds a new set of WS-Addressing headers to the messages forwarded
+ from the ESB. If this property is set to 'true' on a message the ESB will forward it
+ without altering its existing WS-Addressing headers.
+
+ Same as synapse.isresponse property. It is recommended to use this property to flag
+ messages as responses instead of the synapse.isresponse property.
+
+
+
+
Example
+
+
<property name="RESPONSE" value="true"/>
+
+
+
+
+
Property: OUT_ONLY
+
+
+
Name
+
OUT_ONLY
+
+
+
Possible Values
+
"true", "false"
+
+
+
Default Behavior
+
none
+
+
+
Scope
+
synapse
+
+
+
Description
+
+ Set this property to 'true' on a message to indicate that no response message is
+ expected for it once it is forwarded from the ESB. In other words the ESB will do
+ an out-only invocation with such messages. It is very important to set this property
+ on messages that are involved in out-only invocations to prevent the ESB from registering
+ unnecessary callbacks for response handling and eventually running out of memory.
+
+
+
+
Example
+
+
<property name="OUT_ONLY" value="true"/>
+
+
+
+
+
Property: ERROR_CODE
+
+
+
Name
+
ERROR_CODE
+
+
+
Possible Values
+
string
+
+
+
Default Behavior
+
none
+
+
+
Scope
+
synapse
+
+
+
Description
+
+ Use this property to set a custom error code on a message which can be later processed
+ by a Synapse fault handler. If the Synapse encounters an error while mediation or
+ routing this property will be automatically populated.
+
+
+
+
Example
+
+
<property name="ERROR_CODE" value="100100"/>
+
+
+
+
+
Property: ERROR_MESSAGE
+
+
+
Name
+
ERROR_MESSAGE
+
+
+
Possible Values
+
string
+
+
+
Default Behavior
+
none
+
+
+
Scope
+
synapse
+
+
+
Description
+
+ Use this property to set a custom error message on a message which can be later
+ processed by a Synapse fault handler. If the Synapse encounters an error while
+ mediation or routing this property will be automatically populated.
+
+ Use this property to set the exception stacktrace in case of an error. If the ESB
+ encounters an error while mediation or routing this property will be automatically
+ populated.
+
+ Contains the actual exception thrown in case of a runtime error
+
+
+
+
Example
+
+
+
+
+
+
+
Property: TRANSPORT_HEADERS
+
+
+
Name
+
TRANSPORT_HEADERS
+
+
+
Possible Values
+
java.util.Map
+
+
+
Default Behavior
+
Populated with the transport headers of the incoming request
+
+
+
Scope
+
axis2
+
+
+
Description
+
+ Contains the map of transport headers. Automatically populated. Individual
+ values of this map can be accessed using the property mediator in the transport
+ scope.
+
+ Set this property to 'true' if you do not want the ESB to add WS-Addressing headers
+ to outgoing messages. This property can affect messages sent to backend services as
+ well as the responses routed back to clients.
+
+ By default Axis2 will spawn a new thread to handle each outgoing message. To change
+ this behavior remove this property from the message. Removal of this property could
+ be vital when queuing transports like JMS are involved.
+
+ Set automatically by the mediation engine upon startup
+
+
+
+
+ Scope
+
+
+ synapse
+
+
+
+
Property: preserveProcessedHeaders
+
+
+
Name
+
preserveProcessedHeaders
+
+
+
Possible Values
+
true/false
+
+
+
Default Behavior
+
Preserving SOAP headers
+
+
+
Scope
+
synapse(default)
+
+
+
Description
+
+ If we set this property to 'true', synapse tries to preserve the SOAP header of incoming requests.
+ Else, by default synapse removes the soap headers.
+
+ In situations where the ESB is receiving HTTP response messages without the
+ Content-type header, this property can be used to specify a default content type
+ to be used. If no such content type is specified for responses the ESB will
+ default to 'application/octet-stream'.
+
+ In Case of GET requests this contains the query string
+
+
+
+
+ Scope
+
+
+ axis2
+
+
+
+
+ Description
+
+
+ The value of this property will be appended to the target URL when sending
+ messages out in RESTful manner. Useful when it is required to append a context
+ to the target URL in case of RESTful invocations.
+
+ WSO2 Enterprise Service Bus (ESB) Quick Start Guide
+
+
+ This guide demonstrates two sample applications covering the basic and the
+ most common usage scenarios of WSO2 ESB, namely Message Mediation
+ and Service Mediation (using Proxy Services). You will be guided through a
+ series of steps to create, execute, and analyze these mediation
+ configurations using the ESB Management Console.
+
+ In this example, ESB will be used to filter and log the messages passing
+ through it. Although this simple scenario only performs simple filtering
+ and logging, it demonstrates the basics of message mediation, where this
+ simple functionality could be replaced with any combination of advanced
+ mediations such as transformations, and content based routing as well as
+ bridging between different communication protocols. Let's start with
+ the basics.
+
+
+ Download
+
+
+ Our first task is to download WSO2 ESB. Open a Web browser and access
+
+ http://wso2.org/downloads/esb. You will then
+ see the list of available releases. Click on the latest release version,
+ and you will be directed to the WSO2 ESB latest release download page. Now
+ download the binary distribution as a ZIP archive.
+
+
+ Installation
+
+
+ WSO2 ESB can be installed by simply extracting the downloaded binary archive. A
+ directory named wso2esb with the version number will be created in the
+ current working directory, containing all the files required by the ESB.
+ We will refer to this directory as <esb-home> from now on.
+
+
+ Running the Sample Scenario
+
+
+ WSO2 ESB acts as the intermediary between the client and the server.
+ Hence, you will need to run three programs to get an idea of message
+ mediation. The destination server that hosts the backend service that has
+ to be invoked to service the client, the client itself, and the WSO2 ESB,
+ which sits in between to perform the mediation.
+
+
+
+
+ Starting WSO2 ESB
+
+
+
+
+ Let's first start the WSO2 ESB. Set the log level of org.apache.synapse
+ to DEBUG by editing the
+ <esb-home>/lib/log4j.properties file. This will cause the ESB
+ to output debug messages for the actions it is performing. We can inspect
+ these logs later using the Management Console. Then go to the <esb-home>/bin
+ folder and execute the following command.
+
+
Linux: ./wso2server.sh
+Windows: wso2server.bat
+
+ You will see the following message on the console to indicate that the
+ ESB started successfully.
+
+
+[2011-05-23 13:57:03,248] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 20 sec
+
+
+
+ Configuring the ESB to Perform Message Mediation
+
+
+
+
+ After starting the ESB, we have to configure it to perform the required
+ message mediation. WSO2 ESB starts with a default configuration, which is
+ sufficient for our first scenario. Later on, we will change this
+ configuration using the management console to build different mediations.
+ Now examine the default configuration using the ESB console. Open a Web
+ browser and point it to
+
+ https://localhost:9443/carbon. You will be
+ directed to the login screen of the Management Console shown below.
+
+
+
+
+
+
+
+ The Management Console ships with a default username and password
+ combination: "admin", "admin".
+ Type "admin" in both the username and password fields and click
+ Sign In. You will be directed to the main page of the ESB Management
+ Console, which displays information about the ESB as well as brief
+ descriptions about its environment. Click on
+ Monitor > System Logs in the left-hand side navigation pane
+ to display log messages of the system. You will see the same
+ set of log messages displayed in the command line, when starting the ESB.
+ Now click Monitor > System Statistics
+ to view runtime statistics of the
+ system. You will notice that currently there are no runtime statistics as
+ no message mediation has happened.
+
+
+
+ Now it is time to examine the mediation configuration visually. Click on
+ the Sequences link on the left panel. In the
+ Defined Sequences tab you will see that two sequences
+ named "fault" and "main" are currently available. These two sequences are
+ generated automatically by the ESB at start up. We can add any number of
+ sequences using this page to suit our mediation requirements. However these
+ pre-defined sequences are sufficient for this sample application. Let's
+ analyze what happens to the messages inside the main sequence by clicking
+ on the Edit link of the "main" sequence. You will see a
+ set of mediators listed for the main sequence as shown below.
+
+
+
+
+
+
+
+
+ You will see there are two mediators named "In" and "Out" at the top
+ level. These two mediators handle request messages
+ and response messages respectively. Inside the In Mediator, two mediators
+ named Log Mediator and Filter Mediator are listed as children. Therefore,
+ incoming messages will flow through these two mediators.
+
+
+ You will notice that Log Mediator is configured to log all the details of
+ the messages (i.e. full log level) and Filter Mediator is configured only
+ to pass through messages containing "http://localhost:9000" in the
+ WS-Addressing header. You can change this default configuration by
+ clicking on the corresponding mediator icon and modifying the parameter values
+ in the form which appears below. A Send Mediator is listed as
+ the child of the Filter Mediator. Therefore, filtered messages will be
+ sent to the specified WS-Addressing destination. That's all we do for the
+ request messages. Now let's look at the Out Mediator. There is only a Send
+ Mediator defined in the Out Mediator by default. This will just send
+ response messages back to the client.
+
+
+ Now we have a basic understanding about the message flow inside the ESB.
+ We are going to make a small modification to the main sequence to enable
+ statistics monitoring and tracing. Just click on the "Sequences"
+ link in the left menu to display all the available sequences.
+
+
+ Now click on the first two icons under the Actions heading of the "main"
+ sequence, namely Enable Statistics and
+ Enable Tracing.
+
+
+ Now we are done with the ESB configuration. It's time to continue the rest
+ of the steps and see it in action.
+
+
+
+
+
+ Starting the Sample Apache Axis2 Server
+
+
+
+
+ Here we are using a standalone Apache Axis2 Web services engine as the
+ server. You don't have to get it now, as it is already bundled with your
+ ESB distribution. We have to deploy a sample service to which the client
+ can send requests. Go to <esb-home>/samples/axis2Server/src/SimpleStockQuoteService
+ directory. Run "ant" to build and deploy this service to the sample Axis2
+ server.
+
+
user@host:~/wso2esb/samples/axis2Server/src/SimpleStockQuoteService$ ant
+Buildfile: build.xml
+
+clean:
+
+init:
+ [mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp
+ [mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+ [mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/repository/services
+
+compile-all:
+ [javac] Compiling 9 source files to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+
+build-service:
+ [mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 9 files to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [jar] Building jar: /home/user/wso2esb/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
+
+BUILD SUCCESSFUL
+Total time: 1 second
+
+ Now go to <esb-home>/samples/axis2Server directory and start the
+ server using the following command. This will start Axis2 server on port
+ 9000 (HTTP).
+
+
+ Linux / Unix: ./axis2server.sh Windows: axis2server.bat
+
+
+ You will see the following messages on the console.
+
+
user@host:~/wso2esb/samples/axis2Server$ ./axis2server.sh
+ Using JAVA_HOME: /usr/java
+ Using AXIS2 Repository : /home/user/wso2esb/samples/axis2Server/repository
+ Using AXIS2 Configuration : /home/user/wso2esb/samples/axis2Server/repository/conf/axis2.xml
+2007-11-08 18:00:54,283 [-] [main] INFO SimpleHTTPServer [SimpleAxisServer] Starting
+[SimpleAxisServer] Using the Axis2 Repository : /home/user/wso2esb/samples/axis2Server/repository
+[SimpleAxisServer] Using the Axis2 Configuration File : /home/user/wso2esb/samples/axis2Server/repository/conf/axis2.xml
+2007-11-08 18:00:55,494 [-] [main] INFO HttpCoreNIOSender HTTPS Sender starting
+2007-11-08 18:00:55,495 [-] [main] INFO HttpCoreNIOSender HTTP Sender starting
+2007-11-08 18:00:55,798 [-] [main] INFO HttpCoreNIOListener HTTPS Listener starting on port : 9002
+2007-11-08 18:00:55,804 [-] [main] INFO HttpCoreNIOListener HTTP Listener starting on port : 9000
+2007-11-08 18:00:55,805 [-] [main] INFO SimpleHTTPServer [SimpleAxisServer] Started
+
+
+
+ Running the Client
+
+
+
+
+ The final step is running the client. Go to <esb-home>/samples/axis2Client
+ directory and type the following command.
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dsymbol=IBM -Dmode=quote
+
+ You can see the following output with the quote price sent by the server.
+
+ This sends a request for a stock quote for the symbol IBM, sets the
+ transport URL to the ESB (http://localhost:8280), and the WS-Addressing
+ EPR set to the actual server
+ (http://localhost:9000/services/SimpleStockQuoteService). The actual wire
+ level HTTP message sent by the client is as follows, and is sent over port
+ 8280 to the ESB instance on the localhost.
+
+ We have just performed a message mediation using the WSO2 ESB. Now let's
+ analyze how ESB has behaved by looking at the various visual monitoring
+ tools provided by the ESB. First click on Monitor > System Logs
+ to see the log
+ messages produced by the ESB. You will see a log messages view as shown
+ below, displaying the actions performed by the ESB in the mediation
+ process.
+
+
+
+
+
+
+ Now click on Monitor > Mediation Tracer to view the
+ trace messages emitted by the ESB.
+ You will see trace messages as shown in the following image.
+
+
+
+
+
+
+
+ Now let's move on to viewing mediation statistics. Click
+ Monitor > Mediation Statistics to view the overall
+ runtime statistics graphically. You will see the updated statistics
+ reflecting the message mediation we have just performed.
+
+
+
+
+
+
+ Top left box displays the mediated messages per server. Bottom right box
+ displays the mediated messages per sequence.
+
+
+
+ Now let's go deeper into the statistics console and get more information
+ about the runtime statistics. First click on the
+ Server Statistics
+ in the top left box. You will be presented with a summary of the
+ server statistics containing total messages, average response time, etc.
+ In the same way, you will be able to view summarized statistics for
+ sequences by clicking on Sequence Statistics in the
+ bottom right box.
+
+
+ You have successfully completed the first part of this
+ guide. Now let's look at the next scenario, Proxy Services.
+
+
+
+ Proxy Services
+
+
+
+ As the name implies, a proxy service acts as a service hosted in the WSO2
+ ESB, and typically fronts an existing service endpoint. A proxy service
+ can be created and exposed on a different transport, schema, WSDL, or QoS
+ (such as WS-Security, WS-Reliable Messaging) aspect than the real service,
+ and can mediate the messages before being delivered to the actual
+ endpoint, and the responses before they reach the client.
+
+
+ Clients can send requests for proxy services directly to the ESB, as the
+ client sees it as being hosted on it. For example it can perform ?wsdl and
+ view the WSDL of the virtual proxy service. In the ESB configuration, such
+ requests can be handled in anyway you like. The most obvious thing would
+ be to process the message and send it to the actual service, probably
+ running on a different computer, but it is not necessary to always send
+ the message to the actual service. You may list any combination of tasks
+ to be performed on the messages received for the proxy service and
+ terminate the flow or send some message back to the client even without
+ sending it to an actual service. Let's explore a simple proxy services
+ scenario to get a better understanding. As you have downloaded and
+ installed the WSO2 ESB in the previous section, now you can start directly
+ on the sample application.
+
+
+
+ Running the Sample Scenario
+
+
+ As in the previous section, there should be three entities running to
+ demonstrate proxy services, the server, client, and the ESB. Let's start
+ with configuring the ESB with a proxy service to suit our scenario.
+
+
+
+
+ Configuring WSO2 ESB
+
+
+
+
+ Start the ESB as the previous section and log in to the Management
+ Console. Click Web Services > List on the left panel.
+ You will see that currently no proxy services have been defined.
+ Let's add a new proxy
+ service by clicking Web Services > Add > Proxy Service
+ on left panel. You will be shown a list of
+ standard proxy service templates to choose from.
+
+
+
+
+
+
+
+ Select the Custom Proxy template from the list and you
+ will be directed to the proxy service creation wizard as shown below.
+
+
+
+
+
+
+
+ First give a name to the new proxy service. In this sample type
+ "StockQuoteProxy" as the name of the proxy service.
+
+
+ Next we are going to specify a WSDL for this proxy service. It can be
+ displayed using the ?wsdl operation with an actual service. Select
+ 'Specify Source URL' in the 'Publishing WSDL' drop down list under 'General Settings'.
+ You will be prompted with a text box to enter the URL of the WSDL. Type
+ file:repository/samples/resources/proxy/sample_proxy_1.wsdl as the WSDL
+ URL and click on 'Test URI' button to instantly validate the path.
+
+
+ Next, select the transports that you need to expose the proxy service. By default proxy
+ service will available in both HTTP and HTTPS transports. Also you can add service parameters to proxy service.
+ During ESB startup process, it will start all proxy services and that may need to fetch WSDLs associated
+ with proxy services. If ESB cannot locate those WSDLs during statup, it
+ will ignore such services and continue with the startup process.
+
+
+ Then click Next at the bottom of the page to proceed to the next step of the
+ proxy service creation wizard. As the next step of the wizard we will add a
+ target endpoint to handle request messages and a target in sequence to
+ handle request messages. To add a target endpoint, select the option 'Define Inline'
+ under 'Define Endpoint' and click on Create button that appears.
+ In the next sub menu select Address Endpoint. A web form
+ will be displayed to configure the new endpoint.
+
+
+
+
+
+
+
+ Type the EPR of the target endpoint in the Address field. In this case it is
+ "http://localhost:9000/services/SimpleStockQuoteService". Address endpoint
+ editor is shown above. Keep other fields unchanged and
+ click Save to add the endpoint to the proxy service.
+
+
+ As for the In Sequence, we will leave it empty for this sample. So click on
+ Next to proceed to the next step of the wizard.
+
+
+
+
+
+
+ The next step is to add an out sequence to the proxy service. We just want
+ to send the response messages back to the client in this out sequence.
+ Select 'Define Inline' under 'Define Out Sequence' and click
+ Create. You will be presented with a
+ sequence editor. Click on the 'Add Child' icon and select 'Core' and then
+ 'Send', from the sub menu. A send mediator with default configuration will
+ be added. Click Save to save the out sequence
+ configuration. Finally on the wizard click Finish to save
+ and quit the wizard.
+
+
+
+ Now on the services listing page you will be able to see the newly created
+ proxy service. Click on the service name link to enter the service dashboard.
+ On the service dashboard page you will see the actions that can be
+ performed on our new proxy service. Enable the statistics and tracing for
+ the proxy service by clicking on the appropriate icons.
+
+
+
+
+
+
+
+ We have finished configuring the proxy service for our sample. Now let's
+ continue the rest of the sample.
+
+
+
+
+ Starting the Sample Apache Axis2 Server
+
+
+
+
+ As you have built and deployed the SimpleStockQuote service in the
+ previous section, you can simply start the server by switching to the <esb-home>/samples/axis2Server
+ directory and running the following command.
+
+
+
+ Linux / Unix: ./axis2server.sh
+
+
+ Windows: axis2server.bat
+
+
+
+ You can see the console messages as in the previous section.
+
+
+
+
+ Running the Client
+
+
+
+
+
+ Go to the <esb-home>/samples/axis2Clients directory and type the
+ following command:
+
+
+ ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy
+ -Dmode=quote -Dsymbol=IBM
+
+
+ The above command sends a stockquote request directly to the provided
+ transport endpoint at: http://localhost:8280/services/StockQuoteProxy. You
+ will see the response from the server displayed on the console as follows:
+
+
+ Standard :: Stock price = $165.32687331383468
+
+
+
+
+ Monitoring the Mediation
+
+
+
+
+ As with the previous message mediation sample, you will be able to monitor
+ log messages, trace messages, and statistics for the proxy services based
+ mediation. We will look only at the statistics section, which is going to
+ be different from the previous sample. Click
+ Monitor > Mediation Statistics. You will be
+ directed to the overall statistics page.
+
+
+ To get more information about proxy service statistics, click on
+ Proxy Service Statistics in the top right box. You will
+ see the summarized
+ statistics for the StockQuoteProxy service, we have created in this
+ example.
+
+
+
+
+
+
+ This quick guide illustrates the visual construction of a proxy service
+ and a simple use case. Please refer to samples #150 and above in the
+ Samples guide, for in-depth coverage of more advanced use cases. You don't
+ have to worry about the configuration language too much when reading the
+ samples. You can build all those samples visually using the ESB management
+ console without editing any file at all.
+
+
+
+ Yes, you are done with a quick look at the WSO2 ESB. Now it is time to go
+ deeper and reveal the advanced features of it. You can browse through the
+ samples of interested areas. If you have any issue regarding the ESB as a
+ user, feel free to let us know through the WSO2 ESB user mailing list
+ (esb-java-user@wso2.org).
+
+
+
diff --git a/docs/xdoc/release-notes.xml b/docs/xdoc/release-notes.xml
new file mode 100644
index 0000000000..7c9c4c8a5a
--- /dev/null
+++ b/docs/xdoc/release-notes.xml
@@ -0,0 +1,942 @@
+
+
+
+
+
+
+
+ WSO2 API Manager v1.7.0 - 23rd May 2014
+
+
+
+
The WSO2 API Manager 1.7.0 Released!
+
+
+ The WSO2 API Manager team is pleased to announce the release of version 1.7.0 of
+ the Open Source API Manager.
+
+
+
+ WSO2 API Manager is a platform for creating, managing, consuming and monitoring
+ APIs. It employs proven SOA best practices to solve a wide range of API
+ management challenges such as API provisioning, API governance, API security
+ and API monitoring. It combines some of the most powerful and mature components
+ of the WSO2's state-of-the-art Carbon platform to deliver a smooth and end-to-end
+ API management experience while catering to both API publisher and API consumer
+ requirements.
+
+
+
+ WSO2 API Manager is comprised of several modules.
+
+
+
API Provider: Define new APIs and manage them
+
API Store: Browse published APIs and subscribe to them
+
API Gateway: The underlying API runtime based on WSO2 ESB
+
API Key Manager: Performs Key Generation and Key Validation functionalities
+
+
+
+ WSO2 API Manager is developed on top of the revolutionary
+ WSO2 Carbon platform
+ (Middleware a' la carte),
+ an OSGi based framework that provides seamless modularity to your SOA via
+ componentization. This release also contains many new features and a range of
+ optional components (add-ons) that can be installed to customize the behavior
+ of the API Manager. Further, any existing features of the product which are not
+ required in your environment can be easily removed using the underlying
+ provisioning framework of Carbon. In brief, WSO2 API Manager can be fully
+ customized and tailored to meet your exact API management needs.
+
[APIMANAGER-2028] - Cannot provide a registry resource as the wsdl url and create an API
+
+
[APIMANAGER-2030] - Unable to add an API to external store once it was deleted
+
+
[APIMANAGER-2031] - Exception on first log in attempt to key manager/gateway on a distributed setup
+
+
[APIMANAGER-2037] - When adding an API, and when the API name contains special characters, the API addition fails, but the appeared UI message is not descriptive enough for the user to identify what went wrong.
+
[APIMANAGER-2041] - Workflow admin web application login.jag not loaded for the http url
+
+
[APIMANAGER-2043] - User Sign up(Store) workflow : Rejected/Pending users are not removed
+
+
[APIMANAGER-2045] - Any user with a camel case user name can't see generated sand box key.
+
+
[APIMANAGER-2047] - Warning + Exception in the backend while listing Sequences from the Carbon Management Console
+
+
[APIMANAGER-2048] - Cannot view any sequence in the Main -> Manage -> Sequences page in the Carbon Management Console
+
+
[APIMANAGER-2049] - Task not updated/removed when user is deleted
+
+
[APIMANAGER-2050] - Workflow admin web app does not load Application creation Approval tasks
+
+
[APIMANAGER-2051] - Missing column in PostgreSQL db script
+
+
[APIMANAGER-2052] - API gray-scaling for unapproved subscriptions does not work on firefox
+
+
[APIMANAGER-2053] - User sign up is enabled in API store for read only external primary user stores.
+
+
[APIMANAGER-2054] - Tenant user sign up through store is not restricted when sign up work flow is enabled
+
+
[APIMANAGER-2057] - Cannot log in to publisher, store when a <WebContextRoot> is used
+
+
[APIMANAGER-2059] - Error when invoking APIs with WSDL endpoints
+
+
[APIMANAGER-2061] - Correct the spelling mistake in "API Usage from Destination" - statistics table title
+
+
[APIMANAGER-2064] - Statistics update issue in API invocations with load balanced endpoints ( when an endpoint is not available)
+
+
[APIMANAGER-2065] - API Invocation fails intermittently with Unclassified Authentication Failure.
+
+
[APIMANAGER-2066] - Issues with faulty invocation statistics update
+
+
[APIMANAGER-2067] - API stat publishing : Total duration does not show the usage for the entire period in API usage by user table
+
+
[APIMANAGER-2068] - Error in storing OAuth2 token which is from SAML assertion in h2 database for the users who has capital letters in their name.
+
+
[APIMANAGER-2069] - Cannot generate access tokens for the users who have capital letters in their username in h2 database
+
+
[APIMANAGER-2071] - The traverse link add for APIStore and Publisher not working in sso mode
+
+
[APIMANAGER-2076] - Embed solr indexing to APIStore search and add search by API description
+
+
[APIMANAGER-2077] - Tenant support not available for Application grant type restriction
+
+
[APIMANAGER-2081] - External API stores which are configured for the super tenant can be viewed by other tenants, in Publisher
+
+
[APIMANAGER-2082] - External API stores which are configured for tenants cannot be seen in publisher
+
+
[APIMANAGER-2083] - APIs which are not even in published state can be made visible to external stores
+
+
[APIMANAGER-2084] - Once an API is published to an external store there is no way of removing it from that external store other than deleting the API
+
+
[APIMANAGER-2086] - APIs published to external stores shows incorrect original publisher in Recently added API list
+
+
[APIMANAGER-2087] - 'Test Endpoint button' says valid for some invalid endpoints
+
+
[APIMANAGER-2088] - NPE when invoking the /token API for the first time with tenant user credentials
+
+
[APIMANAGER-2091] - Cannot create an API with secured endpoints using Failover endpoints
+
+
[APIMANAGER-2092] - Never Ending loop of retries with secured endpoints when using Loadbalanced endpoints
+
+
[APIMANAGER-2094] - Application Token regeneration is broken in Store
+
+
[APIMANAGER-2095] - Swagger doc gets overridden if two publishers create two APIs with the same name
+
+
[APIMANAGER-2098] - Edit a published API throwing exception
+
+
[APIMANAGER-2099] - workflow-admin application dosn't work when it accessed from management console url due to redirection issue.
+
+
[APIMANAGER-2100] - New API resource definition UI wizard in publisher, is not visible in IE
+
+
[APIMANAGER-2101] - [UI] 'Add new resource' button in API creation wizard is not working with IE
+
+
[APIMANAGER-2102] - When a scope is added to a resource path in API creation wizard it does not get saved
+
+
[APIMANAGER-2104] - Removing the doc type called 'API message format',which is not useful In Publisher documentation view
+
+
[APIMANAGER-2105] - Cannot add callback URLs with 'localhost'
+
+
[APIMANAGER-2108] - Access token generation based on grant types Authorization code/ Implicit fails for API-M 1.7.0
+
[APIMANAGER-2133] - Southbound stat publishing - Destination based usage tracking option no more available on publisher
+
+
[APIMANAGER-2134] - Theme related error when the user store is shared
+
+
[APIMANAGER-2138] - API Docs - Issues with updating /adding new documents
+
+
[APIMANAGER-2139] - Issues with statistic display using Google Analytics
+
+
[APIMANAGER-2140] - APIM version has not been updated in carbon.xml file
+
+
[APIMANAGER-2143] - When an API is created with a "WSDL Endpoint" it does not show the link to the wsdl in store
+
+
[APIMANAGER-2144] - Error when running API-Manager on Keymanager and Gateway profiles
+
+
[APIMANAGER-2147] - Error when publishing to gateway in tenant mode in distributed setup
+
+
[APIMANAGER-2148] - Error on first login attempt from a tenant in a distributed set up
+
+
[APIMANAGER-2149] - [Intermittent] Get the below error when logging in to store as a tenant
+
+
[APIMANAGER-2151] - [Intermittent] Error when logging in to publisher/store after logging into the other node (either publisher or store)
+
+
[APIMANAGER-2152] - Error while publishing the first API of a tenant
+
+
[APIMANAGER-2153] - APIs which are created as "visible to all tenants" are not visible to other tenants
+
+
[APIMANAGER-2154] - NPE when accessing an API in tenant store with out logging in to it
+
+
[APIMANAGER-2155] - Error on store for API changes on publisher
+
+
[APIMANAGER-2162] - API Manager Consent page Deny Action doesn't work
+
+
[APIMANAGER-2164] - Error while trying to validate access token when invoking APIs in tenant mode
+
+
[APIMANAGER-2165] - When sending a multi-rooted JSON message as the payload, with an invalid token you get the payload back in the response converted to xml
+
+
[APIMANAGER-2168] - Error when retrieving tasks to workflow admin when port offset takes a value other than 2
+
+
[APIMANAGER-2169] - Error when retrieving tasks to workflow admin when port offset takes a value other than 2
+
[APIMANAGER-2247] - A not properly initiated thrift client will serve key validation requests,when the thrift client initialize during the key manager [thrift server down]
+
+
[APIMANAGER-2248] - Message tracing on gateway does not occur when an API is invoked with an invalid key
+
+
[APIMANAGER-2249] - [UI] Cannot specify advanced options for an endpoint
+
+
[APIMANAGER-2251] - Cannot view the API-Dashboard of an API
+
[APIMANAGER-2369] - NPE when tenant unloading on gateway nodes
+
+
[APIMANAGER-2370] - Auto subscribed new APIs can be invoked even if the subscription for the original API is not approved
+
+
[APIMANAGER-2372] - Multiple tasks created for the same subscription
+
+
[APIMANAGER-2373] - [Intermittent] 403: Resource forbidden error on gateway nodes when doing a load test
+
+
[APIMANAGER-2374] - Sandbox application token generation not working for a subscriber having upper case username
+
+
[APIMANAGER-2375] - Resource not found exception when tenant getting loaded on gateway node
+
+
[APIMANAGER-2376] - Tenant loading fails in Gateway after restarting the server, due to 'Resource does not exist at path /_system/config/repository/transports/https/listener'
+
[APIMANAGER-2379] - [samples]Two statements failed in userPopulater.sql
+
+
[APIMANAGER-2381] - Key validation fails when gateway caching is enabled (workflow related)
+
+
[APIMANAGER-2382] - Sandbox Application-user token scope is stored as PRODUCTION in IDN_OAUTH2_ACCESS_TOKEN
+
+
[APIMANAGER-2387] - Tenant API store loading when SSO is enabled
+
+
[APIMANAGER-2391] - Visible to Role option is given as mandatory only when the API creaion time. Editing an existing API can be done without filling the Visible to Roles textbox
+
+
[APIMANAGER-2393] - Publisher node trying to publish stats to the BAM
+
+
[APIMANAGER-2394] - Too many INFO/ WARN logs when connecting registry mounts
+
+
[APIMANAGER-2397] - [Intermittent] Resource not found exception at KeyManager node when tenant is logging in to Publisher node
+
+
[APIMANAGER-2398] - Cannot publish to gateway while a mild load test happening (Connection timed out)
+
+
[APIMANAGER-2399] - [intermittent] [loadtest] NPE when changing API status, while running a mild load test
+
+
[APIMANAGER-2400] - [intermittent] ResourceNotFoundException on one tenat's resource while logged in to the store with some other tenant.
+
+
[APIMANAGER-2402] - SQLException: ORA-02292 - After removing a scope restriction from a resource and saving the API
+
+
[APIMANAGER-2403] - http 403 error response for POST requests sent inside a SOAP envelope but for GET requests response comes as a plain xml
+
+
[APIMANAGER-2405] - Workflow admin multiple role log in issue (Intermittant)
+
+
[APIMANAGER-2408] - when registry path is there as wsdl url test option will not work.
+
+
[APIMANAGER-2409] - Cannot install APIM 1.7.0 Key manager feature in IS 5.0.0
+
+
[APIMANAGER-2411] - SOAPAction header is removed by the Gateway
+
+
[APIMANAGER-2419] - Same token is regenerated when token encryption enabled
+
+ Following is a categorization of the core features supported by WSO2 API Manager
+ based on the target user group.
+
+
+
Create a Store of all Available APIs:
+
+
Graphical experience similar to Android Marketplace or Apple App Store.
+
Browse APIs by provider, tags or name.
+
Self-registration to developer community to subscribe to APIs.
+
Subscribe to APIs and manage subscriptions on per-application basis.
+
Subscriptions can be at different service tiers based on expected usage levels.
+
Role based access to API Store; manage public and private APIs.
+
Manage subscriptions at a per-developer level.
+
Browse API documentation, download helpers for easy consumption.
+
Comment on and rate APIs.
+
Forum for discussing API usage issues (Available soon in future version).
+
Try APIs directly on the store front.
+
Internationalization (i18n) support.
+
+
+
+
Publishing and Governing API Use:
+
+
+
Publish APIs to external consumers and partners, as well as internal users.
+
Supports publishing multiple protocols including SOAP, REST, JSON and XML style services as APIs.
+
Manage API versions and deployment status by version.
+
Govern the API lifecycle (publish, deprecate, retire).
+
Attach documentation (files, external URLs) to APIs.
+
Apply Security policies to APIs (authentication, authorization).
+
Associate API available to system defined service tiers.
+
Provision and Manage API keys.
+
Track consumers per API.
+
One-click deployment to API Gateway for immediate publishing.
+
+
+
+
Route API Traffic:
+
+
+
Supports API authentication with OAuth2.
+
Extremely high performance pass-through message routing with sub-millisecond latency.
+
Enforce rate limiting and throttling policies for APIs by consumer.
+
Horizontally scalable with easy deployment into cluster using proven routing infrastructure.
+
Scales to millions of developers/users.
+
Capture all statistics and push to pluggable analytics system.
+
Configure API routing policies with capabilities of WSO2 Enterprise Service Bus.
+
Powered by WSO2 Enterprise Service Bus.
+
+
+
+
Manage Developer Community:
+
+
Self-sign up for API consumption.
+
Manage user account including password reset.
+
Developer interaction with APIs via comments and ratings.
+
Support for developer communication via forums (Available soon in future version).
+
Powered by WSO2 Identity Server.
+
+
+
+
Govern Complete API Lifecycle:
+
+
Manage API lifecycle from cradle to grave: create, publish, block, deprecate and retire.
+
Publish both production and sandbox keys for APIs to enable easy developer testing.
+
Publish APIs to partner networks such as ProgrammableWeb (Available soon in future version).
+
Powered by WSO2 Governance Registry.
+
+
+
+
Monitor API Usage and Performance:
+
+
All API usage published to pluggable analytics framework.
+
Out of the box support for WSO2 Business Activity Monitor and Google Analytics.
+
View metrics by user, API and more.
+
Customized reporting via plugging reporting engines.
+
Monitor SLA compliance.
+
Powered by WSO2 Business Activity Monitor.
+
+
+
+
Pluggable, Extensible and Themeable:
+
+
All components are highly customizable thru styling, theming and open source code.
+
Storefront implemented with Jaggery (jaggeryjs.org) for easy customization.
+
Pluggable to third party analytics systems and billing systems (Available soon in future version).
+
Pluggable to existing user stores including via JDBC and LDAP.
+
Components usable separately - storefront can be used to front APIs gatewayed via third party gateways such as Intel Expressway Service Gateway.
+
Support for Single Sign On (SSO) using SAML 2.0 for easy integration with existing web apps
+
+
+
+
Easily Deployable in Enterprise Setting:
+
+
Role based access control for managing users and their authorization levels.
+
Store front can be deployed in DMZ for external access with Publisher inside the firewall for private control.
+
Different user stores for developer focused store-front and internal operations in publisher.
+
Integrates with enterprise identity systems including LDAP and Microsoft Active Directory.
+
Gateway can be deployed in DMZ with controlled access to WSO2 Identity Server (for authentication/authorization) and governance database behind firewall.
+
+
+
+
+
Support for creating multi-tenanted APIs
+
+
Run a single instance and provide API Management to multiple customers
+
Share APIs between different departments in a large enterprise
+
+
+
+
Publishing and Governing API Use
+
+
Document an API using Swagger
+
Restrict API Access tokens to domains/IPs
+
Ability to block a subscription and restricting a complete application
+
Ability to revoke access tokens
+
Separate validity period configuration for Application Access Token
+
OAuth2 Authorization Code Grant Type Support
+
Configuring execution point of mediation extensions
+
+
+
+
Monitor API Usage and Performance
+
+
Improved dashboard for monitoring usage statistics (Filtering data for a date range, More visually appealing widgets)
+
+
+
+
+
Known Issues
+
+ All the open issues pertaining to WSO2 API Manager are reported at the following
+ location:
+
+ We encourage you to report issues, documentation faults and feature requests
+ regarding
+ WSO2 API Manager through the public API Manager
+ JIRA. You
+ can use the
+ Carbon JIRA
+ to report any
+ issues related to the Carbon base framework or associated Carbon components.
+
+
+
Support
+
+ We are committed to ensuring that your enterprise middleware deployment is
+ completely supported from evaluation to production. Our unique approach
+ ensures that all support leverages our open development methodology and is
+ provided by the very same engineers who build the technology.
+
+
+ For more details and to take advantage of this unique opportunity please
+ visit http://wso2.com/support.
+
The ESB Script Mediator is a ESB extension, and thus all prerequisites are
+not bundled by default with the ESB distribution. Before you use some script
+mediators you may need to manually add the required jar files to the ESB lib
+directory, and optionally perform other installation tasks as may be required
+by the individual scripting language. This is explained in the Samples Setup guide.
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <localEntry key="stockquoteScript" src="file:repository/samples/resources/script/stockquoteTransform.js"/>
+
+ <in>
+ <!-- transform the custom quote request into a standard quote request expected by the service -->
+ <script language="js" key="stockquoteScript" function="transformRequest"/>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <script language="js" key="stockquoteScript" function="transformResponse"/>
+ <send/>
+ </out>
+</definitions>
+
<x><![CDATA[
+ function transformRequest(mc) {
+ var symbol = mc.getPayloadXML()..*::Code.toString();
+ mc.setPayloadXML(
+ <m:getQuote xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>{symbol}</m:symbol>
+ </m:request>
+ </m:getQuote>);
+ }
+
+ function transformResponse(mc) {
+ var symbol = mc.getPayloadXML()..*::symbol.toString();
+ var price = mc.getPayloadXML()..*::last.toString();
+ mc.setPayloadXML(
+ <m:CheckPriceResponse xmlns:m="http://services.samples/xsd">
+ <m:Code>{symbol}</m:Code>
+ <m:Price>{price}</m:Price>
+ </m:CheckPriceResponse>);
+ }
+]]></x>
+
+
Objective: Introduction to the script mediators
+
+
Prerequisites:
+
+
Start the Synapse configuration numbered 350: i.e. wso2esb-samples -sn
+350
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This sample is similar to sample 8 but instead of using XSLT the
+transformation is done with JavaScript and E4X. Note that the script source
+loaded from a resource must be specified within a CDATA tag within an XML
+element. The script used in this example has two functions, 'transformRequest'
+and 'transformResponse', and the Synapse configuration uses the function
+attribute to specify which function should be invoked. Use the stock quote
+client to issue a custom quote client as follows.:
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote
+
+
ESB uses the script mediator and the specified Javascript function to
+convert the custom request to a standard quote request. Subsequently the
+response received is transformed and sent back to the client.
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <in>
+ <!-- transform the custom quote request into a standard quote requst expected by the service -->
+ <script language="js"><![CDATA[
+ var symbol = mc.getPayloadXML()..*::Code.toString();
+ mc.setPayloadXML(
+ <m:getQuote xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>{symbol}</m:symbol>
+ </m:request>
+ </m:getQuote>);
+ ]]></script>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <script language="js"><![CDATA[
+ var symbol = mc.getPayloadXML()..*::symbol.toString();
+ var price = mc.getPayloadXML()..*::last.toString();
+ mc.setPayloadXML(
+ <m:CheckPriceResponse xmlns:m="http://services.samples/xsd">
+ <m:Code>{symbol}</m:Code>
+ <m:Price>{price}</m:Price>
+ </m:CheckPriceResponse>);
+ ]]></script>
+ <send/>
+ </out>
+</definitions>
+
+
Objective: Introduction to in-line script mediation
+
+
Prerequisites:
+
+
Start the Synapse configuration numbered 351: i.e. wso2esb-samples -sn
+351
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This example is functionally equivalent to sample # 350 and sample # 8, and
+demonstrates in-line script mediation in ESB. Use the stock quote client to
+send a custom quote as in example # 350 to test this example.
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <in>
+ <!-- change the MessageContext into a response and set a response payload -->
+ <script language="js"><![CDATA[
+ mc.setTo(mc.getReplyTo());
+ mc.setProperty("RESPONSE", "true");
+ mc.setPayloadXML(
+ <ns:getQuoteResponse xmlns:ns="http://services.samples/xsd">
+ <ns:return>
+ <ns:last>99.9</ns:last>
+ </ns:return>
+ </ns:getQuoteResponse>);
+ ]]></script>
+ </in>
+ <send/>
+</definitions>
+
+
Objective: Accessing the Synapse APIs from scripting
+languages
+
+
Prerequisites:
+
+
Start the Synapse configuration numbered 352: i.e. wso2esb-samples -sn
+352
+
+
+
This example shows how an inline JavaScript mediator script could access the
+Synapse message context API to set its 'To' EPR and to set a custom property to
+mark it as a response. Execute the stock quote client, and you will receive the
+response "99.9" as the last sale price as per the above script.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+ ...
+stockquote:
+ [java] Standard :: Stock price = $99.9
<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <localEntry key="stockquoteScript" src="file:repository/samples/resources/script/stockquoteTransform.rb"/>
+ <in>
+ <!-- transform the custom quote request into a standard quote request expected by the service -->
+ <script language="rb" key="stockquoteScript" function="transformRequest"/>
+
+ <!-- send message to real endpoint referenced by name "stockquote" and stop -->
+ <send>
+ <endpoint name="stockquote">
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <script language="rb" key="stockquoteScript" function="transformResponse"/>
+ <send/>
+ </out>
+</definitions>
This sample uses Ruby so first setup support for this in ESB as described at
+Configuring JRuby.
+
+
Start the Synapse configuration numbered 353: i.e. wso2esb-samples -sn
+353
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This sample is functionally equivalent to sample # 350 (#351 and #8) but
+instead uses a Ruby script using the JRuby interpreter. The script has two
+functions, 'transformRequest' and 'transformResponse', and the Synapse
+configuration specifies which function is to be invoked when used. Execute the
+stock quote client to send a custom stock quote as per example #350 and check
+the received stock quote response.
Objective: Script mediators using Ruby(In-lined Ruby
+Script)
+
+
Prerequisites:
+
+
This sample uses Ruby so first setup support for this in ESB as described at
+Configuring JRuby.
+
+
Start the Synapse configuration numbered 354: i.e. wso2esb-samples -sn
+354
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This sample is functionally equivalent to the sample #353.
+
+
Runs the client with
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote
Following database mediators use Derby in a client/server configuration by
+using the network server. Therefore, to proceed with the following samples, you
+need a working Derby database server and you have to follow the steps in Sample Setup Guide before going
+through the samples.
Prerequisites: Setting up Derby database as explained
+above.
+
+
Start the Synapse configuration numbered 360: i.e. wso2esb-samples -sn 360
+
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This sample demonstrates simple database read operations through ESB. When a
+message arrives at dblookup mediator, it opens a connection to the database and
+executes the SQL query. The SQL query use '?' character for attributes that
+will be filled at runtime. The parameters define how to calculate the value of
+those attributes at runtime. In this sample a dblookup mediator has been used
+to extract 'id' of the company from the company database using the symbol which
+is evaluated using an xpath against the SOAP envelope. Then 'id' base switching
+will be done by a switch mediator.
+
+
When the IBM stock quote is requested,
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
+
ESB console shows
+
INFO LogMediator text = ** Looking up from the Database **INFO LogMediator text = Company ID ? c1
+
+
For the SUN stock quote,
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
+
ESB console shows
+
INFO LogMediator text = ** Looking up from the Database **INFO LogMediator text = Company ID ? c2
+
+
and for the MSFT stock quote,
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
INFO LogMediator text = ** Looking up from the Database ** INFO LogMediator text = Company ID ? c2
+
+
For any other symbols, ESB console shows
+
INFO LogMediator text = ** Unrecognized Company ID **
+
+
and the client gets a response which has following message.
Prerequisites: Setting up Derby database as above.
+
+
Start the Synapse configuration numbered 361: i.e. wso2esb-samples -sn 361
+
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
+
This sample demonstrate simple database write operations. The dbreport
+mediator writes (i.e. inserts one row) to a table using the message details. It
+works the same as the dblookup mediator. In this sample , dbreport mediator is
+used for updating the stock price of the company using the last quote value
+which is calculated by evaluating an XPath against the response message. After
+running this sample, user can check the company table using the Derby client
+tool. It will show the inserted value by the dbreport mediator.
+
+
Run the client using,
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
+
and then execute the following query using database client tool against
+synapsedb.
Objective: Demonstrate the use of dbreport and dblookup
+mediators
+
+
Prerequisites: Setting up Derby database as above.
+
+
Start the Synapse configuration numbered 362: i.e. wso2esb-samples -sn 362
+
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
In this sample ,the dbreport mediator works the same as the above sample. It
+updates the price for the given company using the response messages content.
+Then the dblookup mediator reads the last updated value from the company
+database and logs it.
+
+
When running client,
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
+
ESB console shows,
+
INFO LogMediator text = ** Reporting to the Database **
...
INFO LogMediator text = ** Looking up from the Database **
...
INFO LogMediator text = Stock price - 153.47886496064808
Objective: Demonstrate the use of reusable database
+connection pools
+
+
Prerequisites: Setting up DataBase and DataSources
+according to the sample setup guide.
+
+
Start the Synapse configuration numbered 363: i.e. wso2esb-samples -sn
+363
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
Runs the client as follows
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
+
Then the console output
+
INFO LogMediator text = ** Looking up from the Database **
+ ...
+ INFO LogMediator text = Company ID - c1
+ ...
+ INFO LogMediator text = ** Reporting to the Database **
+ ...
+ INFO LogMediator text = ** Looking up from the Database **
+ ...
+ INFO LogMediator text = Stock price - 183.3635460215262
Objective: Demonstrate the use of dblookup and dbreport mediators to execute a database Stored Procedures
+
+
Prerequisites: Set up MySQL database server according to the sample setup guide.
+
+
Start the Synapse configuration numbered 364: i.e. wso2esb-samples -sn
+364
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
Runs the client as follows
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
+
Then you will get the following console output
+
INFO LogMediator text = ** Looking up from the Database ** ...
+INFO LogMediator text = Company ID - c1 ...
+INFO LogMediator text = Stock price - 183.3635460215262
+
Objective: Demonstrate the use of throttle mediator for
+concurrency throttling
+
+
Prerequisites:
+
+
Deploy the SimpleStockQuoteService in sample Axis2 server and start it on
+port 9000.
+
+
Start ESB with the sample configuration 370 (i.e. wso2esb-samples -sn 370).
+
+
+
Above configuration specifies a throttle mediator inside the in mediator.
+Therefore, all request messages directed to the main sequence will be subjected
+to throttling. Throttle mediator has 'policy', 'onAccept' and 'onReject' tags
+at top level. The 'policy' tag specifies the throttling policy for throttling
+messages. This sample policy only contains a component called
+"MaximumConcurrentAccess" .This indicates the maximum number of concurrent
+requests that can pass through Synapse on a single unit of time. To test
+concurrency throttling, it is required to send concurrent requests to Synapse.
+If Synapse with above configuration, receives 20 requests concurrently from
+clients, then approximately half of those will succeed while the others being
+throttled. The client command to try this is as follows.
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280/
Objective: Demonstrate the use of throttle mediator for restricting
+request counts
+
+
Prerequisites:
+
+
Deploy the SimpleStockQuoteService in sample Axis2 server and start it on
+port 9000.
+
+
Start ESB with the sample configuration 371 (i.e. wso2esb-samples -sn 371).
+
+
+
Above configuration specifies a throttle mediator inside the in mediator.
+Therefore, all request messages directed to the main sequence will be subjected
+to throttling. Throttle mediator has policy, onAccept and onReject tags at the
+top level. Policy tag specifies the throttling policy to be applied for
+messages. It contains some IP address ranges and the maximum number of messages
+to be allowed for those ranges within a time period given in "UnitTime" tag.
+"ProhibitTimePeriod" tag specifies the time period to prohibit further requests
+after the received request count exceeds the specified time. Now run the client
+5 times repetitively using the following command to see how throttling works.
+
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280/
+
+
For the first four requests you will get the quote prices for IBM as
+follows.
+
[java] Standard :: Stock price = $177.20143371883802
+
+
You will receive the following response for the fifth request.
Maximum number of requests within 800000 milliseconds is specified as 4 for
+any server (including localhost) other than the explicitly specified ones.
+Therefore, our fifth request is denied by the throttle mediator. You can verify
+this by looking at the ESB console.
+
[HttpServerWorker-1] INFO LogMediator - text = **Access Accept**
+[HttpServerWorker-2] INFO LogMediator - text = **Access Accept**
+[HttpServerWorker-3] INFO LogMediator - text = **Access Accept**
+[HttpServerWorker-4] INFO LogMediator - text = **Access Accept**
+[HttpServerWorker-5] INFO LogMediator - text = **Access Denied**
<!-- Use of both concurrency throttling and request rate based throttling -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">150000</parameter>
+ </registry>
+
+ <sequence name="onAcceptSequence">
+ <log level="custom">
+ <property name="text" value="**Access Accept**"/>
+ </log>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </sequence>
+ <sequence name="onRejectSequence" trace="enable">
+ <log level="custom">
+ <property name="text" value="**Access Denied**"/>
+ </log>
+ <makefault>
+ <code value="tns:Receiver"
+ xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="**Access Denied**"/>
+ </makefault>
+ <property name="RESPONSE" value="true"/>
+ <header name="To" action="remove"/>
+ <send/>
+ <drop/>
+ </sequence>
+ <proxy name="StockQuoteProxy">
+ <target>
+ <inSequence>
+ <throttle onReject="onRejectSequence" onAccept="onAcceptSequence" id="A">
+ <policy key="repository/samples/resources/policy/throttle_policy.xml"/>
+ </throttle>
+ </inSequence>
+ <outSequence>
+ <throttle id="A"/>
+ <send/>
+ </outSequence>
+ </target>
+ <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
+ </proxy>
+</definitions>
+
+
+
+
+
Objective: Use of both concurrency throttling and request rate based
+throttling
+
+
Prerequisites: Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start ESB with the sample configuration 372 (i.e. wso2esb-samples -sn 372).
+
+
+
Throttle policy is loaded from the ?throttle_policy.xml? .That policy
+contains merging policy from sample 370 and 371. To check the functionality ,
+it is need to run load test.The all enabled request from the concurrency
+throttling will be controlled by the access rate base throttling according to
+the policy.
+
+
Run the client as follows
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
+
+
+
You will get results same as sample 371.if you run the load test, results
+will be different due to affect of concurrency throttling.
Class mediator can be used to write your own custom mediation in Java and
+you have access to the SynapseMessageContext and to the full Synapse API in
+there. This is a useful extension mechanism within ESB to extend its
+functionality. This class can contain fields for which you can assign values at
+runtime through the configuration.
Objective: Demonstrate the use of Class mediator to extend the
+mediation functionality
+
+
Prerequisites:
+
+
Make sure the synapse-samples-1.0.jar is in your class path (by default this
+jar is placed in the lib directory when installing ESB).
+
+
Start ESB with the sample configuration 380 (i.e. wso2esb-samples -sn 380)
+
+
+
Start the sample Axis2 server and deploy the SimpleStockQuoteService.
+
+
In this configuration, ESB hands over the request message to the specified
+endpoint, which sends it to the Axis2 server running on port 9000.
+
+
But the response message is passed through the class mediator before sending
+it back to the client. Two parameters named "discountFactor"
+
+
and "bonusFor" are passed to the instance mediator implementation class
+(i.e. samples.mediators.DiscountQuoteMediator) before each
+
+
invocation. Code of the mediator implementation class is shown below.
+
package samples.mediators;
+
+import org.apache.synapse.MessageContext;
+import org.apache.synapse.Mediator;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.soap.SOAPFactory;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import javax.xml.namespace.QName;
+
+public class DiscountQuoteMediator implements Mediator {
+
+ private static final Log log = LogFactory.getLog(DiscountQuoteMediator.class);
+
+ private String discountFactor="10";
+
+ private String bonusFor="10";
+
+ private int bonusCount=0;
+
+ public DiscountQuoteMediator(){}
+
+ public boolean mediate(MessageContext mc) {
+
+ String price= mc.getEnvelope().getBody().getFirstElement().getFirstElement().
+ getFirstChildWithName(new QName("http://services.samples/xsd","last")).getText();
+
+ //converting String properties into integers
+ int discount=Integer.parseInt(discountFactor);
+ int bonusNo=Integer.parseInt(bonusFor);
+ double currentPrice=Double.parseDouble(price);
+
+ //discounting factor is deducted from current price form every response
+ Double lastPrice = new Double(currentPrice - currentPrice * discount / 100);
+
+ //Special discount of 5% offers for the first responses as set in the bonusFor property
+ if (bonusCount <= bonusNo) {
+ lastPrice = new Double(lastPrice.doubleValue() - lastPrice.doubleValue() * 0.05);
+ bonusCount++;
+ }
+
+ String discountedPrice = lastPrice.toString();
+
+ mc.getEnvelope().getBody().getFirstElement().getFirstElement().getFirstChildWithName
+ (new QName("http://services.samples/xsd","last")).setText(discountedPrice);
+
+ System.out.println("Quote value discounted.");
+ System.out.println("Original price: " + price);
+ System.out.println("Discounted price: " + discountedPrice);
+
+ return true;
+ }
+
+ public String getType() {
+ return null;
+ }
+
+ public void setTraceState(int traceState) {
+ traceState = 0;
+ }
+
+ public int getTraceState() {
+ return 0;
+ }
+
+ public void setDiscountFactor(String discount) {
+ discountFactor=discount;
+ }
+
+ public String getDiscountFactor() {
+ return discountFactor;
+ }
+
+ public void setBonusFor(String bonus){
+ bonusFor=bonus;
+ }
+
+ public String getBonusFor(){
+ return bonusFor;
+ }
+}
+
+
All classes developed for class mediation should implement the Mediator
+interface, which contains the mediate(...) method. mediate(...) method of the
+above class is invoked for each response message mediated through the main
+sequence, with the message context of the current message as the parameter. All
+the details of the message including the SOAP headers, SOAP body and properties
+of the context hierarchy can be accessed from the message context. In this
+sample, the body of the message is retrieved and the discount percentage is
+subtracted from the quote price. If the quote request number is less than the
+number specified in the "bonusFor" property in the configuration, a special
+discount is given.
+
+
Now run the client using the following command.
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
+
+
You will see the below output in the client console with the discounted
+quote value.
+
[java] Standard :: Stock price = $138.77458254967408
+
+
Now check the console running Synapse. You will see the original value and
+the discounted value for the requested quote as follows.
+
Quote value discounted.
+Original price: 162.30945327447262
+Discounted price: 138.77458254967408
Start ESB with the sample configuration 381 (i.e. wso2esb-samples -sn 381)
+
+
+
Start the sample Axis2 server and deploy the SimpleStockQuoteService.
+
+
In this configuration, a proxy has configured to accept incoming JMS messages. JMS messages
+ contains a binary payload. User configure the offset, length, binary encoding of the text
+ literal that it need to use for CBR. And a variable name to set the decoded value as a property.
+ Configuration simply route the messages based on the text to different endpoints.
+ A JMS producer and two instances of a consumer used to demonstrate the CBR functionality.
+
+
Now run the first consumer using the following command.
+
ant mddconsumer -Djms_topic=mdd.MSFT
+
+
Now run the second consumer using the following command.
+
ant mddconsumer -Djms_topic=mdd.GOOG
+
+
So, now both consumers are ready to listen the topic
+
Now run the market data producer to genenrate market data for symbol 'MSFT' using the following command.
+
ant mddproducer -Dsymbol=MSFT
+
+
Now run the market data producer to genenrate market data for symbol 'GOOG' using the following command.
+
ant mddproducer -Dsymbol=GOOG
+
+
You will see the below output in the client console(s) based on the symbol.
+
mddconsumer:
+[java] Market data recived for symbol : topic://mdd.MSFT
+[java] Market data recived for symbol : topic://mdd.MSFT
+
<!-- Introduction to the XQuery mediator -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.esb.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <localEntry key="xquery-key-req"
+ src="file:repository/samples/resources/xquery/xquery_req.xq"/>
+ <proxy name="StockQuoteProxy">
+ <target>
+ <inSequence>
+ <xquery key="xquery-key-req">
+ <variable name="payload" type="ELEMENT"/>
+ </xquery>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ <outSequence>
+ <out>
+ <xquery key="xquery/xquery_res.xq">
+ <variable name="payload" type="ELEMENT"/>
+ <variable name="code" type="STRING"
+ expression="self::node()//m0:return/m0:symbol/child::text()"
+ xmlns:m0="http://services.samples/xsd"/>
+ <variable name="price" type="DOUBLE"
+ expression="self::node()//m0:return/m0:last/child::text()"
+ xmlns:m0="http://services.samples/xsd"/>
+ </xquery>
+ <send/>
+ </out>
+ </outSequence>
+ </target>
+ <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
+ </proxy>
+</definitions>
+
+
This example uses the XQuery mediator to perform transformations. This
+sample behaves the same as sample number 8 and the only difference is that this
+sample uses XQuery instead of XSLT for transformation.
+
+
Execute the custom quote client as 'ant stockquote -Dmode=customquote ...'
+
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dmode=customquote
<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <proxy name="StockQuoteProxy">
+ <target>
+ <inSequence>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ <outSequence>
+ <out>
+ <xquery key="xquery/xquery_commisson.xq">
+ <variable name="payload" type="ELEMENT"></variable>
+ <variable name="commission" type="ELEMENT" key="misc/commission.xml"></variable>
+ </xquery>
+ <send/>
+ </out>
+ </outSequence>
+ </target>
+ <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
+ </proxy>
+</definitions>
+
+
Objective: Demonstrate the use of XQuery mediator to import external
+XML documents to the XQuery engine
+
+
Prerequisites:Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start ESB with the sample configuration 391 (i.e. wso2esb-samples -sn 391).
+
+
+
In this sample, data from commission.xml document is used inside XQUERY
+document. The stock quote price from the response and commission from the
+commission.xml document will be added and given as a new price .
+
+
Invoke the client as follows.
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
Objective: Demonstrate the use of Iterate mediator to split the
+messages in to parts and process them asynchronously and then aggregate the
+responses coming in to ESB
+
+
Prerequisites:Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start ESB with the sample configuration 400 (i.e. wso2esb-samples -sn 400).
+
+
+
In this sample, the message sent to ESB has embedded with a number of
+elements of the same type in one message. When ESB received this message it
+will iterate through those elements and then sent to the specified endpoint.
+When all the responses appear in to ESB then those messages will be aggregated
+to form the resultant response and sent back to the client.
+
+
Invoke the client as follows.
+
ant stockquote -Daddurl=http://localhost:8280/services/SplitAggregateProxy -Ditr=4
Cache mediator can be used to utilize the network bandwidth, to protect the
+backend service from being loaded with the same type of requests like browser
+refresh actions and also to speed up the execution of the web service. This
+mediator should be used with sence, because it is not applicable for each and
+every service (for example services with dynamic responses for a particular
+release)
Objective: Demonstrate the use of Cache mediator in order to cache
+the response and use that cached response as the response for an identical xml
+request
+
+
Prerequisites:Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start ESB with the sample configuration 420 (i.e. wso2esb-samples -sn 420).
+
+
+
In this sample, the message sent to ESB is checked for an existing cached
+response by calculating the hash value of the request. If there is a cache hit
+in ESB then this request will not be forwarded to the actual service, rather
+ESB respond to the client with the cached response. In case of a cache miss
+that particular message will be forwarded to the actual service and cached that
+response in the out path for the use of consecutive requests of the same type.
+
+
+
To observe this behaviour, invoke the client as follows.
+
ant stockquote -Dtrpurl=http://localhost:8280/
+
+
You could notice that if you send more than one requests within 20 seconds
+only the first request is forwarded to the actual service, and the rest of the
+requests will be served by the cache inside ESB. You could observe this by
+looking at the printed line of the axis2 server, as well as by observing a
+constant rate as the response to the client instead of the random rate, which
+changes by each and every 20 seconds.
+
The Callout mediator calls the given service URL with the request message
+which is given by the source attribute, waits for the response and attaches the
+received response to the destination which is given by the target attribute.
+Both the source and the target can be a key or an XPath. In the case of the
+source, this key refers to either a message context property or to a local
+entry. For the target, this key refers to a message context property only.
Objective: Demonstrate the use of the Callout mediator for
+the synchronized web service invocation
+
+
+
Prerequisites: Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start Synapse with the sample configuration 430 (i.e. wso2esb-samples -sn
+430).
+
+
In this sample, Callout mediator does the direct service invocation to the
+StockQuoteService using the client request, get the response and set it as the
+first child of the SOAP message body. Then using the send mediator, the message
+is sent back to the client.
+
+
Invoke the client as follows.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
Objective: Demonstrate the ability to switch between JSON and XML/SOAP content interchange formats
+
+
+
Prerequisites: Deploy the SimpleStockQuoteService in sample
+Axis2 server and start it on port 9000.
+
+
Start Synapse with the sample configuration 440 (i.e. wso2esb-samples -sn
+440).
+
Setup Synapse and the sample Axis2 client for JSON (Refer Synapse Samples Setup Guide for details)
+
+
Invoke the client as follows.
+
ant jsonclient -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/services/JSONProxy
+
JSON client will send a stockquote request to Synapse using the JSON content interchange format.
+ Synapse will trnasform it into a SOAP request and forward to the Axis2 server.
+ The SOAP response from the Axis2 server will be converted into a JSON message and sent back to
+ the JSON client.
+
+
You may use a tool like TCPMon to monitor the JSON requests sent over the wire. A sample JSON request and response is shown below:
+
{"getQuote":{"request":{"symbol":"IBM"}}}
+
{"getQuoteResponse":{"return":{"change":3.853593376681722,"earnings":12.802850763714854,"high":67.92488310190126,"last":66.14619264746406,"lastTradeTimestamp":"Mon Aug 23 16:48:40 IST 2010","low":-66.04000424423522,"marketCap":-9334516.42324327,"name":"IBM Company","open":-64.61950137150009,"peRatio":-19.78600441437058,"percentageChange":5.411779328273005,"prevClose":71.2075112994578,"symbol":"IBM","volume":16842}}}
+
+ URL rewrite mediator enables modifying URL values in the message. The input URL could be taken
+ from the 'To' header of the message or from a property available on the message. Once the input
+ URL is selected, a series of user defined rewrite rules will be evaluated on the message. Depending
+ on the outcome of these rule evaluations, the URL will be modified and set on the message.
+
+
+ URL rewrite mediator breaks the URL down to seven segments.
+
+
+
Protocol
+
User information
+
Hostname
+
Port
+
Path
+
Query
+
Reference parameter
+
+
+ Note that this breakdown is inline with the URI specification (RFC2396). URL rewrite mediator
+ enables rewriting each of the above segments separately and finally combining them to get
+ the final URL value. It also supports rewriting the entire URL string at once.
+
+ Objective: Demonstrate the basic functions of the URL rewrite mediator
+
+
+ Prerequisites: Deploy the SimpleStockQuoteService in sample Axis2 server
+ and start it on port 9000.
+
+
+ Start ESB with the sample configuration 450 (i.e. wso2esb-samples -sn 450).
+
+
+ Invoke the client as follows.
+
+
ant stockquote -Dtrpurl=http://localhost:8280 -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
+
+ Note that the address URL of the client request contains the context 'soap'. But in the
+ Axis2 server all the services are deployed under a context named 'services' by default.
+ ESB will rewrite the To header of the request by replacing the 'soap' context with 'services.
+ Hence the request will be delivered to the Axis2 server and the Axis2 client will receive a
+ valid response.
+
+ Objective: Demonstrate the ability of the URL rewrite mediator to evaluate conditions on messages and perform rewrites based on the results.
+
+
+ Prerequisites: Deploy the SimpleStockQuoteService in sample Axis2 server
+ and start it on port 9000.
+
+
+ Start ESB with the sample configuration 451 (i.e. wso2esb-samples -sn 451).
+
+
+ Invoke the Axis2 client and send some requests to ESB with different address URL values.
+ If the address URL value contains localhost as the hostname and https as the protocol
+ prefix, ESB will route the message as it is. But if the hostname is localhost and the
+ protocol is not https, Synapse will rewrite the URL by setting https as the protocol. The
+ port number will also be set to the HTTPS port of the Axis2 server.
+
+
+ The condition evaluation feature is provided by the Synapse evaluator framework. Currently
+ one can evaluate expressions on URL values, query parameters, transport headers, properties
+ and SOAP envelope content using this framework. Hence URL rewriting can be done based on
+ any of these aspects.
+
+ Objective: Demonstrate the ability of the URL rewrite mediator to perform rewrites based on multiple rules.
+
+
+ Prerequisites: Deploy the SimpleStockQuoteService in sample Axis2 server
+ and start it on port 9000.
+
+
+ Start ESB with the sample configuration 452 (i.e. wso2esb-samples -sn 452).
+
+
+ Invoke the Axis2 client as follows.
+
+
ant stockquote -Dtrpurl=http://localhost:8280 -Daddurl=http://test.com/SimpleStockQuoteService
+
+ The provided address URL does not contain a port number and the context. The URL rewrite
+ mediator will replace the hostname to be 'localhost' and add the context '/services' to the
+ path. Then it will add the appropriate port number to the URL by looking at the protocol
+ prefix. Ultimately the service request will be routed the sample Axis2 server and the
+ client will receive a valid response. Note that the Synapse configuration does not specify
+ any endpoints explicitly. So the messages are sent to the rewritten To header.
+
+
+ Another important aspect shown by this sample is the ability of the URL rewrite mediator to
+ obtain the necessary values by executing XPath expressions. The port numbers are calculated
+ by executing an XPath on the messages.
+
+ WSO2 ESB can be used as an event broker. It comes with a built-in eventing implementation and
+ a lightweight event broker based on Apache Qpid. You can use the ESB management console to
+ create event topics and clients can subscribe to those topics by sending WS-Eventing
+ subscription requests. The management console also allows creating static subscription.
+
+
+ WSO2 ESB is also equipped with an event mediator which can be used to publish messages to
+ predefined topics. With this mediator it is possible for a sequence or a proxy service to
+ directly publish a received request or a response to a topic as an event.
+
+ Objective: Demonstrate the usage of the event mediator to publish messages to event topics
+
+
+ Prerequisites: Deploy the SimpleStockQuoteService in sample Axis2 server
+ and start it on port 9000.
+
+
+ Start ESB with the sample configuration 460 (i.e. wso2esb-samples -sn 460).
+
+
+ Now sign in to the ESB management console can select 'Topics > Add' option from the 'Manage'
+ menu. Enter the name 'stockquote' for the topic and click 'Add Topic'. This will create an
+ event topic named 'stockquote' and you will be directed to the 'Topic Browser' tree view. The
+ newly created topic will be shown on the tree. Click on this topic and select the 'Subscribe'
+ option to create a static subscription. Enter the value 'http://localhost:9000/services/SimpleStockQuoteService'
+ in the 'Event Sink URL' field and click 'Subscribe'.
+
+
+ Now run the sample client as follows to send a request to the main sequence.
+
+
ant stockquote -Dtrpurl=http://localhost:8280 -Dmode=placeorder
+
+ The request will be published to the 'stockquote' topic by the event mediator and as a result
+ the subscriber (Axis2 server in this case) will receive a copy of the message. You will see a
+ log entry in the Axis2 server console indicating the receipt of the place order request.
+
+
+ Note that the provided ESB configuration does not explicitly specify the endpoint of the Axis2
+ server. Also we don't set the actual EPR of the service on the request when sending the message
+ from the client either. Therefore the only reason that Axis2 receives the message is because
+ it is subscribed to the 'stockquote' event topic.
+
<definitions xmlns="http://ws.apache.org/ns/synapse"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://ws.apache.org/ns/synapse http://synapse.apache.org/ns/2010/04/configuration/synapse_config.xsd">
+
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <sequence name="main">
+ <!--Setting the Spring Mediator and its Spring Beans xml file location -->
+ <!--Note that springtest is the bean id used in springCustomLogger.xml -->
+ <spring bean="springtest" key="spring/springCustomLogger.xml"/>
+ <send/>
+ </sequence>
+
+</definitions>
Objective: MTOM and SwA optimizations and request/response
+correlation
+
+
Prerequisites:
+Start the Synapse configuration numbered 51: i.e. wso2esb-samples -sn 51
+Start the Axis2 server and deploy the MTOMSwASampleService if not already
+done
+
+
Execute the 'ant optimizeclient' specifying MTOM optimization as follows:
+
+
ant optimizeclient -Dopt_mode=mtom
+
+
The configuration now sets a local message context property, and forwards
+the message to 'http://localhost:9000/services/MTOMSwASampleService' optimizing
+binary content as MTOM. By sending this message through TCPMon you would be
+able to see the actual message sent over the http transport if required. Thus
+during response processing, by checking the local message property ESB could
+identify the past information about the current message context, and uses
+this knowledge to transform the response back to the client in the same
+format as the original request.
+
+
When the client executes successfully, it will upload a file containing
+the ASF logo and receive its response back again and save it into a temporary
+file.
+
[java] Sending file : ./../../repository/samples/resources/mtom/asf-logo.gif as MTOM
+
[java] Saved response to file : ./../../work/temp/sampleClient/mtom-49258.gif
+
+
Next try SwA as:
+
ant optimizeclient -Dopt_mode=swa
+
[java] Sending file : ./../../repository/samples/resources/mtom/asf-logo.gif as SwA
+[java] Saved response to file : ./../../work/temp/sampleClient/swa-47549.gif
+
+
By using TCPMon and sending the message through it, one can inspect that
+the requests and responses sent are indeed MTOM optimized or sent as http
+attachments as follows:
Objective: Demonstrate the simple load balancing among a set of
+endpoints
+
+
Prerequisites:
+
+
Start ESB with sample configuration 52. (i.e. wso2esb-samples -sn 52)
+
+
Deploy the LoadbalanceFailoverService by switching to <ESB installation
+directory>/samples/axis2Server/src/LoadbalanceFailoverService directory
+and running ant.
+
+
Start three instances of sample Axis2 server on HTTP ports 9001, 9002 and
+9003 and give some unique names to each server.
+
+
Example commands to run sample Axis2 servers from the <ESB installation
+directory>/samples/axis2Server directory in Linux are listed below:
Now we are done with setting up the environment for load balance sample.
+Start the load balance and failover client using the following command:
+
ant loadbalancefailover -Di=100
+
+
This client sends 100 requests to the LoadbalanceFailoverService through
+ESB. ESB will distribute the load among the three endpoints mentioned in the
+configuration in round-robin manner. LoadbalanceFailoverService appends the
+name of the server to the response, so that client can determine which server
+has processed the message. If you examine the console output of the client,
+you can see that requests are processed by three servers as follows:
+
[java] Request: 1 ==> Response from server: MyServer1
+[java] Request: 2 ==> Response from server: MyServer2
+[java] Request: 3 ==> Response from server: MyServer3
+[java] Request: 4 ==> Response from server: MyServer1
+[java] Request: 5 ==> Response from server: MyServer2
+[java] Request: 6 ==> Response from server: MyServer3
+[java] Request: 7 ==> Response from server: MyServer1
+...
+
+
Now run the client without the -Di=100 parameter to send infinite
+requests. While running the client shutdown the server named MyServer1. You
+can observe that requests are only distributed among MyServer2 and MyServer3
+after shutting down MyServer1. Console output before and after shutting down
+MyServer1 is listed below (MyServer1 was shutdown after request 63):
+
...
+[java] Request: 61 ==> Response from server: MyServer1
+[java] Request: 62 ==> Response from server: MyServer2
+[java] Request: 63 ==> Response from server: MyServer3
+[java] Request: 64 ==> Response from server: MyServer2
+[java] Request: 65 ==> Response from server: MyServer3
+[java] Request: 66 ==> Response from server: MyServer2
+[java] Request: 67 ==> Response from server: MyServer3
+...
+
+
Now restart MyServer1. You can observe that requests will be again sent to
+all three servers roughly after 60 seconds. This is because we have specified
+<suspendDurationOnFailure> as 60 seconds in the configuration.
+Therefore, load balance endpoint will suspend any failed child endpoint only
+for 60 seconds after detecting the failure.
Start ESB with sample configuration 53 (i.e. wso2esb-samples -sn 53)
+
+
Deploy the LoadbalanceFailoverService and start three instances of sample
+Axis2 server as mentioned in sample 52.
+
+
Above configuration sends messages with the failover behavior. Initially
+the server at port 9001 is treated as primary and other two are treated as
+back ups. Messages are always directed only to the primary server. If the
+primary server has failed, next listed server is selected as the primary.
+Thus, messages are sent successfully as long as there is at least one active
+server. To test this, run the loadbalancefailover client to send infinite
+requests as follows:
+
ant loadbalancefailover
+
+
You can see that all requests are processed by MyServer1. Now shutdown
+MyServer1 and inspect the console output of the client. You will observe that
+all subsequent requests are processed by MyServer2.
+
+
The console output with MyServer1 shutdown after request 127 is listed
+below:
+
...
+[java] Request: 125 ==> Response from server: MyServer1
+[java] Request: 126 ==> Response from server: MyServer1
+[java] Request: 127 ==> Response from server: MyServer1
+[java] Request: 128 ==> Response from server: MyServer2
+[java] Request: 129 ==> Response from server: MyServer2
+[java] Request: 130 ==> Response from server: MyServer2
+...
+
+
You can keep on shutting down servers like this. Client will get a
+response till you shutdown all listed servers. Once all servers are shutdown,
+the error sequence is activated and a fault message is sent to the client as
+follows.
+
[java] COULDN'T SEND THE MESSAGE TO THE SERVER.
+
+
Once a server is detected as failed, it will be added to the active
+servers list again after 60 seconds (specified in
+<suspendDurationOnFailure> in the configuration). Therefore, if you
+have restarted any of the stopped servers and have shutdown all other
+servers, messages will be directed to the newly started server.
<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main" onError="errorHandler">
+ <in>
+ <send>
+ <endpoint>
+ <!-- specify the session as the simple client session provided by Synapse for
+ testing purpose -->
+ <session type="simpleClientSession"/>
+
+ <loadbalance>
+ <endpoint>
+ <address uri="http://localhost:9001/services/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9002/services/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9003/services/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </loadbalance>
+ </endpoint>
+ </send><drop/>
+ </in>
+
+ <out>
+ <!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
+ <send/>
+ </out>
+ </sequence>
+
+ <sequence name="errorHandler">
+
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
+ </makefault>
+
+ <header name="To" action="remove"/>
+ <property name="RESPONSE" value="true"/>
+
+ <send/>
+ </sequence>
+
+</definitions>
+
+
Objective: Demonstrate the load balancing with session affinity
+using client initiated sessions
+
+
Prerequisites:
+
+
Start ESB with sample configuration 54 (i.e. wso2esb-samples -sn 54).
+
+
Deploy the LoadbalanceFailoverService and start three instances of the
+sample Axis2 server as in sample 52.
+
+
Above configuration is same as the load balancing configuration in sample
+52, except that the session type is specified as "simpleClientSession". This
+is a client initiated session, which means that the client generates the
+session identifier and sends it to with each request. In this sample session
+type, client adds a SOAP header named ClientID containing the identifier of
+the client. ESB binds this ID with a server on the first request and sends
+all seccessive requests containing that ID to the same server. Now switch to
+samples/axis2Client directory and run the client using the following command
+to check this in action.
+
ant loadbalancefailover -Dmode=session
+
+
In the session mode, client continuously sends requests with three diferent
+client (session) IDs. One ID is selected among these three IDs for each
+request randomly. Then client prints the session ID with the responded server
+for each request. Client output for the first 10 requests are shown below.
+
You can see that session number 0 is always directed to the server named
+MyServer1. That means session number 0 is bound to MyServer1. Similarly
+session 1 and 2 are bound to MyServer3 and MyServer2 respectively.
Objective: Demonstrate the session affinity based load balancing
+with failover capability
+
+
Prerequisites:
+
+
Start ESB with sample configuration 55 (i.e. wso2esb-samples -sn 55).
+
+
Deploy the LoadbalanceFailoverService and start four sample Axis2 servers
+on http ports 9001, 9002, 9003 and 9004 respectively (make sure to specify
+unconflicting https ports).
+
+
This configuration also uses "simpleClientSession" to bind sessions as in
+the previous sample. But failover endpoints are specified as the child
+endpoints of the load balance endpoint. Therefore sessions are bound to the
+failover endpoints. Session information has to be replicated among the
+servers listed under each failover endpoint using some clustering mechanism.
+Therefore, if one endpoint bound to a session failed, successive requests for
+that session will be directed to the next endpoint in that failover group.
+Run the client using the following command to observe this behaviour.
Note that session 0 is always directed to MyServer1 and session 1 is
+directed to MyServer3. No requests are directed to MyServer2 and MyServer4 as
+they are kept as backups by failover endpoints. Now shutdown the server named
+MyServer1 while running the sample. You will observe that all successive
+requests for session 0 is now directed to MyServer2, which is the backup
+server for MyServer1's group. This is shown below, where MyServer1 was
+shutdown after the request 534.
Deploy the SimpleStockQuoteService and start the sample Axis2 server.
+
+
This sample uses a WSDL endpoint inside the send mediator. WSDL endpoints
+can extract endpoint's address from the given WSDL. As WSDL documents can
+have many services and many ports inside each service, the service and port
+of the required endpoint has to be specified. As with address endpoints, QoS
+parameters for the endpoint can be specified inline in the configuration. An
+excerpt taken from the sample_proxy_1.wsdl containing the specified service
+and port is listed below.
Specified service and port refers to the endpoint address
+"http://localhost:9000/services/SimpleStockQuoteService" according to the above
+WSDL. Now run the client using the following command.
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
+
+
Client will print the quote price for IBM received from the server running
+on port 9000. Observe the Axis2 console and the ESB console to verify this
+behavior.
+Objective: Demonstrate the simple dynamic load balancing among a set of nodes
+
+Prerequisites:
+
+ Enable clustering and group management in the <ESB installation directory>/ repository/conf/axis2.xml
+ file. This can be done by setting the "enable" attribute of the "cluster" and
+ "groupManagement" elements. Also provide the IP address of you machine as the values of the
+ "mcastBindAddress" and "localMemberHost" parameters.
+
+
Start ESB with sample configuration 57. (i.e. wso2esb-samples -sn 57)
+
+ Deploy the LoadbalanceFailoverService by switching to <Synapse installation directory>/samples/axis2Server/src/LoadbalanceFailoverService
+ directory and running ant.
+
+
+ Enable clustering in the <Synapse installation directory>/samples/axis2Server/ repository/conf/axis2.xml
+ file. This can be done by setting the "enable" attribute of the "cluster"
+ element. Also provide the IP address of you machine as the values of the "mcastBindAddress"
+ and "localMemberHost" parameters. Make sure that the "applicationDomain" of the membershipHandler is
+ the same as the domain name specified in the axis2.xml files of the Axis2 servers. Then Start three
+ instances of sample Axis2 server on HTTP ports 9001, 9002 and 9003 and give some unique names to each
+ server.
+
+
Example commands to run sample Axis2 servers from the <Synapse installation directory>/samples/axis2Server directory in Linux are listed below:
Now we are done with setting up the environment for load balance sample. Start the load balance and failover client using the following command:
+
ant loadbalancefailover -Di=100
+
This client sends 100 requests to the LoadbalanceFailoverService through Synapse. Synapse will distribute the load among the three nodes mentioned in the configuration in a round-robin manner. LoadbalanceFailoverService appends the name of the server to the response, so that client can determine which server has processed the message. If you examine the console output of the client, you can see that requests are processed by three servers as follows:
+
[java] Request: 1 ==> Response from server: MyServer1
+[java] Request: 2 ==> Response from server: MyServer2
+[java] Request: 3 ==> Response from server: MyServer3
+[java] Request: 4 ==> Response from server: MyServer1
+[java] Request: 5 ==> Response from server: MyServer2
+[java] Request: 6 ==> Response from server: MyServer3
+[java] Request: 7 ==> Response from server: MyServer1
+...
+
Now run the client without the -Di=100 parameter, i.e. ant loadbalancefailover, to send infinite requests. While running the client shutdown the server named MyServer1. You can observe that requests are only distributed among MyServer2 and MyServer3 after shutting down MyServer1. Console output before and after shutting down MyServer1 is listed below (MyServer1 was shutdown after request 63):
+
...
+[java] Request: 61 ==> Response from server: MyServer1
+[java] Request: 62 ==> Response from server: MyServer2
+[java] Request: 63 ==> Response from server: MyServer3
+[java] Request: 64 ==> Response from server: MyServer2
+[java] Request: 65 ==> Response from server: MyServer3
+[java] Request: 66 ==> Response from server: MyServer2
+[java] Request: 67 ==> Response from server: MyServer3
+...
+
Now restart MyServer1. You can observe that requests will be again sent to all three servers.
+Objective: Demonstrate the simple static load balancing among a set of nodes
+
+Prerequisites:
+
Start Synapse with sample configuration 58. (i.e. wso2esb-samples -sn 58)
+
Deploy the LoadbalanceFailoverService by switching to <Synapse installation directory>/samples/axis2Server/src/LoadbalanceFailoverService directory and running ant.
+
Start three instances of sample Axis2 server on HTTP ports 9001, 9002 and 9003 and give some unique names to each server.
+
Example commands to run sample Axis2 servers from the <Synapse installation directory>/samples/axis2Server directory in Linux are listed below:
Now we are done with setting up the environment for load balance sample. Start the load balance and failover client using the following command:
+
ant loadbalancefailover -Di=100
+
This client sends 100 requests to the LoadbalanceFailoverService through Synapse. Synapse will distribute the load among the three nodes mentioned in the configuration in a round-robin manner. LoadbalanceFailoverService appends the name of the server to the response, so that client can determine which server has processed the message. If you examine the console output of the client, you can see that requests are processed by three servers as follows:
+
[java] Request: 1 ==> Response from server: MyServer1
+[java] Request: 2 ==> Response from server: MyServer2
+[java] Request: 3 ==> Response from server: MyServer3
+[java] Request: 4 ==> Response from server: MyServer1
+[java] Request: 5 ==> Response from server: MyServer2
+[java] Request: 6 ==> Response from server: MyServer3
+[java] Request: 7 ==> Response from server: MyServer1
+...
+
Now run the client without the -Di=100 parameter, i.e. ant loadbalancefailover, to send infinite requests. While running the client shutdown the server named MyServer1. You can observe that requests are only distributed among MyServer2 and MyServer3 after shutting down MyServer1. Console output before and after shutting down MyServer1 is listed below (MyServer1 was shutdown after request 63):
+
...
+[java] Request: 61 ==> Response from server: MyServer1
+[java] Request: 62 ==> Response from server: MyServer2
+[java] Request: 63 ==> Response from server: MyServer3
+[java] Request: 64 ==> Response from server: MyServer2
+[java] Request: 65 ==> Response from server: MyServer3
+[java] Request: 66 ==> Response from server: MyServer2
+[java] Request: 67 ==> Response from server: MyServer3
+...
+
Now restart MyServer1. You can observe that requests will be again sent to all three servers.
Objective: Demonstrate the weighted load balancing among a set of
+endpoints
+
+
Prerequisites:
+
+
Start ESB with sample configuration 59. (i.e. wso2esb-samples -sn 59)
+
+
Deploy the LoadbalanceFailoverService and start three instances of sample Axis2 server as mentioned in sample 52.
+
+
Above configuration sends messages with the weighted loadbalance behaviour. Weight of each leaf
+address endpoint is defined by integer value of "loadbalance.weight" property associated with each endpoint.
+If weight of a endpoint is x, x number of requests will send to that endpoint before switch to next active endpoint.
+ To test this, run the loadbalancefailover client to send 100 requests as follows:
+
ant loadbalancefailover -Di=100
+
+
This client sends 100 requests to the LoadbalanceFailoverService through
+ESB. ESB will distribute the load among the three endpoints mentioned in the
+configuration in weighted round-robin manner. LoadbalanceFailoverService appends the
+name of the server to the response, so that client can determine which server
+has processed the message. If you examine the console output of the client,
+you can see that requests are processed by three servers as follows:
+
[java] Request: 1 ==> Response from server: MyServer1
+[java] Request: 2 ==> Response from server: MyServer2
+[java] Request: 3 ==> Response from server: MyServer2
+[java] Request: 4 ==> Response from server: MyServer3
+[java] Request: 5 ==> Response from server: MyServer3
+[java] Request: 6 ==> Response from server: MyServer3
+[java] Request: 7 ==> Response from server: MyServer1
+[java] Request: 8 ==> Response from server: MyServer2
+[java] Request: 9 ==> Response from server: MyServer2
+[java] Request: 10 ==> Response from server: MyServer3
+[java] Request: 11 ==> Response from server: MyServer3
+[java] Request: 12 ==> Response from server: MyServer3
+...
+
+
As logs, endpoint with weight 1 received a 1 request and endpoint with weight 2 received 2
+requests and etc... in a cycle
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- log all attributes of messages passing through -->
+ <log level="full"/>
+
+ <!-- Send the messageto implicit destination -->
+ <send/>
+</definitions>
+
+
Objective: Introduction to ESB. Shows how a message could be made
+to pass through ESB and logged before it is delivered to its
+ultimate receiver.
+
+
The Stock quote client can operate in the following modes for this example.
+
+
Smart Client mode
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
+
Using ESB as a HTTP Proxy
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dprxurl=http://localhost:8280/
+
+
Gateway Mode / Dumb Client
+
+
See sample # 1
+
+
Prerequisites:
+ Start the Synapse configuration numbered 0: e.g. wso2esb-samples -sn 0
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
Execute the Smart Client
+
+
By tracing the execution of ESB with the log output level set to DEBUG,
+you will see the client request arriving at ESB with a WS-Addressing 'To' set
+to EPR http://localhost:9000/services/SimpleStockQuoteService. The ESB engine
+logs the message at the "full" log level (i.e. all the message headers and
+the body) then sends the message to its implicit 'To' address which is
+http://localhost:9000/services/SimpleStockQuoteService. You will see a message in
+the Axis2 server console confirming that the message got routed to the sample
+server and the sample service hosted at the sample server generating a stock
+quote for the requested symbol.
+
Sat Nov 18 21:01:23 IST 2006 SimpleStockQuoteService :: Generating quote for : IBM
+
+
The response message generated by the service is again received by ESB,
+and flows through the same mediation rules, which logs the response message
+and then sends it back. This time to the client. On the client console you
+should see an output similar to the following based on the message received
+by the client.
+
Standard :: Stock price = $95.26454380258552
+
+
Execute the Proxy Client
+
+
You will see the exact same behaviour as per the previous example when you
+run this scenario. However this time the difference is at the client, as it
+sends the message to the WS-Addressing 'To' address
+http://localhost:9000/services/SimpleStockQuoteService, but the transport
+specifies ESB as the http proxy.
Objective: Introduction to simple content based routing. Shows how
+a message could be made to pass through ESB using the Dumb Client mode, where
+ESB acts as a gateway to accept all messages and then perform mediation and
+routing based on message properties or content.
+
+
Prerequisites:
+Start the Synapse configuration numbered 1: i.e. wso2esb-samples -sn 1
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
+
Execute the Dumb Client as:
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuote
+
+
This time you will see ESB receiving a message for which ESB was set as
+the ultimate receiver of the message. Based on the 'To' EPR of
+http://localhost:8280/services/StockQuote, ESB performs a match to the path
+'/StockQuote' and as the request matches the XPath expression of the filter
+mediator, the filter mediator's child mediators execute. This sends the
+message to a different endpoint as specified by the endpoint definition. The
+'drop' mediator terminates further processing of the current message in a
+configuration. During response processing, the filter condition fails, and
+thus the implicit 'send' mediator forwards the response back to the client.
+
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples">
+ <case regex="IBM">
+ <!-- the property mediator sets a local property on the *current* message -->
+ <property name="symbol" value="Great stock - IBM"/>
+ </case>
+ <case regex="MSFT">
+ <property name="symbol" value="Are you sure? - MSFT"/>
+ </case>
+ <default>
+ <!-- it is possible to assign the result of an XPath expression as well -->
+ <property name="symbol"
+ expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"
+ xmlns:m0="http://services.samples"/>
+ </default>
+ </switch>
+
+ <log level="custom">
+ <!-- the get-property() XPath extension function allows the lookup of local message properties
+ as well as properties from the Axis2 or Transport contexts (i.e. transport headers) -->
+ <property name="symbol" expression="get-property('symbol')"/>
+ <!-- the get-property() function supports the implicit message headers To/From/Action/FaultTo/ReplyTo -->
+ <property name="epr" expression="get-property('To')"/>
+ </log>
+
+ <!-- Send the messages where they are destined to (i.e. the 'To' EPR of the message) -->
+ <send/>
+</definitions>
+
+
Objective: Introduce switch-case mediator and writing and reading
+of local properties set on a message instance
+
+
Prerequisites:
+Start the Synapse configuration numbered 2: i.e. wso2esb-samples -sn 2
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done.
+
+
Execute the 'ant stockquote ..' request again in the smart client mode,
+specifying 'IBM', 'MSFT' and 'SUN' as the stock symbols. When the symbol IBM
+is requested, viewing the mediation logs you will see that the case
+statements' first case for 'IBM' is executed and a local property named
+'symbol' was set to 'Great stock - IBM'. Subsequently this local property
+value is looked up by the log mediator and logged using the 'get-property()'
+XPath extension function.
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService
+-Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
INFO LogMediator - symbol = Great stock - IBM, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService
+-Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
INFO LogMediator - symbol = Are you sure? - MSFT, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService
<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- define a string resource entry to the local registry -->
+ <localEntry key="version">0.1</localEntry>
+ <!-- define a reuseable endpoint definition -->
+ <endpoint name="simple">
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+
+ <!-- define a reusable sequence -->
+ <sequence name="stockquote">
+ <!-- log the message using the custom log level. illustrates custom properties for log -->
+ <log level="custom">
+ <property name="Text" value="Sending quote request"/>
+ <property name="version" expression="get-property('version')"/>
+ <property name="direction" expression="get-property('direction')"/>
+ </log>
+ <!-- send message to real endpoint referenced by key "simple" endpoint definition -->
+ <send>
+ <endpoint key="simple"/>
+ </send>
+ </sequence>
+
+ <sequence name="main">
+ <in>
+ <property name="direction" value="incoming"/>
+ <sequence key="stockquote"/>
+ </in>
+ <out>
+ <send/>
+ </out>
+ </sequence>
+</definitions>
+
+
Objective: Illustrates local registry entry definitions, reusable
+endpoints and sequences
+
+
Prerequisites:
+Start the Synapse configuration numbered 3: i.e. wso2esb-samples -sn 3
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This example uses a sequence named as "main" that specifies the main
+mediation rules to be executed. This is equivalent to directly specifying the
+mediators of the main sequence within the <definitions> tags. This is
+the recommended and also a better approach for non-trivial configurations.
+Execute the 'ant stockquote ..' request again, and following through the
+mediation logs you will now notice that the sequence named "main" is
+executed. Then for the incoming message flow the <in> mediator
+executes, and it calls the sequence named "stockquote".
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
As the "stockquote" sequence executes, the log mediator dumps a simple
+text/string property, result of an XPath evaluation, that picks up the key
+named "version", and a second result of an XPath evaluation that picks up a
+local message property set previously by the <property> mediator. The
+get-property() XPath extension function is able to read message properties
+local to the current message, local or remote registry entries, Axis2 message
+context properties as well as transport headers. The local entry definition
+for "version" defines a simple text/string registry entry for that which is
+visible to all messages that pass through ESB.
+
[HttpServerWorker-1] INFO LogMediator - Text = Sending quote request, version = 0.1, direction = incoming
+[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] DEBUG AddressEndpoint - Sending To: http://localhost:9000/services/SimpleStockQuoteService
Objective: Introduction to error handling with the 'fault'
+sequence
+
+
Prerequisites:
+Start the Synapse configuration numbered 4: i.e. wso2esb-samples -sn 4
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
When the IBM stock quote is requested, the configuration routes it to the
+defined inline endpoint, which routes the message to the
+SimpleStockQuoteService on the local Axis2 instance. Hence a valid response
+message is shown at the client.
+
+
If you lookup a stock quote for 'MSFT', ESB is instructed to route the
+message to the endpoint defined as the 'bogus' endpoint, which does not
+exist. ESB executes the specified error handler sequence closest to the point
+where the error was encountered. In this case, the currently executing
+sequence is 'main' and it does not specify an 'onError' attribute. Whenever
+ESB cannot find an error handler, it looks for a sequence named 'fault'. Thus
+the 'fault' sequence can be seen executing, and writing the generic error
+message to the logs.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : bogus
+[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <fault> :: mediate()
+[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured, message = Reference to non-existent endpoint for key : bogus
+
+
When the 'SUN' quote is requested, a custom sequence 'sunSequence' is
+invoked, and it specifies 'sunErrorHandler' as its error handler. Hence when
+the send fails, you could see the proper error handler invocation and the
+custom error message printed as follows.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunSequence> :: mediate()
+[HttpServerWorker-1] DEBUG SequenceMediator - Setting the onError handler for the sequence
+[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
+[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : sunPort
+[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunErrorHandler> :: mediate()
+[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
+[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured for stock SUN, message = Reference to non-existent endpoint for key : sunPort
Objective: Makefault mediator and sending back error responses
+
+
+
Prerequisites:
+Start the Synapse configuration numbered 5: i.e. wso2esb-samples -sn 5
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
When the MSFT stock quote is requested, an unknown host exception would be
+generated. A connection refused exception would be generated for the SUN
+stock request. This error message is captured and returned to the original
+client as a SOAP fault in this example.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
+
returns,
+
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+ <faultstring>Connection refused or failed for : bogus:9000 </faultstring><detail /></soapenv:Fault>
+
+
And
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
+
returns,
+
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+ <faultstring> Connection refused or failed for : localhost/127.0.0.1:9009</faultstring><detail /></soapenv:Fault>
Objective: Introduction to header, in (out) mediators
+
+
Prerequisites:
+Start the Synapse configuration numbered 6: i.e. wso2esb-samples -sn 6
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
In this example we use the stockquote client in the dumb client mode,
+setting the 'To' EPR of the message to ESB. Then the 'in' mediator processes
+the incoming messages, and manipulates the 'To' header to refer to the stock
+quote service on the sample Axis2 server. Thus it is now possible to request
+for a stock quote as follows.
Objective: Introduction to local (static) registry entries and the
+validate mediator
+
+
Prerequisites:
+Start the Synapse configuration numbered 7: i.e. wso2esb-samples -sn 7
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This example shows how a static XML fragment could be made available to
+the ESB local registry. Resources defined in the local registry are static
+(i.e. never changes over the lifetime of the configuration) and may be
+specified as a source URL, inline text or inline xml. In this example the
+schema is made available under the key 'validate_schema'.
+
+
The validate mediator by default operates on the first child element of
+the SOAP body. You may specify an XPath expression using the 'source'
+attribute to override this behaviour. The validate mediator now uses the
+'validate_schema' resource to validate the incoming message, and if the
+message validatation fails it invokes the 'on-fail' sequence of mediators.
+
+
+
If you send a stockquote request using 'ant stockquote ...' you will get a
+fault back with the message 'Invalid custom quote request' as the schema
+validation failed. This is because the schema used in the example expects a
+slightly different message than what is created by the stock quote client.
+(i.e. expects a 'stocksymbol' element instead of 'symbol' to specify the stock
+symbol)
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:./repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <!-- define the request processing XSLT resource as a static URL source -->
+ <localEntry key="xslt-key-req" src="file:repository/samples/resources/transform/transform.xslt"/>
+
+ <in>
+ <!-- transform the custom quote request into a standard quote requst expected by the service -->
+ <xslt key="xslt-key-req"/>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <!-- the key is looked up in the remote registry and loaded as a 'dynamic' registry resource -->
+ <xslt key="transform/transform_back.xslt"/>
+ </out>
+ <send/>
+</definitions>
+
+
Objective: Introduction to static and dynamic registry resources
+and the XSLT mediator
+
+
Prerequisites:
+Start the Synapse configuration numbered 8: i.e. wso2esb-samples -sn 8
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
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 preference and override
+the remote resource.
+
+
In this example you will notice the new 'registry' definition. ESB 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 for the resource being looked up. The registry
+caches a resource once requested, and caches it internally for a specified
+duration. Once this period expires, it will reload the meta information about
+the resource and reload its cached copy if necessary, the next time the
+resource is requested.
+
+
Hence the second XSLT resource key 'transform/transform_back.xslt'
+concatenated with the 'root' of the SimpleURLRegistry
+'file:repository/samples/resources/' forms the complete URL of the
+resource as
+'file:repository/samples/resources/transform/transform_back.xslt' and
+caches its value for a period of 15000 ms.
+
+
Execute the custom quote client as 'ant stockquote -Dmode=customquote ...'
+and analyze the the ESB debug log output
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote
+
+
The incoming message is now transformed into a standard stock quote
+request as expected by the SimpleStockQuoteService deployed on the local
+Axis2 instance, 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 where necessary. The response from the
+SimpleStockQuoteService is converted back into the custom format as expected
+by the client during the out message processing.
+
+
During the response processing the SimpleURLRegistry fetches the resource.
+
+
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.
+
+
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 noticed the cached
+resource has expired and will check the meta information about the resource
+to check if the resource itself 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.
+
[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
+
+
Now edit the
+repository/samples/resources/transform/transform_back.xslt file and add a
+blank line at the end. Now when you run the client again, and if the cache is
+expired, the resource would be re-fetched from its URL by the registry and
+this can be seen by the following debug log messages
+
[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
+
+
Thus the SimpleURLRegistry allows resource to be cached, and updates
+detected so that the changes could be reloaded without restarting the ESB
+instance.
Objective: Introduction to dynamic sequences with a
+Registry
+
+
Prerequisites:
+Start the Synapse configuration numbered 9: i.e. wso2esb-samples -sn 9
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This example introduces the dynamic behaviour of ESB through the use of a
+Registry. ESB supports dynamic definitions for sequences and endpoints, and
+as seen before, for resources. In this example we define a Synapse
+configuration which references a sequence definition specified as a registry
+key. The registry key resolves to the actual content of the sequence which
+would be loaded dynamically by ESB at runtime, and cached appropriately as
+per its definition in the registry. Once the cache expires, ESB would recheck
+the meta information for the definition and re-load the sequence definition
+if necessary and re-cache it again.
+
+
Once ESB is started, execute the stock quote client as 'ant stockquote..'.
+You will notice that that ESB fetches the definition of the sequence from the
+registry and executes its rules as follows:
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
Now if you execute the client immediately (i.e. within 15 seconds of the
+last execution) you will notice that the sequence was not reloaded. If you
+edit the sequence definition in
+repository/samples/resources/sequence/dynamic_seq_1.xml (i.e. edit the
+log message to read as "*** Test Message 2 ***") and execute the client
+again, you will notice that the new message is not yet visible (i.e. if you
+execute this within 15 seconds of loading the resource for the first time)
+However, after 15 seconds elapsed since the original caching of the sequence,
+you will notice that the new sequence is loaded and executed by ESB from the
+following log messages.
Objective: Introduction to dynamic endpoints with the
+Registry
+
+
Prerequisites:
+Start the Synapse configuration numbered 10: i.e. wso2esb-samples -sn 10
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+Start a second Axis2 server on http port 9001 and https port 9003 as follows:
+
+
./axis2server.sh -http 9001 -https 9003
+
+
This example introduces dynamic endpoints, where the definition of an
+endpoint is stored in the Registry. To follow this example execute the stock
+quote client as 'ant stockquote..' and see that the message is routed to the
+SimpleStockQuoteService on the default Axis2 instance on http port 9000.
+Repeat the above example immediately again, and notice that the endpoint is
+cached and reused by ESB - similarly to example # 8.
+
ant stockquote -Dtrpurl=http://localhost:8280/
+
+
Now edit the repository/samples/resources/endpoint/dynamic_endpt_1.xml
+definition and update the address to
+"http://localhost:9001/services/SimpleStockQuoteService". After the cached
+expires, the Registry loads the new definition of the endpoint, and then the
+messages can be seen being routed to the second sample Axis2 server on http
+port 9001.
Prerequisites:
+Start the Synapse configuration numbered 11: i.e. wso2esb-samples -sn 11
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This example shows a full registry based ESB configuration. Thus it is
+possible to start a remote configuration from multiple instances of ESB in a
+clustered environment easily. The Synapse configuration held on a node
+hosting ESB simply points to the registry and looks up the actual
+configuration by requesting the key 'synapse.xml'.
+
+
(Note: Full registry based configuration is not dynamic atleast for the
+moment. i.e. it is not reloading itself)
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
[HttpServerWorker-1] INFO LogMediator - message = This is a dynamic Synapse configuration
+
+
The actual synapse.xml loaded is:
+
<!-- a registry based Synapse configuration -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <log level="custom">
+ <property name="message" value="This is a dynamic Synapse configuration $$$"/>
+ </log>
+ <send/>
+</definitions>
Objective: Demonstrate one way messaging / fireAndForget through
+ESB
+
+
Prerequisites:
+Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps
+above)
+Start the Synapse configuration numbered 0: i.e. wso2esb-samples -sn 0
+
+
This example invokes the one-way 'placeOrder' operation on the
+SimpleStockQuoteService using the custom client which uses the Axis2
+ServiceClient.fireAndForget() API. To test this, use 'ant
+-Dmode=placeorder...' and you will notice the one way message flowing through
+ESB into the sample Axis2 server instance, which reports the acceptance of
+the order as follows:
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=placeorder
+
SimpleStockQuoteService :: Accepted order for : 7482 stocks of IBM at $ 169.27205579038733
+
+
If you send your client request through TCPmon, you will notice that the
+SimpleStockQuoteService replies to ESB with a HTTP 202 reply, and that ESB
+in-turn replies to the client with a HTTP 202 acknowledgement
Prerequisites: Start the Axis2 server
+and deploy the SimpleStockQuoteService (Refer steps above) Start
+the Synapse configuration numbered 0: i.e. wso2esb-samples.sh -sn 0
+
+
+This example invokes the same 'getQuote' operation on the
+SimpleStockQuoteService using the custom client which uses the Axis2
+ServiceClient API with useSeparateListener set to true so that the response is
+coming through a different channel than the one which is used to send the request
+to a callback defined in the client.
+To test this, use 'ant
+-Dmode=dualquote...' and you will notice the dual channel invocation
+through Synapse into the sample Axis2 server instance, which reports the response
+back to the client over a different channel:
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=dualquote
+
Response received to the callback
+ Standard dual channel :: Stock price = $57.16686934968289
+
+If you send your client request through TCPmon, you will notice that
+Synapse replies to the client with a HTTP 202 acknowledgment when you send the request and
+the communication between synapse and the server happens on a single channel and then you
+get the response back from synapse to the clients callback in a different channel (which
+cannot be observed through TCPmon)
+
+
+Also you could see the wsa:Reply-To header being something like
+http://localhost:8200/axis2/services/anonService2 which implies that the reply
+is being on a different channel listening on the port 8200. Please note that it is
+required to engage addressing when using the dual channel invocation because it
+requires the wsa:Reply-To header.
+
+Objective: Sequence and Endpoints as local registry entries
+
+
Prerequisites: Start the Axis2 server
+and deploy the SimpleStockQuoteService (Refer steps above) Start
+the Synapse configuration numbered 14: i.e. wso2esb-samples.sh -sn 14
+
+
+This example shows sequences and endpoints fetched from local registry.
+Thus it is possible to have endpoints sequences as local registry entries including file entries.
+Execute the following command to see the sample working, where you will be able to see the
+log statement from the fetched sequence from the local entry and the endpoint will be fetched from
+the specified file at runtime and be cached in the system
+Objective: Introduction to Message Copying and Content Enriching with Enrich Mediator
+
+Prerequisites:
+ Start the Synapse configuration numbered 15: i.e. synapse -sample 15
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already done
+
+
./axis2server.sh
+
This sample demonstrate the various capabilities of Enrich Mediator. Inside the in-sequence we store/copy different
+ parts of the message to properties and just before sending the message to the StockQuoteService, we modify the
+ request value based on the local entry value-init_req. Then in the out-sequence, the enrich mediator is used
+ to enrich a soap header based on the 'lastTradeTimestamp' value of the response.
+
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuote
+
You can try with different local entries as the source with the correct target xpath values.
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <sequence name="main">
+ <in>
+ <!-- define the request processing XSLT resource as a property value -->
+ <property name="symbol" value="transform/transform.xslt"/>
+ <!-- {} denotes that this key is a dynamic one and it is not a static key -->
+ <!-- use Xpath expression "get-property()" to evaluate real key from property -->
+ <xslt key="{get-property('symbol')}"/>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <!-- the key is looked up in the remote registry using a static key -->
+ <xslt key="transform/transform_back.xslt"/>
+ </out>
+ <send/>
+ </sequence>
+
+</definitions>
+
+
+Objective: Introduction to dynamic and static keys
+
+Prerequisites:
+ Start the Synapse configuration numbered 16: i.e. synapse -sample 16
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already done
+
+
./axis2server.sh
+
This Sample demonstrates the use of dynamic keys with mediators. XSLT mediator is used as an
+ example for that and deference between static and dynamic usage of keys are shown with that.
+
+
The first registry resource "transform/transform.xslt" is set as a property value. Inside the
+ XSLT mediator the local property value is lookup using the Xpath expression "get-property()".
+ Likewise any Xpath expression can be enclosed inside "{ }" to denote that it is a dynamic key.
+ Then the mediator will evaluate the real value for that expression.
+
+
The second XSLT resource "transform/transform_back.xslt" is used simply as a static key as
+ usual. It is not included inside "{ }" and because of the mediator directly use the static
+ value as the key.
+
+
Execute the custom quote client as 'ant stockquote -Dmode=customquote' and analys the output
+ which is similar to the Sample 8.
+
+
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuote
+
You can try with different local entries as the source with the correct target xpath values.
+ Objective: Demonstrate the ability to construct the Synapse configuration from a file hierarchy
+
+
+ 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.
+
+ Objective: Demonstrate the ability to monitor the Synapse configuration at runtime using the
+ SynapseObserver interface
+
+
+ Open the synapse.properties file in the ESB_HOME/webapps/ROOT/WEB-INF/classes directory using a text editor and add the following
+ line to the synapse.properties file. This entry defines the simple logging Synapse observer.
+
+ Open the log4j.properties file in the ESB_HOME/lib directory and add the followin line which sets the INFO log
+ level to the samples.userguide package.
+
+
log4j.category.samples.userguide=INFO
+
+ Start Synapse using any of the sample configurations. The SimpleLoggingObserver will capture events that occur
+ while constructing the Synapse configuration and log them on the console as follows.
+
+
+ 2009-08-06 14:30:24,578 [-] [main] INFO SimpleLoggingObserver Simple logging observer initialized...Capturing Synapse events...
+ 2009-08-06 14:30:24,604 [-] [main] INFO SimpleLoggingObserver Endpoint : a3 was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,605 [-] [main] INFO SimpleLoggingObserver Endpoint : a2 was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,606 [-] [main] INFO SimpleLoggingObserver Endpoint : null was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,611 [-] [main] INFO SimpleLoggingObserver Local entry : a1 was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,649 [-] [main] INFO SimpleLoggingObserver Proxy service : StockQuoteProxy2 was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,661 [-] [main] INFO SimpleLoggingObserver Proxy service : StockQuoteProxy1 was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,664 [-] [main] INFO SimpleLoggingObserver Sequence : main was added to the Synapse configuration successfully
+ 2009-08-06 14:30:24,701 [-] [main] INFO SimpleLoggingObserver Sequence : fault was added to the Synapse configuration successfully
+
+
+ The SimpleLoggingObserver is implemented as follows. It does not override any of the event handler implementations
+ in the AbstractSynapseObserver class. The AbstractSynapseObserver logs all the received events by default.
+
+ Objective: Demonstrate the priority based mediation capability of ESB.
+
+
+ Prerequisites: Deploy the
+ SimpleStockQuoteService in sample Axis2 server and start it on port
+ 9000. Priority is applied only when ESB is loaded with enough messages to consume its core number of threads.
+ So to observe the priority based mediation, it is required to use a load testing tool like JMeter, SOAP UI or Apache bench.
+
+
+ Start ESB with the sample configuration 652 (i.e. wso2esb-samples.sh -sn 652).
+
+
+ In this sample, client should send a HTTP header that specifies the priority of the message.This header name is priority.
+ This header is retrieved in the ESB configuration using the $trp:priority XPath expression. Then it is matched against
+ the value 1. If it has the value 1, message is executed with priority 1. Otherwise the message is executed with priority 10.
+
+
+ Here are two sample XML files that can be used to invoke the service using a tool like JMeter, or Ab. For SOAP UI,
+ user can use the WSDL repository/samples/resources/proxy/sample_proxy_1.wsdl to create the request. The only
+ difference between the two demonstrated requests here is the symbol. One has the symbol as IBM and other has MSFT. For one type of
+ request set the priority header to 1 and for the next set the priority header to 10. Then load ESB with high
+ volume of traffic from both types of requests using the load testing tool. In the back end server it prints the
+ symbol of the incoming requests. User should be able to see more of high priority symbol.
+
+ Here is the priority configuration file used by the NHTTP transport to determine the priority based on HTTP level properties.
+
+
<priorityConfiguration>
+ <priority-executor>
+ <!-- two priorities specified with priority 10 and 1. Both priority messages has a queue depth of 100 -->
+ <queues isFixedCapacity="true" nextQueue="org.apache.synapse.commons.executors.PRRNextQueueAlgorithm">
+ <queue size="100" priority="10"/>
+ <queue size="100" priority="1"/>
+ </queues>
+ <!-- these are the default values, values are put here to show their availability -->
+ <threads core="20" max="100" keep-alive="5"/>
+ </priority-executor>
+
+ <!-- if a message comes that we cannot determine priority, we set a default priority of 1 -->
+ <conditions defaultPriority="1">
+ <condition priority="10">
+ <!-- check for the header named priority -->
+ <equal type="header" source="priority" value="5"/>
+ </condition>
+ <condition priority="1">
+ <equal type="header" source="priority" value="1"/>
+ </condition>
+ </conditions>
+</priorityConfiguration>
+
+
+ Objective: Demonstrate the priority based dispatching of NHTTP transport.
+
+
+ Prerequisites: Deploy the
+ SimpleStockQuoteService in sample Axis2 server and start it on port
+ 9000. Priority is applied only when ESB is loaded with enough messages to consume its core number of threads.
+ So to observe the priority based dispatching, it is required to use a load testing tool like JMeter, SOAP UI or Apache bench.
+
+
+ Open axis2.xml in repository/conf directory and uncomment the following parameter to the configuration.
+ priorityConfigFile. Set the value to repository/samples/resources/priority/priority-configuration.xml
+
+
+ We'll use the sample number 150. Start ESB with the sample configuration 150 (i.e. wso2esb-samples.sh -sn 150).
+
+
+ In this sample, client should send a HTTP header that specifies the priority of the message.This header name is priority.
+ This header is retrieved in the prioirty configuration. Then it is matched against
+ the value 1 and 10. Depending on this value message is executed with priority 1 or 10.
+
+
+ Here are two sample XML files that can be used to invoke the service using a tool like JMeter, or Apache Ab. For SOAP UI,
+ user can use the WSDL repository/conf/sample/resources/proxy/sample_proxy_1.wsdl to create the request. The only
+ difference between the two demonstrated requests here is the symbol. One has the symbol as IBM and other has MSFT. For one type of
+ request set the priority header to 1 and for the next set the priority header to 10. Then load ESB with high
+ volume of traffic from both types of requests using the load testing tool. In the back end server it prints the
+ symbol of the incoming requests. User should be able to see more of high priority symbol.
+
+ Objective:Demonstrate the smooks mediatot EDI message processing.
+
+
+ Prerequisites: Deploy the
+ SimpleStockQuoteService in sample Axis2 server and start it on port 9000. Then add the
+ plain text builder to the messageBuilders section of the axis2.xml found in the
+ repository/conf directory. Here is the sample configuration.
+
+ Prerequisites: Deploy the
+ SimpleStockQuoteService in sample Axis2 server and start it on port 9000. Then uncomment the Message Relay's Message Builder and Message Formatter in the axis2.xml.
+ These configurations can be found in the messageFormatters and messageBuilders section of the axis2.xml.
+ A message formatter or builder is defined for a content type. So make sure you comment
+ out the normla builders and formatters for a content type when uncomenting the message
+ relay builders and formatters.
+
+
Here are the Message Relay Formatter and Builder classes. You need to uncomment the entries containing the following builder and formatter.
+
org.wso2.carbon.relay.ExpandingMessageFormatter
+
org.wso2.carbon.relay.BinaryRelayBuilder
+
Send a message to the sample using the sample axis2 client.
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
+
You can see the messages going through the proxy by looking at the console because we have two log mediators in this sample. The actual message is not built and printed as a Base64 encoded string.
+ Objective:Demonstrate the Message Relay with Builder mediator.
+
+
+ Prerequisites:Set up is same as sample 655.
+
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
+
You can see the actual messages going through the proxy by looking at the console because we have
+ two log mediators in this sample. Becuase we have the builder mediator in place, unlike in sample 655 we have the actual message printed.
+ Objective:Demonstrate the use of the transaction mediator in a distributed transaction
+
+
+
+
Prerequisites:
+ Start the Synapse configuration numbered 267: i.e. wso2esb-samples -sn 267
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already done
+
+ To run this sample it is required to deploy synpase on JBoss application server(This is only tested with JBoss application sever),
+ you can use the war distribution to deploy synapse on JBoss application server. Use the
+ synpase_sample_652.xml as the synapse confiuration file and start JBoss with that synpase
+ configuration file. Also you need to define two XA datasources for above two datasources.
+ You'll need to refer JBoss documentation to see how to do this. It also required to have two database instances,
+ this will be used by the two XA datasources. Refer the Sample Setup Guide to see how
+ you can set up the derby database server. In this sample a record is delete from one database
+ and it is added into the second database. If either of the operations(deleting from the
+ 1st database and adding into the second database) fails everything will be roll backed.
+ The records will be untouched.
+
+
Invoke the client as follows.
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN/
+
+
+
\ No newline at end of file
diff --git a/docs/xdoc/samples/proxy_samples.xml b/docs/xdoc/samples/proxy_samples.xml
new file mode 100644
index 0000000000..8d54e45ef6
--- /dev/null
+++ b/docs/xdoc/samples/proxy_samples.xml
@@ -0,0 +1,621 @@
+
+
+
+
+
+
+
+ WSO2 ESB - Proxy Service Samples
+
+
+
+
Running the Proxy Services samples with WSO2 Enterprise Service Bus (ESB)
Prerequisites:
+Start the Synapse configuration numbered 150: i.e. wso2esb-samples -sn 150
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
Once ESB starts, you could go to
+http://localhost:8280/services/StockQuoteProxy?wsdl and view the WSDL generated
+for the proxy service defined in the configuration. This WSDL is based on the
+source WSDL supplied in the proxy service definition, and is updated to
+reflect the proxy service EPR.
+
+
Execute the stock quote client by requesting for a stock quote on the
+proxy service as follows:
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
+
+
An 'inSequence' or 'endpoint' or both of these would decide how the
+message would be handled after the proxy service receives the message. In the
+above example, the request received is forwarded to the sample service hosted
+on Axis2. The 'outSequence' defines how the response is handled before it is
+sent back to the client. By default, a proxy service is exposed over all
+transports configured for ESB, unless these are specifically mentioned
+through the 'transports' attribute.
Objective: Using custom sequences and endpoints for message
+mediation with proxy services
+
+
Prerequisites:
+Start the Synapse configuration numbered 151: i.e. wso2esb-samples -sn 151
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
This configuration creates two proxy services.. The first proxy service
+'StockQuoteProxy1' uses the sequence named 'proxy_1' to process incoming
+messages and the sequence named "out" to process outgoing responses. The
+second proxy service 'StockQuoteProxy2' is set to directly forward messages
+that are received to the endpoint named 'proxy_2_endpoint' without any
+mediation.
+
+
You could send a stock quote request to each of these proxy services and
+receive the reply generated by the actual service hosted on the Axis2
+instance.
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy1 ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy2
Objective: Switching transports and message format from SOAP to REST/POX
+
+
+
Prerequisites:
+Start the Synapse configuration numbered 152: i.e. wso2esb-samples -sn 152
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not
+already done
+
+
This configuration demonstrates how a proxy service could be exposed on a
+subset of available transports, and how it could switch from one transport to
+another. This example exposes the created proxy service only on https, and
+thus if the user tries to access it over http, would result in a fault.
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy
+...
+ [java] org.apache.axis2.AxisFault: The service cannot be found for the endpoint reference (EPR) /services/StockQuoteProxy
+
+
Accessing this over https (ant stockquote
+-Dtrpurl=https://localhost:8243/services/StockQuoteProxy) causes the proxy
+service to access the SimpleStockQuoteService on the sample Axis2 server
+using REST/POX. This could be seen if the message exchange was captured using
+TCPMon as follows. The REST/POX response is now transformed back into a SOAP
+message and returned to the client.
Start the Synapse configuration numbered 153: i.e. wso2esb-samples -sn 153
+Start the Axis2 server and deploy the SecureStockQuoteService if not already
+done
+
+
The proxy service will receive secure messages with security headers which
+are MustUnderstand. But hence element 'engageSec' is not present in the proxy
+configuration ESB will not engage that Apache Rampart on this proxy service.
+It is expected that an MustUnderstand failure exception on the AxisEngine
+would occur before the message arrives ESB. But ESB handles this message and
+gets it in by setting all the headers which are MustUnderstand and not
+processed to processed state. This will enable ESB to route the messages
+without reading the Security headers (just routing the messages from client
+to service, both of which are secure). To execute the client, send a stock
+quote request to the proxy service, and sign and encrypt the request by
+specifying the client side security policy as follows:
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dpolicy=./../../repository/samples/resources/policy/client_policy_3.xml
+
+
By following through the debug logs or TCPMon output, you could see that
+the request received by the proxy service was signed and encrypted. Also,
+looking up the WSDL of the proxy service by requesting the URL
+http://localhost:8280/services/StockQuoteProxy?wsdl reveals the security policy
+attachments are not there and security is not engaged. When sending the
+message to the backend service, you could verify that the security headers
+were there as in the original message to ESB from client, and that the
+response received does use WS-Security, and forwarded back to the client
+without any modification. You should note that this wont be a security hole
+because the message inside ESB is signed and encrypted and can only be
+forwarded to a secure service to be useful.
Sample setup is same as LoadBalance endpoints (#53 to #54).
+
+
Start the Synapse configuration numbered 154: i.e. wso2esb-samples -sn 154
+Start the Axis2 server and deploy the LoadbalanceFailoverService if not already
+done
+
+
Runs the client with
+
ant loadbalancefailover -Dmode=session -Dtrpurl=http://localhost:8280/services/LBProxy
+ Objective: Demonstrate the dual channel invocation with Synapse proxy services
+
+
+ Prerequisites: Start the Synapse
+ configuration numbered 155: i.e. wso2esb-samples -sn 155 Start the
+ Axis2 server and deploy the SimpleStockQuoteService if not already done
+
+
+
+ This sample will show the action of the dual channel invocation within client and Synapse
+ as well as within synapse and the actual server. Note that if you want to enable dual
+ channel invocation you need to set the separateListener attribute to true of the
+ enableAddressing element of the endpoint.
+
+
+ Execute the stock quote client by requesting for a stock quote on a dual channel from the
+ proxy service as follows:
+
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dmode=dualquote
+
+ In the above example, the request received is forwarded to the sample service
+ hosted on Axis2 and the endpoint specifies to enable addressing and do the invocation
+ over a dual channel. If you observe this message flow by using a TCPmon, you could see that
+ on the channel you send the request to synapse the response has been written as an
+ HTTP 202 Accepted, where as the real response from synapse will come over a different channel
+ which cannot be obsesrved unless you use tcpdump to dump all the TCP level messages.
+
+
+ At the same time you can observe the behaviour of the invocation between synapse and
+ the actual Axis2 service, where you can see a 202 Accepted message being delivered to synapse
+ as the response to the request. The actual response will be delivered to synapse over a
+ different channel.
+
+ Objective: Using synapse to integrate services.
+
+
+ Prerequisites: We will be using two services in this sample;
+ i.e. SimpleStockQuoteService and SecureStockQuoteService. Therefore the prerequisites
+ of sample 100 is also applied here.
+
+
Start the Synapse
+ configuration numbered 156: i.e. wso2esb-samples -sn 156 Start the
+ Axis2 server and deploy the SimpleStockQuoteService if not already done.
+
+
+ This sample contains a proxy service which provides the seamless integration of
+ SimpleStockQuoteService and SecureStockQuoteService. Once a client send a
+ request to this proxy service, it sends the same request to both these services
+ and resolve the service with cheapest stock quote price.
+
+
+ Execute the stock quote client by requesting for a cheapest stock quote
+ from the proxy service as follows:
+
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy
+
+ Above sample uses the concept of specifying the receiving sequence in the
+ send mediator. In this case once the message is sent from the in sequence
+ then the response won't come to out sequence as the receiving sequence is
+ specified in the send mediator.
+
+ Objective: Routing Messages based on the HTTP Transport properties.
+
+
+ Prerequisites: Start the Synapse configuration numbered 157: i.e. wso2esb-samples -sn 157
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.
+ For this particular case we will be using 'curl' to send requests with custom HTTP Headers to the proxy service. You may use a similar tool with facilitate those requirements.
+
The request file : stockQuoteReq.xml, should contain the following request.
+
Start the Synapse configuration numbered 100: i.e. wso2esb-samples -sn 100
+Start the Axis2 server and deploy the SecureStockQuoteService if not already
+done
+
+
Use the stock quote client to send a request without WS-Security. ESB is
+configured to enable WS-Security as per the policy specified by
+'policy_3.xml' for the outgoing messages to the SecureStockQuoteService
+endpoint hosted on the Axis2 instance. The debug log messages on ESB shows
+the encrypted message flowing to the service and the encrypted response being
+received by ESB. The wsse:Security header is then removed from the decrypted
+message and the response is delivered back to the client, as expected. You
+may execute the client as follows:
+
ant stockquote -Dtrpurl=http://localhost:8280/
+
+
The message sent by ESB to the secure service can be seen as follows, when
+TCPMon is used.
Objective: Demonstrate the message exchange between ESB and the
+server using WS-ReliableMessaging (WS-RM)
+
+
Prerequisites:
+
+
Deploy the ReliableStockQuoteService in the sample Axis2 server by
+switching to the samples/axis2Server/src/ReliableStockQuoteService directory
+and running ant.
+
+
Start the sample Axis2 server on port 9000.
+
+
Start ESB with the sample configuration 101 (i.e. wso2esb-samples -sn 101).
+
+
+
In the above configuration, WS-RM is engaged to the endpoint using the
+<enableRM/> tag. It is possible to engage WS-RM to both Address and
+WSDL endpoints using this tag. In addition to the RM enabled endpoint,
+RMSequence mediator is specified before the send mediator. This mediator is
+used to specify the set of messages to be sent using a single RM sequence. In
+this sample it is specified as single message per sequence. It also specifies
+the version of the WS-RM to be used. Refer to the ESB configuration language
+documentation for more information about the RMSequence mediator. RM related
+SOAP headers are removed from the message in the out mediator as WS-RM
+message exchange happens only between the ESB and the server. Now run the
+sample client using the following command.
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
+
+
You can observe the client output displaying the quote price for IBM as
+follows:
+
[java] Standard :: Stock price = $189.2521262517493
+
+
There is no difference to be observed between the normal message exchange
+and WS-RM enabled message exchange as far as client and server outputs are
+considered. But if you look at the wire level messages, you would observe
+additional WS-RM messages and WS-RM elements. ESB, the initiator of the RM
+sequence, first try to create a sequence by sending a message with
+CreateSequence element.
ESB keeps on sending above message till the server responds with a valid
+response message with 200 OK HTTP header. If the server is not ready with a
+response, it will respond with 202 Accepted HTTP header for all requests.
+Once the server is ready with a response it will send the response message
+with sequence ID as follows.
Note that although each of above messages are separate SOAP messages, in
+most cases they will be exchanged in a single socket connection as HTTP
+Keep-Alive header is used.
Objective: Demonstrate the message exchange between ESB and the
+server using WS-ReliableMessaging 1.1 Specification (WS-RM).This sample is similar
+ to sample 101 except it uses the RM 1.1 for the communication.
+
+
Prerequisites:
+
+
Deploy the ReliableStockQuoteService in the sample Axis2 server by
+switching to the samples/axis2Server/src/ReliableStockQuoteService directory
+and running ant.
+
+
Start the sample Axis2 server on port 9000.
+
+
Start ESB with the sample configuration 102 (i.e. wso2esb-samples -sn 102).
+
+
+
In the above configuration, WS-RM is engaged to the endpoint using the
+<enableRM/> tag. It is possible to engage WS-RM to both Address and
+WSDL endpoints using this tag. In addition to the RM enabled endpoint,
+RMSequence mediator is specified before the send mediator. This mediator is
+used to specify the set of messages to be sent using a single RM sequence. Also it specifies the RM version. In
+this sample it is specified as single message per sequence. It also specifies
+the version of the WS-RM to be used. Refer to the ESB configuration language
+documentation for more information about the RMSequence mediator. RM related
+SOAP headers are removed from the message in the out mediator as WS-RM
+message exchange happens only between the ESB and the server. Now run the
+sample client using the following command.
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
+
+
You can observe the client output displaying the quote price for IBM as
+follows:
+
[java] Standard :: Stock price = $189.2521262517493
+
You can observer the set of messages exchnaged between ESB and back end service using a tool like TCPMon
+
+
+
\ No newline at end of file
diff --git a/docs/xdoc/samples/qos_proxy_samples.xml b/docs/xdoc/samples/qos_proxy_samples.xml
new file mode 100644
index 0000000000..03d7b98240
--- /dev/null
+++ b/docs/xdoc/samples/qos_proxy_samples.xml
@@ -0,0 +1,194 @@
+
+
+
+
+
+
+
+ WSO2 ESB - QoS Proxy Service Samples
+
+
+
+
Running QoS addition and deduction proxy service samples with WSO2 ESB
Start the Synapse configuration numbered 200: i.e. wso2esb-samples -sn 200
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
The proxy service expects to receive a signed and encrypted message as
+specified by the security policy. Please see Apache Rampart and Axis2
+documentation on the format of the policy file. The element 'engageSec'
+specifies that Apache Rampart should be engaged on this proxy service. Hence
+if Rampart rejects any request messages that does not conform to the
+specified policy, those messages will never reach the 'inSequence' to be
+processed. Since the proxy service is forwarding the received request to the
+simple stock quote service that does not use WS-Security, we are instructing
+ESB to remove the wsse:Security header from the outgoing message. To execute
+the client, send a stock quote request to the proxy service, and sign and
+encrypt the request by specifying the client side security policy as follows:
+
+
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dpolicy=./../../repository/samples/resources/policy/client_policy_3.xml
+
+
By following through the debug logs or TCPMon output, you could see that
+the request received by the proxy service was signed and encrypted. Also,
+looking up the WSDL of the proxy service by requesting the
+URLhttp://localhost:8280/services/StockQuoteProxy?wsdl reveals the security
+policy attachment to the supplied base WSDL. When sending the message to the
+backend service, you could verify that the security headers were removed, and
+that the response received does not use WS-Security, but that the response
+being forwarded back to the client is signed and encrypted as expected by the
+client.
Objective: Demonstrate the reliable message exchange between the
+client and ESB using WS-ReliableMessaging (WS-RM)
+
+
Prerequisites:
+
+
Deploy the SimpleStockQuoteService in the sample Axis2 server and start it
+on port 9000.
+
+
Start ESB with the sample configuration number 201 (i.e. wso2esb-samples -sn 201).
+
+
In the above configuration, a proxy service is created with WS-RM enabled
+using the <enableRM/> tag. Therefore, this proxy service is capable of
+communicating with a WS-RM client. It also removes the WS-RM headers in the
+In Sequence before the message is sent to the back end server. This is
+required as the reliable messaging is applicable only between the client and
+ESB. Now start the client with WS-RM as follows:
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dwsrm=true
+
+
In this case, client sends WS-RM enabled request to ESB where ESB sends
+normal request to the server. This can be observed by examining the wire
+level messages between the client and ESB. These messages would be similar to
+the wire level messages shown in sample 101. Each message would perform a
+similar function to the messages discussed in sample 53.
Objective: Demonstrate the reliable message exchange between the
+client and ESB using WS-ReliableMessaging (WS-RM)
+
+
Prerequisites:
+
+
Deploy the SimpleStockQuoteService in the sample Axis2 server and start it
+on port 9000.
+
+
Start ESB with the sample configuration number 202 (i.e. wso2esb-samples -sn 202).
+
+
In the above configuration, a proxy service is created with WS-RM enabled
+using the <enableRM/> tag. Therefore, this proxy service is capable of
+communicating with a WS-RM client. It also removes the WS-RM 1.1 headers in the
+In Sequence before the message is sent to the back end server. This is
+required as the reliable messaging is applicable only between the client and
+ESB. Now start the client with WS-RM as follows:
+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dwsrm11=true
+
+
In this case, client sends WS-RM enabled request to ESB where ESB sends
+normal request to the server. This can be observed by examining the wire
+level messages between the client and ESB. These messages would be similar to
+the wire level messages shown in sample 102. Each message would perform a
+similar function to the messages discussed in sample 53.
+
+
\ No newline at end of file
diff --git a/docs/xdoc/samples/rest_api_samples.xml b/docs/xdoc/samples/rest_api_samples.xml
new file mode 100644
index 0000000000..b7007b9275
--- /dev/null
+++ b/docs/xdoc/samples/rest_api_samples.xml
@@ -0,0 +1,102 @@
+
+
+
+
+
+
+
+ WSO2 ESB - REST API Samples
+
+
+
+
Running the REST API Samples with WSO2 Enterprise Service Bus (ESB)
<!-- An empty flat synapse configuration shipped with the WSO2 ESB -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- You can add any flat sequences, endpoints, etc.. to this synapse.xml file if you do
+ *not* want to keep the artifacts in several files -->
+<api name="StockQuoteAPI" context="/stockquote">
+ <resource uri-template="/view/{symbol}" methods="GET">
+ <inSequence>
+ <payloadFactory>
+ <format>
+ <m0:getQuote xmlns:m0="http://services.samples">
+ <m0:request>
+ <m0:symbol>$1</m0:symbol>
+ </m0:request>
+ </m0:getQuote>
+ </format>
+ <args>
+ <arg expression="get-property('uri.var.symbol')"/>
+ </args>
+ </payloadFactory>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ <outSequence>
+ <send/>
+ </outSequence>
+ </resource>
+ <resource url-pattern="/order/*" methods="POST">
+ <inSequence>
+ <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
+ <property name="OUT_ONLY" value="true"/>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ </resource>
+</api>
+</definitions>
+
+
Objective: Introduction to REST API
+
+
Prerequisites:
+Start the Axis2 server and deploy the SimpleStockQuoteService
+Start the Synapse configuration numbered 800: i.e. wso2esb-samples -sn 800
+You might need a REST client like curl to test this
The above GET calls will be handled by the first resource in the StockQuoteAPI. These REST calls will get converted into SOAP calls and will be sent to the Axis2 server. Response will be sent to the client in POX format.
+
+
The following command POSTs a simple XML to the ESB. Save following sample place order request as "placeorder.xml" file in your local file system and execute the command. That is used to invoke a SOAP service. ESB returns the 202 response back to the client.
Running the Rule samples with WSO2 Enterprise Service Bus (ESB)
+
+
Introduction
+
+
Rule mediator integrates the WSO2 rules component into the WSO2 ESB to
+provide you with a suitable capability to define your organization's
+dynamic integration decisions in terms of rules.This guide provides you with a
+seven samples, which are quite simple. The goal of the samples is to make you
+an expertise in using rule mediator. Please follow the configuration guide of
+the rule mediator before proceeding with the samples if you have not already
+done so.
+
+
Sample 600 : Rule Mediator as a Filter - Simple Rule Based
+Routing
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed.
+
+
Run the client as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
+
+
Or as
+
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
+
+
Then, you will get stock quote price in the client side.
+
+
In this sample , with in the rule mediator , the value, which is extracted
+from the SOAP envelope using XPath
+'//m0:getQuote/m0:request/m0:symbol', is added to the rule
+engine as a string fact . The message context property named
+"execute_children" is to indicate it is need to execute the
+child mediators of rule mediator. That property is set only if the symbol is
+IBM.
+
+
Now use following commands
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
+
+
+
+
and
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
+
+
+
+
Then , you will get errors . This is because , 'symbol' is not equal to
+"IBM".
+
+
+
Sample 601: Rule Mediator as a Filter - Simple Rule Based
+Routing (Keeping Ruleset in the Registry)
+
<!-- Simple rule based routing of messages - same as filter mediator -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+
+ <localEntry key="rule-script-key"
+ src="file:repository/samples/resources/rule/simple_rule_base.xml"/>
+
+ <in>
+
+ <rule>
+ <ruleset >
+ <source key="rule-script-key"/>
+ <creation>
+ <property name="source" value="xml"/>
+ </creation>
+ </ruleset>
+ <session type="stateless"/>
+ <facts>
+ <fact name="mc" type="context"/>
+ <fact name="symbol" type="java.lang.String"
+ expression="//m0:getQuote/m0:request/m0:symbol/child::text()"
+ xmlns:m0="http://services.samples"/>
+ </facts>
+
+ <childMediators>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ <drop/>
+ </childMediators>
+
+ </rule>
+
+ </in>
+
+ <out>
+ <send/>
+ </out>
+
+</definitions>
Objective: Introduction to simple rule based routing
+
+
Prerequisites:
+Start the Synapse configuration numbered 601: (i.e. ./wso2esb-samples.sh -sn
+601)
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
Please tests this sample same as above (600) sample because this has same
+functionality as above one.
+
+
Sample 602 : Rule Mediator as a Filter - Simple rule based
+routing (Using the Drools Native Language )
+
<!-- Simple rule based routing of messages - same as filter mediator -->
+<!-- The use of Drools native language -->
+
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+
+ <localEntry key="rule-script-key"
+ src="file:repository/samples/resources/rule/simple_rule_base.drl"/>
+
+ <in>
+
+ <rule>
+ <ruleset >
+ <source key="rule-script-key"/>
+ </ruleset>
+ <session type="stateless"/>
+ <facts>
+ <fact name="mc" type="context"/>
+ <fact name="symbol" type="java.lang.String"
+ expression="//m0:getQuote/m0:request/m0:symbol/child::text()"
+ xmlns:m0="http://services.samples"/>
+ </facts>
+ <childMediators>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ <drop/>
+ </childMediators>
+
+ </rule>
+
+ </in>
+
+ <out>
+ <send/>
+ </out>
+
+</definitions>
Objective: Introduction to simple rule based routing (Using
+Drools native language )
+
+
Prerequisites:
+Start the Synapse configuration numbered 602: (i.e. ./wso2esb-samples.sh -sn
+602)
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
Please tests this sample same as sample 600 because this has same
+functionality as it.
+
+
Sample 603 : Advance Rule Based Routing - Switching Routing
+Decision According to the Rules - Rule Mediator as Switch mediator
Objective: Advance rule based routing - Switching routing
+decision according to the rules - Rule mediator as Switch mediator.
+
+
Prerequisites:
+Start the Synapse configuration numbered 603: i.e. (i.e. ./wso2esb-samples.sh
+-sn 603)
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
This sample shows how can rule mediator act as Switch mediator. In this
+sample, the use of input with type 'sequence' is being
+introducing. The type 'sequence' indicates the synapse sequences. This enables
+to use defined sequences (reference or in-lined) with in rule script.
+
+
In rule script , there are three cases each for 'IBM','SUN' and 'MSFT'. When
+condition is match , then corresponding rule will be got fire.
+
+
Invoke IBM rule by running client as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
+
+
+
+
You will get stock quote price successfully
+
+
Then invoke SUN rule by running client as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
Start the Synapse configuration numbered 604: (i.e. ./wso2esb-samples.sh -sn
+604)
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed
+
+
In this sample , a simple transformation is happened . If the symbol is
+either SUN or MSFT , then it will changed into IBM in the SOAP envelope and
+then invoke the external service.
+
+
Run client as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
+
+
Or as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
+
+
+
+
Then check the axis2server log or console .
+
Mon Mar 03 16:33:05 IST 2008 samples.services.SimpleStockQuoteService :: Generating quote for : IBM
+
+
Sample 605 : Simple Message Transformation
+
<!-- Simple rule based transformation (changing message ) -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.wso2.carbon.mediation.registry.ESBRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/samples/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <localEntry key="rule-script-key"
+ src="file:repository/samples/resources/rule/commission_rule.xml"/>
+ <in>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </in>
+
+ <out>
+ <rule>
+ <ruleset >
+ <source key="rule-script-key"/>
+ <creation>
+ <property name="source" value="xml"/>
+ </creation>
+ </ruleset>
+ <session type="stateless"/>
+ <facts>
+ <fact name="symbol" type="java.lang.String"
+ expression="self::node()//m0:return/m1:symbol/child::text()"
+ xmlns:m0="http://services.samples"
+ xmlns:m1="http://services.samples/xsd"/>
+ <fact name="price" type="java.lang.Double"
+ expression="self::node()//m0:return/m1:last/child::text()"
+ xmlns:m0="http://services.samples"
+ xmlns:m1="http://services.samples/xsd"/>
+ </facts>
+ <results>
+ <result name="price" type="java.lang.Double"
+ expression="self::node()//m0:return/m1:last"
+ xmlns:m0="http://services.samples"
+ xmlns:m1="http://services.samples/xsd"/>
+ </results>
+ </rule>
+ <send/>
+ </out>
+</definitions>
+
+
rule script - commission_rule.xml
+
<package name="SimpleMessageTransformationRules"
+ xmlns="http://drools.org/drools-5.0"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+ xs:schemaLocation="http://drools.org/drools-5.0 drools-4.0.xsd">
+
+ <rule name="Get commission form SUN and MSFT but not from IBM ">
+
+ <lhs>
+ <pattern object-type="String" identifier="symbol">
+ </pattern>
+ <pattern object-type="Double" identifier="price">
+ </pattern>
+ <eval>symbol.equals("MSFT") || symbol.equals("SUN")</eval>
+ </lhs>
+
+ <rhs>
+ Double newPrice = price.doubleValue()+ 3000.68;
+ update(drools.getWorkingMemory().getFactHandle(price),newPrice);
+ retract(drools.getWorkingMemory().getFactHandle(symbol));
+ </rhs>
+ </rule>
+
+</package>
Start the Synapse configuration numbered 605: (i.e. ./wso2esb-samples.sh -sn
+605)
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed.
+
+
This sample also illustrates a simple transformation using rule mediator. In
+here, for MSFT and SUN a commission is added to the price.(3000.68).
+
+
Invoke synapse(esb) with symbol IBM as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
+
+
Then you will get the price as usual value .
+
Standard :: Stock price = $81.35674789750315
+
+
Then invoke synapse(esb) with symbol MSFT or SUN as
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
+
+
+
Then you will get the price whic is always above 3000.
+
Standard :: Stock price = $3082.1975970450094
+
+
+
Sample 606 : Advanced Transformation and Use of Custom Java
+Objects
Objective: Advanced transformation using rule mediator.
+
+
Prerequisites:
+
+
Start the Synapse configuration numbered 606: (i.e. ./wso2esb-samples.sh -sn
+606)
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+deployed.
+
+
The classes GetQuoteRequest.java and
+CheckPriceResponse.java which are shown in bellow, have to be
+compiled and put in classpath. Easy way may be putting as a jar inside
+repository/components/lib. Pleas note that these classes need
+to be group to package org.wso2.carbon.rule.samples.
+
+
This sample also illustrates a advanced transformation using rule mediator.
+
+
+
This sample illustrates the functionality offered by XSLT sample (sample 8
+in the synapse (esb) samples). Both of the request and response are
+transformed.
+
+
In this sample , use Java objects to archive the easy transformation. if the
+a toXML() method returns a valid XML , it is possible to
+attached it into SOPA envelope. It is same concepts as serializing object into
+XML . if there is no method of toXML , then Java Object is
+serialized into an XML based Axis2 POJO to XML binding.
This is just a example to show what kind of cool thing can be done using
+rule mediator.
+
+
Runs the client in custom mode as follows
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote
+
+
diff --git a/docs/xdoc/samples/store_n_forward_samples.xml b/docs/xdoc/samples/store_n_forward_samples.xml
new file mode 100644
index 0000000000..3c4d642a67
--- /dev/null
+++ b/docs/xdoc/samples/store_n_forward_samples.xml
@@ -0,0 +1,210 @@
+
+
+
+
+
+
+
+ WSO2 ESB - Store and Forward Messaging patterns with Message Stores and Message Processors
+
+
+
+
Store and Forward Messaging patterns with Message Stores and Message Processors
+
+ Message Stores and Message Processors can be used to implement different store
+ and forward messaging patterns.
+ This can be use to cater different SLA s and other QoS aspects.
+
Prerequisites:
+ Start the configuration numbered 700: i.e. wso2esb-samples -sn 700
+
+
To Execute the Client :
+
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=placeorder
+
+
When you execute the client the message will be dispatched to the main sequence.
+ In the Main sequence store mediator will store the placeOrder request message in the "MyStore" Message Store
+
+
Before Storing the message store mediator will invoke the sequence :onStoreSequence. See the log
+
INFO - LogMediator To: http://localhost:9000/services/SimpleStockQuoteService, WSAction: urn:placeOrder, SOAPAction: urn:placeOrder, ReplyTo: http://www.w3.org/2005/08/addressing/none, MessageID: urn:uuid:54f0e7c6-7b43-437c-837e-a825d819688c, Direction: request, On-Store = Storing message
+
+
+
+
You can then use the JMX view of Synapse Message Store by using the jconsole and view the stored
+ Messages and delete them.
+
+ Objective:Introduction to Message Sampling Processor
+
+
Prerequisites:
+ Start the configuration numbered 701: i.e. wso2esb-samples -sn 701
+
Start the SimpleStockQuoteService if its not already started
+
To Execute the Client few times:
+
ant stockquote
+ -Daddurl=http://localhost:9000/services/SimpleStockQuoteService
+ -Dtrpurl=http://localhost:8280/ -Dmode=placeorder
+
+
When you execute the client the message will be dispatched to the main sequence.
+ In the Main sequence store mediator will store the placeOrder request message in the
+ "MyStore" Message Store
+
+
+
Message Processor will consume the messages and forward to the send_seq sequence in
+ configured rate.
+
+
You will observe that service invocation rate is not changing when increasing the rate we
+ execute the client.
+
Objective: Introduce the concept of tasks and how simple trigger
+ works
+
+
Prerequisites:
+ You will need access to build the SimpleStockQuoteService as mentioned in the
+ above and start the sample axis2 server before staring ESB.
+
+
When ever ESB gets started with this configuration (i.e. ./wso2esb-samples -sn 300), this task will run
+ periodically in 5 second intervals. You could limit the number of times that
+ you want to run this task by adding a count attribute with an integer as the
+ value, if the count is not present as in this sample this task will run
+ forever.
+
+
One can write his own task class implementing the
+ org.apache.synapse.startup.Task interface and implementing the execute method
+ to do the task. For this particular sample we have used the MessageInjector
+ which just injects a message specified into the ESB environment.
Prerequisites:
+ Start the Synapse configuration numbered 750: i.e. wso2esb-samples -sn 750
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+ done
+
+
Execute the stock quote client by requesting for a stock quote on the
+ proxy service as follows:
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dmode=customquote
+
+
ESB Sequence Template can act a reusable function. Here proxy service reuses template xslt_func which will transform requests with the given xslt local entry key And will log
+ the message before and after. It takes xslt transformation corresponding to local entry key as an
+ argument (for insequence this key is xslt-key-req and out sequence it is xslt-key-back). We use
+ call-template mediator for passing the xslt key parameter to a sequence template. ESB console
+ will display how the custom stockquote is transformed and the transformed response from the service.
<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <proxy name="SplitAggregateProxy">
+ <target>
+ <inSequence>
+ <!--use iterate sequence template to split incoming request and send-->
+ <call-template target="iter_func">
+ <with-param xmlns:m0="http://services.samples" name="iter_expr" value="{{//m0:getQuote/m0:request}}"/>
+ <with-param xmlns:m0="http://services.samples" name="attach_path" value="{{//m0:getQuote}}"/>
+ </call-template>
+ </inSequence>
+ <outSequence>
+ <!--use aggregate sequence template to combine the responses and send back-->
+ <call-template target="aggr_func">
+ <with-param xmlns:m0="http://services.samples" name="aggr_expr" value="{{//m0:getQuoteResponse}}"/>
+ </call-template>
+ </outSequence>
+ </target>
+ </proxy>
+
+ <!--this sequence template will aggregate the responses , merge and send back to the client. This takes aggregate
+ expression as an argument-->
+ <template xmlns="http://ws.apache.org/ns/synapse" name="aggr_func">
+ <parameter name="aggr_expr"/>
+ <sequence>
+ <log level="full"/>
+ <aggregate>
+ <completeCondition>
+ <messageCount min="-1" max="-1"/>
+ </completeCondition>
+ <onComplete expression="$func:aggr_expr">
+ <log level="full" />
+ <send/>
+ </onComplete>
+ </aggregate>
+ </sequence>
+ </template>
+
+ <!--this sequence template will iterate through stock quote symbols ,split and send them to endpoints. Takes Iterate
+ expression and soap attaach path as arguments -->
+ <template xmlns="http://ws.apache.org/ns/synapse" name="iter_func">
+ <parameter name="iter_expr"/>
+ <parameter name="attach_path"/>
+ <sequence>
+
+ <iterate xmlns:m0="http://services.samples" preservePayload="true" attachPath="$func:attach_path" expression="$func:iter_expr">
+ <target>
+ <sequence>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </sequence>
+ </target>
+ </iterate>
+ </sequence>
+ </template>
+</definitions>
+
+
Objective: Demonstrate the use of tempaltes in Split/Aggregate scenario .
+
+
Prerequisites:Deploy the SimpleStockQuoteService in sample
+ Axis2 server and start it on port 9000.
+
+
Start ESB with the sample configuration 751 (i.e. wso2esb-samples -sn 751).
+
+
+
This will be the same sample demonstrated in advanced mediation with Iterate mediator used to split the
+ messages in to parts and process them asynchronously and then aggregate the
+ responses coming in to ESB. Only addition will be two sequence templates 'iter_func' and
+ 'aggr_func' which will split the message and aggregate the responses back , respectively.
+
+
Invoke the client as follows.
+
ant stockquote -Daddurl=http://localhost:8280/services/SplitAggregateProxy -Ditr=4
+
+
Sequence Template 'iter_func' takes iterate expressions and attach path as arguments.
+
+
Sequence Template 'aggr_func' takes aggregate expression as argument.
+
+
In this sample we are using special dynamic xpath expressions(in double curly braces {{expr}}) in call-template mediator so that
+ they are evaluated only when iteration and aggregation is done. Note that function scope (ie:-$func) is used to access template
+ parameters in 'iter_func' and 'aggr_func'.
+
Objective: Demonstrate how to use endpoint templates in a load balance configuration .
+
+
Prerequisites:Sample setup is same as LoadBalance endpoint scenario (#154).
+
+Start the Synapse configuration numbered 752: i.e. wso2esb-samples -sn 752
+Start the Axis2 server and deploy the LoadbalanceFailoverService if not already done
+
+
+
+
Configuration demonstrates a single endpoint template named 'endpoint_template'. Three endpoint templates
+ are created inside loadbalance endpoint which will point to this template. Note different parameters passed
+ on to the same template ie:- service url and suspend duration as parameters
+
+
Invoke the client as follows.
+
ant loadbalancefailover -Dmode=session -Dtrpurl=http://localhost:8280/services/LBProxy
+
+
+
As in the previous loadbalance samples client console will show loadbalance requests going towards three endpoints
+ created from the same template. Notice differnt suspension times for three services in a failed
+ endpoint scenario as well. (reflects different parameters passed onto the template)
+
Objective: Introduction to switching transports with proxy
+services
+
+
Prerequisites:
+Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps
+above)
+Download, install and start a JMS server, and configure ESB to listen on JMS
+(refer notes below)
+Start the Synapse configuration numbered 250: i.e. wso2esb-samples -sn 250
+For this example we would use ActiveMQ as the JMS provider. Once ActiveMQ is
+installed and started you should get a message as follows:
+
INFO BrokerService - ActiveMQ JMS Message Broker (localhost) started
+
+
You will now need to configure the Axis2 instance used by ESB (not the
+sample Axis2 server) to enable JMS support using the above provider. Refer to
+the Axis2 documentation on setting up JMS for more details
+(http://ws.apache.org/axis2/1_1/jms-transport.html). You will also need to
+copy the ActiveMQ client jar files
+activemq-core-5.2.0.jar and geronimo-j2ee-management_1.0_spec-1.0.jar into
+the repository/components/lib directory to allow ESB to connect to the JMS provider.
+
+
For a default ActiveMQ v4.0 installation, you may uncomment the Axis2
+transport listener configuration found at repository/conf/axis2.xml as
You need to enable the JMS transport sender for the ESB to be able to send
+messages over the JMS transport. To enable the JMS transport sender uncomment
+the Axis2 transport sender configuration found at repository/conf/axis2.xml as
Once you start the Synapse configuration and request for the WSDL of the
+proxy service (http://localhost:8280/services/StockQuoteProxy?wsdl) you will
+notice that its exposed only on the JMS transport. This is because the
+configuration specified this requirement in the proxy service definition.
+
+
Now lets send a place order request on JMS, using the dumb stock quote
+client as follows:
+
ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/StockQuoteProxy -Djms_payload=MSFT
+
+
On the ESB debug log you will notice that the JMS listener received the
+request message as:
+
[JMSWorker-1] DEBUG ProxyServiceMessageReceiver -Proxy Service StockQuoteProxy received a new message...
+
+
Now if you examine the console running the sample Axis2 server, you will
+see a message indicating that the server has accepted an order as follows:
+
+
Accepted order for : 16517 stocks of MSFT at $ 169.14622538721846
+
+
In this sample, client sends the request message to the proxy service
+exposed over JMS in Synapse. ESB forwards this message to the HTTP EPR of the
+simple stock quote service hosted on the sample Axis2 server, which sends a
+202 Accepted response back to the ESB. Since the placeOrder operation is an
+in-only service operation the JMS client does not receive any response in this
+sample.
Prerequisites:
+Download, install and start a JMS server
+
+
Configure sample Axis2 server for JMS (refer notes above)
+Start the Axis2 server and deploy the SimpleStockQuoteService (see below)
+Configure the Synapse JMS transport (refer notes above - sample 250)
+Start the Synapse configuration numbered 251: i.e. wso2esb-samples -sn 251
+
+
To switch from HTTP to JMS, edit the
+samples/axis2Server/repository/conf/axis2.xml for the sample Axis2 server and
+enable JMS (refer notes above), and restart the server. Now you can see that
+the simple stock quote service is available in both JMS and HTTP in the
+sample Axis2 server. To see this, point your browser to the WSDL of the
+service at http://localhost:9000/services/SimpleStockQuoteService?wsdl. JMS URL
+for the service is mentioned as below:
You may also notice that the simple stock quote proxy service exposed in
+ESB is now available only in HTTP as we have specified transport for that
+service as HTTP. To observe this, access the WSDL of stock quote proxy
+service at http://localhost:8280/services/StockQuoteProxy?wsdl.
+
+
This ESB configuration creates a proxy service over HTTP and forwards
+received messages to the above EPR using JMS. To test this, send a place
+order request to ESB using HTTP as follows:
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dmode=placeorder -Dsymbol=MSFT
+
+
The sample Axis2 server console will print a message indicating that it
+has accepted the order as follows:
+
Accepted order for : 18406 stocks of MSFT at $ 83.58806051152119
Objective: Pure POX/Text and Binary JMS Proxy services - including
+MTOM
+
+
Prerequisites:
+Configure JMS for ESB (Refer notes)
+Start the Synapse configuration numbered 252: i.e. wso2esb-samples -sn 252
+Start the Axis2 server and deploy the SimpleStockQuoteService and the
+MTOMSwASampleService if not already done
+
+
This configuration creates three JMS proxy services named
+JMSFileUploadProxy, JMSTextProxy and JMSPoxProxy exposed over JMS queues with
+the same names as the services. The first part of this example demonstrates
+the pure text message support with JMS, where a user sends a space separated
+text JMS message of the form "<price> <qty> <symbol>". ESB
+converts this message into a SOAP message and sends this to the
+SimpleStockQuoteServices' placeOrder operation. ESB uses the script mediator
+to transform the text message into a XML payload using the Javascript support
+available to tokenize the string. The proxy service property named
+"transport.jms.Wrapper" defines a custom wrapper element QName, to be used
+when wrapping text/binary content into a SOAP envelope.
+
+
Execute JMS client as follows. This will post a pure text JMS message with
+the content defined (e.g. "12.33 1000 ACP") to the specified JMS destination
+- dynamicQueues/JMSTextProxy
+
ant jmsclient -Djms_type=text -Djms_payload="12.33 1000 ACP" -Djms_dest=dynamicQueues/JMSTextProxy
+
+
Following the debug logs, you could notice that ESB received the JMS text
+message and transformed it into a SOAP payload as follows. Notice that the
+wrapper element "{http://services.samples/xsd}text" has been used to hold the
+text message content.
Now, you could see how the script mediator created a stock quote request
+by tokenizing the text as follows, and sent the message to the placeOrder
+operation of the SimpleStockQuoteService.
The sample Axis2 server would now accept the one way message and issue the
+following message:
+
Wed Apr 25 19:50:56 LKT 2007 samples.services.SimpleStockQuoteService :: Accepted order for : 1000 stocks of ACP at $ 12.33
+
+
The next section of this example demonstrates how a pure binary JMS
+message could be received and processed through ESB. The configuration
+creates a proxy service named 'JMSFileUploadProxy' that accepts binary
+messages and wraps them into a custom element
+'{http://services.samples/xsd}element'. The received message is then
+forwarded to the MTOMSwASampleService using the SOAP action
+'urn:oneWayUploadUsingMTOM' and optimizing binary conent using MTOM. To
+execute this sample, use the JMS client to publish a pure binary JMS message
+containing the file
+'./../../repository/samples/resources/mtom/asf-logo.gif' to the JMS
+destination 'dynamicQueues/JMSFileUploadProxy' as follows:
+
ant jmsclient -Djms_type=binary -Djms_dest=dynamicQueues/JMSFileUploadProxy -Djms_payload=./../../repository/samples/resources/mtom/asf-logo.gif
+
+
Examining the ESB debug logs reveals that the binary content was received
+over JMS and wrapped with the specified element into a SOAP infoset as
+follows:
+
[JMSWorker-1] DEBUG ProxyServiceMessageReceiver - Proxy Service JMSFileUploadProxy received a new message...
+...
+[JMSWorker-1] DEBUG ProxyServiceMessageReceiver - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+<soapenv:Body><axis2ns1:element xmlns:axis2ns1="http://services.samples/xsd">R0lGODlhgw...AAOw==</axis2ns1:element></soapenv:Body>
+</soapenv:Envelope>
+
+
Thereafter the message was sent as a MTOM optimized message as specified
+by the 'format=mtom' attribute of the endpoint, to the MTOMSwASampleService
+using the SOAP action 'urn:oneWayUploadUsingMTOM'. Once received by the
+sample service, it is saved into a temporary file and could be verified for
+correctness.
+
Wrote to file : ./../../work/temp/sampleServer/mtom-29208.gif
+
+
The final section of this example shows how a POX JMS message received by
+ESB is sent to the SimpleStockQuoteService as a SOAP message. Use the JMS
+client as follows to create a POX (Plain Old XML) message with a stock quote
+request payload (without a SOAP envelope), and send it to the JMS destination
+'dynamicQueues/JMSPoxProxy' as follows:
+
ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/JMSPoxProxy -Djms_payload=MSFT
+
+
You can see that ESB received the POX message and displays it as follows
+in the debug logs, and then converts it into a SOAP payload and sends to the
+SimpleStockQuoteService after setting the SOAP action as 'urn:placeOrder'.
+
+
+
[JMSWorker-1] DEBUG ProxyServiceMessageReceiver - Proxy Service JMSPoxProxy received a new message...
+...
+[JMSWorker-1] DEBUG ProxyServiceMessageReceiver - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><m:placeOrder xmlns:m="http://services.samples/xsd">
+ <m:order>
+ <m:price>172.39703010684752</m:price>
+ <m:quantity>19211</m:quantity>
+ <m:symbol>MSFT</m:symbol>
+ </m:order>
+</m:placeOrder></soapenv:Body></soapenv:Envelope>
+[JMSWorker-1] DEBUG ProxyServiceMessageReceiver - Using the sequence named pox_proxy for message mediation
+...
+[JMSWorker-1] DEBUG HeaderMediator - Setting header : Action to : urn:placeOrder
+...
+[JMSWorker-1] DEBUG AddressEndpoint - Sending message to endpoint :: name = AnonymousEndpoints resolved address = http://localhost:9000/services/SimpleStockQuoteService
+[JMSWorker-1] DEBUG AddressEndpoint - SOAPAction: urn:placeOrder
+[JMSWorker-1] DEBUG AddressEndpoint - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><m:placeOrder xmlns:m="http://services.samples/xsd">
+ <m:order>
+ <m:price>172.39703010684752</m:price>
+ <m:quantity>19211</m:quantity>
+ <m:symbol>MSFT</m:symbol>
+ </m:order>
+</m:placeOrder></soapenv:Body></soapenv:Envelope>
+[JMSWorker-1] DEBUG Axis2FlexibleMEPClient - sending [add = false] [sec = false] [rm = false] [ mtom = false] [ swa = false] [ force soap=true; pox=false] [ to null]
+
+
The sample Axis2 server displays a successful message on the receipt of
+the message as:
+
Wed Apr 25 20:24:50 LKT 2007 samples.services.SimpleStockQuoteService :: Accepted order for : 19211 stocks of MSFT at $ 172.39703010684752
Objective: Demonstrate one way message bridging from JMS to http
+and replying with a http 202 Accepted response
+
+
Prerequisites:
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already
+done
+
+
Start the Synapse configuration numbered 253: i.e. wso2esb-samples -sn 253
+
+
+
This example invokes the one-way 'placeOrder' operation on the
+SimpleStockQuoteService using the Axis2 ServiceClient.fireAndForget() API at
+the client. To test this, use 'ant -Dmode=placeorder...' and you will notice
+the one way JMS message flowing through ESB into the sample Axis2 server
+instance over http, and Axis2 acknowledging it with a http 202 Accepted
+response.
+
ant stockquote -Dmode=placeorder -Dtrpurl="jms:/JMStoHTTPStockQuoteProxy?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&transport.jms.ContentTypeProperty=Content-Type&transport.jms.DestinationType=queue"
+
SimpleStockQuoteService :: Accepted order for : 7482 stocks of IBM at $ 169.27205579038733
+
+
The second example shows how ESB could be made to respond with a http 202
+Accepted response to a request received. The proxy service simply logs the
+message received and acknowledges it. On the ESB console you could see the
+logged message, and if TCPMon was used at the client, you would see the 202
+Accepted response sent back to the client from ESB
+
ant stockquote -Dmode=placeorder -Dtrpurl=http://localhost:8280/services/OneWayProxy
Objective: Using the file system as transport medium using VFS
+transport listener and sender
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not
+already done
+
+
Create three new directories in a test directory. e.g. in, out, original
+in /home/user/test. Open
+ESB_HOME/repository/samples/synapse_sample_254.xml and edit the following
+values. Change transport.vfs.FileURI, transport.vfs.MoveAfterProcess,
+transport.vfs.MoveAfterFailure parameter values to the above in, original,
+original directories respectively. Change outSequence endpoint address uri to
+out directory with the prefix vfs:. Values you have to change are
+marked with <!--CHANGE-->.
+
+
In the axis2.xml uncomment the VFS transport listener and sender.
+
+
Start the Synapse configuration numbered 254: i.e. wso2esb-samples -sn 254
+
+
+
Copy ESB_HOME/repository/samples/resources/vfs/test.xml to the
+directory given in transport.vfs.FileURI above.
VFS transport listener will pick the file from in directory and
+send it to the Axis2 service. The request XML file will be moved to
+original directory. The response from the Axis2 server will be saved
+to out directory.
+
Note: Please make sure to uncomment "VFSTransportListener" and "VFSTransportSender" in the axis2 configuration.(axis2.xml)
Create a new test directory in the FTP server. Open
+ESB_HOME/repository/samples/synapse_sample_255.xml and edit the following
+values. Change transport.vfs.FileURI parameter value point to the test
+directory at the FTP server. Change outSequence endpoint address uri email
+address to a working email address. Values you have to change are marked with
+<!--CHANGE-->.
+
+
Start the Synapse configuration numbered 255: i.e. wso2esb-samples -sn 255
+
+
+
Copy ESB_HOME/repository/samples/resources/vfs/test.xml to the ftp
+directory given in transport.vfs.FileURI above.
+
+
VFS transport listener will pick the file from the directory in the ftp
+server and send it to the Axis2 service. The file in the ftp directory will
+be deleted. The response will be sent to the given email address.
After a few seconds (e.g. 30s), you should receive a POX response in your
+email account with the stock quote reply.
+
Note that in this sample we used the transport.mail.ContentType property to make sure
+that the transport parses the request message as POX. If you remove this property, you may still
+be able to send requests using a standard mail client if instead of writing the XML in the body of
+the message, you add it as an attachment. In that case, you should use .xml as a suffix
+for the attachment and format the request as a SOAP 1.1 message. Indeed, for a file with suffix
+.xml the mail client will most likely use text/xml as the content type, exactly
+as required for SOAP 1.1. Sending a POX message using this approach will be a lot trickier,
+because most standard mail clients don't allow the user to explicitly set the content type.
+ Objective: Demonstrate the usage of the FIX (Financial Information eXchange) transport with proxy services
+
+
+ Prerequisites:
+ You will need the two sample FIX applications that come with Quickfix/J
+ (Banzai and Executor). Configure the two applications to establish
+ sessions with the ESB. See
+ Configuring Sample FIX Applications
+
+ Open up the ESB_HOME/repository/samples/synapse_sample_257.xml file
+ and make sure that transport.fix.AcceptorConfigURL property points to the
+ fix-synapse.cfg file you created. Also make sure that transport.fix.
+ InitiatorConfigURL property points to the synapse-sender.cfg file you
+ created. Once done you can start the Synapse configuration numbered 257:
+ i.e. wso2esb-samples -sn 257. Note that the ESB creates a new FIX session with
+ Banzai at this point.
+
+
+ Send an order request from Banzai to the ESB.
+
+
+ WSO2 ESB will create a session with Executor and forward the order request. The
+ responses coming from the Executor will be sent back to Banzai.
+
+ Objective: Demonstrate switching from HTTP to FIX
+
+
+ Prerequisites:
+ You will need the Executor sample application that comes with Quickfix/J.
+ Configure Executor to establish a session with Synapse. See Configuring Sample FIX
+ Applications
+
+ Configure Synapse for FIX samples. See
+ Configuring Synapse for FIX Samples. There is no need to create the fix-synapse.cfg
+ file for this sample. Having only the synapse-sender.cfg file is sufficient.
+
+
+ Go to the ESB_HOME/repository/samples/synapse_sample_258.xml
+ file and make sure that transport.fix.InitiatorConfigURL property
+ points to the synapse-sender.cfg file you created. Once done you can
+ start the Synapse configuration numbered 258: i.e. wso2esb-samples -sn 258
+
+
+ Invoke the FIX Client as follows. This command sends a FIX message
+ embedded in a SOAP message over HTTP.
+
+
ant fixclient -Dsymbol=IBM -Dqty=5 -Dmode=buy -Daddurl=http://localhost:8280/services/FIXProxy
+
+ Synapse will create a session with Executor and forward the order request. The
+ first response coming from the Executor will be sent back over HTTP. Executor
+ generally sends two responses for each incoming order request. But since the
+ response has to be forwarded over HTTP only one can be sent back to the client.
+
+Objective: Demonstrate the capability of switching between FIX to HTTP
+
+Prerequisites:
+ You will need the sample FIX blotter that come with Quickfix/J (Banzai). Configure the blotter to establish sessions with Synapse. See
+Configuring Sample FIX Applications
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not already deployed
Open up the ESB_HOME/repository/samples/synapse_sample_259.xml file and make sure that transport.fix.AcceptorConfigURL property points to the fix-synapse.cfg file you created. Once done you can start the Synapse configuration numbered 259: i.e. wso2esb-samples -sn 259. Note that Synapse creates a new FIX session with Banzai at this point.
+
Send an order request from Banzai to Synapse. e.g. Buy DELL 1000 @ 100. User has to send a 'Limit' Order because price is a mandatory field for 'placeOrder' operation.
+
ESB will forward the order request to one-way 'placeOrder' operation on the SimpleStockQuoteService. ESB uses a simple XSLT mediator to transform the incoming FIX to a SOAP message.
+Objective: Demonstrate the capability of switching between FIX and AMQP protocols
+
+Prerequisites:
+ You will need the sample FIX blotter that comes with Quickfix/J (Banzai). Configure the blotter to establish sessions with Synapse. See
+Configuring Sample FIX Applications
Start the AMQP consumer, by switching to samples/axis2Client directory and running the consumer using the following command. Consumer will listen to the queue 'QpidStockQuoteService', accept the orders and reply to the queue 'replyQueue'.
+
ant amqpconsumer -Dpropfile=$ESB_HOME/repository/samples/resources/fix/direct.properties
Open up the ESB_HOME/repository/samples/synapse_sample_260.xml file and make sure that the transport.fix.AcceptorConfigURL property points to the fix-synapse.cfg file you created. Once done you can start the Synapse configuration numbered 260: i.e. wso2esb-samples -sn 260. Note that Synapse creates a new FIX session with Banzai at this point.
+
Send an order request from Banzai to Synapse. e.g. Buy DELL 1000 @ MKT.
+
Synapse will forward the order request by binding it to a JMS message payload and sending it to the AMQP consumer. AMQP consumer will send a execution back to Banzai.
+Objective: Demonstrate the capability of switching between FIX versions e.g. FIX4.0 to FIX4.1
+
+Prerequisites:
+ You will need the two sample FIX applications that come with Quickfix/J (Banzai and Executor). Configure the two applications to establish sessions with Synapse. See
+Configuring Sample FIX Applications.
+
Add the following lines to the Banzai configuration file (banzai.cfg).
+
DataDictionary=~/etc/spec/FIX40-synapse.xml
+
Note: FIX40-synapse.xml can be found at $ESB_HOME/repository/sampless/resources/fix. This is a custom FIX data dictionary file that has added tag 150,151 to the execution messages (35=8) of FIX4.0. Make sure the DataDictionary property of the banzai.cfg points to this data dictionary file.
+
Add the following lines to the Executor configuration file (executor.cfg).
Configure Synapse for FIX samples. We will be using two custom configuration files for Synapse in this sample. These two custom configuration files can be found at ESB_HOME/repository/conf/sample/resources/fix directory. The two files are called fix-synapse-m40.cfg and synapse-sender-m.cfg. You can point your Synapse configuration to these two files (this is already done in the supplied synapse_sample_261.xml file) or you may create copies of them and point the Synapse configuration to the copies. In either case make sure that the properties like FileStorePath and FileLogPath in the two files point to valid locations in your local file system.
+
Open up the $ESB_HOME/repository/samples/synapse_sample_261.xml file and make sure that transport.fix.AcceptorConfigURL property points to the fix-synapse-m40.cfg file described above and transport.fix.InitiatorConfigURL points to the synapse-sender-m.cfg file described above. Once done you can start the Synapse configuration numbered 261: i.e. wso2esb-samples -sn 261. Note that Synapse creates a new FIX session with Banzai at this point.
+
Send an order request from Banzai to Synapse. e.g. Buy DELL 1000 @ MKT.
+
Synapse will forward the order request from FIX4.0 to the Executor that accepts FIX4.1 messages. Executor will send an ack and an execution back to Banzai.
+Objective: Demonstrate the capability of CBR FIX messages
+
+Prerequisites:
+ You will need the two sample FIX applications that come with Quickfix/J (Banzai and Executor). Configure the two applications to establish sessions with Synapse. See
+Configuring Sample FIX Applications
+
Add the following lines to banzai.cfg.
+
DataDictionary=~/etc/spec/FIX40-synapse.xml
+
Note: FIX40-synapse.xml can be found at $ESB_HOME/repository/samples/resources/fix. This is a custom FIX data dictionary file that has added tag 150,151 to the execution messages (35=8) of FIX4.0. Make sure the DataDictionary property of the banzai.cfg points to this data dictionary file.
Open up the ESB_HOME/repository/samples/synapse_sample_262.xml file and make sure that transport.fix.AcceptorConfigURL property points to the fix-synapse.cfg file you created and transport.fix.InitiatorConfigURL points to the synapse-sender.cfg file you created. Once done you can start the Synapse configuration numbered 262: i.e. wso2esb-samples -sn 262. Note that Synapse creates a new FIX session with Banzai at this point.
+
Send an order request from Banzai to Synapse. e.g. Buy GOOG 1000 @ MKT, Buy MSFT 3000 @ MKT, Buy SUNW 500 @ 100.20
+
Synapse will forward the order requests with symbol 'GOOG' to FIX endpoint FIX-4.0 @ localhost:19876.
+
Synapse will forward the order requests with symbol 'MSFT' to FIX endpoint FIX-4.1 @ localhost:19877.
+
Synapse will not forward the orders with other symbols to any endpoint. (default case has kept blank in the configuration)
+Objective: Introduction to switching transports with proxy services. The JMS provider will be JBoss Messaging(JBM).
+
+Prerequisites:
+ Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps above)
+ Download, install and start JBM server, and configure Synapse to listen on JBM (refer notes below)
+ Start the ESB configuration numbered 263: i.e. wso2esb-samples -sn 263
+ We need to configure the required queues in JBM. Add the following entry to JBM jms configuration inside file-config/stand-alone/non-clustered/jbm-jms.xml.
+
Once you started the JBM server with the above changes you'll be able to see the following on STDOUT.
+
10:18:02,673 INFO [org.jboss.messaging.core.server.impl.MessagingServerImpl] JBoss Messaging Server version 2.0.0.BETA3 (maggot, 104) started
+
You also need to copy the jbm-core-client.jar, jbm-jms-client.jar, jnp-client.jar(these jars are inside $JBOSS_MESSAGING/client folder) and
+ jbm-transports.jar, netty.jar(these jars are from $JBOSS_MESSAGING/lib folder) jars from JBM into the $ESB_HOME/repository/components/lib directory. This was tested with JBM 2.0.0.BETA3
+
+
You need to add the following configuration for Axis2 JMS transport listener in axis2.xml found at repository/conf/axis2.xml.
Once you start ESB configuration 263 and request for the WSDL of the proxy service (http://localhost:8280/services/StockQuoteProxy?wsdl) you will notice that its exposed only on the JMS transport. This is because the configuration specified this requirement in the proxy service definition.
+
Before running the JMS client you need to open the build.xml ant script and uncomment the following block under the
+jmsclient target.
Now lets send a stock quote request on JMS, using the dumb stock quote client as follows:
+
ant jmsclient -Djms_type=pox -Djms_dest=StockQuoteProxy -Djms_payload=MSFT -Djava.naming.provider.url=jnp://localhost:1099 -Djava.naming.factory.initial=org.jnp.interfaces.NamingContextFactory -Djava.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+
On the ESB debug(you'll need to enable debug log in ESB) log you will notice that the JMS listener received the request message as:
+
[JMSWorker-1] DEBUG ProxyServiceMessageReceiver -Proxy Service StockQuoteProxy received a new message...
+
Now if you examine the console running the sample Axis2 server, you will see a message indicating that the server has accepted an order as follows:
+
Accepted order for : 16517 stocks of MSFT at $ 169.14622538721846
+
In this sample, the client sends the request message to the proxy service exposed over JMS in Synsape. Synapse forwards this message to the HTTP EPR of the simple stock quote service hosted on the sample Axis2 server.
+Note that the operation is out-only and no response is sent back to the client. The transport.jms.ContentType property
+is necessary to allow the JMS transport to determine the content type of incoming messages. With the given configuration
+it will first try to read the content type from the 'contentType' message property and fall back to 'application/xml'
+(i.e. POX) if this property is not set. Note that the JMS client used in this example doesn't send any content type information.
+
Note: It is possible to instruct a JMS proxy service to listen to an already existing destination without creating a new one. To do this, use the parameter elements on the proxy service definition to specify the destination and connection factory etc.
+ Objective: Demonstrate sending request response scenario with JMS transport
+
+
+ Prerequisites:
+ You need to set up ESB and axis2 server to use the JMS transport. See
+ Sample 251 for more details.
+
+
+ This sample is similar to the Sample 251. Only difference is we are expecting a response from the server. JMS transport uses transport.jms.ContentTypeProperty to
+ determine the content type of the response message. If this property is not set JMS transport treats the incoming message as plain text.
+
+
+ In the out path we remove the message context property TRANSPORT_HEADERS. If these property is not removed JMS headers will be passed to the client.
+
+
Start ESB using sample 264.
+
wso2esb-samples -sn 264
+
Start Axis2 server with SimpleStockService deployed
+
Invoke the stockquote client using the following command.
+
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dsymbol=MSFT
+
The sample Axis2 server console will print a message indicating that it has received the request:
+
Generating quote for : MSFT
+
In the client side it shoud print a message indicating it has received the price.
Objective: Using vfs transport to access a windows share
+
+
+
Prerequisites:
+You will need access a windows shared folder. Just create a folder(called 'test') on a windows machine
+and create three sub folders in, out and original inside that folder.Then assign the permission
+to the network users to read and write into the root 'test' folder and the folders inside that directory.
+
+Open ESB_HOME/repository/samples/synapse_sample_265.xml and edit the following values. Change transport.vfs.FileURI,
+transport.vfs.MoveAfterProcess, transport.vfs.MoveAfterFailure parameter values to the above in, original, original
+directories respectively. Change outSequence endpoint address uri to out directory with the prefix vfs:.
+Values you have to change are marked with <!--CHANGE-->.
+
+
+
Copy ESB_HOME/repository/samples/resources/vfs/test.xml to the directory given in transport.vfs.FileURI above.
+
+
Start the Axis2 server and deploy the SimpleStockQuoteService if not
+already done
+
+
Enable vfs transport receiver and the vfs transport sender in the ESB axis2.xml. Just uncomment the
+ VFSTransportListener and the VFSTransportSender in axis2.xml
+
+
Start the Synapse configuration numbered 265: i.e. wso2esb-samples -sn 265
+
+
+
VFS transport listener will pick the file from in directory and send it to the Axis2 service. The request XML
+file will be moved to original directory. The response from the Axis2 server will be saved to out directory.
Objective: Demonstrate receiving SOAP messages over TCP and forwarding them over HTTP
+
+
+
Prerequisites:
+You need to configure Synpase to use the TCP transport.The sample Axis2 client should also be setup to send TCP requests. Refer Setting Up the TCP Transport section in the sample setup guide for more details.
+Start Synpase using sample 266: ie synapse -sample 266
+Start Axis2 server with SimpleStockService deployed
+
+
+ This sample is similar to Sample 250 . Only difference is instead of the JMS transport we will be using the TCP transport to receive messages. TCP is not an application layer protocol. Hence there are no application level headers available in the requests. Synapse has to simply read the XML content coming through the socket and dispatch it to the right proxy service based on the information available in the message payload itself. The TCP transport is capable of dispatching requests based on addressing headers or the first element in the SOAP body. In this sample, we will get the sample client to send WS-Addressing headers in the request. Therefore the dispatching will take place based on the addressing header values.
+
+Invoke the stockquote client using the following command. Note the TCP URL in the command.
+
+
ant stockquote -Daddurl=tcp://localhost:6060/services/StockQuoteProxy -Dmode=placeorder
+
+ The TCP transport will receive the message and hand it over to the mediation engine. Synapse will dispatch the request to the StockQuoteProxy service based on the addressing header values.
+ The sample Axis2 server console will print a message indicating that it has received the request:
+
+
Thu May 20 12:25:01 IST 2010 samples.services.SimpleStockQuoteService :: Accepted order #1 for : 17621 stocks of IBM at $ 73.48068475255796
Objective: Demonstrate receiving SOAP messages over UDP and forwarding them over HTTP
+
+
+
Prerequisites:
+You need to configure Synpase to use the TCP transport.The sample Axis2 client should also be setup to send TCP requests. Refer Setting Up the TCP Transport section in the sample setup guide for more details.
+Start Synpase using sample 267: ie synapse -sample 267
+Start Axis2 server with SimpleStockService deployed
+
+
+ This sample is similar to Sample 266. Only difference is instead of the TCP transport we will be using the UDP transport to receive messages.
+
+Invoke the stockquote client using the following command. Note the TCP URL in the command.
+
+
ant stockquote -Daddurl=udp://localhost:9999?contentType=text/xml -Dmode=placeorder
+
+ Since we have configured the content type as text/xml for the proxy service, incoming messages will be processed as SOAP 1.1 messages.
+ The sample Axis2 server console will print a message indicating that it has received the request:
+
+
Thu May 20 12:25:01 IST 2010 samples.services.SimpleStockQuoteService :: Accepted order #1 for : 17621 stocks of IBM at $ 73.48068475255796
+
Objective: Proxy services with the Local transport
+
+
+
This sample contains three proxy services. The stockquote client invokes the LocalTransportProxy.
+ Then the message will be sent to the SecondProxy and then it will be sent to the StockQuoteProxy.
+ The StockQuoteProxy will invoke the backend service and return the response to the client.
+ In this sample, the communication between proxy services are done through the Local transport.
+ Since Local transport calls are in-JVM calls, it will reduce the time taken for the communication
+ between proxy services.
+
+
Prerequisites:
+Start the Synapse configuration numbered 268: i.e. wso2esb-samples -sn 268
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already done
+
+
Execute the stock quote client by requesting for a stock quote on the
+proxy service as follows:
+
ant stockquote -Daddurl=http://localhost:8280/services/LocalTransportProxy
Running the WSO2 Enterprise Service Bus (ESB) Samples
+
+
While the Samples Setup Guide
+document above gives you a generic description on how to set up and run
+the WSO2 ESB samples, this document takes each sample, one by one and
+discusses the objective of the sample, its prerequisites, and its expected
+behavior when the sample is built.
+
+
Note: The ESB configurations listed below, with each
+sample, is the raw source XML serialization of the sample configuration. This
+may be viewed graphically through the WSO2 ESB administration console after
+logging into the console.
WSO2 Enterprise Service Bus (ESB) Samples Setup Guide
+
+
Overview
+
+
The WSO2 ESB ships with a set of working examples that demonstrate some of
+the basic features and capabilities of itself. A set of sample clients and
+services are provided in addition to the sample configurations. Scripts are
+provided to execute the sample scenarios as explained below.
+
+
This document provides step-by-step instructions on how to install the
+pre-requisites, and set up the samples - generic instructions on how to start
+the sample server, deploy a service, and run the client.
You will need a Java development kit / JRE version 1.5.x or later and
+Apache Ant 1.7.0 or later, at a minimum, to try out the samples. Ant can be
+downloaded from http://ant.apache.org.
+The JMS examples can be executed against an ActiveMQ installation by default
+(or another JMS provider with configuration) and any HTTPS examples would
+require a JDK version 1.5 or later.
+
+
Once you setup ant go to the bin directory of the distribution and run
+the build.xml file which resides in that directory using ant. You could do this
+by typing 'ant' on a console in this directory.
+
+
Note*: The samples and the documentation assumes that you are running the
+ESB in DEBUG mode. You can switch from the default INFO log messages to DEBUG
+log messages by changing the line "log4j.category.org.apache.synapse=INFO" as
+"log4j.category.org.apache.synapse=DEBUG" in the
+lib/log4j.properties file.
+
+
Understanding the Samples
+
+
+
+
+
Client
+
WSO2 ESB
+
Service
+
+
+
ant stockquote
+
./wso2esb-samples.sh -sn <n>
+
SimpleStockQuoteService
+
+
+
+
+
SecureStockQuoteService etc.
+
+
+
+
+
The above table depicts the interactions between the clients, the ESB
+and services at a high level. The Clients are able to send SOAP/REST or POX
+messages over transports such as HTTP/HTTPS or JMS with WS-Addressing,
+WS-Security, or WS-Reliable messaging. They could send binary optimized
+content using MTOM or SwA or binary or plain text JMS messages. After
+mediation through the ESB, the requests are passed over to the sample
+services. The sample clients and services are explained below.
+
+
Using the Sample Clients
+
+
The sample clients can be executed from the samples/axis2Client directory
+through the provided Ant script. Simply executing 'ant' displays the
+available clients and some of the sample options used to configure them. The
+sample clients available are listed below:
+
+
1. Stock Quote Client
+
+
This is a simple SOAP client that could send stock quote requests, and
+receive and display the last sale price for a stock symbol.
customquote - sends a quote request in a custom format. The ESB would
+ transform this custom request into the standard stock quote request
+ format and send it to the service. Upon receipt of the response, it would
+ be transformed again to a custom response format and returned to the
+ client, which will then display the last sales price.
+
Note : See samples/axis2Client/src/samples/common/StockQuoteHandler.java
+for sample responses expected by the clients.
+
+
Smart Client Mode:
+
+
The 'addurl' property sets the WS-Addressing EPR, and the 'trpurl' sets a
+transport URL for a message. Thus by specifying both properties, the client
+can operate in the 'smart client' mode, where the addressing EPR could
+specify the ultimate receiver, while the transport URL set to the ESB ensures
+that any necessary mediation takes place before the message is delivered to
+the ultimate reciver.
+
+
e.g: ant stockquote -Daddurl=<addressingEPR> -Dtrpurl=<esb>
+
+
Gateway / Dumb Client Mode:
+
+
By specifying only a transport URL, the client operates in the 'dumb
+client' mode, where it sends the message to the ESB and depends on the ESB
+rules for proper mediation and routing of the message to the ultimate
+destination.
+
+
e.g: ant stockquote -Dtrpurl=<esb>
+
+
Proxy Client Mode:
+
+
In this mode, the client uses the 'prxurl' as an HTTP proxy to send the
+request. Thus by setting the 'prxurl' to the ESB, the client could ensure
+that the message would reach the ESB for mediation. The client could
+optionally set a WS-Addressing EPR if required.
+
+
e.g: ant stockquote -Dprxurl=<esb> [-Daddurl=<addressingEPR>]
+
+
Specifying a Policy
+
+
By specifying a WS-Policy using the 'policy' property, QoS aspects such as
+WS-Security could be enforced on the request. The policy specifies details
+such as timestamps, signatures, and encryption. See Apache Axis2 and Apache
+Rampart documentation for more information.
+
+
2. Generic JMS Client
+
+
The JMS client is able to send plain text, plain binary content, or POX
+content by directly publishing a JMS message to the specified destination.
+The JMS destination name should be specified with the 'jms_dest' property.
+The 'jms_type' property could specify 'text', 'binary' or 'pox' to specify
+the type of message payload.
+
+
The plain text payload for a 'text' message can be specified through the
+'payload' property. For binary messages, the 'payload' property would contain
+the path to the binary file. For POX messages, the 'payload' property will
+hold a stock symbol name to be used within the POX request for stock order
+placement request.
Note: The JMS client assumes the existence of a default ActiveMQ (5.2.0) installation on the
+ local machine.
+
+
3. MTOM / SwA Client
+
+
The MTOM / SwA client can send a binary image file as a MTOM or SwA
+optimized message, and receive the same file again through the response and
+save it as a temporary file. The 'opt_mode' can specify 'mtom' or 'swa'
+respectively for the above mentioned optimizations. Optionally, the path to a
+custom file can be specified through the 'opt_file' property, and the
+destination address can be changed through the 'opt_url' property if
+required.
+
+
e.g. ant optimizeclient -Dopt_mode=[mtom | swa]
+
+
Starting the Sample Services
+
+
The sample services ship with a pre-configured Axis2 server, and
+demonstrates in-only and in-out SOAP/REST or POX messaging over HTTP/HTTPS
+and JMS transports using WS-Addressing, WS-Security, and WS-Reliable
+Messaging. It also handles binary content using MTOM and SwA.
+
+
The sample services can be found in the samples/axis2Server/src directory
+and can be built and deployed using Ant from each service directory.
To start the Axis2 server, go to the samples/axis2Server directory and
+execute the axis2server.sh or axis2server.bat script. This starts the Axis2
+server with the HTTP transport listener on port 9000 and HTTPS on 9002
+respectively. To enable JMS transport, you will need to set up and start a
+JMS provider. An ActiveMQ 5.2.0 JMS server on the local machine is
+supported by default, and can be easily enabled by uncommenting the JMS
+transport from the repository/conf/axis2.xml
+
+
The Sample services are as follows:
+
+
1. SimpleStockQuoteService
+
+
This service has four operations, getQuote (in-out), getFullQuote(in-out),
+getMarketActivity(in-out) and placeOrder (in-only). The getQuote operation
+will generate a sample stock quote for a given symbol. The getFullQuote
+operation will generate a history of stock quotes for the symbol for a number
+of days, and the getMarketActivity operation returns stock quotes for a list
+of given symbols. The placeOrder operation will accept a one way message for
+an order.
+
+
2. SecureStockQuoteService
+
+
This service is a clone of the SimpleStockQuoteService, but has
+WS-Security enabled and an attached security policy for signing and
+encrypting messages.
+
+
3. MTOMSwASampleService
+
+
This service has three operations: uploadFileUsingMTOM(in-out),
+uploadFileUsingSwA(in-out) and oneWayUploadUsingMTOM(in-only), and also
+demonstrates the use of MTOM and SwA. The uploadFileUsingMTOM and
+uploadFileUsingSwA operations accept a binary image from the SOAP request as
+MTOM and SwA, and returns this image back again as the response, while the
+oneWayUploadUsingMTOM saves the request message to the disk.
+
+
Starting Sample ESB Configurations
+
+
To start the WSO2 ESB with the sample default configuration, execute the
+wso2server.bat or wso2server.sh script found in the /bin directory. This starts
+up an instance of the ESB using the Synapse and Axis2 configuration files
+located in the conf directory. The repository/samples directory contains
+the sample configurations available as synapse_sample_<n>.xml files. To
+start a specific sample configuration of the ESB, use the wso2esb-samples.sh or
+wso2esb-samples.bat as follows:
The samples used in this guide assumes the existence of a local
+ActiveMQ (5.1.0 or higher) installation, which is properly installed and started.
+
+
To enable the JMS transport, you need to uncomment the JMS transport
+listener configuration. If you are using a JMS provider other than ActiveMQ,
+this configuration should be updated to reflect your environment. Once
+uncommented, the default configuration should be as follows. To enable JMS
+for the ESB, the repository/conf/axis2.xml must be updated. To
+enable JMS support for the sample Axis2 server, the
+samples/axis2Server/repository/conf/axis2.xml file must be updated.
+
+
<!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)-->
+ <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
+ <parameter name="myTopicConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter>
+ </parameter>
+
+ <parameter name="myQueueConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+
+ <parameter name="default" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+ </transportReceiver>
+
+
Setting up Mail Transport Sender
+
+
To enable the mail transport sender for samples, you need to uncomment the mail
+transport sender configuration in the repository/conf/axis2.xml.
+Uncomment the mail transport sender sample configuration and make sure it
+points to a valid SMTP configuration for any actual scenarios.
To enable the mail transport receiver for samples, you need to uncomment the mail
+transport receiver configuration in the repository/conf/axis2.xml.
+Uncomment the mail transport receiver sample configuration. Note: you need to provide
+correct parameters for a valid mail account at service level.
+ To run the FIX samples used in this guide you need a local
+ Quickfix/J installation.
+ Download Quickfix/J from here.
+
+
+ Simply uncomment the FIX transport sender and FIX transport receiver configurations
+ in the repository/conf/axis2.xml. Alternatively if the
+ FIX transport management bundle is in use you can enable the FIX transport
+ listener and the sender from the WSO2 ESB management console. Login to the
+ console and navigate to 'Transports' on management menu. Scroll down to
+ locate the sections related to the FIX transport. Simply click on 'Enable'
+ links to enable the FIX listener and the sender.
+
+
+
+ Configuring the ESB for FIX Samples
+
+
+ In order to configure WSO2 ESB to run the FIX samples given in this
+ guide you will need to create some FIX configuration files as
+ specified below (You can find the config files from
+ $ESB_HOME/repository/conf/sample/resources/fix folder.
+
+
+ The FileStorePath property in the following two files should point
+ to two directories in your local file system. Once the samples
+ are executed, Synapse will create FIX message stores in these two
+ directories.
+
+
+ Put the following entries in a file called fix-synapse.cfg
+
+ If you are using a binary distribution of Quickfix/J, the two
+ samples and their configuration files are all packed to a
+ single jar file called quickfixj-examples.jar. You will have to
+ extract the jar file, modify the configuration files and pack
+ them to a jar file again under the same name.
+
+
+ You can pass the new configuration file as a command line parameter too, in that case you don't
+ need to modify the quickfixj-examples.jar.
+ You can copy the config files from $ESB_HOME/repository/conf/sample/resources/fix folder to
+ $QFJ_HOME/etc folder. Execute the sample apps from $QFJ_HOME/bin, ./banzai.sh/bat ../etc/banzai.cfg
+ executor.sh/bat ../etc/executor.sh.
+
+
+
+ Locate and edit the FIX configuration file of Executor to be as follows.
+ This file is usually named executor.cfg
+
+ The FileStorePath property in the above two files should point
+ to two directories in your local file system. The launcher scripts for
+ the sample application can be found in the bin directory of Quickfix/J
+ distribution.
+
+
+ For more information regarding the FIX sample applications please
+ refer the Example Applications section in the Quickfix/J
+ documentation. For more information on configuring Quickfix/J applications
+ refer the Configuring Quickfix/J section of the Quickfix/J
+ documentation.
+
+
+
+
+ Configure WSO2 ESB for AMQP Transport
+
+
+
+ The samples used in this guide assumes the existence of a local QPid
+ (1.0-M2 or higher) installation properly installed and started up. You also
+ need to copy the following client JAR files into the 'repository/components/lib' directory
+ to support AMQP. These files are found in the 'lib' directory of the
+ QPid installation.
+
+
+
qpid-client-1.0-incubating-M2.jar
+
qpid-common-1.0-incubating-M2.jar
+
geronimo-jms_1.1_spec-1.0.jar
+
slf4j-api-1.4.0.jar **
+
slf4j-log4j12-1.4.0.jar **
+
+
+ Note: To configure FIX (Quickfix/J 1.3) with AMQP (QPid-1.0-M2) copy the sl4j-* libraries comes with QPid and ignore the sl4j-*
+ libraries that come with Quickfix/J.
+
+
+ To enable the AMQP over JMS transport, you need to uncomment the JMS transport
+ listener configuration. To enable AMQP over JMS for ESB, the repository/conf/axis2.xml must be updated,
+ while to enable JMS support for the sample Axis2 server the
+ samples/axis2Server/repository/conf/axis2.xml file must be updated.
+
+
<!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment -->
+ <transportReceiver name="jms" class="org.apache.synapse.transport.jms.JMSListener">
+ </transportReceiver>
+
+ <transportSender name="jms" class="org.apache.synapse.transport.jms.JMSSender">
+ </transportReceiver>
+
+
+
+ Locate and edit the AMQP connection settings file for the message consumer, this fle is usually named direct.properties
+ and can be found in the repository/samples/resources/fix directory.
+
+ Locate and edit the AMQP connection settings file for WSO2 ESB, this fle is usually named con.properties
+ and can be found in the repository/samples/resources/fix directory.
+
+ To enable the TCP transport for samples first you need to download the Axis2 TCP transport jar
+ and copy it to the lib directory of Synapse. This library can be downloaded from the
+ WS-Commons Transports website. Then open up the axis2.xml file and uncomment the TCP transport
+ receiver and sender configurations:
+
+ If you wish to use the sample Axis2 client to send TCP messages, you have to uncomment the
+ TCP transport sender configuration in the samples/axis2Client/client_repo/conf/axis2.xml file.
+
+
+
+
+ Configure WSO2 ESB for UDP Transport
+
+
+
+ To enable the UDP transport for samples first you need to download the Axis2 UDP transport jar and
+ copy it to the lib directory of Synapse. This library can be downloaded from the
+ WS-Commons Transports website. Then open up
+ the axis2.xml file and uncomment the UDP transport receiver
+ and sender configurations:
+
+ If you wish to use the sample Axis2 client to send UDP messages, you have to uncomment the UDP
+ transport sender configuration in the samples/axis2Client/client_repo/conf/axis2.xml file.
+
+
+
+
+ Configuring WSO2 ESB for supporting JSON
+
+
+
+ JSON Then open up is a lightweight data-interchange format. It can be used as an alternative to XML or SOAP.
+ To enable the JSON support in Synapse, following two jar files should be deployed into the 'lib' directory of Synapse.
+ Having deployed the necessary libraries you should now register the JSON message builder and
+ formatter with Synapse. Open up 'repository/conf/axis2.xml' file of Synapse and add the following
+ two entries under the 'messageBuilders' and 'messageFormatters' sections respectively.
+
+ If you are planning to run sample 440, you should also add the above two entries to the
+ 'samples/axis2Client/client_repo/conf/axis2.xml' file.
+
+
+
+
Configuring the ESB for Script Mediator Support
+
+
The Script Mediator is a Synapse extension, and thus all pre-requisites
+for all BSF supported scripting languages may not be bundled by default with
+the ESB distribution. Before you use some script mediators, you may need to
+manually add the required .jar files to the lib
+directory('lib/extensions'), and optionally perform other installation
+tasks as may be required by the individual scripting language. This is
+detailed in the following sections.
+ You can download and install the JRuby engine manually. Download
+ the file named "jruby-complete-1.3.0.wso2v1.jar" from the WSO2 P2 repository and copy
+ it into repository/components/dropins directory.
+
CREATE table company(name varchar(10), id varchar(10), price double);
+
+
+ Inserts some data using following statements
+
INSERT into company values ('IBM','c1',0.0);
+ INSERT into company values ('SUN','c2',0.0);
+ INSERT into company values ('MSFT','c3',0.0);
+
+
+
+
When using Derby, you need to add derby.jar, derbyclient.jar and
+derbynet.jar to the classpath. This can be done by putting the above three
+jars into the ESB lib/extensions directory. For testing these samples Derby10.3.2.1
+binary distribution was used.
+
+
You can use any other database product instead of Derby. Then you have to
+change the database connection details accordingly. Also you have to copy the
+required database driver jars to the ESB classpath.
Definition of the reusable database connection pool or datasources can be
+done using datasources.properties file. It is possible to
+configure any number of datasources. Currently this only supports two types of
+datasources and those are based on Apache DBCP datasources. Those types are
+BasicDataSource and PerUserPoolDataSource (based on Apache DBCP). Following
+configuration includes both two definition. This configuration is related with
+sample 363.
+
+
Configuration is somewhat similar to the log4j appender configuration.
+
+
It requires two databases, follow the above specified (Setting up Derby
+Database server) steps to create the two databases
+'jdbc:derby://localhost:1527/lookupdb',
+'jdbc:derby://localhost:1527/reportdb' using the user name and
+password as 'esb'. Fill in the data for those two databases as
+per described in the above section
+
+
+
datasources.properties configuration
+
+
###############################################################################
+# DataSources Configuration
+###############################################################################
+synapse.datasources=lookupds,reportds
+synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory
+synapse.datasources.providerPort=2199
+# If following property is present , then assumes that there is an external JNDI provider and will not start a RMI registry
+#synapse.datasources.providerUrl=rmi://localhost:2199
+
+synapse.datasources.lookupds.registry=Memory
+synapse.datasources.lookupds.type=BasicDataSource
+synapse.datasources.lookupds.driverClassName=org.apache.derby.jdbc.ClientDriver
+synapse.datasources.lookupds.url=jdbc:derby://localhost:1527/lookupdb;create=false
+# Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider
+synapse.datasources.lookupds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler
+synapse.datasources.lookupds.username=esb
+# Depending on the password provider used, you may have to use an encrypted password here!
+synapse.datasources.lookupds.password=esb
+synapse.datasources.lookupds.dsName=lookupdb
+synapse.datasources.lookupds.maxActive=100
+synapse.datasources.lookupds.maxIdle=20
+synapse.datasources.lookupds.maxWait=10000
+
+synapse.datasources.reportds.registry=JNDI
+synapse.datasources.reportds.type=PerUserPoolDataSource
+synapse.datasources.reportds.cpdsadapter.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
+synapse.datasources.reportds.cpdsadapter.className=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
+synapse.datasources.reportds.cpdsadapter.name=cpds
+synapse.datasources.reportds.dsName=reportdb
+synapse.datasources.reportds.driverClassName=org.apache.derby.jdbc.ClientDriver
+synapse.datasources.reportds.url=jdbc:derby://localhost:1527/reportdb;create=false
+# Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider
+synapse.datasources.reportds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler
+synapse.datasources.reportds.username=esb
+# Depending on the password provider used, you may have to use an encrypted password here!
+synapse.datasources.reportds.password=esb
+synapse.datasources.reportds.maxActive=100
+synapse.datasources.reportds.maxIdle=20
+synapse.datasources.reportds.maxWait=10000
+
+
+
+
To secure data sources password, it is need to use the mechanism for
+securing secret Information. Please refer securing
+secret Information guide. If that mechanism is used, then passwords
+that have been specified are considered as aliases and those are used for
+picking actual passwords. To get password securely, it is needed to set the
+password provider for each data source. The password provider should be an
+implementation of
+org.apache.synapse.commons.security.secret.SecretCallbackHandler.
+There are few options and for more information please refer securing
+secret Information guide.
+
+
For run this sample, you just need to uncomment
+secret-conf.properties, cipher-text.properties and
+datasources.properties. Those files are in conf directory.
WSO2 Enterprise Service Bus (ESB), Securing Confidential Information
+
+
+ This guide describes how confidential information can be handled in a
+ secured manner in the ESB environment. From the context of the ESB
+ confidential information refers mainly to passwords. But confidential
+ information could be anything and hence instructions given in this guide
+ applies to all such confidential information elements.
+
+
+
Secret Providers
+
+
The word 'secret' is used to refer to anything which needs to be kept as a
+secret. Eventhough the current usage is limited to passwords, API supports any type of data. Secret
+retrieving is done through 'SecretCallbackHandler' implementations.
+Currently there are a few implementations and more implementations can be added as needed.
+
+
JBossEncryptionSecretCallbackHandler
+
+
+
This is the default implementation used within the JBoss Application Server to secure
+database passwords. It uses a hardcoded pass phrase (Need to use same pass phrase
+that have been used for encryption). Admin can encrypt passwords using a pass phrase
+and hard code that in the 'JBossEncryptionSecretCallbackHandler'
+and make the source code closed.
+
+
JlineSecretCallbackHandler
+
+
+
This is a command line based approach. Jline provides a way of reading passwords
+without echoing text - similar to jdk 6 scanners.
+
+
JMXSecretCallbackHandler
+
+
+
This is only supported in Synapse. With this we must use a JMX Console to provide
+secrets. This may be useful for any users that manage servers in a production
+environment using JMX.
+
+
HardCodedSecretCallbackHandler
+
+
+
Admin needs to hard code password and make source code closed. This can be used
+to just provide keystore passwords and other secrets can be retrieved using
+'SecretManagerSecretCallbackHandler' (described next)
+
+
SecretManagerSecretCallbackHandler
+
+
+
All secrets are managed using the Secret Manager. Secret Manager can keep
+any number of secret repositories. Those are arranged in a cascading manner. All
+secrets are stored in one place - secret repositories. Secrets can be accessed by
+providing aliases for them (no need to put encrypted values inline in
+application configurations). Key stores required by the Secret Manager and secret
+repositories are configurable. It can be done through the
+'secret-conf.properties'. Currently, there is only one secret
+repository and it is called the FileBaseSecretRepository. It uses cipher-text.properties
+to keep secrets. It keeps aliases vs. its actual secret in encrypted format
+(encrypted by a key in keystore)
+
+
Example
+
+
secret-conf.properties
+
############################################################################
+# Secret Securing Configuration
+############################################################################
+# The following property specifies a global password provider implementation
+# which will be used globally if not overriden in specific configurations
+#carbon.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
+#Examples:
+#carbon.secretProvider=org.apache.synapse.commons.security.secret.handler.SecretManagerSecretCallbackHandler
+#carbon.secretProvider=org.apache.synapse.commons.security.secret.handler.JMXSecretCallbackHandler
+#carbon.secretProvider=org.apache.synapse.commons.security.secret.handler.JlineSecretCallbackHandler
+#carbon.secretProvider=org.apache.synapse.commons.security.secret.handler.JBossEncryptionSecretCallbackHandler
+
+#Secret Repositories configuration
+
+secretRepositories=file
+secretRepositories.file.provider=org.apache.synapse.commons.security.secret.repository.filebased.FileBaseSecretRepositoryProvider
+secretRepositories.file.location=cipher-text.properties
+
+#KeyStores configurations
+
+keystore.identity.location=resources/security/wso2carbon.jks
+keystore.identity.type=JKS
+keystore.identity.alias=wso2carbon
+keystore.identity.store.password=wso2carbon
+#keystore.identity.store.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
+keystore.identity.key.password=wso2carbon
+#keystore.identity.key.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
+#keystore.identity.parameters=enableHostnameVerifier=false;keyStoreCertificateFilePath=/home/esb.cer
+
+keystore.trust.location=resources/security/client-truststore.jks
+keystore.trust.type=JKS
+keystore.trust.alias=wso2carbon
+keystore.trust.store.password=wso2carbon
+#keystore.trust.store.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
+
+
+
cipher-text.properties
+
+
aliases=esb
+
+# configuration per each plaintext
+esb.secret=M6U74dMVvRm4XFMczki2qZ6CsTvnUuRTjSditlACR5vTISSMI7F/mCTVJGOGdKJjij+VWVhBtmAOkElyvR9TwlUECnZ1o5DNsTK6l8je+9amc/ziTQLP3Q1tzm/Ex1pzHsG6jPGGrv3O0B9pZTfYFqRvlcNhM7Ve3WvA3ibs4Yk=
+esb.secret.alias=wso2carbon
+esb.secret.keystore=identity
+
+
For security operations (encrypt / decrypt), Secret Manager uses a KeyStore
+and securing the keystore passwords can be done by any of above mentioned ways.
+In the current implementation, there is only a one Secret Repository - A file
+based Secret Repository. It is possible to implements secret repositories based
+on database, directory servers, registry etc.
+
+
General API for Retrieving Secrets
+
+
Consider that an application has a configuration for passwords as
+
+
<datasource>
+ <password>pass</password>
+ <secretProvider>any implementation of SecretCallbackHandler- class name</secretProvider>
+ </datasource>
+
+
For JBossEncryptionSecretCallbackHandler, 'password' should
+contain an encrypted value. In any other case, it is just an alias- can keep
+any human readable text. For example in Secret Manger, actual password is in
+secret repositories. For file based repository, it is something like bellow.
All 'SecretCallbackHandlers' other than the
+'SecretManagerSecretCallbackHandler' are stateless enabling to be used
+without any additional code. With 'SecretManagerSecretCallbackHandler',
+it is best if there is only one 'SecretManager' instance. More
+precisely, a single 'SecretManagerSecretCallbackHandler' instance.
+For this, there is a carbon module called 'secretvault'. It just reads
+'secret-conf.properties' and initiates a new
+'SecretCallbackHandler' instance. This can be a
+'SecretManagerSecretCallbackHandler' or any other
+'SecretCallbackHandlers' instance that needs to be shared
+globally. To acccess this instance one must follow the instuctions
+given below.
+The annotations at the top are required and the Maven SCR plugin must be used to build the code. Please refer
+Maven 2 documentation on how to use the Maven SCR plugin. SCR plugin generates OSGi declarative service
+descriptors by parsing the scr annotations stated in the source files.
+
+
+
Logic on Set
+
+
If the secret that needs to be resolved can be accessed directlym, for example
+passing as an argument, you can use the following logic.
Now you can pass either an actual password or a SecretProvider or
+SecretInformation to the code location that uses the password. But if the code that
+performs secret resolution can not be accessed, for example, when using a configuration
+such as follows - you cannot pass resolved password directly.
+
+
<datasource>
+ <password>pass</password>
+ <secretProvider>any implementation of SecretCallbackHandler- class name</secretProvider>
+ </datasource>
+
+
You have to do following if the scenario is similar to the above.
Then you have to specify secretProvider in the configuration
+as
+org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler.
+This is another SecretCallbackHandler that uses the handler
+set in the SharedSecretCallbackHandlerCache. You need to
+use Retrieving API. What we do here is using OSGI services in order
+to share across any component and use the Singleton pattern to share across classes in a
+single component and enable using the Retrieving API as it is.
+
+
Ciphertool
+
+
This is a simple tool to encrypt and decrypt simple texts.There are scripts
+named ciphertool.sh & ciphertool.bat available in the bin directory to launch the tool. The arguments
+accepted by this tool with their meanings are shown bellow.
+
+
keystore - If keys are in a store , its location
+
storepass - Password to access keyStore
+
keypass - To get private key
+
alias - Alias to identify key owner
+
storetype - Type of keyStore, Default is JKS
+
keyfile - If key is in a file
+
opmode - encrypt or decrypt , Default is encrypt
+
algorithm - encrypt or decrypt algorithm , Default is RSA
+
source - Either cipher or plain text as an in-lined form
+
outencode - Currently base64 and used for encoding the result
+
inencode - Currently base64 and used to decode input
+
trusted - Is KeyStore a trusted store? If this argument is provided, consider as a
+ trusted store
+
passphrase - if a simple symmetric encryption using a pass phrase shall
+ be used
A sequence is the basis of message mediation. A sequence is a collection of
+mediators. Sequence editor allows creation of sequences from the UI. Sequences
+can be created as named sequences and refer later from other parts of ESB
+configuration. Some configurations expects sequences to be defined in the place
+they are used. We call this type of sequences inline sequences. Sequence editor
+is used in both these cases for creating a sequence.
+
+
Sequence List
+
+
Use the Mediation
+Sequences page to add new sequences or edit existing sequences. As shown
+in Figure,1 the sequence management section displays a list of existing
+sequences.
+
+
+
+
+
+
Figure 1: Mediation sequence management
+
+
+
+
In the navigator, under Manage/Mediation, click Sequences. The Mediation Sequences
+page appears.
+
+
Enable Statistics
+
+
Click Enable Statistics to
+ gather information relating to a particular sequence.
+
+
+
Enable Tracing
+
+
Click Enable Tracing to turn
+ on all trace messages for the corresponding sequence
+
+
+
+
+
The above options are turned off by default because they cause a severe
+performance degradation. Use these options only in a situation where you have
+to debug a particular problem.
+
+
Edit
+
+
Click Edit to open the
+ sequence in the design view for editing purposes.
+
+
+
Delete
+
+
Click Delete to remove a
+ particular sequence from the system.
+
+
+
+
+
+
+
Adding a Sequence
+
+
On the Mediation Sequences
+ page, click Add Sequence. The Design Sequence page
+ appears.
+
Enter a sequence name.
+
Click Add Child, and select the required nodes for your
+ sequence.
+
+
+
+
+
Figure 2: Add sequence design view
+
+
Editing a sequence
+
+
On the Mediation
+ Sequences page, click Edit.
+ The Design
+ Sequence page appears, displaying the selected sequence.
+
Click on the node you want edit. The
+ properties for that node will be displayed below.
+
+
+
+
+
Figure 3: Editing a sequence
+
+
+
+
Figure 4: Editing node specific properties
+
+
You can edit the node specific attributes displayed in the Design view.
+
+
You can add a sibling node, in the Design view..
+
You can add only siblings to some nodes, while you can also add a child
+ node to others.
+
You can move the selected node up or down using the arrow icons.
+
You can also delete the node.
+
+
+
Click switch to source view to view
+the XML of the particular sequence. If you're familiar with the Synapse
+configuration language you can edit the XML directly. After editing you can
+save the sequences by clicking the save button. If you click on swith
+to design view source will be saved before going to the graphical
+view.
+
+
+
+
+
+
Figure 5: Source view of the sequence editor
+
+
diff --git a/docs/xdoc/setting_java_home.xml b/docs/xdoc/setting_java_home.xml
new file mode 100644
index 0000000000..c2834945e9
--- /dev/null
+++ b/docs/xdoc/setting_java_home.xml
@@ -0,0 +1,51 @@
+
+
+
+
+
+
+
+ How to setup JAVA_HOME environment variable in Windows
+
+
+
How to setup JAVA_HOME environment variable in Windows
+
+
Please follow the instructions to set up JAVA_HOME environment variable in your computer.
+ First find out the installation folder of Java development kit (JDK) in your machine.
+ Let's
+ assume it is installed in the folder "C:/j2sdk1.4.2"
+
+
+
+
Right click on the My Computer icon on your desktop and select properties
+
Click the Advanced Tab
+
Click the Environment Variables button
+
Under System Variable, click New
+
Enter the variable name as JAVA_HOME
+
Enter the variable value as the install path for the Development Kit
+
Click OK
+
Click Apply Changes
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/xdoc/source-repository.xml b/docs/xdoc/source-repository.xml
new file mode 100644
index 0000000000..a7e0eebf4d
--- /dev/null
+++ b/docs/xdoc/source-repository.xml
@@ -0,0 +1,133 @@
+
+
+
+
+
+
+
+
+ WSO2 ESB - Source Repository
+
+
+
+ [ Documentation Index ]
+
WSO2 Enterprise Service Bus (ESB) Source Repository
+ WSO2 ESB is developed on top of the revolutionary WSO2 Carbon platform. You might need the
+ source of the Carbon platform as well apart from the ESB source code. Please note that both
+ ESB and the Carbon platform is open source and the code is available under the Apache
+ Software License v2.0.
+
+
This code base contains the ESB product source code inside the directory "product" and
+ it also contains the source for the platform under the directory "carbon-pltform". Further
+ there will be a "build.sh" script to build the ESB with the platform.
+
+
This script accepts any of the maven related system properties, but the property to skip
+ the tests has been shortned to "-ts", for example to build the ESB with the platform on
+ skipping tests the command is;
+
+
+
$ ./build.sh -ts
+
+
+
To build off-line with this build script you can pass in the "-o" option. If you just
+ need to build either the product or a specific part of the platform (for example Synapse)
+ you just need to traverse to that directory and use maven to build any of the projects.
+
+
Source code of the WSO2 ESB trunk
+
Everyone can access the Subversion repository via HTTPS, but Committers must checkout
+ the Subversion repository via HTTPS.
+
The Carbon project is the root project of the OSGi platform on whcih all the Java
+ product stack is built on top of, and the carbon-components contains all the components
+ not just ESB specific components. So you obviously need to build just the set of
+ components required by the ESB, which can be achieved through;
+
+
+
+
$ mvn clean install -Dproduct=esb
+
+
+
To commit changes to the repository, execute the following command (svn will prompt
+ you for your password)
+
+
+
$ svn commit --username your-username -m "A message"
+
+
+
Access from behind a firewall
+
For those users who are stuck behind a corporate firewall which is blocking http access
+ to the Subversion repository, you can try to access it via the developer connection:
+
The Subversion client can go through a proxy, if you configure it to do so.
+ First, edit your "servers" configuration file to indicate which proxy to use. The
+ files location depends on your operating system. On Linux or Unix it is
+ located in the directory "~/.subversion". On Windows it is in "%APPDATA%\Subversion".
+ (Try "echo %APPDATA%", note this is a hidden directory.)
+
+
There are comments in the file explaining what to do. If you don't have that file, get
+ the latest Subversion client and run any command; this will cause the configuration
+ directory and template files to be created.
+
+
Example : Edit the 'servers' file and add something like :
ESB configuration language is a very powerful and robust way of driving enterprise
+data/messages through ESB mediation engine. However your requirements can become
+such that very large amount of configuration files in the form of sequences,
+endpoints ,proxies and transformations would be required to satisfy all the
+mediation requirements of your system. In such cases number of configuration files
+will be scattered all over and would be extremely hard to manage. What would be
+frustrating to note is that , most of the configurations of particular types are
+redundant in nature.
+
ESB Templates try to minimize this redundancy 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 where-as, a template is a class that can be used to wield
+instance objects such as templates and endpoints. Thus ESB Templates is an ideal
+way to improve re-usability and readability of ESB configurations/xml s. Addition
+to that users can utilize predefined Templates that reflect commonly used EIP
+patterns for rapid development of ESB message/mediation flows.
+
+
+
Templates
+
ESB templates comes in two different forms.
+
+
+
+
Sequence Templates
+
This defines a templated form of a ESB sequence. Sequence
+ Template has the ability to parameterize xpath expressions used
+ within a sequence defined inside a template. We invoke a Sequence
+ Template with a mediator named call-template by passing parameter
+ values
+ ie:-
+
+
Defines a templated form of an endpoint. Endpoint Template has
+ the ability to parameterize a endpoint defined within it.
+ Invoking a template of this kind is achieved using a template
+ Endpoint
+ ie:-
+
+Template is a parametrized sequence defined in ESB. Parameters of a template are defined in the form
+of xpath statement/s.
+Callers can invoke such a template by populating parameters with static values /xpath expressions . We call such an artifact, Call-Template mediator.
+
+
+
In other words template sequence is an abstract/generic form of a ESB sequence. Only a call template mediator can make
+a sequence template in to a concrete sequence. Let's illustrate this with a simple example. Suppose we have a sequence which
+logs hello world in four different languages. You would do that in ESB in following way,
Instead of printing our hello world message for each and every language inside the sequence, we can create a generalized template of this
+actions which will accept any greeting message(from a particular language) and log it on screen. For example we can create the following template, which
+you may name "HelloWorld_Logger".
With our "HelloWorld_Logger" in place, call-template mediator can populate this template with actual hello world messages and execute
+ the sequence of actions defined within the template like with any other sequence. This is illustrated below
Note how call template mediator/s point to the same template "HelloWorld_Logger" and pass different arguments to it. This way sequence templates make it easy to
+stereotype different workflows inside ESB.
+
+
+
Syntax
+
<template name="string">
+ <!-- parameters this sequence template will be supporting -->
+ (
+ <parameter name="string"/>
+ ) *
+ <!--this is the in-line sequence of the template -->
+ <sequence>
+ mediator+
+ </sequence>
+ </template>
+
+sequence template is a top level element defined with the name attribute in ESB
+configuration. Both endpoint and sequence template starts with a template element.
+Parameters (ie:-<parameter>) are the inputs supported by this sequence template .
+These sequence template parameters can be referred by a xpath expression defined
+inside the in-line sequence. For example parameter named 'foo' can be referred
+by a property mediator (defined inside the in-line sequence of the template) in
+following ways
+
+Note the scope variable used in the xpath expression. We use function scope or
+?func? to refer to template parameters. Only through this parameter name, we can
+refer to a particular parameter value passed externally by a invoker such as call-
+template mediator. WSO2 Management console UI provide easy way of adding these parameters. An example is
+shown below.
<call-template target="string">
+ <!-- parameter values will be passed on to a sequence template -->
+ (
+ <!--passing plain static values -->
+ <with-param name="string" value="string" /> |
+ <!--passing xpath expressions -->
+ <with-param name="string" value="{string}" /> |
+ <!--passing dynamic xpath expressions where values will be compiled
+dynamically-->
+ <with-param name="string" value="{{string}}" /> |
+ ) *
+ <!--this is the in-line sequence of the template -->
+ </call-template>
+
+
call-template mediator should define a target template it should be invoking ,
+with 'target' attribute.
+
<with-param> element is used to parse parameter values to a target sequence
+template. Note that parameter names has to be exact match to the names specified
+in target template. Parameter element can contain three types of parameterized
+values. xpath values are passed in within curly braces (ie:- {}) for value
+attribute. Special type of xpath expressions can be declared in double curly
+braces. These xpath expressions will be evaluated dynamically (others are
+evaluated before invoking a template or outside the template ) .
+
+
Please note that this is currently
+only supported for special type of mediators such as iterator and aggregate mediator, where actual
+xpath operations are made on a different soap message than the message coming in
+to the mediator. Following shows how users can declare parameters inside call-template mediator UI
+
+
+
+
+
Figure 2: Passing Values with Call Template Mediator
+
Endpoint Template Configuration
+
Endpoint Template is a generalized form of endpoint configuration used in ESB. Unlike sequence
+templates , endpoint templates are always parameterized using '$' prefixed values (ie:- NOT xpath expressions).
+
Template Endpoint is the artifact that makes a template of endpoint type into a concrete endpoint. In other words an
+endpoint template would be useless without a Template Endpoint referring to it.
+This is semantically similar to the relationship between a Sequence template and a Call-template mediator.
+For example lets say we have two default endpoints with following hypothetical configurations,
We can see that these two endpoints have different set of error codes and different progression factors for suspension. Futhermore number of retries are different between them. By defining a endpoint template we can converge these
+ two endpoints to a generalized form. This is illustrated in the follwoing (Note how '$' is used to paramaeterize configuration and $name is a implicit/default parameter) ,
Since we have a template defined we can use template endpoints to create two concrete endpoint instances with different parameter values for this scenario.
+ This is shown below.
As with call-template mediator , above template endpoint will stereotype endpoints with customized configuration parameters.
+ This makes it very easy to understand and maintain certain ESB configurations and improves reusability in a certain way.
+
+
Syntax
+
<template name="string">
+ <!-- parameters this endpoint template will be supporting -->
+ (
+ <parameter name="string"/>
+ ) *
+ <!--this is the in-line endpoint of the template -->
+ <endpoint [name="string"] >
+ address-endpoint | default-endpoint | wsdl-endpoint | load-balanced-
+endpoint | fail-over-endpoint
+ </endpoint>
+</template>
+
+
Similar to sequence templates ,endpoint templates are defined as top level element
+(with the name specified by the name attribute )of ESB configuration
+Parameters (ie:-<parameter>) are the inputs supported by this endpoint template .
+These endpoint template parameters can be referred by $ prefixed parameter name.
+For example parameter named 'foo' can be referred by $foo. Most of the parameters
+of the endpoint definition can be parametrized with $ prefixed values. This is
+shown in the following extract,
Note $name and $uri are default parameters that a template can use anywhere within
+the endpoint template (usually used as parameters for endpoint name and address
+attributes). Following figure shows, how a endpoint template design page is rendered in WSO2 Management console
+ UI.
+
+
+
+
+
Figure 3: Designing an Endpoint Template
+
+
Template Endpoint
+
Syntax
+
<endpoint [name="string"] [key="string"] template="string">
+ <!-- parameter values will be passed on to a endpoint template -->
+ (
+ <parameter name="string" value="string" />
+ ) *
+</endpoint>
+
Template endpoint defines parameter values that can parameterize endpoint . The 'template' attribute
+points to a target endpoint template.
+
As in the endpoint template , Note that parameter names has to be exact match to
+the names specified in target endpoint template. UI for a template endpoint is depicted below
+
+ Transaction plays a major role in today's business world. It adds a very important functionality to your
+ system, which you will only see in a system crash. Having a good transactional support will
+ ensure correct functionality in a system crash. This guide describes the transaction support avilable
+ in WSO2 ESB.
+
+
+
+ Transaction mediator
+
+
A new synpase mediator (transaction mediator) has been added to support the distributed transactions
+ using Java transaction API(JTA). JTA allows applications to perform a distributed transaction that
+ is, transactions that access and update data on two or more networked computer resources (an example would
+ be to have two databases or a database and a message queue such as JMS). This mediator can be used to
+ perform a distributed transaction. The synapse configuration has been extended to add explicit transaction
+ markers. What this means is you can use the synpase configuration language to define the start, end etc..,
+ of your transaction. It's the responsibility of the user to define when to start, commit or rollback the
+ transaction. For example we can mark the start of a transaction at the start of a database commit and end
+ of the transaction at the end of the database commit and we can mark rollback transaction if a failure occurs.
+
+
+ Transaction mediator configuration
+
+
+ Transaction mediator has the following configuration
+
Create a new jta transaction. Generate a fault if a transaction already exist.
+
+
+
use-existing-or-new
+
Create a new jta transaction. Do nothing if a transaction exist.
+
+
+
fault-if-no-tx
+
Generate a fault if no transaction exist. Do nothing if a transaction exist.
+
+
+
commit
+
Commit transaction. Generate a fault if no transaction exist.
+
+
+
rollback
+
Rollback transaction. Generate a fault if no transaction exist.
+
+
+
suspend
+
Suspend transaction. Generate a fault if no transaction exist.
+
+
+
resume
+
Resume transaction. Generate a fault if no transaction exist.
+
+
+
To use the transaction mediator you need to have a JTA provider in your environment. What this mean is you
+ need to deploy WSO2 ESB in an application sever which provide the JTA service. JBoss is an example of such
+ application server. Refer the Reference section to see how you can deploy ESB on JBoss.
+
An example is avilable in the article(see Reference section) which demostrate the
+ distributed transaction support.
+
+
+
Java Message Service(JMS) transactions
+
In addition to the distributed transactions, WSO2 ESB also has the support for JMS transactions. The JMS
+ transport which ships with WSO2 ESB has the support for both local and distrbuted transactions.
+
+ A local transaction represents a unit of work on a single connection to a data source managed by a resource
+ manager. In JMS, we can use the JMS API to get a transacted session and call methods for commit or rollback
+ for the relevant transaction objects. This is managed internal to a resource manager. There is no external
+ transaction manager involved in the coordination of such transactions
+
+
JMS local transaction configuration
+
To start a local JMS transaction you defined following property in JMS transport Listner/Sender in axis2.xml
By default the sesstion is not transacted and if you want to use JMS local transaction set the above parameter
+ to true. And you need to set the following property in synpase fault handler to rollback the transaction in
+ case of a failure.
+
WSO2 ESB also has the support for distributed JMS transaction. You can use JMS transport with more than one
+ distributed resources( for example a JMS queue and a remote database server).
+
Transaction mediator can be used to mark a distributed transaction which involves a distrbution transaction
+ which span through mulitple JMS resources.
+
The article contains a sample on JMS distributed transaction(see Reference
+ section).
+ The User Guide describes how to configure WSO2 ESB using the
+ Web based management console. The WSO2 Management Console has been tested
+ on the Mozilla Firefox 2.0, 3.0 and Internet Explorer 6.0, 7.0 Web Browsers at a
+ resolution of 1024x768.
+
+ Please refer the Installation Guide
+ for details on how to install and run the WSO2 ESB.
+
+
+
+
+
+ Accessing the ESB Web based Management Console
+
+
+ Once WSO2 ESB has been successfully installed and started, launch a Web
+ browser instance and point it to the URL https://localhost:9443/carbon.
+ This will take you to the Sign In page of the WSO2 ESB
+ Management Console.
+
+
+ Signing In
+
+
+ Enter your user name and password to log on to the ESB Management Console.
+
+
+ The default username / password is : admin / admin
+
+
+ You can change your password using the instructions
+ given below.
+
+
+ If you get any errors when trying
+ to sign in, click Sign-in Help. A list of
+ possible errors, their descriptions and solutions will be displayed.
+
+
+ Changing Your User Name and Password
+
+
+ You can change the default password using user management. Click on User Management menu
+ from left.
+
+
+ Please refer the documentation on managing
+ users for details.
+
+
+ Icons and Descriptions
+
+
+
+
+
+ Icon
+
+
+ Description
+
+
+
+
+
+
+
+ Add - Click this icon to add an item. Most
+ often clicking on this icon gives a submenu from which you can
+ select an element.
+
+
+
+
+
+
+
+ Edit - Click this icon to modify an
+ existing item.
+
+
+
+
+
+
+
+ Delete - Click this icon to permanently
+ delete an item. A message will appear prompting you to confirm the
+ deletion.
+
+
+
+
+
+
+
+ Registry Browser - Click this icon to view
+ the registry browser. You can select elements from the local
+ registry as well as the integrated registry, as both registries are
+ displayed in the browser. Also user has the option of choosing from
+ the Governance registry as well as from the Configuration registry.
+
+
+
+
+
+
+
+ Namespace Editor - Click this icon to open
+ the Namespace Editor dialog box.
+
+
+
+
+
+
+
+ Disable Statistics - This icon indicates
+ that statistics generation is in progress. Click this icon to stop
+ statistics generation for the respective element.
+
+
+
+
+
+
+
+ Enable Statistics - This icon indicates
+ that statics are not been generated at present. Click this icon to
+ start statistics generation for the respective element.
+
+
+
+
+
+
+
+ Disable Tracing - This icon indicates that
+ message tracing is in progress. Click this icon to stop tracing for
+ the respective element.
+
+
+
+
+
+
+
+ Enable Tracing - This icon indicates that
+ messages are not been traced at present. Click this icon to start
+ tracing messages for the respective element.
+
+
+
+
+
+
+
+ Proxy Service - This icon will be used to denote
+ Proxy Services on the services listing page.
+
+
+
+
+
+
+
+ Context-sensitive Help - To learn about a
+ feature, click this icon. A context-sensitive help window will pop up.
+
+
+
+
+
+
+ Common Screens and Dialog Boxes
+
+
+
+ Registry Browser - This dialog box is invoked
+ from the Pick from Registry option. The Registry
+ Browser contains elements from the integrated registry and the local
+ registry.
+
+
+
+
+
+
+
+ Add Namespace - This dialog box is invoked by
+ clicking Namespaces link from the configuration section
+ of mediators. XML namespaces provide a simple method for qualifying
+ an element and attribute names used in Extensible Markup Language
+ documents by associating them with namespaces identified by URI
+ references. Enter a prefix and the URI which it identifies.
+
+
+
+
+
+
+ Managing the underlying Synapse Configuration
+
+
+ The Synapse configuration
+ language consists of endpoints, sequences, registry entries,
+ tasks, proxy services and more. Messages coming into ESB are processed by the
+ underlying Synapse engine through mediation sequences and delivered to the
+ specified endpoints. In addition, scheduled tasks may inject new messages
+ into the ESB periodically or execute other tasks.
+
+
+ Proxy Services
+
+
+ Proxy services define virtual services hosted on the ESB that can accept
+ requests, mediate them, and deliver them to an actual service. Proxy
+ services could perform transport or interface switching and expose
+ different semantics than the actual service, i.e., WSDL, policies, and QoS
+ aspects like WS-RM, WS-Security, etc.
+
+
+
+ Adding a Proxy Service
+
+
+ This function allows you to add a proxy service. Please refer
+ Adding a Proxy Service for details.
+
+
+ Proxy Service Actions
+
+
+ You can edit, delete, enable statistics, start and stop the proxy service,
+ and enable tracing for the proxy service as described below. All existing
+ proxy services will be displayed in the services listing page with a special
+ icon been used to denote Proxy Services. Clicking on the name of a Proxy Service
+ there will take you to configurations specific to that service. The proxy
+ service actions are initiated by clicking on the respective links that could be
+ found in the in the table.
+
+
+
+
+
+
+
+ Please refer the documentation of
+ the service listing page for general configurations that could be done on a proxy service.
+
+
+ Proxy Service specific configurations
+
+
+
+ Edit Proxy Service
+
+
+ Use this function to modify existing proxy services.
+
+
+
+ In the Specific Configuration section of the Proxy Service
+ click the Edit link. The proxy service page will be displayed.
+
+
+
+ Redeploy Proxy Service
+
+
+ Use this function to redeploy the proxy service.
+
+
+
+ In the Specific Configuration section of the Proxy Service
+ click the Redeploy link. This will redeploy the proxy service.
+
+
+
+ Enable Statistics
+
+
+ Use this function to generate statistics for the proxy services.
+
+
+
+ In the Specific Configuration section of the Proxy Service
+ click the Enable Statistics link.
+
+
+
+
+
+ Enable Tracing
+
+
+ Use this function to enable tracing for the proxy services.
+
+
+
+ In the Specific Configuration section of the Proxy Service
+ click the Enable Tracing link.
+
+
+
+
+
+ Scheduled Tasks
+
+
+ The built-in Quartz scheduler lets administrators schedule tasks to run at
+ specified intervals. Tasks may be used to initiate long-running tasks,
+ automate recurring processes and facilitate reporting etc. The tasks are
+ simple Java classes that must implement org.apache.synapse.startup.Task
+ interface that just defines a single 'public void execute();' method. A
+ Task may thus use the ESB/Apache Synapse APIs to poll external services,
+ inject messages into the ESB or perform any task that could be implemented
+ in Java.
+
+
+ Please refer the
+ documentation on scheduled tasks for details.
+
+
+ Endpoints
+
+
+ An endpoint is a specific destination for a message. It may be specified
+ as an Address endpoint, WSDL endpoint, a fail over group, or a load balance
+ group.
+
+
+ Endpoints can be added, edited, and deleted. You can also enable
+ statistics for Address and WSDL endpoints.
+
+
+ Please refer the documentation on
+ endpoints for details.
+
+
+ Sequences
+
+
+ A sequence element is used to define a sequence of mediators that can be
+ invoked later as a sequence. If the configuration defines a sequence named
+ Main, then it is considered as the main mediation sequence of the ESB. If
+ such a sequence is not defined locally, and a registry has been specified,
+ the registry is looked up for a key named "main" to find the main mediator
+ sequence. If User doesn't define a main or fault sequence ESB will create default sequences.
+
+
+ Please refer the documentation on managing
+ sequences for details.
+
+
+
+ Message Stores
+
+
+ A Message Store element is used to define a Message store that can be used to store ESB
+ Messages. Store mediator can be used to store the messages in a message store.Message processor
+ associated with Message store can be used to implement different messaging patterns.
+
+
+ Associated Message processors can be used to consume messages from message stores and do processing.
+
+
+ Users can create there own message store implementations and use it. WSO2 ESB ships with in memory
+ message store and a jms message store.
+
+
+ Please refer the
+ documentation
+ on managing
+ Message stores for details.
+
+
+ Message Processor
+
+
+ A sequence element is used to define a Message Processor which can be used to process messages
+ in an associated message store.
+
+
+ Please refer the
+ documentation
+ on managing
+ sequences for details.
+
+
+ Local Registry Entries
+
+
+ The local registry entries are used to locally define resources such as
+ scripts, schemas, WSDLs, policies and other resources in a configuration.
+ They are not uploaded or fetched from the Integrated Registry. They are
+ static. An entry that exists in the local registry has higher precedence
+ over an entry with the same name that exists in the integrated registry.
+
+
+ Adding a Local Registry Entry
+
+
+
+ Click Local Entries on the navigator.
+
+
+ In the Manage Local Registry Entries pane, you can choose the type of
+ local entry you want and click Add of each entry to add a
+ one.
+
+
+
+
+
+
+
+
+
+ In-Lined Text
+
+
+
+
+
+ Enter a name for the entry.
+
+
+ In the Value field, specify the property
+ values
+
+
+ Click Save.
+
+
+
+ In-Lined XML
+
+
+
+
+
+ Enter a name for the XML entry.
+
+
+ In the Value field, enter the XML code.
+
+
+ Click Save.
+
+
+
+ Source URL
+
+
+
+ Enter a name of the source file.
+
+
+ In the Value field, specify the location of
+ the source file as a URL.
+
+
+ Click Save.
+
+
+
+
+ Local Registry Actions
+
+
+ You can edit and delete previously entered local registry entries. All
+ existing local registry entries will be displayed in the Registry Entries
+ table. The registry actions are initiated by clicking on the respective
+ icons in the table.
+
+
+
+
+
+
+
+
+ Edit Local Registry Entry
+
+
+ Use this option to modify registry entries.
+
+
+
+ In the Actions column of the Registry table,
+ click the corresponding Edit icon of the entry you want to edit. The
+ registry entry page will be displayed.
+
+
+ Make the necessary changes and click Save.
+
+
+
+ Delete Local Registry Entry
+
+
+ Use this function to delete registry entries that have been entered
+ previously.
+
+
+
+ In the Actions column of the Registry table,
+ click the corresponding Delete icon of the entry you want to delete.
+
+
+
+
+ ESB Configuration (Source View)
+
+
+ This function commits the configuration changes you have made to the local
+ storage of the host running the ESB. The XML code for your configuration
+ is displayed in the Current Configuration text area. You can also make any
+ changes directly in the XML code.
+
+
+ To apply your changes and save the configuration to the local storage click
+ the Update button. This will first validate the provided
+ configuration and warn you about any faults or inconsistencies detected. User has
+ the option of proceeding with the update operation or cancelling it at this
+ point. If no faults are detected, the configuration will be applied and saved to
+ the storage.
+
+
+ The Reset operation could be used to revert any changes you
+ have made to the source view and revert back to last saved configuration.
+
+
+ Please refer the documentation on managing
+ synapse configuration for details.
+
+
+
+
+
+ Managing the Integrated Registry
+
+
+ The registry provides a mechanism of creating and storing configuration
+ elements outside the ESB. These registry contents can be dynamically
+ loaded or modified, which will allow runtime modification of the ESB
+ behaviors. The folder structure gives a clear view of the available files
+ and easy access to modifying the files. Once these files are loaded, their
+ content are cached in the ESB for the specified duration, and is updated
+ at the end of the caching period.
+
+
+ You can use these files at the time of defining target sequences and
+ target endpoints for the proxy services.
+
+
+
+ Manage Registry Entry
+
+
Please refer the documentation on managing
+ the embedded registry for details.
+ WSO2 Enterprise Service Bus (ESB) Webapp Deployment Guide
+
+
+
+ WSO2 ESB can be deployed on different application servers such as IBM WebSphere,
+ BEA WebLogic Server, JBoss and Apache Tomcat. This guide describes how to deploy the ESB
+ on Apache Tomcat in a step-by-step manner. The methodology should be the same for
+ other application server deployments as well, but it will require some knowledge on the
+ application server for you to get it working on that particular application server.
+
+
Step 1 - Downloading and installing Apache Tomcat
+
+
+ You can download the latest version of Apache Tomcat from
+ here (We will be using Apache
+ Tomcat 5.5.20 to demonstrate this particular deployment). Extract the downloaded distribution
+ to a specific location and define the environment variables properly. (Assume you extracted
+ the downloaded Tomcat into the folder \opt\software\apache-tomcat-5.5.20)
+
+ Download the WSO2 ESB distribution and extract to a specific location in the file system.
+ (E.g.:- /opt/software/wso2esb-4.0.0).
+
+
+
+ Copy the repository in the extracted distribution to a different location
+ (this is the directory we are planning to treat as ESB_HOME, E.g.:- /opt/software/esb-home)
+
+
+
Step 3 - Enable HTTPS on the Apache Tomcat
+
+
+ Next you will need to enable HTTPS on Apache Tomcat since WSO2 ESB administration console
+ runs over HTTPS. To do this, open up the server.xml file located at $CATALINA_HOME/conf
+ using a text editor and uncomment the following:
+
+ You will have to set an environment variable with the name CARBON_HOME pointing it to
+ the directory into which you have copied the repository directory.
+
+
+
E.g.:-
+ CARBON_HOME=/opt/software/esb-home
+
+
+
Step 5 - Copying required files to Apache Tomcat
+
+
Now create a new directory inside the webapps folder of Tomcat.
Open the carbon.xml file which is in the CARBON_HOME/conf folder and specify the
+ following URL as the ServerURL https://localhost:8443/esb/services/
+
+
Then you need to specify the absolute paths of the WSO2CARBON_DB of the two files
+ registry.xml and user-mgt.xml
+
In order for the logging to work properly you need to copy the log4j.properties file
+ found at the lib directory of the extracted distribution to the webapp classpath
+
You need to specify the absolute paths for the two .jks files wso2carbon.jks and
+ client-truststore.jks specified in the HTTPS transport configuration section of the
+ axis2.xml and also the wso2carbon.jks file specified in the carbon.xml file.
+
+
Further, you need to uncomment the wsdlEPRPrefix parameter of the HTTP and HTTPS
+ transport receiver configurations and put the value as
+
http://${host}:${port}/services
+
+
Finally you will have to specify the absolute path of the Synapse configuration files in the
+ axis2.xml file located at CARBON_HOME/repository/conf. Simply change,
+
+ Now you can start the Apache Tomcat server by giving the command from the tomcat
+ installation bin directory
+
./catalina.sh run
+
+
Step 7 - Login to the WSO2 ESB Administration Console
+
+
Now you should be able to login to the WSO2 ESB Administration Console as,
+
https://localhost:8443/esb/carbon
+
+
Specific Instructions when Deploying WSO2 ESB in Other Application Servers
+
JBoss
+
+
In [Step-5], You should skip copying jboss-transaction-api-1.0.1.GA.jar when copying jars from
+ /opt/software/wso2esb-4.0.0/lib/api/ to
+ /opt/software/apache-tomcat-5.5.20/webapps/esb/WEB-INF/lib
+
+ WSO2 ESB supports standard XPath functions and variables through its underlying XPath
+ engine. All these standard XPath features are available for configuring the ESB.
+ XPath allows to build custom functions to extend its functionality. There are several
+ custom XPath functions and variables defined by the WSO2 ESB for accessing various
+ message properties.
+
+
Functions
+
+ There are two custom functions supported by the ESB.
+
+
get-property
+
base64Encode
+
+
get-property function
+
Syntax:
+
+
+ get-property(String propertyName)
+
+ get-property(String scope, String propertyName)
+
+
+ Get property function retrieves a message property at the given scope. If only the property
+ name is specified without the scope it assumes the default syanpse scope.
+
+ Supported Scopes
+
+
synpase
+
axis2
+
transport
+
+
Special Properties suported by get-property function
+
+
+
+
Name
+
Return Value
+
+
+
To
+
Incoming URL as a String or empty string («») if a To address is
+ not defined.
+
+
+
+
From
+
From address as a String or empty string («») if a From address
+ is not defined
+
+
+
+
Action
+
SOAP Addressing Action header value as a String or empty string («»)
+ if a Action is not defined
+
+
+
+
FaultTo
+
SOAP FautTo header value as a String or empty string («») if a
+ FaultTo address is not defined
+
+
+
+
ReplyTo
+
ReplyTo header value as a String or empty string («») if a
+ ReplyTo address is not defined
+
+
+
+
MessageID
+
A unique identifier (UUID) for the message as a String or empty string («»)
+ if MessageID is not defined. This id is guaranteed to be unique.
+
+
+
+
FAULT
+
TRUE if the message has a fault or empty string if message doesn't have a
+ fault
+
+
+
+
MESSAGE_FORMAT
+
Returns pox, get, soap11, soap12 depending on the message. If a message type
+ is unknown this returns soap12
+
+
+
+
OperationName
+
Operation name corresponding to the message. A proxy service with a WSDL can
+ have different operations. If the WSDL is not defined ESB defines fixed
+ operations
+
+
+
+
+
base64Encode function
+
Syntax:
+
+
base64Encode(string)
+
+
Returns the base64 encoded value of the argument.
+
+
Variables
+
There are several variables supported by the ESB. These are used for accessing various
+ properties and refer to fixed parts in the ESB.
+
+
$axis2
+
$trp
+
$ctx
+
$url
+
+
+
These XPath variables gets the properties at various scopes.
+
+
$axis2
+
+
Gets the property at the axis2 scope.
+
+
i.e. To get the property named 'messageType' use the following XPath expression
+
+
$axis2:messageType
+
+
$trp
+
+
Gets a transport header.
+
+
i.e. To get the transport header named Content-Type use the following XPath expression
+
+
$trp:Content-Type
+
+
HTTP transport headers are considered to be case insensitive. So in HTTP case
+
+
$trp:Content-Type and $trp:CONENT-TYPE are equal.
+
+
$ctx
+
+
Gets a property at the default scope.
+
+
i.e To get the property named 'foo' at the default scope use the following XPath expresion
+
+
$ctx:foo
+
+
$url
+
+
Gets a URL parameter.
+
+
i.e. To get the URL parameter named 'bar' use the following XPth expression
+
+
+
+
+
+
+
+
+
+
+ 
+ 
+ 
+
+
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+
+ 
+ 
+ 
+
+ 
+
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
\ No newline at end of file
diff --git a/docs/xdoc/source-repository.xml b/docs/xdoc/source-repository.xml
new file mode 100644
index 0000000000..a7e0eebf4d
--- /dev/null
+++ b/docs/xdoc/source-repository.xml
@@ -0,0 +1,133 @@
+
+
+
+
+
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+