incubator-wadi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bdud...@apache.org
Subject svn commit: r356933 [34/35] - in /incubator/wadi/trunk: ./ etc/ modules/ modules/assembly/ modules/assembly/src/ modules/assembly/src/bin/ modules/assembly/src/conf/ modules/assembly/src/main/ modules/assembly/src/main/assembly/ modules/core/ modules/c...
Date Wed, 14 Dec 2005 23:36:16 GMT
Added: incubator/wadi/trunk/wadi-site/src/site/fml/faq.2.fml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/fml/faq.2.fml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/fml/faq.2.fml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/fml/faq.2.fml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,724 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *
+ * 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-lock
+ *
+ * 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.
+ */
+ -->
+
+<faqs title="WADI - Frequently Asked Questions">
+
+  <part id="general">
+    <title>General</title>
+
+    <faq id="pronounciation">
+      <question>How is WADI pronounced? [20/04/04]</question>
+      <answer>
+	WADI is pronounced: 'woddy'.
+      </answer>
+    </faq>
+
+    <faq id="acronym">
+      <question>What does WADI stand for? [20/04/04]</question>
+      <answer>
+	W[eb] A[pplication] D[istribution] I[nfrastructure].
+      </answer>
+    </faq>
+
+    <faq id="what">
+      <question>What does WADI do? [19/04/04]</question>
+      <answer>
+
+       	WADI is a J2EE component that manages and ensures the scalable
+       	and transparent high availability of Web container state.
+
+	<p/>
+
+	Such state is stored in an HttpSession. This is the per-client
+	server-side repository of conversational state and the only
+	resource to be distributed in a &lt;distributable/&gt; Web
+	Application.
+
+	<p/>
+
+	The management of distributable HttpSessions is currently
+	loosely specified.  Consequently, it unfortunately tends to be
+	very much an afterthought in existing Open Source
+	implementations.
+
+	<p/>
+
+	WADI's goal is to identify and explain the shortcomings
+	present in current offerings and to provide an implementation
+	which draws upon this crystallisation of the current state of
+	play to provide a highly flexible toolkit capable of
+	delivering a number of different solutions in a complex
+	problem space.
+
+	<p/>
+
+	WADI is able to achieve this, because the project is focussed,
+	not on the delivery of a complete, working web-container, but
+	simply upon the problem of distributed state management.
+
+	<p/>
+
+	Ultimately, WADI will live or die upon its ability to justify
+	its architecture in terms of the constraints placed upon it by
+	the Servlet and Java language specifications and to deliver a
+	production-ready implementation of this in a format that is
+	sufficiently performant, flexible, functional and available as
+	to be worth the investment, over and above just taking a vanilla
+	web-container out of the box, that the user will have to make to
+	put it to use.
+
+	<p/>
+
+	You are the Jury. Your verdict is final!
+
+      </answer>
+    </faq>
+
+    <faq id="goals">
+      <question>What are WADI's goals? [20/04/04]</question>
+      <answer>
+
+	WADI is a collection of pluggable components which,
+	ultimately, aim to provide a complete solution to all the
+	common problems encountered in managing user state in the
+	J2EE web tier. Particular issues addressed are/will be:
+
+	<ul>
+	  <li>A reliable solution to application and container space HttpSession concurrency issues</li>
+	  <li>Ensuring that HttpRequest and HttpSession meet somewhere in the cluster for correct processing</li>
+	  <li>Persistent HttpSessions - saved to store whilst web container is down</li>
+	  <li>Reversible eviction of aging HttpSessions to long term storage</li>
+	  <li>HttpSession migration directly between cluster nodes</li>
+	  <li>Bulletproof HttpSessions - through state replication</li>
+	  <li>A simple and reliable semantic which encompasses all the above</li>
+	</ul>
+
+	HttpSessions have taken a back seat in terms of reliability
+	and effort put into their implementation to EJBs for some
+	time. With the proliferation of web farms and increasing
+	reliability and performance requirements in the web tier, WADI
+	will address these issues.
+      </answer>
+    </faq>
+
+    <faq id="platforms">
+      <question>On what platform[s] does WADI run? [20/04/04]</question>
+      <answer>
+	<ul>
+	  <li>J2SE 1.4.x</li>
+	  <li>J2EE 1.4 (Servlet 2.4)</li>
+	</ul>
+      </answer>
+    </faq>
+
+    <faq id="integration">
+      <question>With which J2EE containers is it integrated? [19/04/04]</question>
+      <answer>
+
+	WADI currently plugs into <a
+	  href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc">Tomcat
+	  5</a> and <a href="http://jetty.mortbay.org">Jetty 5</a>, in
+	the form of an HttpSession Manager and a Filter. Any other web
+	container that is flexible enough to allow the substitution of
+	its HttpSession Manager with another 3rd party implementation
+	should present a fairly straightforward integration target for
+	WADI. Filters are a standard J2EE component, so will be
+	pluggable into any compliant or compatible implementation.
+
+	<p/>
+
+	In as far as WADI is integrated with the two web containers
+	mentioned above, it may be considered integrated with
+	application servers which embed them (notably e.g. Geronimo,
+	Jonas and JBoss). Particular attention will be paid to the
+	Geronimo integration, for reasons given below.
+
+      </answer>
+    </faq>
+
+    <faq id="how">
+      <question>How is this integration achieved? [19/04/04]</question>
+      <answer>
+
+	WADI comprises three main components, A Filter, a portable
+	HttpSession implementation and an HttpSession Manager. The
+	Filter is portable. The Manager has implementations that plug
+	into Jetty and Tomcat, replacing their existing HttpSession
+	Managers and HttpSession implementations with its
+	own. HttpSessions will be able to be exchanged between
+	instances of any WADI-enabled web-container.
+
+	The Filter end of WADI keeps track of which HttpRequests are
+	visiting which HttpSessions, enabling WADI to know when it may
+	interact with an HttpSession (e.g. for migration) without
+	involving itself in concurrency issues with application-space
+	threads. The Filter is also able to relocate requests, by
+	various pluggable mechanisms, from one node to another, before
+	the HttpRequest enters application code.
+
+	The HttpSession Manager is responsible for HttpSession
+	creation, destruction, pooling, location and
+	migration. Auxiliary code performs all the other tasks
+	involved in HttpSession migration etc...
+
+      </answer>
+    </faq>
+
+    <faq id="fnality">
+      <question>What functionality does WADI bring to the table? [19/04/04]</question>
+      <answer>
+	Managing distributed state is a complex affair. Rather than
+	mandate a particular direction, WADI attempts to abstract the
+	basic patterns of use into Policy interfaces. A number of
+	different such Policy plugins, governing e.g. eviction,
+	migration, Id generation etc, ship with WADI, and the user is
+	encouraged to write their own implementations and submit them
+	to the project to fill any functional gaps.
+
+	<p/>
+
+	Currently WADI can:
+
+	<p/>
+	In a non-distributed environment:
+	<ul>
+	  <li>
+	    Perform the full set of duties of a standard session
+	    manager.
+	  </li>
+	</ul>
+
+	<p/>
+	In a distributed environment:
+	<ul>
+	  <li>
+	    Persist sessions via a pluggable MigrationPolicy between
+	    web container start/stop cycles. All the correct
+	    notifications will be triggered upon
+	    HttpSessionActivationListeners.
+	  </li>
+	  <li>
+	    Select, according to a user supplied EvictionPolicy,
+	    sessions for Passivation and using the above
+	    MigrationPolicy, move them into shared storage, from which
+	    they may be re-activated, in a race-safe environment, by
+	    any web-container instance that shares the store. Once
+	    again, the correct notifications will be made to session
+	    Listeners.
+	  </li>
+	  <li>
+	    Reference based semantics (See WADI Paper - LINK TODO) may
+	    be completely maintained in a distributed environment. We
+	    believe this is the only Open Source Session Manager to be
+	    able to do this reliably. i.e., any legacy webapp,
+	    provided that it stores client state exclusively in the
+	    corresponding http session, may be deployed in distributed
+	    mode with no further code changes.
+	  </li>
+	</ul>
+
+	<p/>
+	In the future we expect WADI to be able to:
+
+	<ul>
+	  <li>
+	    draw on existing functionality to provide performant and
+	    flexible high availibility and scalability of it's managed
+	    state, via a variety of pluggable backends.
+	  </li>
+	  <li>
+	    because of it's flexibility, WADI should provide a
+	    platform with which a number of mission critical third
+	    party product integrations (e.g. http load-balancers) will
+	    be able to be tightly integrated, resolving many of the
+	    existing problems in providing clustered web-tier state
+	    management.
+	  </li>
+	</ul>
+
+      </answer>
+    </faq>
+
+    <faq id="why">
+      <question>Why would I even want to store important information in the Web tier? [19/04/04]</question>
+      <answer>
+	Strictly speaking, data associated with presentation lives in
+	the web tier whilst data associated with the business should
+	be stored in the EJB tier.
+
+	<p/>
+
+	State management in the EJB tier is more tightly specified,
+	simpler and generally better implemented than the equivalent
+	functionality in the web-tier, so the tendancy has been to
+	push all important data in this direction, when high
+	availibility and fail-over are a major concern.
+
+	<p/>
+
+	Unfortunately, even designs such as the above cannot get away
+	from the fact that the web-client requires a single handle on
+	the conversational state held in some J2EE tier and that the
+	only such handle provided by the J2EE specifications is that
+	which binds a url parameter/session cookie to a web
+	session. So whilst you can store all data in the EJB tier,
+	unless you want to start learning proprietary tricks to
+	associate an EJB handle with a web client, you have no option
+	but to put your EJB into the relevant web session and pray
+	that it survives whatever gets thrown at it.
+
+	<p/>
+
+	This is obviously an unsatisfactory state of affairs, and
+	WADI's aim is to restore confidence in the reliability of web
+	sessions in general and to clearly demonstrate, that with a
+	little thought, in a number of cases, a distributed web
+	session may be implemented more efficiently and reliably than
+	the corresponding stateful EJB session.
+      </answer>
+    </faq>
+
+    <faq id="why">
+      <question>Why should I need it? [19/04/04]</question>
+      <answer>
+
+	If you have a requirement to store presentation state in your
+	J2EE web tier and this state is of value and you are not keen
+	on shoehorning it into the business tier in order to achieve
+	its persistance and distribution, then you should be looking
+	at WADI.
+
+      </answer>
+    </faq>
+
+    <faq id="competition">
+      <question>How does it differentiate itself from the competition? [19/04/04]</question>
+      <answer>
+
+	The competition is HttpSession implementations in the open
+	source world. At the time of writing, and to the best of my
+	knowledge, these begin to address the same issues as WADI, in
+	terms of e.g. paging HttpSessions to/from disc, or state
+	replication, but are marked as 'experimental' or have unclear
+	semantics, or are non-performant.I haven't found a single
+	implementation which addresses all the issues which WADI
+	chooses to - otherwise I would have contributed to that
+	project.
+
+      </answer>
+    </faq>
+
+    <faq id="aspectj">
+      <question>Why AspectJ? - I prefer AspectXYZ [19/04/04]</question>
+      <answer>
+
+	The complex and flexible requirements of middleware particularly
+	lend themselves to AOP. The previous incarnation of WADI, the
+	Jetty HttpSession replication implementation, used a system of
+	deploytime aggregated custom 'interceptors' to compose its
+	HttpSession container on the fly. The move to AspectJ is intended
+	to preserve that investment of time in the decomposition of the
+	HttpSession container into its various aspects whilst paying
+	minimum price at runtime for what is now a statically-typed,
+	compile time abstraction. At the time of the project's inception a
+	number of AOP technologies were investigated. AspectJ was chosen
+	as being the most runtime efficient and mature of this
+	selection. Note that the investment is in figuring out how to
+	break a system down into aspects, rather than implementing it
+	using any particular proprietary aspect technology. If a more
+	suitable AOP implementation comes along we foresee no problem in
+	porting WADI to it.
+
+      </answer>
+    </faq>
+
+    <faq id="status">
+      <question>What is WADI's current status? [19/04/04]</question>
+      <answer>
+
+	Changing daily :-)
+
+	<p/>
+
+	WADI started as a 'proof of concept' project, but is moving
+	rapidly towards production readiness. We will be looking for
+	beta-testers soon.
+
+	<p/>
+
+	Initial WADI development was done with Jetty and Tomcat was
+	added recently, so the flexibility of the Tomcat integration
+	still lags a little, but this is on our todo list.
+
+      </answer>
+    </faq>
+
+    <faq id="where">
+      <question>Where is it going? [19/04/04]</question>
+      <answer>
+
+	Currently we are concentrating on resolving all the issues
+	surrounding concurrency, migration and session/request
+	relocation. Once these have been resolved, the next large piece of
+	functionality will be state replication.
+
+      </answer>
+    </faq>
+
+    <faq id="where">
+      <question>How does WADI relate to Apache Geronimo? [19/04/04]</question>
+      <answer>
+
+	WADI started life as a design for a Jetty/Geronimo
+	component. We soon realized that, because of WADI's
+	abstraction of all significant functionality into pluggable
+	strategies with well-defined APIs, there would ultimately be
+	nothing tieing it exclusively to Jetty or Geronimo. At this
+	point it became WADI - a standalone project, now able to be
+	used by a wider audience, particularly stand-alone Tomcat
+	users.
+
+	<p/>
+
+	Ultimately, WADI's goals still involve a seamless integration
+	with Geronimo. This will be achieved by backing relevant WADI
+	plugins with Geronimo services. The authors of this project
+	are involved in the design of Geronimo clustering
+	functionality and substantial part of WADI is simply the
+	reflection of concerns encountered in the Web tier of this
+	design.
+
+      </answer>
+    </faq>
+
+    <faq id="involved">
+      <question>This is interesting stuff - how do I get involved? [19/04/04]</question>
+      <answer>
+
+	Check out WADI from cvs or download a snapshot (when we get them
+	going) and play with it in Tomcat or Jetty. Report problems on the
+	mailing list or codehaus Jira and join in the discussion on the
+	mailing list and irc (when we have one).Bug fixes are always
+	welcome :-). These are the ways to have a direct impact on the
+	quality and direction of the project. There will also be a WADI
+	BOF at JavaOne this year, for those of you who are attending -
+	more details to follow.
+
+	<p/>
+
+	If your interest is more general, but still within the J2EE
+	space, you might consider getting involved with the Apache
+	Geronimo Project. There is plenty of scope here to scratch any
+	itch that you might have.
+
+      </answer>
+    </faq>
+
+  </part>
+
+  <part id="technical">
+    <title>Technical</title>
+
+    <faq id="build">
+      <question>What's going on with the build system - Ant or Maven? [19/04/04]</question>
+      <answer>
+
+	WADI started life as an Ant project. We are now moving over to
+	Maven. Unfortunately, the way that the maven-aspectj-plugin
+	does things is rather dissimilar to the way we were doing
+	things in Ant. We hope to resolve this issue soon.
+
+	<p/>
+
+	If anyone has successfully run AJDoc with AspectJ-1.2 from
+	Ant, please drop us a mail with an example
+	(jules@coredevelopers.net).
+
+      </answer>
+    </faq>
+
+    <faq id="starting">
+      <question>How do I get started? [19/04/04]</question>
+      <answer>
+
+	For the moment we will do this using Ant:
+
+	<p/>
+
+	You'll need the following env vars set up in your shell
+	(apologies to MS users - I'm sure you'll work it out).
+
+	<ul>
+	  <li>JAVA_HOME</li>
+	  <li>ASPECTJ_HOME</li>
+	  <li>JETTY_HOME</li>
+	  <li>TOMCAT_HOME</li>
+	</ul>
+
+      </answer>
+    </faq>
+
+    <faq id="tomcat">
+      <question>How do I run the Tomcat integration? [19/04/04]</question>
+      <answer>
+
+	On Un*x:
+
+	<pre>build.sh tomcat.0</pre>
+
+	This will run the Tomcat in $TOMCAT_HOME with the
+	configuration <a href="http://cvs.wadi.codehaus.org/cvsweb.cgi/wadi/conf/tomcat.xml?rev=1.2;content-type=text%2Fx-cvsweb-markup">tomcat.xml</a> which
+	installs a context /wadi and sets up WADI as the HttpSession
+	Manager for this context. Although WADI classes are present in
+	WEB-INF/classes, it appears that they must be put on Tomcat's
+	classpath before starting it.
+
+      </answer>
+    </faq>
+
+    <faq id="jetty">
+      <question>How do I run the Jetty integration? [19/04/04]</question>
+      <answer>
+
+	On Un*x:
+
+	<pre>build.sh jetty.0</pre>
+
+	This will run the Jetty in $JETTY_HOME with the configuration
+	<a href="http://cvs.wadi.codehaus.org/cvsweb.cgi/wadi/conf/jetty.xml?rev=1.2;content-type=text%2Fx-cvsweb-markup;only_with_tag=MAIN">jetty.xml</a>. This runs a stripped
+	down Jetty, into which it installs the WADI webapp at
+	/wadi. It then uses the WEB-INF/jetty-web.xml to set up WADI
+	as the HttpSession Manager. WADI classes are loaded from
+	WEB-INF/classes by the webapp's ClassLoader. i.e. The webapp
+	is in control of how its state is managed, rather than the
+	deployer.
+
+      </answer>
+    </faq>
+
+    <faq id="war">
+      <question>Why is WADI packaged as a WAR? [19/04/04]</question>
+      <answer>
+
+	This is simply an artifact of how it is developed. Having it
+	compile directly into an unpacked WAR means that the test
+	webapp may be deployed immediately WADI has been built,
+	omitting a tedious 'packaging' step. This speeds the
+	development iteration.
+
+	<p/>
+
+	It is intended that, ultimately, WADI will be packaged into a
+	single wadi.jar. For Jetty I would expect this to be put in
+	WEB-INF/lib whereas for Tomcat, somewhere like
+	$TOMCAT_HOME/server/common.
+
+      </answer>
+    </faq>
+
+    <faq id="logging">
+      <question>What is WADI using for Logging infrastructure? [19/04/04]</question>
+      <answer>
+
+	WADI uses commons-logging, and in the current development
+	configuration this is implemented via J2SE1.4 native
+	logging. However, just to confuse matters, because I find the
+	double line output format of this system unreadable, I have
+	plugged in an Open Source logging formatter (gt2-main.jar)
+	which has nicer output.
+
+	<p/>
+
+	I didn't just use log4j, because I wanted to preserve a TRACE
+	level, which it does not support out-of-the-box.
+
+      </answer>
+    </faq>
+
+    <faq id="design">
+      <question>How is WADI put together? [19/04/04]</question>
+      <answer>
+
+	WADI installs as an HttpSession Manager for a particular
+	Context/WebApp. This Manager then installs (programmatically) a
+	Filter at the front of the webapp's Filter stack.
+	<p/>
+
+	The Manager may be considered to be the webapp's HttpSession
+	factory. It is in control of HttpSession creation and
+	destruction and provides its own HttpSession
+	implementation. Both Tomcat and Jetty (fortunately) have well
+	defined internal Manager and HttpSession
+	APIs. org.codehaus.wadi.shared provides core classes which
+	implement standard and WADI functionality as well as interfaces
+	defining pluggable strategies and
+	policies. org.codehaus.wadi.tomcat and org.codehaus.wadi.jetty
+	extend these classes with the necessary glue to fit them into
+	the targer webcontainer. Finally, org.codehaus.wadi.plugins
+	provides concrete implementations of these pluggable APIs,
+	e.g. HttpSession and HttpRequest relocation mechanisms.
+
+	<p/>
+
+	WADI does not set out to tell you how to distribute your
+	webapp. We believe that there are many different ways that you
+	might wish to do this. WADI simply provides a framework and
+	(eventually) every conceivable ability that you might
+	require. Useful default behaviour is supplied, but it is
+	expected that this will be customised with the use of the
+	supplied plugins.
+
+      </answer>
+    </faq>
+
+    <faq id="concurrency">
+      <question>How do you deal with concurrency in a webapp's HttpSessions? [19/04/04]</question>
+      <answer>
+
+	The servlet spec specifically mandates that implementations should
+	allow multiple concurrent request threads to pass through an
+	HttpSession. It omits describing any synchronisation protocol
+	around the HttpSession that the container and application might
+	use in order to coordinate their activities. This has presented a
+	problem for a number of Manager implementations that I have looked
+	at. Many chose simply to ignore the problem.
+
+	<p/>
+
+	This problem becomes far more pressing as the number of
+	activities that the Manager may wish to perform on an active
+	HttpSession increases in frequency or complexity. WADI, for
+	instance, needs to be able to guarantee that no application
+	threads are altering an HttpSession's content whilst the Manager
+	is trying to serialise the HttpSession as part of a relocation
+	(migration) to long term store or another node.
+
+	<p/>
+
+	Synchronising around the HttpSession would not actually solve
+	our problem. If we wish to relocate an HttpSession to another
+	node, we must prevent, once we have made this decision any
+	further requests for this session on this node from entering
+	application code here during the relocation.
+
+	<p/>
+
+	WADI's Filter looks at each incoming request. If it references a
+	local HttpSession it tries to acquire a non-exclusive lock in
+	that HttpSession (non-exclusive so that many concurrent request
+	threads may run). When the Manager wishes to e.g. relocate the
+	HttpSession it will try to acquire an exclusive lock in the
+	HttpSession. In this way application and container-space threads
+	are properly coordinated.
+
+      </answer>
+    </faq>
+
+    <faq id="relocation">
+      <question>Tell me what you mean by HttpSession and HttpRequest relocation [19/04/04]</question>
+      <answer>
+
+	Introducing state into a cluster thoroughly complicates
+	matters. It becomes important that client request and server-side
+	state meet each other somewhere in the cluster for correct
+	processing. Location becomes all important. WADI has the ability
+	to relocate both HttpSessions, by migrating them from node to node
+	(or to long term store) and to relocate HttpRequests by
+	redirection and proxying. Various pluggable strategies and
+	policies allow the user to define how and when this will be done.
+      </answer>
+    </faq>
+
+  </part>
+
+  <part id="business">
+    <title>Business</title>
+
+    <faq id="support">
+      <question>Where can I buy support for WADI?  [19/04/04]</question>
+      <answer>
+	WADI is developed and maintained by partners in <a
+	  href="http://www.coredevelopers.net">Core Developers
+	  Network</a>. If you wish to discuss support, consulting or
+	enhancements around WADI, please <address><a
+	    href="mailto:sales@coredevelopers.net">mail</a></address> us.
+      </answer>
+    </faq>
+
+  </part>
+</faqs>
+
+<!--
+	<p/>
+
+	Relocation
+
+	<p/>
+
+	In certain circumstances (perhaps when a node fails)
+	HttpRequests may arrive at a node which is not in possession
+	of the relevant HttpSession. WADI might take a proactive
+	stance, in which it seeks to ever allow this to happen, or a
+	reactive stance in which we accept this and work around it.
+
+	<p/>
+
+	WADI currently chooses the latter. The reasoning behind this
+	is that the expense in terms of extra processing, distributed
+	locking and synchronisation that we would have to impose on
+	the common case, a correctly routed request, would outweigh
+	any benefit derived from the removal of the exceptional case,
+	an incorrectly routed one. Furthermore, in all likelihood, we
+	would not be able to eradicate the exceptional case, merely
+	reduce its frequency of occurrance. So we would still need to
+	implement all the code to handle the exceptional case anyway.
+
+	<p/>
+
+	Accepting that exceptional cases will arise, leaves WADI with
+	two resolutions :
+
+	<ul>
+	  <li>relocate the request to the session</li>
+	  <li>relocate the session to the request</li>
+	</ul>
+
+	HttpRequest Relocation
+
+	<p/>
+
+	This is currently achieved by means of :
+
+	<ul>
+	  <li>redirection</li>
+	  <li>proxying</li>
+	</ul>
+
+	HttpSession relocation
+
+	<p/>
+
+	This is currently achieved by :
+
+	<ul>
+	  <li>migration of session directly from one node to another</li>
+	  <li>migration of session to shared, long-term store and thence to any node in the cluster</li>
+	</ul>
+
+-->

Added: incubator/wadi/trunk/wadi-site/src/site/fml/faq.fml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/fml/faq.fml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/fml/faq.fml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/fml/faq.fml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,909 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *
+ * 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-lock
+ *
+ * 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.
+ */
+ -->
+
+<faqs title="WADI - Frequently Asked Questions">
+
+  <part id="general">
+    <title>General</title>
+
+    <faq id="pronounciation">
+      <question>How is WADI pronounced? [20/04/04]</question>
+      <answer>
+	WADI is pronounced: 'woddy'.
+      </answer>
+    </faq>
+
+    <faq id="acronym">
+      <question>What does WADI stand for? [20/04/04]</question>
+      <answer>
+	W[eb] A[pplication] D[istribution] I[nfrastructure].
+      </answer>
+    </faq>
+
+    <faq id="what">
+      <question>What does WADI do? [21/11/05]</question>
+      <answer>
+
+       	WADI is a J2EE container plugin that manages and ensures the
+       	scalable and transparent high availability of J2EE Web
+       	container state.
+
+	<p/>
+
+	Such state is stored in an HttpSession. This is the per-client
+	server-side repository of conversational state and the only
+	resource to be distributed in a &lt;distributable/&gt; Web
+	Application.
+
+	<p/>
+
+	The management of distributable HttpSessions is currently
+	loosely specified.  Consequently, it unfortunately tends to be
+	very much an afterthought in existing Open Source
+	implementations.
+
+	<p/>
+
+	WADI's goal is to identify and explain the shortcomings
+	present in current offerings and to provide an implementation
+	which draws upon this crystallisation of the current state of
+	play to provide a highly flexible toolkit capable of
+	delivering a number of different solutions in a complex
+	problem space.
+
+	<p/>
+
+	WADI is able to achieve this, because the project is focussed,
+	not on the delivery of a complete, working web-container, but
+	simply upon the problem of distributed state management.
+
+	<p/>
+
+	Ultimately, WADI will live or die upon its ability to justify
+	its architecture in terms of the constraints placed upon it by
+	the Servlet and Java language specifications and to deliver a
+	production-ready implementation of this in a format that is
+	sufficiently performant, flexible, and functional as to be
+	worth the investment, over and above just taking a vanilla
+	web-container out of the box, that the user will have to make
+	to put it to use.
+
+	<p/>
+
+	You are the Jury. Your verdict is final!
+
+      </answer>
+    </faq>
+
+    <faq id="goals">
+      <question>What are WADI's goals? [08/06/04]</question>
+      <answer>
+
+	We can crystallise WADI's goals into two stages:
+
+	<ul>
+	  <li>
+	    To be able to walk into your web farm and 'ctl-c' any
+	    webcontainer node without losing any HttpSessions
+	    (i.e. customers).
+	  </li>
+
+	  <li>
+	    To be able to walk into the same web farm and 'kill -9'
+	    any webcontainer node without losing any HttpSessions
+	    (i.e. customers).
+	  </li>
+	</ul>
+
+	<p/>
+
+	The first of these two cases is important because it allows
+	easy maintenance of existing h/w or s/w. This may seem a
+	trivial requirement, but many existing solutions are
+	time-consuming and/or error-prone (involving draining sessions
+	off target nodes over long periods etc.), to the point that
+	many sites simply accept that maintenance will impact quality
+	of service.
+
+	<p/>
+
+	The second of these two cases deals with a more exceptional
+	case - the catastrophic failure of a webcontainer node. As
+	online competition for business increases, systems are being
+	required to provide higher and higher levels of
+	availibility. This can be critical in particular areas. The
+	ability to preserve web-tier state beyond the failure of its
+	node is correspondingly an increasing requirement.
+
+      </answer>
+    </faq>
+
+    <faq id="goals">
+      <question>What resolutions to these goals does WADI propose? [22/11/05]</question>
+      <answer>
+
+	WADI addresses its problem space through dividing and
+	conquering. The goals above have been broken down into the
+	following feature set.
+
+	<ul>
+	  <li>
+	    Perform the full set of duties associated with a standard,
+	    non-distributable session manager.
+	  </li>
+
+	  <li>
+	    A reliable solution to application and container space
+	    HttpSession concurrency issues - so that the container may
+	    safely serialise a session if/when the need arises.
+	  </li>
+
+	  <li>
+	    The ability to migrate sessions to/from a pluggable shared
+	    long-term storage mechanism allows WADI to preserve JVM
+	    resources by evicting infrequently used sessions during a
+	    node's lifetime and to ensure their availibility to its
+	    peers both during its lifetime and after shutdown.
+	  </li>
+
+	  <li>
+	    Further pluggable strategies allow the user to control
+	    e.g. compression algorithms used in such migration. These
+	    could be extended to perform other types of transformation
+	    - e.g. encryption, for sites where security is a priority.
+	  </li>
+
+	  <li>
+	    WADI is able to relocate sessions by migration directly
+	    between peer nodes in the cluster. If a request arrives at
+	    a node that does not have the corresponding session, it
+	    can locate it and arrange its immigration underneath the
+	    incoming request.
+	  </li>
+
+	  <li>
+	    Pluggable load-balancer integrations allow WADI to
+	    leverage specific mechanisms to control/predict on which
+	    node user requests will fall.
+	  </li>
+
+	  <li>
+	    WADI is also able to relocate requests between peers. It
+	    uses redirection (load-balancer integration permitting) or
+	    proxying. If a request arrives at a node that does not
+	    have the corresponding session, it can locate it and send
+	    the request on to the correct node..
+	  </li>
+
+	  <li>
+	    Bulletproof HttpSessions - through state replication -
+	    This is the second phase of WADI development, currently
+	    under implemention. We are drawing on the experience of
+	    having already twice implemented such mechanisms for <a
+	    href="http://jetty.mortbay.org">Jetty</a>. More details to
+	    follow...
+	  </li>
+
+	  <li>
+	    All of the above in a manner completely compatible with
+	    the current J2EE Servlet Specification (2.4), thus
+	    preserving the users investment in the J2EE platform and
+	    avoiding vendor lockin.
+	  </li>
+	</ul>
+
+	HttpSessions have taken a back seat, in terms of reliability
+	and effort put into their implementation, to EJBs for some
+	time. With the proliferation of web farms and increasing
+	reliability and performance requirements in the web tier, WADI
+	will address these issues.
+
+      </answer>
+    </faq>
+
+    <faq id="platforms">
+      <question>On what platform[s] does WADI run? [20/04/04]</question>
+      <answer>
+	<ul>
+	  <li>J2SE 1.4.x</li>
+	  <li>J2EE 1.4 (Servlet 2.4)</li>
+	</ul>
+      </answer>
+    </faq>
+
+    <faq id="integration">
+      <question>With which J2EE containers is it integrated? [22/11/05]</question>
+      <answer>
+
+	WADI currently plugs into
+
+	<ul>
+	  <li><a href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc">Tomcat 5.0</a></li>
+	  <li><a href="http://jakarta.apache.org/tomcat/tomcat-5.5-doc">Tomcat 5.5</a></li>
+	  <li><a href="http://jetty.mortbay.org">Jetty 5</a></li>
+	  <li><a href="http://jetty.mortbay.org">Jetty 6</a></li>
+	  <li><a href="http://www.sf.net/projects/jboss">JBoss 4</a></li>
+	</ul>
+	in the form of an HttpSession Manager and a Filter. See the
+	documentation in 'Getting Started'. Any other web container
+	that is flexible enough to allow the substitution of its
+	HttpSession Manager with another 3rd party implementation
+	should present a fairly straightforward integration target for
+	WADI. Filters are a standard J2EE component, so will be
+	pluggable into any compliant or compatible implementation.
+
+	<p/>
+
+	In as far as WADI is integrated with the two web containers
+	mentioned above, it may be considered integrated with
+	application servers which embed them (notably e.g. <a
+	href="http://geronimo.apache.org">Geronimo</a>, Jonas and <a
+	href="http://www.sf.net/projects/jboss">JBoss</a>). Particular
+	attention is being paid to the <a
+	href="http://geronimo.apache.org">Geronimo</a> integration,
+	for reasons given below.
+
+      </answer>
+    </faq>
+
+    <faq id="how">
+      <question>How is this integration achieved? [22/11/05]</question>
+      <answer>
+
+	WADI comprises three main components, A Filter, a portable
+	HttpSession implementation and an HttpSession Manager. The
+	Filter is portable. The Manager plugs into the webcontainer,
+	replacing theirits own native HttpSession Manager and
+	HttpSession implementation. WADI HttpSessions are portable
+	between any WADI-enabled webcontainer, so these may be freely
+	mixed within a cluster whilst still aloowing the migration of
+	sessions between themselves.
+
+	The Filter end of WADI keeps track of which HttpRequests are
+	visiting which HttpSessions, enabling WADI to know when it may
+	interact with an HttpSession (e.g. for migration) without
+	involving itself in concurrency issues with application-space
+	threads. The Filter is also able to relocate requests, by
+	various pluggable mechanisms, from one node to another, before
+	the HttpRequest enters application code.
+
+	The HttpSession Manager is responsible for HttpSession
+	creation, destruction, pooling, location, migration and
+	replication. Auxiliary pluggable code performs all the other
+	tasks involved in HttpSession migration etc...
+
+      </answer>
+    </faq>
+
+    <faq id="why">
+      <question>Why would I even want to store important information in the Web tier? [19/04/04]</question>
+      <answer>
+	Strictly speaking, data associated with presentation lives in
+	the web tier whilst data associated with the business should
+	be stored in the EJB tier.
+
+	<p/>
+
+	State management in the EJB tier is more tightly specified,
+	simpler and generally better implemented than the equivalent
+	functionality in the web-tier, so the tendancy has been to
+	push all important data in this direction, when high
+	availibility and fail-over are a major concern.
+
+	<p/>
+
+	Unfortunately, even designs such as the above cannot get away
+	from the fact that the web-client requires a single handle on
+	the conversational state held in some J2EE tier and that the
+	only such handle provided by the J2EE specifications is that
+	which binds a url parameter/session cookie to a web
+	session. So whilst you can store all data in the EJB tier,
+	unless you want to start learning proprietary tricks to
+	associate an EJB handle with a web client, you have no option
+	but to put your EJB into the relevant web session and pray
+	that it survives whatever gets thrown at it.
+
+	<p/>
+
+	This is obviously an unsatisfactory state of affairs, and
+	WADI's aim is to restore confidence in the reliability of web
+	sessions in general and to clearly demonstrate, that with a
+	little thought, in a number of cases, a distributed web
+	session may be implemented more efficiently and reliably than
+	the corresponding stateful EJB session.
+      </answer>
+    </faq>
+
+    <faq id="why">
+      <question>Why should I need it? [19/04/04]</question>
+      <answer>
+
+	If you have a requirement to store presentation state in your
+	J2EE web tier and this state is of value and you are not keen
+	on shoehorning it into the business tier in order to achieve
+	its persistance and distribution, then you should be looking
+	at WADI.
+
+      </answer>
+    </faq>
+
+    <faq id="competition">
+      <question>How does it differentiate itself from the competition? [22/11/05]</question>
+      <answer>
+
+	The competition is HttpSession implementations in the open
+	source world. At the time of writing, and to the best of my
+	knowledge, these begin to address the same issues as WADI, in
+	terms of e.g. paging HttpSessions to/from disc, or state
+	replication, but have unclear semantics under concurrent load,
+	or are lacking important features. I haven't found a single
+	implementation which addresses all the issues which WADI
+	chooses to in one package - otherwise I would have contributed
+	to that project.
+
+	<p/>
+
+	Here is a brief summary of the current state of play:
+
+	<p/>
+
+	<table border="1">
+	  <tr>
+	    <th>Implementation</th>
+	    <th>Session Persistance</th>
+	    <th>Shared Store</th>
+	    <th>Session Eviction</th>
+	    <th>Session Replication</th>
+	    <th>Replication Whole/Delta</th>
+	    <th>Replication Partitioned</th>
+	    <th>Replication Technology</th>
+	    <th>Author</th>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">Jetty5,6/TC5.0,5.5: WADI</th>
+	    <td>Y</td>
+	    <td>Y</td>
+	    <td>Y</td>
+	    <td>NYI - Y</td>
+	    <td>NYI - both</td>
+	    <td>NYI - auto - pluggable</td>
+	    <td>ActiveCluster/Pluggable</td>
+	    <td align="left">Jules Gosnell &amp; The WADI Team</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">Jetty4/5: Jules' DSM</th>
+	    <td>Y</td>
+	    <td>Y</td>
+	    <td>N</td>
+	    <td>Y</td>
+	    <td>both</td>
+	    <td>manual</td>
+	    <td>JGroups/Pluggable</td>
+	    <td align="left">Jules Gosnell</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">TC4/JBoss: Thomas' DSM</th>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>Y</td>
+	    <td>whole</td>
+	    <td>manual</td>
+	    <td>JBossHA/JGroups</td>
+	    <td align="left">Thomas Peuss</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">TC5: PersistentManager</th>
+	    <td>Y</td>
+	    <td>?</td>
+	    <td>Y</td>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>N/A</td>
+	    <td align="left">Kief Morris</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">TC5: DeltaManager</th>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>delta</td>
+	    <td>N?</td>
+	    <td>?</td>
+	    <td>JGroups?</td>
+	    <td align="left">Filip Hanik, Craig McClanahan, Jean-Francois Arcand</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">TC5: SimpleTcpReplicationManager</th>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>N</td>
+	    <td>Y</td>
+	    <td>delta</td>
+	    <td>N?</td>
+	    <td>JGroups</td>
+	    <td align="left">Filip Hanik, Bela Ban</td>
+	  </tr>
+	  <tr align="center">
+	    <th align="left">TC5: - New JCluster-based</th>
+	    <td>?</td>
+	    <td>?</td>
+	    <td>?</td>
+	    <td>?</td>
+	    <td>?</td>
+	    <td>NYI - auto - clock</td>
+	    <td>JCluster/JGroups</td>
+	    <td align="left">Rob Block</td>
+	  </tr>
+	</table>
+
+	<p/>
+
+	Please notify us of mistakes or other features/implementations
+	that you would like to see in this table.
+
+      </answer>
+    </faq>
+
+    <faq id="jk">
+      <question>So tell me about WADI and mod_jk [22/11/05]</question>
+      <answer>
+
+      Mod_jk poses particular problems for session maintenance beyond
+      the lifetime of a single vm. Mod_jk implements session affinity
+      via a contract with the webcontainer. Each node has a unique
+      id. This id is appended to any session created on this node
+      i.e. if a session '1234' is created on node 'red', the cookie
+      returned to the browser will have a value of
+      '1234.red'. Mod_jk's workers.properties is used to map the 'red'
+      to a particular host:port combination each time it is seen. This
+      is a very efficient and effective way of achieving affinity,
+      until 'red' disappears. Then the browser is left holding a
+      cookie with no corresponding node. Rather than implementing a
+      contract involving some sort of predictability, e.g. failing
+      over to the next node in the list. Mod_jk will simply treat the
+      session as if it had no affinity and select a 'random' live node
+      and drop the request on it. Subsequent requests will be routed
+      to different nodes, whilst the session cookie still ends in
+      '.red'.
+
+     <p/>
+
+     How does WADI maintain a session's availability in these
+     circumstances ? If 'red' is shutdown cleanly it will migrate its
+     sessions to its surviving peers. The next request will cause the
+     node upon which it lands to acquire the relevant session from a
+     peer, if it does not already own it, and then process the request
+     in the normal manner. This node will then rewrite the routing
+     info at the end of the session id with its own unique id,
+     sticking all subsequent requests to itself. Thus affinity
+     immediately 'fails-over' onto another node, maintaining session
+     availibility at minimum price paid only in the exceptional case.
+
+      </answer>
+    </faq>
+
+    <faq id="aspectj">
+      <question>Why AspectJ? - I prefer AspectXYZ [22/11/05]</question>
+      <answer>
+
+	The complex and flexible requirements of middleware
+	particularly lend themselves to AOP. The previous incarnation
+	of WADI, the <a href="http://jetty.mortbay.org">Jetty</a>
+	HttpSession replication implementation, used a system of
+	deploytime aggregated custom 'interceptors' to compose its
+	HttpSession container on the fly. The move to AspectJ is
+	intended to preserve that investment of time in the
+	decomposition of the HttpSession container into its various
+	aspects whilst paying minimum price at runtime for what is now
+	a statically-typed, compile time abstraction. At the time of
+	the project's inception a number of AOP technologies were
+	investigated. AspectJ was chosen as being the most runtime
+	efficient and mature of this selection. Note that the
+	investment is in figuring out how to break a system down into
+	aspects, rather than implementing it using any particular
+	proprietary aspect technology. If a more suitable AOP
+	implementation comes along we foresee no problem in porting
+	WADI to it.
+
+	<p/>
+	Update: We have now removed our Aspectj dependency and
+	collapsed the aspected code back into pure Java. This was done
+	for a number of reasons.
+	<ul>
+	  <li>The number of cross-cutting concerns found was not as great as was expected at the outset of the project.</li>
+	  <li>AspectJ integration with Eclipse, whilst useful, was often flaky</li>
+	  <li>AspectJ integration with Maven1 was inadequate and we had to roll our own</li>
+	  <li>AspectJ integration with Maven2, at the point of our migration, did not exist</li>
+	  <li>The number of developers on the project is growing and the use of AspectJ raises the skills requirement</li>
+	  <li>I have heard FUD to the effect of 'Aspects are slow' being taken seriously by architects in big companies.</li>
+	</ul>
+	So, whilst I am personally still a dedicated Aspect fan
+	(coming from a Lisp/CLOS background), I came to the conclusion
+	that WADI was not the right place to use them. My apologies to
+	the AspectJ and wider Aspect community.
+
+      </answer>
+    </faq>
+
+    <faq id="status">
+      <question>What is WADI's current status? [08/06/04]</question>
+      <answer>
+
+	Changing daily :-)
+
+	<p/>
+
+	WADI started as a 'proof of concept' project, but is moving
+	rapidly towards production readiness. We will be releasing
+	very shortly.
+
+	<p/>
+
+	Functionality in <a
+	href="http://jakarta.apache.org/tomcat">Tomcat</a> and <a
+	href="http://jetty.mortbay.org">Jetty</a> is now equivalent,
+	so all further WADI development is now being done on a
+	webcontainer-independant platform.
+
+      </answer>
+    </faq>
+
+    <faq id="where">
+      <question>Where is it going? [22/11/05]</question>
+      <answer>
+	Currently, we are concentrating on hardening the distributed
+	hash map, implementing in-vm state replication and openEJB and
+	Geronimo integrations.
+      </answer>
+    </faq>
+
+    <faq id="where">
+      <question>How does WADI relate to <a
+      href="http://geronimo.apache.org">Apache Geronimo</a>?
+      [22/11/05]</question>
+      <answer>
+
+	WADI started life as a design for a <a
+	href="http://jetty.mortbay.org">Jetty</a>/<a
+	href="http://geronimo.apache.org">Geronimo</a> component. We
+	soon realized that, because of WADI's abstraction of all
+	significant functionality into pluggable strategies with
+	well-defined APIs, there would ultimately be nothing tieing it
+	exclusively to <a href="http://jetty.mortbay.org">Jetty</a> or
+	<a href="http://geronimo.apache.org">Geronimo</a>. At this
+	point it became WADI - a standalone project, now able to be
+	used by a wider audience, particularly stand-alone <a
+	href="http://jakarta.apache.org/tomcat">Tomcat</a> users.
+
+	<p/>
+
+	Ultimately, WADI's goals still involve a seamless integration
+	with <a href="http://geronimo.apache.org">Geronimo</a>. This
+	will be achieved by backing relevant WADI plugins with <a
+	href="http://geronimo.apache.org">Geronimo</a> services. The
+	authors of this project are involved in the design of <a
+	href="http://geronimo.apache.org">Geronimo</a> clustering
+	functionality and substantial part of WADI is simply the
+	reflection of concerns encountered in the Web tier of this
+	design.
+
+	<p/>
+
+	WADI has acccepted the Geronimo community's invitation to
+	become an official geronimo subproject and the relevant pieces
+	of the project will soon be moving over to the ASF. This site
+	will continue as the optional WADI code that integrates with
+	GPL and LGPL licensed 3rd party components may not be
+	distributed from ASF servers.
+
+      </answer>
+    </faq>
+
+    <faq id="where">
+      <question>How does WADI relate to <a
+      href="http://openejb.codehaus.org/">OpenEJB</a>?
+      [22/11/05]</question>
+      <answer>
+
+	<p/>
+
+	WADI provides a number of clustering related services to the
+	web-tier which have direct equivalents in the EJB tier (The
+	management of clustered SFSBs).
+
+	<p/>
+
+	WADI and OpenEJB communities are in discussion as to how WADI
+	technology may be reused beneath OpenEJB in order to provide
+	HA EJBs.
+
+	<p/>
+
+	We expect the outcome to be a genericisation of a number of
+	WADI components, a number of intelligent client-side EJB
+	client proxies and some pluggable OpenEJB internals. Work is
+	underway on a complete OpenEJB integration.
+
+      </answer>
+    </faq>
+
+    <faq id="involved">
+      <question>This is interesting stuff - how do I get involved? [22/11/05]</question>
+      <answer>
+
+	Work you way through the <a href="http://docs.codehaus.org/display/WADI/Getting+Started">Getting Started</a>
+	documentation and the <a href="http://docs.codehaus.org/display/WADI/Maven+2.0">Maven2</a> and <a
+	href="http://docs.codehaus.org/display/WADI/Eclipse">Eclipse</a> Developers sections on the <a
+	href="http://docs.codehaus.org/display/WADI/Home">WIKI</a>.
+
+	Get onto the <a href="mail-lists.html">mailing lists</a> and
+	<a href="irc://irc.codehaus.org/wadi">#WADI</a>, report
+	problems here or on <a
+	href="http://jira.codehaus.org/browse/WADI">Codehaus
+	Jira</a>.Bug fixes are always welcome :-). These are the ways
+	to have a direct impact on the quality and direction of the
+	project <p/>
+
+	If your interest is more general, but still within the J2EE
+	space, you might consider getting involved with the <a
+	href="http://geronimo.apache.org">Apache Geronimo</a>
+	Project. There is plenty of scope here to scratch any itch
+	that you might have.
+
+      </answer>
+    </faq>
+
+  </part>
+
+  <part id="technical">
+    <title>Technical</title>
+
+    <faq id="format">
+      <question>What format is WEB-INF/wadi-web.xml in? [22/11/05]</question>
+      <answer>
+
+	<p/>
+
+	We looked at various mechanisms including those already in use
+	by Jetty and Tomcat and ultimately chose <a href="http://www.springframework.org/">Spring</a>
+	for WADI's configuration mechanism.
+
+	<p/>
+
+	<ul>
+	  <li>It will already be familiar to part of our community and has a growing community of its own</li>
+	  <li>It extends as quickly as you can write classes - no admin overhead (c.f. TC and Digester)</li>
+	  <li>Small and lightweight - it took 6 lines of code to insert</li>
+	</ul>
+
+	<p/>
+
+	The format is basically a direct mapping from Java to XML with
+	a little syntactic sugar. Any public method on the WADI
+	session manager or its subcomponents may be called directly
+	from XML just before it is started. This results in
+	anextremely flexible configuration mechanism, which is exactly
+	what WADI needs at this stage. Please peruse the online WADI
+	<a href="http://wadi.codehaus.org/apidocs/org/codehaus/wadi/shared/Manager.html">JavaDoc</a>
+	for a complete listing of available methods/types.
+
+      </answer>
+    </faq>
+
+    <faq id="logging">
+      <question>What is WADI using for Logging infrastructure? [22/11/05]</question>
+      <answer>
+
+	WADI uses commons-logging, and this is backed onto
+	org.apache.commons.logging.impl.SimpleLog logging. We chose
+	this over Jdk1.4 logging, because this seems to swallow all
+	its input afterstarting Runtimme.ShutdownHook(). Logging what
+	happens during shutdown is important to WADI and SimpleLog
+	seems to do this with no problems.
+
+	<p/>
+
+	We didn't use the log4j backend, because we wanted to preserve
+	a TRACE level, which it does not support out-of-the-box.
+
+	<p/>
+
+	When running in JBoss we provide a custom commons-logging
+	backend which maps WADI's TRACE level directly to JBoss' TRACE
+	level (by default WADI DEBUG and TRACE will be collapsed into
+	JBoss DEBUG).
+
+      </answer>
+    </faq>
+
+    <faq id="design">
+      <question>How is WADI put together? [19/04/04]</question>
+      <answer>
+
+	WADI installs as an HttpSession Manager for a particular
+	Context/WebApp. This Manager then installs (programmatically) a
+	Filter at the front of the webapp's Filter stack.
+	<p/>
+
+	The Manager may be considered to be the webapp's HttpSession
+	factory. It is in control of HttpSession creation and
+	destruction and provides its own HttpSession
+	implementation. Both <a
+	href="http://jakarta.apache.org/tomcat">Tomcat</a> and <a
+	href="http://jetty.mortbay.org">Jetty</a> (fortunately) have
+	well defined internal Manager and HttpSession
+	APIs. org.codehaus.wadi.shared provides core classes which
+	implement standard and WADI functionality as well as
+	interfaces defining pluggable strategies and
+	policies. org.codehaus.wadi.tomcat and org.codehaus.wadi.jetty
+	extend these classes with the necessary glue to fit them into
+	the targer webcontainer. Finally, org.codehaus.wadi.plugins
+	provides concrete implementations of these pluggable APIs,
+	e.g. HttpSession and HttpRequest relocation mechanisms.
+
+	<p/>
+
+	WADI does not set out to tell you how to distribute your
+	webapp. We believe that there are many different ways that you
+	might wish to do this. WADI simply provides a framework and
+	(eventually) every conceivable ability that you might
+	require. Useful default behaviour is supplied, but it is
+	expected that this will be customised with the use of the
+	supplied plugins.
+
+      </answer>
+    </faq>
+
+    <faq id="concurrency">
+      <question>How do you deal with concurrency in a webapp's HttpSessions? [19/04/04]</question>
+      <answer>
+
+	The servlet spec specifically mandates that implementations should
+	allow multiple concurrent request threads to pass through an
+	HttpSession. It omits describing any synchronisation protocol
+	around the HttpSession that the container and application might
+	use in order to coordinate their activities. This has presented a
+	problem for a number of Manager implementations that I have looked
+	at. Many chose simply to ignore the problem.
+
+	<p/>
+
+	This problem becomes far more pressing as the number of
+	activities that the Manager may wish to perform on an active
+	HttpSession increases in frequency or complexity. WADI, for
+	instance, needs to be able to guarantee that no application
+	threads are altering an HttpSession's content whilst the Manager
+	is trying to serialise the HttpSession as part of a relocation
+	(migration) to long term store or another node.
+
+	<p/>
+
+	Synchronising around the HttpSession would not actually solve
+	our problem. If we wish to relocate an HttpSession to another
+	node, we must prevent, once we have made this decision any
+	further requests for this session on this node from entering
+	application code here during the relocation.
+
+	<p/>
+
+	WADI's Filter looks at each incoming request. If it references a
+	local HttpSession it tries to acquire a non-exclusive lock in
+	that HttpSession (non-exclusive so that many concurrent request
+	threads may run). When the Manager wishes to e.g. relocate the
+	HttpSession it will try to acquire an exclusive lock in the
+	HttpSession. In this way application and container-space threads
+	are properly coordinated.
+
+      </answer>
+    </faq>
+
+    <faq id="relocation">
+      <question>Tell me what you mean by HttpSession and HttpRequest relocation [19/04/04]</question>
+      <answer>
+
+	Introducing state into a cluster thoroughly complicates
+	matters. It becomes important that client request and server-side
+	state meet each other somewhere in the cluster for correct
+	processing. Location becomes all important. WADI has the ability
+	to relocate both HttpSessions, by migrating them from node to node
+	(or to long term store) and to relocate HttpRequests by
+	redirection and proxying. Various pluggable strategies and
+	policies allow the user to define how and when this will be done.
+      </answer>
+    </faq>
+
+  </part>
+
+  <part id="business">
+    <title>Business</title>
+
+    <faq id="support">
+      <question>Where can I buy support for WADI?  [19/04/04]</question>
+      <answer>
+	WADI is developed and maintained by partners in <a
+	href="http://www.coredevelopers.net">Core Developers
+	Network</a>. If you wish to discuss support, consulting or
+	enhancements around WADI, please <address><a
+	href="mailto:sales@coredevelopers.net">mail</a></address> us.
+      </answer>
+    </faq>
+
+  </part>
+</faqs>
+
+<!--
+	<p/>
+
+	Relocation
+
+	<p/>
+
+	In certain circumstances (perhaps when a node fails)
+	HttpRequests may arrive at a node which is not in possession
+	of the relevant HttpSession. WADI might take a proactive
+	stance, in which it seeks to ever allow this to happen, or a
+	reactive stance in which we accept this and work around it.
+
+	<p/>
+
+	WADI currently chooses the latter. The reasoning behind this
+	is that the expense in terms of extra processing, distributed
+	locking and synchronisation that we would have to impose on
+	the common case, a correctly routed request, would outweigh
+	any benefit derived from the removal of the exceptional case,
+	an incorrectly routed one. Furthermore, in all likelihood, we
+	would not be able to eradicate the exceptional case, merely
+	reduce its frequency of occurrance. So we would still need to
+	implement all the code to handle the exceptional case anyway.
+
+	<p/>
+
+	Accepting that exceptional cases will arise, leaves WADI with
+	two resolutions :
+
+	<ul>
+	  <li>relocate the request to the session</li>
+	  <li>relocate the session to the request</li>
+	</ul>
+
+	HttpRequest Relocation
+
+	<p/>
+
+	This is currently achieved by means of :
+
+	<ul>
+	  <li>redirection</li>
+	  <li>proxying</li>
+	</ul>
+
+	HttpSession relocation
+
+	<p/>
+
+	This is currently achieved by :
+
+	<ul>
+	  <li>migration of session directly from one node to another</li>
+	  <li>migration of session to shared, long-term store and thence to any node in the cluster</li>
+	</ul>
+
+-->

Added: incubator/wadi/trunk/wadi-site/src/site/resources/css/maven-theme.css
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/css/maven-theme.css?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/resources/css/maven-theme.css (added)
+++ incubator/wadi/trunk/wadi-site/src/site/resources/css/maven-theme.css Wed Dec 14 15:32:56 2005
@@ -0,0 +1,175 @@
+body {
+        background-color: #fff;
+	font-family: Verdana, Helvetica, Arial, sans-serif;
+	margin-left: auto;
+	margin-right: auto;
+	background-repeat: repeat-y;
+	font-size: 13px;
+	padding: 0px;
+}
+td, select, input, li{
+	font-family: Verdana, Helvetica, Arial, sans-serif;
+	font-size: 12px;
+	color:#333333;
+}
+code{
+  font-size: 12px;
+}
+a {
+  text-decoration: none;
+}
+a:link {
+  color:#47a;
+}
+a:visited  {
+  color:#666666;
+}
+a:active, a:hover {
+  color:#990000;
+}
+#legend li.externalLink {
+  background: url(../images/external.png) left top no-repeat;
+  padding-left: 18px;
+}
+a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:active, a.externalLink:hover {
+  background: url(../images/external.png) right center no-repeat;
+  padding-right: 18px;
+}
+#legend li.newWindow {
+  background: url(../images/newwindow.png) left top no-repeat;
+  padding-left: 18px;
+}
+a.newWindow, a.newWindow:link, a.newWindow:visited, a.newWindow:active, a.newWindow:hover {
+  background: url(../images/newwindow.png) right center no-repeat;
+  padding-right: 18px;
+}
+h2 {
+	font-size: 17px;
+	color: #333333;  
+}
+h3 {
+	padding: 4px 4px 4px 24px;
+	color: #666;
+	background-color: #ccc;
+	font-weight: bold;
+	font-size: 14px;
+	background-repeat: no-repeat;
+	background-position: left bottom;
+}
+p {
+  line-height: 1.3em;
+  font-size: 12px;
+  color: #000;
+}
+#breadcrumbs {
+	height: 13px;
+	background-image: url(../images/breadcrumbs.jpg);
+	padding: 5px 10px 14px 20px;
+}
+* html #breadcrumbs {
+	padding-bottom: 8px;
+}
+#leftColumn {
+	margin: 10px 0 10px 0;
+	border-top-color: #ccc;
+	border-top-style: solid;
+	border-top-width: 1px;
+	border-right-color: #ccc;
+	border-right-style: solid;
+	border-right-width: 1px;
+	border-bottom-color: #ccc;
+	border-bottom-style: solid;
+	border-bottom-width: 1px;
+	padding-right: 5px;
+	padding-left: 5px;
+}
+#navcolumn h5 {
+	font-size: smaller;
+	border-bottom: 1px solid #aaaaaa;
+	padding-top: 2px;
+	padding-left: 9px;
+	color: #49635a;
+	background-image: url(../images/h5.jpg);
+	background-repeat: no-repeat;
+	background-position: left bottom;
+}
+
+table.bodyTable th {
+  color: white;
+  background-color: #bbb;
+  text-align: left;
+  font-weight: bold;
+}
+
+table.bodyTable th, table.bodyTable td {
+  font-size: 11px;
+}
+
+table.bodyTable tr.a {
+  background-color: #ddd;
+}
+
+table.bodyTable tr.b {
+  background-color: #eee;
+}
+
+.source {
+  border: 1px solid #999;
+  overflow:auto
+}
+dt {
+	padding: 4px 4px 4px 24px;
+	color: #333333;
+	background-color: #ccc;
+	font-weight: bold;
+	font-size: 14px;
+	background-repeat: no-repeat;
+	background-position: left bottom;
+}
+.subsectionTitle {
+	font-size: 13px;
+	font-weight: bold;
+	color: #666;
+
+}
+
+table {
+	font-size: 10px;
+}
+.xright a:link, .xright a:visited, .xright a:active {
+  color: #666;
+}
+.xright a:hover {
+  color: #003300;
+}
+#banner {
+	height: 93px;
+}
+#navcolumn ul {
+	margin: 5px 0 15px -0em;
+}
+#navcolumn ul a {
+	color: #333333;
+}
+#navcolumn ul a:hover {
+	color: red;
+}
+#intro {
+	border: solid #ccc 1px;
+	margin: 6px 0px 0px 0px;
+	padding: 10px 40px 10px 40px;
+}
+.subsection {
+	margin-left: 3px;
+	color: #333333;
+}
+
+.subsection p {
+	font-size: 12px;
+}
+#footer {
+  padding: 10px;
+  margin: 20px 0px 20px 0px;
+  border-top: solid #ccc 1px; 
+  color: #333333;
+}

Added: incubator/wadi/trunk/wadi-site/src/site/resources/css/site.css
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/css/site.css?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/resources/css/site.css (added)
+++ incubator/wadi/trunk/wadi-site/src/site/resources/css/site.css Wed Dec 14 15:32:56 2005
@@ -0,0 +1,52 @@
+a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:active, a.externalLink:hover {
+  background: none;
+  padding-right: 0;
+}
+
+/*
+body ul {
+  list-style-type: square;
+}
+*/
+
+#downloadbox {
+  float: right;
+  margin: 0 10px 20px 20px;
+  padding: 5px;
+  border: 1px solid #999;
+  background-color: #eee;
+}
+
+#downloadbox h5 {
+  color: #000;
+  margin: 0;
+  border-bottom: 1px solid #aaaaaa;
+  font-size: smaller;
+  padding: 0;
+}
+
+#downloadbox p {
+  margin-top: 1em;
+  margin-bottom: 0;
+}
+
+#downloadbox ul {
+  margin-top: 0;
+  margin-bottom: 1em;
+  list-style-type: disc;
+}
+
+#downloadbox li {
+  font-size: smaller;
+}
+
+/*
+h4 {
+  padding: 0;
+  border: none;
+  color: #000;
+  margin: 0;
+  font-size: larger;
+  font-weight: bold;
+}
+*/

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/breadcrumbs.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/breadcrumbs.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/breadcrumbs.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/codehaus-small.png
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/codehaus-small.png?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/codehaus-small.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/folder-open.gif
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/folder-open.gif?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/folder-open.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/h5.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/h5.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/h5.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/loadbalancing.0.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/loadbalancing.0.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/loadbalancing.0.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.0.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/location.0.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.0.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.1.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/location.1.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.1.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.2.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/location.2.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.2.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.3.jpg
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/location.3.jpg?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/location.3.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/resources/images/wadi.png
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/resources/images/wadi.png?rev=356933&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wadi/trunk/wadi-site/src/site/resources/images/wadi.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wadi/trunk/wadi-site/src/site/site.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/site.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/site.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/site.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,43 @@
+<project name="Mojo">
+   <bannerLeft>
+      <name>WADI</name>
+      <src>/images/wadi.png</src>
+      <href>http://wadi.codehaus.org</href>
+   </bannerLeft>
+   <bannerRight>
+      <name>Codehaus</name>
+      <src>/images/codehaus-small.png</src>
+      <href>http://www.codehaus.org</href>
+   </bannerRight>
+   <body>
+      <links>
+         <item name="Geronimo" href="http://geronimo.apache.org"/>
+         <item name="Tomcat" href="http://tomcat.apache.org"/>
+         <item name="Jetty" href="http://jetty.mortbay.org/jetty/index.html"/>
+      </links>
+      
+      <menu name="WADI">
+         <item name="About" href="./index.html"/>
+         <item name="Getting Started" href="./getting-started/index.html"/>
+         <item name="Documentation" href="./documentation/index.html"/>
+         <item name="FAQ" href="./faq.html"/>
+         <item name="Wiki" href="http://docs.codehaus.org/pages/listpages-dirview.action?key=WADI"/>
+         <item name="How To Help" href="./help.html"/>
+      </menu>
+      <menu name="Modules">
+         <item name="Core" href="wadi-core/index.html"/>
+         <item name="JBoss 4" href="wadi-jboss4/index.html"/>
+         <item name="JGroups" href="wadi-jgroups/index.html"/>
+         <item name="Jetty 5" href="wadi-jetty5/index.html"/>
+         <item name="Jetty 6" href="wadi-jetty6/index.html"/>
+         <item name="Tomcat 5.0.x" href="wadi-tomcat50/index.html"/>
+         <item name="Tomcat 5.5" href="wadi-tomcat55/index.html"/>
+         <item name="Example Webapp" href="wadi-webapp/index.html"/>
+         
+      </menu>
+      <menu name="Source">
+         <item name="Browse the Source" href="http://cvs.wadi.codehaus.org/" />
+      </menu>
+      ${reports}
+   </body>
+</project>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/eclipse.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/eclipse.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/eclipse.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/eclipse.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<document>
+    <properties>
+        <title>WADI - Developing with WADI and Eclipse</title>
+    </properties>
+    <body>
+        <section name="Documentation">            
+            <p>
+                Since WADI uses <a href="http://maven.apache.org">Maven 2</a> its simple to get started.
+                <ol>
+                    <li><a href="./get_code.html">Get</a> the code.</li>
+                    <li>from the command line cd to the wadi directory and use 'cvs up -Pd' (this will cause a lot of old empty directories to be deleted)</li>
+                    <li>run mvn install</li>
+                    <li>run mvn eclipse:eclipse</li>
+                    <li>fire up Eclipse</li>
+                    <li>
+                        prepare the classpath
+                        <ol>
+                            <li>Choose Window -> Preferences -> Java -> Build Path -> Classpath Variables</li>
+                            <li>Hit the New... button</li>
+                            <li>Specify M2_REPO as the name</li>
+                            <li>Specify ~/.m2/repository (or where ever your maven 2 repo lives) as the Path</li>
+                        </ol>        
+                    </li>
+                    <li>
+                        add the modules as projects
+                        <ol>
+                            <li>Use right click -> Import... ->Existing Project into Workspace</li>
+                            <li>Hit the Next button</li>
+                            <li>Choose the location of the module (i.e. $WADI/modules/core) the modules are eclipse projects, the root is not a project.</li>
+                            <li>Hit the Finish button</li>
+                        </ol>
+                    </li>
+                    <li>if Eclipse does not recognize that this project is shared then choose Project->Share... from the Package Explorer context menu</li>
+                </ol>
+             </p>
+        </section>
+    </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/get_code.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/get_code.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/get_code.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/get_code.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+<document>
+    <properties>
+        <title>WADI - Source Code</title>
+    </properties>
+    <body>
+        <section name="Source Code">            
+            <p>
+                <b>WEB Access</b>
+                <br/>
+                    The web interface to the code can be found here <a href="http://cvs.wadi.codehaus.org/wadi/">http://cvs.wadi.codehaus.org/wadi/</a>.
+                <br/>
+                <b>Anonymous Access</b>
+                <br/>
+                    Describe this after the move to SVN is complete.
+                <br/>
+                <b>Developer Access</b>    
+                <br/>    
+                    Describe this after the move to SVN is complete.
+                <br/>
+            </p>
+        </section>
+    </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/index.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/index.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/index.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/documentation/index.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<document>
+    <properties>
+        <title>WADI - Documentation</title>
+    </properties>
+    <body>
+        <section name="Documentation">            
+            <p>
+                <ul>
+                    <li><a href="../getting-started/index.html">Getting Started</a></li>
+                </ul>
+            </p>
+        </section>
+        <section name="Installation and Configuration">                  
+            <a name="installation"></a>
+            <p>
+                <ul>
+                    <li><a href="./eclipse.html">Eclipse and WADI</a></li>
+                    <li>Configuring WADI and TOMCAT (Comming Soon)</li>
+                    <li>Configuring WADI and Jetty (Coming Soon)</li>
+                </ul>
+            </p>
+        </section>
+    </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/evacuation.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/evacuation.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/evacuation.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/evacuation.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,74 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <title>Getting Started: Evacuation</title>
+  </properties>
+  <body>
+    <section name="Evacuation">
+      "Run for your lives!"
+      <p>
+	The most common reason for a node to leave a cluster is
+	shutdown for scheduled for maintenance. With the increasing
+	frequency of software updates, this is becoming more and more
+	common and with the increasing number of nodes in your
+	cluster, more and more complex and error prone.
+      </p>
+      <p>
+	Every time a node leaves a cluster, the sessions that it is
+	carrying will become unavailable, unless they can be evacuated
+	to surviving nodes, as it leaves.
+      </p>
+      Let's take a look at WADI doing this.
+      <p>
+	We start a <font color="red">red</font> and <font color="green">green</font> node.
+      </p>
+      <p>
+	When everything has settled down, create a session on <font color="red">red</font> with e.g. :<a href="http://localhost:8080/wadi/session.jsp">http://localhost:8080/wadi/session.jsp</a>.
+      </p>
+      <p>
+	Shutdown <font color="red">red</font> gently (i.e. ctl-c).
+      </p>
+      <p>
+	<font color="red">red</font> will say something like this :
+      </p>
+      <p>
+	<code>
+	  2005/12/07 21:24:55:568 GMT [DEBUG] Utils - -motion: 9B8858BA311C365632247E66387415BA : memory -> cluster (65 millis)
+	</code>
+      </p>
+      <p>
+	<font color="green">green</font> should say e.g. :
+      </p>
+      <p>
+	<code>
+	  Utils - -motion: 9B8858BA311C365632247E66387415BA : cluster -> memory (20 millis)
+	</code>
+      </p>
+      <p>
+	and the Partition Master (in this case <font color="green">green</font>, because it is the only surviving node):
+      </p>
+      <p>
+	<code>
+	  LocalPartition#67@green - -relocation {9B8858BA311C365632247E66387415BA : red -> green}
+	</code>
+      </p>
+      <p>
+	Note that Partitions are evacuated first and then Sessions
+	are evacuated to their respective Partitions. This ensures
+	that the sessions are left in the most efficient place that
+	they can be and are scattered evenly around the surviving
+	nodes.
+      </p>
+      <p>
+	In this way, WADI maintains the availability of sessions beyond the lifetime of their container.
+      </p>
+    </section>
+      <p>
+      Try creating more than one session on a node in a larger cluster
+      and then shutting it down - you may need to restart your
+      browser, use more than one browser, or a tool like Jakarta
+      JMeter. You should see sessions evacuating from this node to
+      different nodes all across the cluster.
+      </p>
+  </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/geronimo.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/geronimo.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/geronimo.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/geronimo.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <title>Getting Started - Geronimo</title>
+  </properties>
+  <body>
+    <section name="Getting Started - Geronimo">
+      TODO !
+    </section>
+  </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/index.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/index.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/index.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/index.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,43 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <title>Getting Started with WADI</title>
+  </properties>
+  <body>
+    <section name="Getting Started with WADI">
+      <p>
+	To familiarise yourself with WADI, you will need to follow the following steps:
+      </p>
+      <p>
+	If you are impatient, forget about running the s/w and go
+	straight to the demos. You should be able to glean quite a lot
+	from just reading through them.
+      </p>
+      <p>
+	NOTE - say something about this release being a 'technology
+	preview' and how to treat it gently...
+      </p>
+      <p>
+	NOTE - say something about setting up the browser - cookies
+	required (Konqueror may not work - and why)
+      </p>
+      <p>
+	<ol>
+	  <li><a href="./install.html">installation guide</a> (REHASH)</li>
+	  <li><a href="./start.html">start</a> the required services (REHASH)</li>
+	  <li>
+	    walk through some demos:
+	    <ul>
+	      <li><a href="./partitioning.html">partitioning</a> demo</li>
+	      <li><a href="./location.html">location</a> demo</li>
+	      <li><a href="./evacuation.html">evacuation</a> demo</li>
+	      <li><a href="./paging.html">paging</a> demo</li>
+	      <li><a href="./loadbalancing.html">load balancing</a> demo (mod_jk2) (REHASH)</li>
+	      <li><a href="./jmxmonitoring.html">JMX monitoring</a> demo (mc4j) (REHASH)</li>
+	    </ul>
+	  </li>
+	</ol>
+      </p>
+    </section>
+  </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/install.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/install.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/install.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/install.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <title>Getting Started with WADI</title>
+  </properties>
+  <body>
+    <section name="Getting Started: Installation">
+      <p>
+	You can put together a heterogeneous cluster of <a href="./tomcat.html">Tomcat</a>, <a href="./jetty.html">Jetty</a>,<a href="./geronimo.html">Geronimo</a> and <a href="./jboss.html">JBoss</a> instances.
+      </p>
+      <p>
+	If you are using a clustered configuration
+	<ol>
+	  <li>Download a copy of <a href="http://dist.codehaus.org/activemq/distributions">activemq-3.2.1</a> - unpack it somewhere</li>
+	  <li>Set ACTIVEMQ_HOME to this dir and export it</li>
+	  <li>Then
+	    <ul>
+	      <li>
+		Either:
+		<ol>
+		  <li>download a copy of WADI 2.0-SNAPSHOT - unpack it somewhere</li>
+		  <li>set WADI_HOME to this dir and export it</li>
+		</ol>
+	      </li>
+	      <li>
+		Or:
+		<ol>
+		  <li>check out the latest WADI src from CVS</li>
+		  <li>Build it</li>
+		  <li>set WADI_HOME to the top of this tree and export it</li>
+		</ol>
+	      </li>
+	    </ul>
+	  </li>
+	</ol>
+      </p>
+    </section>
+  </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jboss.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jboss.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jboss.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jboss.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,46 @@
+<?xml version="1.0"?>
+<document>
+    <properties>
+        <title>Getting Started - JBoss</title>
+    </properties>
+    <body>
+        <section name="Getting Started - JBoss">            
+            <p>
+                 <ol>
+                     <li>download a copy of <a href="http://www.jboss.com/products/jbossas/downloads">JBoss4.0+</a> - unpack it somewhere</li>
+                     <li>set JBOSS4_HOME to this directory and export it</li>
+                     <li>Copy $WADI_HOME/lib/wadi-jboss4-*.jar to e.g. $JBOSS4_HOME/server/default/lib (contains logging integration - see below)</li>
+                     <li>Create a wadi.sar containing all the jars from $WADI_HOME/lib (except wadi-jboss4-*.sar) and a META-INF/jboss-service.xml (use e.g. $WADI_HOME/conf/jboss-service.xml)</li>
+                     <li>copy the sar into e.g. $JBOSS4_HOME/server/default/deploy</li>
+                     <li>copy $WADI_HOME/webapps/wadi-webapp-*.war into the same dir</li>
+                     <li>In $JBOSS4_HOME/bin, start your JBoss like this
+                         <code><pre>JAVA_OPTS="-Dx=... -Dy=..." ./run.sh</pre></code>
+                         where x,y..z are properties from your chosen conf/node.*.properties file.
+                     </li>
+                     <li>If you are using the DiscStore, you may have to create a 'sessions' dir underneath java.io.tmpdir for WADI to page sessions in and out of.</li>
+                </ol>
+                
+                Logging Integration :
+                <br/>
+                <br/>
+                JBoss4 uses a customised log4j (adds 'trace' level) for logging. WADI uses the commons-logging API. By default, WADI will log out to JBosses loggers, but WADI trace-level will be collapsed into JBoss debug-level. This can be annoying. wadi-jboss4-*.jar contains a Log class that bridges the gap between the two logging systems and channels WADI-trace to JBoss-trace. It cannot be installed via the wadi.sar, since it must be available to log4j at startup time, hence the alternate deployment location.
+                <br/>
+                <br/>
+                Actually getting trace output from JBoss can be quite problematic in itself. Here is how I achieve it.
+                
+                <ol>
+                    <li>Remove the 'Threshold' attribute from your &lt;appender/&gt; clause - Setting it to 'TRACE' does not seem to work (probably because this is a custom log level).</li>
+                    <li>To enable WADI trace level logging, include a category clause e.g. : 
+                        <code><pre>&lt;category name="org.codehaus.wadi"&gt;&lt;priority value="TRACE" class="org.jboss.logging.XLevel"/&gt;&lt;/category&gt;</pre></code>
+                    </li>
+                    <li>In order to get the logging bridge installed add a:
+                        <code><pre>-Dorg.apache.commons.logging.Log=org.codehaus.wadi.jboss4.JBossLog</pre></code>
+                        to your JAVA_OPTS when starting JBoss.
+                    </li>                  
+                </ol>
+                    
+                An example log4j.xml is included in $WADI_HOME/conf/jboss-log4j.xml. This may be copied to or merged with e.g. $JBOSS_HOME/server/default/conf/log4j.xml
+            </p>
+        </section>
+    </body>
+</document>

Added: incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jetty.xml
URL: http://svn.apache.org/viewcvs/incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jetty.xml?rev=356933&view=auto
==============================================================================
--- incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jetty.xml (added)
+++ incubator/wadi/trunk/wadi-site/src/site/xdoc/getting-started/jetty.xml Wed Dec 14 15:32:56 2005
@@ -0,0 +1,26 @@
+<?xml version="1.0"?>
+<document>
+    <properties>
+        <title>Getting Started - Jetty</title>
+    </properties>
+    <body>
+        <section name="Getting Started - Jetty">            
+            <p>
+                Either:
+                <ol>
+                    <li>download a copy of <a href="http://sourceforge.net/project/showfiles.php?group_id=7322">Jetty 5+</a> - unpack it somewhere</li>
+                    <li>set JETTY5_HOME to this directory and export it</li>
+                </ol>
+                Or:
+                <ol>
+                    <li>download a copy of <a href="http://sourceforge.net/project/showfiles.php?group_id=7322">Jetty 6+</a> - unpack it somewhere</li>
+                    <li>set JETTY6_HOME to this directory and export it</li>
+                </ol>
+                
+                Finally, to start the node :
+                
+                from $WADI_HOME/bin run e.g. './node.sh jetty5 <font color="red">red</font>' or './node.sh jetty6 <font color="red">red</font>'
+            </p>
+        </section>
+    </body>
+</document>



Mime
View raw message