You are viewing a plain text version of this content. The canonical link for it is here.
Posted to wadi-commits@incubator.apache.org by bd...@apache.org on 2005/12/14 23:36:16 UTC
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...
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 <distributable/> 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 <distributable/> 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 & 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 <appender/> 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><category name="org.codehaus.wadi"><priority value="TRACE" class="org.jboss.logging.XLevel"/></category></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>