axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r560481 - in /webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@: clustering-guide.xml contents.xml toc.xml
Date Sat, 28 Jul 2007 04:00:20 GMT
Author: rajith
Date: Fri Jul 27 21:00:19 2007
New Revision: 560481

added documentation for clustering support


Added: webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/clustering-guide.xml
--- webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/clustering-guide.xml (added)
+++ webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/clustering-guide.xml Fri
Jul 27 21:00:19 2007
@@ -0,0 +1,293 @@
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements. See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership. The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License. You may obtain a copy of the License at
+  ~
+  ~
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "">
+<html lang="en" xmlns="" xml:lang="en">
+<meta http-equiv="content-type" content="" />
+<title>Axis2 Clustering Support</title>
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+media="all" />
+<body lang="en" xml:lang="en">
+<!-- Introduction Para -->
+<h1>Axis2 Clustering Support</h1>
+<p>Are you interested in improving Scalability and High Availability of your Web Services?</p>
+<p>Axis2 1.3 provides experimental clustering support to add <b><i>Scalability,
Failover and High Availability</i></b> to your Web Services.
+This guide will explain the extent of clustering support and it's the current limitations.
+It also highlights the recommended approaches using examples.</p>
+<p>Axis2 clustering support can be used in several scenarios.
+However it is important to understand the current limitations and the risks/impacts associated
with each scenario.
+<!-- Content menu -->
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#scalability">Scalability</a></li>
+<li><a href="#failover">Failover</a></li>
+<li><a href="#ha">High Availability</a></li>
+<li><a href="#stateless_webservices">Clustering for Stateless Web Services</a></li>
+<li><a href="#stateful Web Services">Clustering for Stateful Web Services</a></li>
+<li><a href="#config">Configuring Axis2 to add Clustering Support</a></li>
+<li><a href="#scalability_stateless_example">Example 1: Scalability and HA with
Stateless Web Services</a></li>
+<li><a href="#failover_stateful_example">Example 2: Failover for Stateful Web
+<li><a href="#scalability_stateful_example">Example 3: Scalability and HA with
Stateful Web Services</a></li>
+<li><a href="#summary">Summary</a></li>
+<li><a href="#furtherstudy">For Further Study</a></li>
+<!-- Intro -->
+<a name="introduction" id="introduction"></a>
+<p>In the context of Axis2 clustering, a node is defined as a separate process with
a unique port number where it listens for requests on a given transport . A physical machine
can contain more than one node.</p>
+<!-- Scalability -->
+<a name="scalability" id="scalability"></a>
+<p>In order to maintain the same level of serviceability (QoS) during an increase in
load you need the ability to scale.
+Axis2 provides replication support to scale horizontally. That is, you can deploy the same
service in more than one node to share the work load, thereby increasing or maintaining the
same level of serviceability (throughput etc).</p>
+<!-- Failover -->
+<a name="failover" id="failover"></a>
+<p>Axis2 provides excellent support for Failover by replicating to backup node(s).

+If you deploy your Stateful Web Services in this mode, you can designate 1-2 backups and
replicate state. 
+In the event the primary node fails, the clients can switch to one of the backups. 
+If you use Synapse with the Failover mediator you can provide transparent Failover.</p>
+<!-- HA -->
+<a name="ha" id="ha"></a>
+<h2>High Availability</h2>
+<p>You can improve the availability of your Web Service by using the following Axis2
+<li><b>Failover</b> support will ensure that a client will continued be
served, without any interruption due to a node failure.</li>
+<li><b>Scalability</b> support will ensure that your services can maintain
the same level of serviceability/availability (QoS) in increased load conditions.</li>
+<li><b>Hot Deploy</b> feature ensures that you could deploy new services
without shutting down your existing services.</li>
+<!-- Stateless Web Services -->
+<a name="stateless_webservices" id="stateless_webservices"></a>
+<h2>Clustering for Stateless Web Services</h2>
+<p>This is the simplest use case. 
+If your Web Service does not store any state in the context hierarchy then you could deploy
your service in "n" number of nodes. To ensure identical configuration for your services,
you can load from a central repository using the URLBasedAxisConfigurator. This is not a must,
but it makes management of the cluster easy and less error prone.</p>
+<p>Since it is stateless no explicit replication is needed. If a node fails any other
node in the cluster can take over. You can use a load balancer to direct requests based on
a particular algorithm (Ex: Round Robin, Weight based, Affinity based). You can increase the
no of nodes to handle scalability (to scale vertically) without worrying about the overhead
of replication as the services are stateless</p>
+<!-- Stateful Web Services -->
+<a name="stateful_webservices" id="stateful_webservices"></a>
+<h2>Clustering for Stateful Web Services</h2>
+<p>This is a more complicated use case where your Web Service needs to store state
in the context hierarchy. Each Web Service instance (deployed in separate nodes) will need
to share state among themselves. Axis2 provides replication to support sharing of state among
+<p>However, if more than one node tries to update the same state in the context hierarchy,
conflicts will arise and the integrity of your data will be compromised. Now your cluster
will have inconsistent state. This can be avoided using a locking mechanism. However Axis2
currently does not support it yet.</p>
+<p>If this shared state is read more frequently and updated rarely the probability
of conflicts decrease. You may use Axis2 in the above use case for Stateful Web Services based
on your discretion. However it's important to remember that there can be conflicts.<i><b>If
you have frequent writes it is not advisable to use Axis2 until we introduce locking support</b></i></p>
+<p>Please note this warning is only applicable to the following use cases.
+<li>Your Service is deployed in Application Scope</li>
+<li>You store information in the ServiceGroupContext (irrespective of your scope)</li>
+<p>You may safely use services in "soapsession" scope provided you <i><b>don't
modify (or modify at all) state in ServiceGroupContext frequently</b></i>. In
soap-session the service context is exclusive to the client who owns the session. Therefore
only that client can modify state. A conflict might arise if the same client tries to access
the same service in two different nodes simultaneously which happens to modify the same state.
However this is rare, but might arise due to an error in the load balancer or the client.
If you use Sticky sessions, it will ensure that state will be changed in one node only by
directing all requests by the same client to the same node. This is the safest way to use
Axis2 clustering support for Stateful Web Services to acheive scalability.
+<!-- Configuring Axis2 to add Clustering support -->
+<a name="config" id="config"></a>
+<h2>Configuring Axis2 to add Clustering Support</h2>
+<p>You need to add the following snippet to your axis2.xml</p>
+   &lt;cluster class=&quot;org.apache.axis2.clustering.tribes.TribesClusterManager&quot;&gt;
+     &lt;contextManager class=&quot;org.apache.axis2.clustering.context.DefaultContextManager&quot;&gt;
+        &lt;listener class=&quot;org.apache.axis2.clustering.context.DefaultContextManagerListener&quot;/&gt;
+        &lt;replication&gt;
+            &lt;defaults&gt;
+                &lt;exclude name=&quot;local_*&quot;/&gt;
+                &lt;exclude name=&quot;LOCAL_*&quot;/&gt;
+            &lt;/defaults&gt;
+            &lt;context class=&quot;org.apache.axis2.context.ConfigurationContext&quot;&gt;
+                &lt;exclude name=&quot;SequencePropertyBeanMap&quot;/&gt;
+                &lt;exclude name=&quot;NextMsgBeanMap&quot;/&gt;
+                &lt;exclude name=&quot;RetransmitterBeanMap&quot;/&gt;
+                &lt;exclude name=&quot;StorageMapBeanMap&quot;/&gt;
+                &lt;exclude name=&quot;CreateSequenceBeanMap&quot;/&gt;
+                &lt;exclude name=&quot;ConfigContextTimeoutInterval&quot;/&gt;
+                &lt;exclude name=&quot;ContainerManaged&quot;/&gt;
+            &lt;/context&gt;
+            &lt;context class=&quot;org.apache.axis2.context.ServiceGroupContext&quot;&gt;
+                &lt;exclude name=&quot;my.sandesha.*&quot;/&gt;
+            &lt;/context&gt;
+            &lt;context class=&quot;org.apache.axis2.context.ServiceContext&quot;&gt;
+                &lt;exclude name=&quot;my.sandesha.*&quot;/&gt;
+            &lt;/context&gt;
+        &lt;/replication&gt;
+     &lt;/contextManager&gt;
+   &lt;/cluster&gt;
+<p>The exclude tag tells the system to avoid replicating that particular property.
This is a useful
+feature as you would need to have properties that is node specific only. 
+The default config in axis2 will have all properties the axis2 system doesn't want to replicate.
Web Service developers can also use this to filter out properties that should be local only.
+<!-- Example1 Scalability & HA with Stateless Web Service -->
+<a name="scalability_stateless_example" id="scalability_stateless_example"></a>
+<h2>Example 1: Scalability and HA with Stateless Web Services</h2>
+<p>The following is a good example for deploying a Stateless Web Service for Scalability
and High Availability.
+The following service can be deployed in "application" scope in "n" nodes using a central
+Once state is loaded by a particular node it will be shared by other nodes as the config
context will replicate the data.
+Even if two nodes load the data at the same time, there want be any conflicts as it is the
same set of data.
+(All nodes should synchronize their clocks using a time server to avoid loading different
sets of data)</p>
+<p>For the sake of this example we assume replication is cheaper than querying the
+So once queried it will be replicated to the cluster</p>
+ * This Service is responsible for providing the top 5
+ * stocks for the day, week or quarter
+ */
+public class Top5StockService
+	public String[] getTop5StocksForToday()
+	{
+		// If cache is null or invalid fetch it from data base
+		ConfigurationContext configContext =
+            MessageContext.getCurrentMessageContext().getConfigurationContext();
+		String[]  symbols = (String[])configContext.getProperty(TOP5_TODAY);
+		if (!checkValidity(configContext.getProperty(TOP5_TODAY_LOAD_TIME)))
+                {
+		    symbols = loadFromDatabase(TOP5_TODAY);
+                    configContext.setProperty(TOP5_TODAY,symbols);
+		    configContext.setProperty(TOP5_TODAY_LOAD_TIME,new java.util.Date()); 	 
+                } 
+		return symbols;
+	}
+	public String[] getTop5StocksForTheWeek()
+	{
+		 // If cache is null or invalid fetch it from data base
+		.............
+	}
+	public String[] getTop5StocksForTheQuarter()
+	{
+		// If cache is null or invalid fetch it from data base
+                ............
+	}
+<!-- Example2 Failover for Stateful Web Service -->
+<a name="failover_stateful_example" id="failover_stateful_example"></a>
+<h2>Example 2: Failover for Stateful Web Services</h2>
+<p>The following example demonstrates Failover support by replicating state in a service
deployed in "soapsession" scope.
+You can deploy the service in 2 nodes. Then point a client to the first node and add a few
items to the shopping cart.
+Assuming the primary node has crashed, point the client to the backup node. You should be
able to checkout the cart with the items you added in the first node.</p>
+public class ShoppingCart
+	public final static String SHOPPING_CART = "SHOPPING_CART";
+	public final static String DISCOUNT = "DISCOUNT";
+	public void createSession()
+	{
+		List&lt;Item&gt; cart = new ArrayList&lt;Item&gt;();
+		ServiceContext serviceContext =
+            MessageContext.getCurrentMessageContext().getServiceContext();
+		serviceContext.setProperty(SHOPPING_CART, cart);
+	}
+	public void addItem(Item item)
+	{
+		ServiceContext serviceContext =
+            MessageContext.getCurrentMessageContext().getServiceContext();
+		List&lt;Item&gt; cart = (List&lt;Item&gt;)serviceContext.getProperty(SHOPPING_CART);
+		cart.add(item);
+	}
+	public void removeItem(Item item)
+	{
+		ServiceContext serviceContext =
+            MessageContext.getCurrentMessageContext().getServiceContext();
+		List&lt;Item&gt; cart = (List&lt;Item&gt;)serviceContext.getProperty(SHOPPING_CART);
+		cart.remove(item);
+	}
+	public double checkout()
+	{
+		ServiceContext serviceContext =
+            MessageContext.getCurrentMessageContext().getServiceContext();
+		List&lt;Item&gt; cart = (List&lt;Item&gt;)serviceContext.getProperty(SHOPPING_CART);
+		double discount = (Double)serviceContext.getServiceGroupContext().getProperty(DISCOUNT);
+		double total = 0;
+		for (Item i : cart)
+		{
+			total = total + i.getPrice();
+		}
+		total = total - total * (discount/100);
+		return total;
+	}	
+<!-- Example 3 Scalability & HA with Stateful Web Services -->
+<a name="scalability_stateful_example" id="scalability_stateful_example"></a>
+<h2>Example3: Scalability and HA with Stateful Web Services</h2>
+<p>You can deploy the the above Shopping Cart service in several active nodes (with
a backup(s) for each node). 
+You only replicate to your backup nodes for Failover. The load balancer should ensure sticky
+ The strategy is to partition your load between the active nodes to achieve scalability and
replication to the backups to achieve Failover. These in turn will increase the high availability
of your services. Since the above example doesn't use Service Group Context to write any state
there want be any conflicts.</p>
+<p>For the sake of this example we assume that all read only properties for the Service
Group Context is loaded at initialization
+ <b><i>Please note this is the recommended approach for Stateful Web Services
due to the current limitations</i></b>
+<a name="summary" id="summary"></a>
+<p>Apache Axis2 provides experimental support for clustering to improve the following
properties of your Web Services.
+<li>High Availability</li>
+It is important to understand the current limitations when leveraging clustering support.
+<a name="furtherstudy" id="furtherstudy"></a>
+<h2>For Further Study</h2>
+<p>Apache Axis2-<a href=
+<p>Axis2 Architecture-<a href=
+<p>Introduction to Apache Axis2-<a href=

Modified: webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/contents.xml
--- webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/contents.xml (original)
+++ webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/contents.xml Fri Jul 27
21:00:19 2007
@@ -148,7 +148,10 @@
 <li><a href="ejb-provider.html">Guide to using EJB Provider in
 Axis2</a> - This guide explains how to use an EJB provider in Axis2
 using an example</li>
+<li><a href="clustering-guide.html">Clustering Guide</a> - This guide will
show how you can leverage clustering support to improve Scalability, Failover and High Availability
of your Web Services</li>
 <p><strong>Data Bindings:</strong></p>
 <li><a href="adb/adb-howto.html">ADB How-to</a> - A guide on the

Modified: webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/toc.xml
--- webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/toc.xml (original)
+++ webservices/axis2/branches/java/1_3/xdocs/@axis2_version_dir@/toc.xml Fri Jul 27 21:00:19
@@ -64,9 +64,9 @@
 <li><a href="Axis2ArchitectureGuide.html" target=
 "mainFrame">Architecture Guide</a></li>
 <li><a href="pojoguide.html" target="mainFrame">POJO Guide</a></li>
-<li><a href="spring.html" target="mainFrame">Spring Guide</a></li>
-<li><a href="modules.html" target="mainFrame">Modules
+<li><a href="spring.html" target="mainFrame">Spring Guide</a></li>
+<li><a href="modules.html" target="mainFrame">ModulesGuide</a></li>
+<li><a href="clustering-guide.html" target="mainFrame">Clustering Guide</a></li>
 <li>ADB Data Binding
 <li>14.1 <a href="adb/adb-howto.html" target=

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message