This is the README for how to set up the Fossil/JSON test web page
under Apache on Unix systems. This is only intended only for
Fossil/JSON developers/tinkerers:

First, copy cgi-bin/fossil-json.cgi.example to
cgi-bin/fossil-json.cgi.  Edit it and correct the paths to the fossil
binary and the repo you want to serve. Make it executable.

MAKE SURE that the fossil repo you use is world-writable OR that your
Web/CGI server is set up to run as the user ID of the owner of the
fossil file. ALSO: the DIRECTORY CONTAINING the repo file must be
writable by the CGI process.

Next, set up an apache vhost entry. Mine looks like:

<VirtualHost *:80>
    ServerAlias fjson
    ScriptAlias /cgi-bin/ /home/stephan/cvs/fossil/fossil-json/ajax/cgi-bin/
    DocumentRoot /home/stephan/cvs/fossil/fossil-json/ajax
</VirtualHost>

Now add your preferred vhost name (fjson in the above example) to /etc/hosts:

  127.0.0.1 ...other aliases... fjson

Restart your Apache.

Now visit: http://fjson/

that will show the test/demo page. If it doesn't, edit index.html and
make sure that:

  WhAjaj.Connector.options.ajax.url = ...;

points to your CGI script. In theory you can also do this over fossil
standalone server mode, but i haven't yet tested that particular test
page in that mode.

#!/path/to/fossil/binary
repository: /path/to/repo.fsl

var TestApp = {
    serverUrl:
        //'http://localhost:8080'
        //'http://fjson/cgi-bin/fossil-json.cgi'
        //'http://192.168.1.62:8080'
        'http://fossil.wanderinghorse.net/repos/fossil-json-java/index.cgi'
        ,
    verbose:true,
    wiki:{}
};
(function bootstrap() {
    var srcdir = '../js/';
    var includes = [srcdir+'json2.js',
                    srcdir+'whajaj.js',
                    srcdir+'fossil-ajaj.js'
                    ];
    for( var i in includes ) {
        load(includes[i]);
    }
    WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.rhino;
    TestApp.fossil = new FossilAjaj({
        asynchronous:false, /* rhino-based impl doesn't support async or timeout. */
        timeout:0,
        url:TestApp.serverUrl,
        beforeSend:function(req,opt){
            if(!TestApp.verbose) return;
            print("SENDING REQUEST: AJAJ options="+JSON.stringify(opt));
            if(req) print("Request envelope="+WhAjaj.stringify(req));
        },
        afterSend:function(req,opt){
            //if(!TestApp.verbose) return;
            //print("REQUEST RETURNED: opt="+JSON.stringify(opt));
            //if(req) print("Request="+WhAjaj.stringify(req));
        },
        onError:function(req,opt){
            if(!TestApp.verbose) return;
            print("ERROR: "+WhAjaj.stringify(opt));
        },
        onResponse:function(resp,req){
            if(!TestApp.verbose) return;
            print("GOT RESPONSE: "+(('string'===typeof resp) ? resp : WhAjaj.stringify(resp)));
        }
    });
})();

/**
    Throws an exception of cond is a falsy value.
*/
function assert(cond, descr){
    descr = descr || "Undescribed condition.";
    if(!cond){
        throw new Error("Assertion failed: "+descr);
    }else{
        print("Assertion OK: "+descr);
    }
}

/**
    Calls func() in a try/catch block and throws an exception if
    func() does NOT throw.
*/
function assertThrows(func, descr){
    descr = descr || "Undescribed condition failed.";
    var ex;
    try{
        func();
    }catch(e){
        ex = e;
    }
    if(!ex){
        throw new Error("Function did not throw (as expected): "+descr);
    }else{
        print("Function threw (as expected): "+descr+": "+ex);
    }
}

/**
    Convenience form of TestApp.fossil.sendCommand(command,payload,ajajOpt).
*/
function send(command,payload, ajajOpt){
    TestApp.fossil.sendCommand(command,payload,ajajOpt);
}

/**
    Asserts that resp is-a Object, resp.fossil is-a string, and
    !resp.resultCode.
*/
function assertResponseOK(resp){
    assert('object' === typeof resp,'Response is-a object.');
    assert( 'string' === typeof resp.fossil, 'Response contains fossil property.');
    assert( !resp.resultCode, 'resp.resultCode='+resp.resultCode);
}
/**
    Asserts that resp is-a Object, resp.fossil is-a string, and
    resp.resultCode is a truthy value. If expectCode is set then
    it also asserts that (resp.resultCode=='FOSSIL-'+expectCode).
*/
function assertResponseError(resp,expectCode){
    assert('object' === typeof resp,'Response is-a object.');
    assert( 'string' === typeof resp.fossil, 'Response contains fossil property.');
    assert( resp.resultCode, 'resp.resultCode='+resp.resultCode);
    if(expectCode){
        assert( 'FOSSIL-'+expectCode == resp.resultCode, 'Expecting result code '+expectCode );
    }
}

function testHAI(){
    TestApp.fossil.HAI({
        onResponse:function(resp,req){
            assertResponseOK(resp);
            TestApp.serverVersion = resp.fossil;
        }
    });
    assert( 'string' === typeof TestApp.serverVersion, 'server version = '+TestApp.serverVersion);
}
testHAI.description = 'Get server version info.';

function testIAmNobody(){
    TestApp.fossil.whoami('/json/whoami');
    assert('nobody' === TestApp.fossil.userName, 'User == nobody.' );
    assert(!TestApp.fossil.authToken, 'authToken is not set.' );
   
}
testIAmNobody.description = 'Ensure that current user is "nobody".';


function testAnonymousLogin(){
    TestApp.fossil.login();
    assert('string' === typeof TestApp.fossil.authToken, 'authToken = '+TestApp.fossil.authToken);
    assert( 'string' === typeof TestApp.fossil.userName, 'User name = '+TestApp.fossil.userName);
    TestApp.fossil.userName = null;
    TestApp.fossil.whoami('/json/whoami');
    assert( 'string' === typeof TestApp.fossil.userName, 'User name = '+TestApp.fossil.userName);
}
testAnonymousLogin.description = 'Perform anonymous login.';

function testAnonWiki(){
    TestApp.fossil.sendCommand('/json/wiki/list',undefined,{
        beforeSend:function(req,opt){
            TestApp.fossil.ajaj.options.beforeSend(req,opt);
            assert( req && (req.authToken==TestApp.fossil.authToken), 'Request envelope contains expected authToken.'  );
        },
        onResponse:function(resp,req){
            assertResponseOK(resp);
            assert( (typeof [] === typeof resp.payload) && resp.payload.length,
                "Wiki list seems to be okay.");
            TestApp.wiki.list = resp.payload;
        }
    });
    TestApp.fossil.sendCommand('/json/wiki/get',{
        page:TestApp.wiki.list[0]
    },{
        onResponse:function(resp,req){
            assertResponseOK(resp);
            assert(resp.payload.name == TestApp.wiki.list[0], "Fetched page name matches expectations.");
            print("Got first wiki page: "+WhAjaj.stringify(resp.payload));
        }
    });
}
testAnonWiki.description = 'Fetch wiki list as anonymous user.';

function testAnonLogout(){
    TestApp.fossil.logout({
        onResponse:function(resp,req){
            assertResponseOK(resp);
        }
    });
    TestApp.fossil.logout({
        onResponse:function(resp,req){
            assertResponseError(resp);
        }
    });
}
testAnonLogout.description = 'Log out anonymous user.';

(function runAllTests(){
    var testList = [
        testHAI,
        testIAmNobody,
        testAnonymousLogin,
        testAnonWiki,
        testAnonLogout
    ];
    var i, f;
    for( i = 0; i < testList.length; ++i ){
        f = testList[i];
        try{
            print("Running test #"+(i+1)+": "+(f.description || "no description."));
            f();
        }catch(e){
            print("Test failed: "+e);
            throw e;
        }
    }

})();

print("Done!");

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
	<title>Fossil/JSON raw request sending</title>
	<meta http-equiv="content-type" content="text/html;charset=utf-8" />
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script> 
    <script type="text/javascript" src="js/whajaj.js"></script>
    <script type="text/javascript" src="js/fossil-ajaj.js"></script>

<style type='text/css'>
th {
  text-align: left;
  background-color: #ececec;  
}

.dangerWillRobinson {
    background-color: yellow;
}
</style>

<script type='text/javascript'>
WhAjaj.Connector.options.ajax.url =
/*
    Change this to your CGI/server root path:
*/
     //'http://fjson/cgi-bin/fossil.cgi'
     //'/repos/fossil-sgb/json.cgi'
    '/cgi-bin/fossil-json.cgi'
     ;
var TheApp = {
      response:null,
      sessionID:null,
      jqe:{}/*jqe==jQuery Elements*/,
      ajaxCount:0,
      cgi: new FossilAjaj()
};


TheApp.startAjaxNotif = function()
{
    ++this.ajaxCount;
    TheApp.jqe.responseContainer.removeClass('dangerWillRobinson');
    this.jqe.ajaxNotification.attr( 'title', this.ajaxCount+" pending AJAX operation(s)..." );
    if( 1 == this.ajaxCount ) this.jqe.ajaxNotification.fadeIn();
};

TheApp.endAjaxNotif = function()
{
    --this.ajaxCount;
    this.jqe.ajaxNotification.attr( 'title', this.ajaxCount+" pending AJAX operation(s)..." );
    if( 0 == this.ajaxCount ) this.jqe.ajaxNotification.fadeOut();
};

TheApp.responseContainsError = function(resp) {
    if( resp && resp.resultCode ) {
        //alert("Error response:\n"+JSON.stringify(resp,0,4));
        TheApp.jqe.taResponse.val( "RESPONSE CONTAINS ERROR INFO:\n"+WhAjaj.stringify(resp) );
        //TheApp.jqe.responseContainer.css({backgroundColor:'yellow'});
        //TheApp.jqe.responseContainer.addClass('dangerWillRobinson');
        TheApp.jqe.responseContainer.flash( '255,0,0', 1500 );
        return true;
    }
    return false;
};


TheApp.sendRequest = function() {
    var path = this.jqe.textPath.val();
    var self = this;
    var data = this.jqe.taRequest.val();
    var doPost = (data && data.length);
    var req;
    if( doPost ) try {
        req = JSON.parse(data);
    }
    catch(e) {
        TheApp.jqe.taResponse.val("Request is not valid JSON.\n"+e);
        return;
    }
    if( req ) {
        req.requestId = this.cgi.generateRequestId();
    }
    var self = this;
    var opt = {
        url: WhAjaj.Connector.options.ajax.url + path,
        method: doPost ? 'POST' : 'GET'
    };
    this.cgi.sendRequest( req, opt );
};
jQuery.fn.animateHighlight = function(highlightColor, duration) {
    var highlightBg = highlightColor || "#FFFF9C";
    var animateMs = duration || 1500;
    var originalBg = this.css("backgroundColor");
    this.stop().css("background-color", highlightBg).animate({backgroundColor: originalBg}, animateMs);
};
jQuery.fn.flash = function( color, duration )
{
    var current = this.css( 'color' );
    this.animate( { color: 'rgb(' + color + ')' }, duration / 2);
    this.animate( { color: current }, duration / 2 );
};

function myJsonPCallback(obj){
    alert("JSONP callback got:\n"+WhAjaj.stringify(obj));
}

jQuery(document).ready(function(){
    var ids = [// list of HTML element IDs we use often.
        'btnSend',
        'ajaxNotification',
        'currentAuthToken',
        'responseContainer',
        'taRequest',
        'taRequestOpt',
        'taResponse',
        'textPath',
        'timer'
    ];
    var i, k;
    for( i = 0; i < ids.length; ++i ) {
        k = ids[i];
        TheApp.jqe[k] = jQuery('#'+k);
    }
    TheApp.jqe.textPath.
        keyup(function(event){
            if(event.keyCode == 13){
                TheApp.sendRequest();
            }
        });
    TheApp.timer = {
        _tstart:0,_tend:0,duration:0,
        start:function(){
            this._tstart = (new Date()).getTime();
        },
        end:function(){
            this._tend = (new Date()).getTime();
            return this.duration = this._tend - this._tstart;
        }
    };
    var opt = TheApp.cgi.ajaj.options;
    opt.beforeSend = function(req,opt) {
        TheApp.timer.start();
        var val =
            req ?
            (('string'===typeof req) ? req : WhAjaj.stringify(req))
            : '';
        TheApp.jqe.taResponse.val('');
        TheApp.jqe.taRequest.val( val );
        TheApp.jqe.taRequestOpt.val( opt ? WhAjaj.stringify(opt) : '' );
        TheApp.startAjaxNotif();
    };
    opt.afterSend = function(req,opt) {
        TheApp.timer.end();
        TheApp.endAjaxNotif();
        TheApp.jqe.timer.text( "(Round-trip time (incl. JS overhead): "+TheApp.timer.duration+'ms)' );
    };
    opt.onResponse = function(resp,req) {
        var val;
        if(this.jsonp) return /*was already handled*/;
        try {
            val = WhAjaj.stringify(resp);
        }
        catch(e) {
            val = WhAjaj.stringify(e)
        }
        //alert("onResponse this:"+WhAjaj.stringify(this));
        //alert("val="+val);
        // FIXME: this.url is hosed for login because of how i overload onResponse()
        if( this.url ) TheApp.jqe.textPath.val(this.url.replace(WhAjaj.Connector.options.ajax.url,''));
        TheApp.jqe.taResponse.val( val );
    };
    opt.onError = function(req,opt) {
        TheApp.jqe.taResponse.val( "ERROR SENDING REQUEST:\n"+WhAjaj.stringify(opt) );
    };

    TheApp.cgi.onLogin = function(){
      TheApp.jqe.taResponse.val( "Logged in. Auth token =\n"+this.authToken );
      TheApp.jqe.currentAuthToken.text("Auth token: "+(this.authToken || "not logged in"));
    };
    TheApp.cgi.onLogout = function(){
      TheApp.jqe.taResponse.val( "Logged out!" );
      TheApp.jqe.currentAuthToken.text("");
    };

});

</script>

</head>

<body>
<span id='ajaxNotification'></span>
<h1>You know, for sending raw JSON requests to Fossil...</h1>

If you're actually using this page, then you know what you're doing and don't
need help text, hoverhelp, and a snazzy interface.

<br><br>
See also: <a href='wiki-editor.html'>prototype wiki editor</a>.

<h2>Request...</h2>

Path: <input type='text' size='40' id='textPath' value='/json/HAI'/>
<input type='button' value='Send...' id='btnSend' onclick='TheApp.sendRequest()' /><br/>
If the POST textarea is not empty then it will be posted with the request.
<hr/>
<strong>Quick-posts:</strong><br/>
<input type='button' value='HAI' onclick='TheApp.cgi.HAI()' />
<input type='button' value='HAI JSONP' onclick='TheApp.cgi.sendCommand("/json/HAI",undefined,{jsonp:"myJsonPCallback"});' />

<input type='button' value='version' onclick='TheApp.cgi.sendCommand("/json/version")' />
<input type='button' value='stat' onclick='TheApp.cgi.sendCommand("/json/stat")' />
<input type='button' value='whoami' onclick='TheApp.cgi.sendCommand("/json/whoami")' />
<input type='button' value='cap' onclick='TheApp.cgi.sendCommand("/json/cap")' />
<input type='button' value='branch/list' onclick='TheApp.cgi.sendCommand("/json/branch/list")' />
<input type='button' value='timeline/ci' onclick='TheApp.cgi.sendCommand("/json/timeline/ci?files=true")' />
<input type='button' value='timeline/wiki' onclick='TheApp.cgi.sendCommand("/json/timeline/wiki")' />
<input type='button' value='timeline/ticket' onclick='TheApp.cgi.sendCommand("/json/timeline/ticket")' />
<input type='button' value='wiki/list' onclick='TheApp.cgi.sendCommand("/json/wiki/list")' />
<input type='button' value='wiki/get Fossil' onclick='TheApp.cgi.sendCommand("/json/wiki/get",{page:"Fossil"})' />
<input type='button' value='user/list' onclick='TheApp.cgi.sendCommand("/json/user/list")' />
<input type='button' value='user/get' onclick='TheApp.cgi.sendCommand("/json/user/get?name=anonymous")' />
<input type='button' value='artifact/XYZ' onclick='TheApp.cgi.sendCommand("/json/artifact?uuid=json")' />

<!--
<input type='button' value='get whiki' onclick='TheApp.cgi.getPages("whiki")' />
<input type='button' value='get more' onclick='TheApp.cgi.getPages("HelloWorld/WhikiNews")' />
<input type='button' value='get client data' onclick='TheApp.cgi.getPageClientData("HelloWorld/whiki/WhikiCommands")' />
<input type='button' value='save client data' onclick='TheApp.cgi.savePageClientData({"HelloWorld":[1,3,5]})' />
-->
<hr/>
<b>Login:</b>
<br/>
<input type='button' value='Anon. PW' onclick='TheApp.cgi.sendCommand("/json/anonymousPassword")' />
<input type='button' value='Anon. PW+Login' onclick='TheApp.cgi.login()' />
<br/>
name:<input type='text' id='textUser' value='json-demo' size='12'/>
pw:<input type='password' id='textPassword' value='json-demo' size='12'/>
<input type='button' value='login' onclick='TheApp.cgi.login(jQuery("#textUser").val(),jQuery("#textPassword").val(),{onResponse:TheApp.onLogin})' />
<input type='button' value='logout' onclick='TheApp.cgi.logout()' />
<br/>
<span id='currentAuthToken' style='font-family:monospaced'></span>

<br/>

<hr/>

<table>
    <tr>
        <th>POST data</th>
        <th>Request AJAJ options</th>
    </tr>
    <tr>
        <td width='50%'>
            
            <textarea id='taRequest' rows='10' cols='50'></textarea>
        </td>
        <td width='50%'>
            <textarea id='taRequestOpt' rows='10' cols='40' readonly></textarea>
            
        </td>
    </tr>
    <tr>
        <th colspan='2'>Response <span id='timer'></span></th>
    </tr>
    <tr>
        <td colspan='2' id='responseContainer'>
            <textarea id='taResponse' rows='20' cols='80' readonly></textarea>
        </td>
    </tr>
</table>
<div></div>
<div></div>
<div></div>

</body></html>

/**
    This file contains a WhAjaj extension for use with Fossil/JSON.

    Author: Stephan Beal (sgbeal@googlemail.com)

    License: Public Domain
*/

/**
    Constructor for a new Fossil AJAJ client. ajajOpt may be an optional
    object suitable for passing to the WhAjaj.Connector() constructor.
    
    On returning, this.ajaj is-a WhAjaj.Connector instance which can 
    be used to send requests to the back-end (though the convenience 
    functions of this class are the preferred way to do it). Clients 
    are encouraged to use FossilAjaj.sendCommand() (and friends) instead 
    of the underlying WhAjaj.Connector API, since this class' API 
    contains Fossil-specific request-calling handling (e.g. of authentication
    info) whereas WhAjaj is more generic.
*/
function FossilAjaj(ajajOpt)
{
    this.ajaj = new WhAjaj.Connector(ajajOpt);
    return this;
}

FossilAjaj.prototype.generateRequestId = function() {
    return this.ajaj.generateRequestId();
};

/**
   Proxy for this.ajaj.sendRequest().
*/
FossilAjaj.prototype.sendRequest = function(req,opt) {
    return this.ajaj.sendRequest(req,opt);
};

/**
    Sends a command to the fossil back-end. Command should be the
    path part of the URL, e.g. /json/stat, payload is a request-specific
    value type (may often be null/undefined). ajajOpt is an optional object
    holding WhAjaj.sendRequest()-compatible options.
    
    This function constructs a Fossil/JSON request envelope based
    on the given arguments and adds this.authToken and a requestId
    to it.
*/
FossilAjaj.prototype.sendCommand = function(command, payload, ajajOpt) {
    var req;
    ajajOpt = ajajOpt || {};
    if(payload || this.authToken || ajajOpt.jsonp) {
        req = {
            payload:payload,
            requestId:('function' === typeof this.generateRequestId) ? this.generateRequestId() : undefined,
            authToken:this.authToken || undefined,
            jsonp:('string' === typeof ajajOpt.jsonp) ? ajajOpt.jsonp : undefined
        };
    }
    ajajOpt.method = req ? 'POST' : 'GET';
    // just for debuggering: ajajOpt.method = 'POST'; if(!req) req={};
    if(command) ajajOpt.url = this.ajaj.derivedOption('url',ajajOpt) + command;
    this.ajaj.sendRequest(req,ajajOpt);
};

/**
    Sends a login request to the back-end.

    ajajOpt is an optional configuration object suitable for passing 
    to sendCommand().

    After the response returns, this.authToken will be
    set to the response payload.
    
    If name === 'anonymous' (the default if none is passed in) then
    this function must make two requests - the first one gets the
    captcha code and the second one submits it.
    
    If this object has an onLogin() function it is called (with
    no arguments) before the onResponse() handler of the login is called
    (that is the 2nd request for anonymous logins).

*/
FossilAjaj.prototype.login = function(name,pw,ajajOpt) {
    name = name || 'anonymous';
    var self = this;
    var loginReq = {
        name:name,
        password:pw
    };
    ajajOpt = this.ajaj.normalizeAjaxParameters( ajajOpt || {} );
    var oldOnResponse = ajajOpt.onResponse;
    ajajOpt.onResponse = function(resp,req) {
        var thisOpt = this;
        //alert('login response:\n'+WhAjaj.stringify(resp));
        if( resp && resp.payload ) {
            self.authToken = resp.payload.authToken;
            self.userName = resp.payload.name;
            self.capabilities = resp.payload.capabilities;
        }
        if( WhAjaj.isFunction( self.onLogin ) ){
            try{ self.onLogin(); }
            catch(e){}
        }
        if( WhAjaj.isFunction(oldOnResponse) ) {
            oldOnResponse.apply(thisOpt,[resp,req]);
        }
    };
    function doLogin(){
        //alert("Sending login request..."+WhAjaj.stringify(loginReq));
        self.sendCommand('/json/login', loginReq, ajajOpt);
    }
    if( 'anonymous' === name ){
      this.sendCommand('/json/anonymousPassword',undefined,{
          onResponse:function(resp,req){
            if( WhAjaj.isFunction(oldOnResponse) ){
                oldOnResponse.apply(this, [resp,req]);
            };
            if(resp && !resp.resultCode){
                //alert("Got PW. Trying to log in..."+WhAjaj.stringify(resp));
                loginReq.anonymousSeed = resp.payload.seed;
                loginReq.password = resp.payload.password;
                doLogin();
            }
          }
      });
    }
    else doLogin();
};

/**
    Logs out of fossil, invaliding this login token.

    ajajOpt is an optional configuration object suitable for passing 
    to sendCommand().
    
    If this object has an onLogout() function it is called (with
    no arguments) before the onResponse() handler is called.
    IFF the response succeeds then this.authToken is unset.
*/
FossilAjaj.prototype.logout = function(ajajOpt) {
    var self = this;
    ajajOpt = this.ajaj.normalizeAjaxParameters( ajajOpt || {} );
    var oldOnResponse = ajajOpt.onResponse;
    ajajOpt.onResponse = function(resp,req) {
        var thisOpt = this;
        if( resp && !resp.payload ) delete self.authToken;
        if( WhAjaj.isFunction( self.onLogout ) ){
            try{ self.onLogout(); }
            catch(e){}
        }
        if( WhAjaj.isFunction(oldOnResponse) ) {
            oldOnResponse.apply(thisOpt,[resp,req]);
        }
    };
    this.sendCommand('/json/logout', undefined, ajajOpt );
};

/**
    Sends a HAI request to the server. /json/HAI is an alias /json/version.

    ajajOpt is an optional configuration object suitable for passing 
    to sendCommand().
*/
FossilAjaj.prototype.HAI = function(ajajOpt) {
    this.sendCommand('/json/HAI', undefined, ajajOpt);
};


/**
    Sends a /json/whoami request. Updates this.userName and this.authToken
    based on the response, removing them if the response does not contain
    that data.
*/
FossilAjaj.prototype.whoami = function(ajajOpt) {
    var self = this;
    ajajOpt = this.ajaj.normalizeAjaxParameters( ajajOpt || {} );
    var oldOnResponse = ajajOpt.onResponse;
    ajajOpt.onResponse = function(resp,req) {
        var thisOpt = this;
        if( resp && resp.payload ){
            self.authToken = resp.payload.authToken;
            self.userName = resp.payload.name;
        }
        else {
            delete self.userName;
            delete self.authToken
        }
        if( WhAjaj.isFunction(oldOnResponse) ) {
            oldOnResponse.apply(thisOpt,[resp,req]);
        }
    };
    self.sendCommand('/json/whoami', undefined, ajajOpt);
};

/**
    This file provides a JS interface into the core functionality of
    JSON-centric back-ends. It sends GET or JSON POST requests to
    a back-end and expects JSON responses. The exact semantics of
    the underlying back-end and overlying front-end are not its concern,
    and it leaves the interpretation of the data up to the client/server
    insofar as possible.

    All functionality is part of a class named WhAjaj, and that class
    acts as namespace for this framework.

    Author: Stephan Beal (http://wanderinghorse.net/home/stephan/)

    License: Public Domain
    
    This framework is directly derived from code originally found in 
    http://code.google.com/p/jsonmessage, and later in 
    http://whiki.wanderinghorse.net, where it contained quite a bit 
    of application-specific logic. It was eventually (the 3rd time i 
    needed it) split off into its own library to simplify inclusion 
    into my many mini-projects.
*/


/**
    The WhAjaj function is primarily a namespace, and not intended 
    to called or instantiated via the 'new' operator.
*/
function WhAjaj()
{
}

/** Returns a millisecond Unix Epoch timestamp. */
WhAjaj.msTimestamp = function()
{
    return (new Date()).getTime();
};

/** Returns a Unix Epoch timestamp (in seconds) in integer format.

    Reminder to self: (1.1 %1.2) evaluates to a floating-point value 
    in JS, and thus this implementation is less than optimal.
*/
WhAjaj.unixTimestamp = function()
{
    var ts = (new Date()).getTime();
    return parseInt( ""+((ts / 1000) % ts) );
};

/**
    Returns true if v is-a Array instance.
*/
WhAjaj.isArray = function( v )
{
    return (v &&
            (v instanceof Array) ||
            (Object.prototype.toString.call(v) === "[object Array]")
            );
    /* Reminders to self:
        typeof [] == "object"
        toString.call([]) == "[object Array]"
        ([]).toString() == empty
    */
};

/**
    Returns true if v is-a Object instance.
*/
WhAjaj.isObject = function( v )
{
    return v &&
        (v instanceof Object) &&
        ('[object Object]' === Object.prototype.toString.apply(v) );
};

/**
    Returns true if v is-a Function instance.
*/
WhAjaj.isFunction = function(obj)
{
    return obj
    && (
    (obj instanceof Function)
    || ('function' === typeof obj)
    || ("[object Function]" === Object.prototype.toString.call(obj))
    )
    ;
};

/**
    Parses window.location.search-style string into an object
    containing key/value pairs of URL arguments (already urldecoded).
    
    If the str argument is not passed (arguments.length==0) then 
    window.location.search.substring(1) is used by default. If 
    neither str is passed in nor window exists then false is returned.

    On success it returns an Object containing the key/value pairs
    parsed from the string.
    
    FIXME: for keys in the form "name[]", build an array of results,
    like PHP does.
 
*/
WhAjaj.processUrlArgs = function(str) {
    if( 0 === arguments.length ) {
        if( (undefined === typeof window) ||
            !window.location ||
            !window.location.search )  return false;
        else str = (''+window.location.search).substring(1);
    }
    if( ! str ) return false;
    var args = {};
    var sp = str.split(/&+/);
    var rx = /^([^=]+)(=(.+))?/;
    var i, m;
    for( i in sp ) {
        m = rx.exec( sp[i] );
        if( ! m ) continue;
        args[decodeURIComponent(m[1])] = (m[3] ? decodeURIComponent(m[3]) : true);
    }
    return args;
};

/**
    A simple wrapper around JSON.stringify(), using my own personal
    preferred values for the 2nd and 3rd parameters. To globally
    set its indentation level, assign WhAjaj.stringify.indent to
    an integer value (0 for no intendation).
    
    This function is intended only for human-readable output, not
    generic over-the-wire JSON output (where JSON.stringify(val) will
    produce smaller results).
*/
WhAjaj.stringify = function(val) {
    if( ! arguments.callee.indent ) arguments.callee.indent = 4;
    return JSON.stringify(val,0,arguments.callee.indent);
};

/**
    Each instance of this class holds state information for making 
    AJAJ requests to a back-end system. While clients may use one 
    "requester" object per connection attempt, for connections to the
    same back-end, using an instance configured for that back-end 
    can simplify usage. This class is designed so that the actual 
    connection-related details (i.e. _how_ it connects to the 
    back-end) may be re-implemented to use a client's preferred 
    connection mechanism (e.g. jQuery).
    
    The optional opt paramater may be an object with any (or all) of 
    the properties documented for WhAjaj.Connector.options.ajax. 
    Properties set here (or later via modification of the "options" 
    property of this object) will be used in calls to 
    WhAjaj.Connector.sendRequest(), and these override (normally) any
    options set in WhAjaj.Connector.options.ajax. Note that 
    WhAjaj.Connector.sendRequest() _also_ takes an options object, 
    and ones passed there will override, for purposes of that one 
    request, any options passed in here or defined in 
    WhAjaj.Connector.options.ajax. See WhAjaj.Connector.options.ajax
    and WhAjaj.Connector.prototype.sendRequest() for more details
    about the precedence of options.
    
    Sample usage:
    
    @code
    // Set up common connection-level options:
    var cgi = new WhAjaj.Connector({
        url: '/cgi-bin/my.cgi',
        timeout:10000,
        onResponse(resp,req) { alert(JSON.stringify(resp,0.4)); },
        onError(req,opt) {
            alert(opt.errorMessage);
        }
    });
    // Any of those options may optionally be set globally in
    // WhAjaj.Connector.options.ajax (onError(), beforeSend(), and afterSend()
    // are often easiest/most useful to set globally).

    // Get list of pages...
    cgi.sendRequest( null, {
        onResponse(resp,req){ alert(WhAjaj.stringify(resp)); }
    });
    @endcode

    For common request types, clients can add functions to this
    object which act as wrappers for backend-specific functionality. As
    a simple example:
    
    @code
    cgi.login = function(name,pw,ajajOpt) {
        this.sendRequest( {name:name, password:pw}, ajajOpt );
    };
    @endcode
    
    TODOs:
    
    - Caching of page-load requests, with a configurable lifetime.
    
    - Use-cases like the above login() function are a tiny bit 
    problematic to implement when each request has a different URL 
    path (i know this from the whiki implementation). This is partly 
    a side-effect of design descisions made back in the very first 
    days of this code's life. i need to go through and see where i 
    can bend those conventions a bit (where it won't break my other 
    apps unduly).
*/
WhAjaj.Connector = function(opt)
{
    this.options = WhAjaj.isObject(opt) ? opt : {};
    //TODO?: this.$cache = {};
};

/**
    The core options used by WhAjaj.Connector instances for performing
    network operations. These options can (and some _should_)
    be changed by a client application. They can also be changed
    on specific instances of WhAjaj.Connector, but for most applications
    it is simpler to set them here and not have to bother with configuring
    each WhAjaj.Connector instance. Apps which use multiple back-ends at one time,
    however, will need to customize each instance for a given back-end.
*/
WhAjaj.Connector.options = {
    /**
        A (meaningless) prefix to apply to WhAjaj.Connector-generated
        request IDs.
    */
    requestIdPrefix:'WhAjaj.Connector-',
    /**
        Default options for WhAjaj.Connector.sendRequest() connection 
        parameters. This object holds only connection-related 
        options and callbacks (all optional), and not options 
        related to the required JSON structure of any given request. 
        i.e. the page name used in a get-page request are not set 
        here but are specified as part of the request object.

        These connection options are a "normalized form" of options 
        often found in various AJAX libraries like jQuery, 
        Prototype, dojo, etc. This approach allows us to swap out 
        the real connection-related parts by writing a simple proxy 
        which transforms our "normalized" form to the 
        backend-specific form. For examples, see the various 
        implementations stored in WhAjaj.Connector.sendImpls.

        The following callback options are, in practice, almost 
        always set globally to some app-wide defaults:

        - onError() to report errors using a common mechanism.
        - beforeSend() to start a visual activity notification
        - afterSend() to disable the visual activity notification

        However, be aware that if any given WhAjaj.Connector instance is 
        given its own before/afterSend callback then those will 
        override these. Mixing shared/global and per-instance
        callbacks can potentially lead to confusing results if, e.g.,
        the beforeSend() and afterSend() functions have side-effects
        but are not used with their proper before/after partner.
        
        TODO: rename this to 'ajaj' (the name is historical). The 
        problem with renaming it is is that the word 'ajax' is 
        pretty prevelant in the source tree, so i can't globally 
        swap it out.
    */
    ajax: {
        /**
            URL of the whiki back-end CGI binary.
        */
        url: '/some/path',

        /**
            Connection method. Some connection-related functions might
            override any client-defined setting.
            
            Must be one of 'GET' or 'POST'. For custom connection 
            implementation, it may optionally be some 
            implementation-specified value.

            Normally the API can derive this value automatically - if the
            request uses JSON data it is POSTed, else it is GETted.
        */
        method:'GET',

        /**
            A hint whether to run the operation asynchronously or 
            not. Not all concrete WhAjaj.Connector.sendImpl() 
            implementations can support this. Interestingly, at 
            least one popular AJAX toolkit does not document 
            supporting _synchronous_ AJAX operations. All common 
            browser-side implementations support async operation, but 
            non-browser implementations migth not.
        */
        asynchronous:true,

        /**
            A HTTP authentication login name for the AJAX 
            connection. Not all concrete WhAjaj.Connector.sendImpl() 
            implementations can support this.
        */
        loginName:undefined,

        /**
            An HTTP authentication login password for the AJAJ 
            connection. Not all concrete WhAjaj.Connector.sendImpl() 
            implementations can support this.
        */
        loginPassword:undefined,

        /**
            A connection timeout, in milliseconds, for establishing 
            an AJAJ connection. Not all concrete 
            WhAjaj.Connector.sendImpl() implementations can support this.
        */
        timeout:10000,

        /**
            If an AJAJ request receives JSON data from the back-end, that
            data is passed as a plain Object as the response parameter
            (exception: in jsonp mode it is passed a string). The initiating
            request object is passed as the second parameter, but clients
            can normally ignore it (only those which need a way to map
            specific requests to responses will need it).
            
            Note that the response might contain error information which
            comes from the back-end. The difference between this error info
            and the info passed to the onError() callback is that this data
            indicates an application-level error, whereas onError() is used
            to report connection-level problems or when the backend produces
            non-JSON data (which, when not in jsonp mode, is unexpected and
            is as fatal to the request as a connection error).
        */
        onResponse: function(response, request){},

        /**
            If an AJAX request fails to establish a connection or it 
            receives non-JSON data from the back-end, this function 
            is called (e.g. timeout error or host name not 
            resolvable). It is passed the originating request and the
            "normalized" connection parameters used for that 
            request. The connectOpt object "should" (or "might") 
            have an "errorMessage" property which describes the 
            nature of the problem.
            
            Clients will almost always want to replace the default 
            implementation with something which integrates into 
            their application.
        */
        onError: function(request, connectOpt)
        {
            alert('AJAJ request failed:\n'
                +'Connection information:\n'
                +JSON.stringify(connectOpt,0,4)
            );
        },

        /**
            Called before each connection attempt is made. Clients 
            can use this to, e.g.,  enable a visual "network activity
            notification" for the user. It is passed the original 
            request object and the normalized connection parameters 
            for the request. If this function changes opt, those 
            changes _are_ applied to the subsequent request. If this 
            function throws, neither the onError() nor afterSend() 
            callbacks are triggered and WhAjaj.Connector.sendImpl() 
            propagates the exception back to the caller.
        */
        beforeSend: function(request,opt){},

        /**
            Called after an AJAJ connection attempt completes, 
            regardless of success or failure. Passed the same 
            parameters as beforeSend() (see that function for 
            details).
            
            Here's an example of setting up a visual notification on 
            ajax operations using jQuery (but it's also easy to do 
            without jQuery as well):
            
            @code
            function startAjaxNotif(req,opt) {
                var me = arguments.callee;
                var c = ++me.ajaxCount;
                me.element.text( c + " pending AJAX operation(s)..." );
                if( 1 == c ) me.element.stop().fadeIn();
            }
            startAjaxNotif.ajaxCount = 0.
            startAjaxNotif.element = jQuery('#whikiAjaxNotification');
            
            function endAjaxNotif() {
                var c = --startAjaxNotif.ajaxCount;
                startAjaxNotif.element.text( c+" pending AJAX operation(s)..." );
                if( 0 == c ) startAjaxNotif.element.stop().fadeOut();
            }
            @endcode

            Set the beforeSend/afterSend properties to those 
            functions to enable the notifications by default.            
        */
        afterSend: function(request,opt){},

        /**
            If jsonp is a string then the WhAjaj-internal response
            handling code ASSUMES that the response contains a JSONP-style
            construct and eval()s it after afterSend() but before onResponse().
            In this case, onResponse() will get a string value for the response
            instead of a response object parsed from JSON. 
        */
        jsonp:undefined
    }
};

/**
    Tries to find the given key in any of the following, returning
    the first match found: opt, this.options, WhAjaj.Connector.options.ajax.

    Returns undefined if key is not found.
*/
WhAjaj.Connector.prototype.derivedOption = function(key,opt) {
    var v = opt ? opt[key] : undefined;
    if( undefined !== v ) return v;
    else v = this.options[key];
    if( undefined !== v ) return v;
    else v = WhAjaj.Connector.options.ajax[key];
    return v;
};
/**
    Returns a unique string on each call containing a generic 
    reandom request identifier string. This is not used by the core 
    API but can be used by client code to generate unique IDs for 
    each request (if needed).

    The exact format is unspecified and may change in the future.

    Request IDs can be used by clients to "match up" responses to 
    specific requests if needed. In practice, however, they are 
    seldom, if ever, needed. When passing several concurrent 
    requests through the same response callback, it might be useful 
    for some clients to be able to distinguish, possibly re-routing 
    them through other handlers based on the originating request type.
    
    If this.options.requestIdPrefix or 
    WhAjaj.Connector.options.requestIdPrefix is set then that text
    is prefixed to the returned string.
*/
WhAjaj.Connector.prototype.generateRequestId = function()
{
    if( undefined === arguments.callee.sequence )
    {
        arguments.callee.sequence = 0;
    }
    var pref = this.options.requestIdPrefix || WhAjaj.Connector.options.requestIdPrefix || '';
    return pref +
        WhAjaj.msTimestamp() +
        '/'+(Math.round( Math.random() * 100000000) )+
        ':'+(++arguments.callee.sequence);
};

/**
    Copies (SHALLOWLY) all properties in opt to this.options.
*/
WhAjaj.Connector.prototype.addOptions = function(opt) {
    var k, v;
    for( k in opt ) {
        if( ! opt.hasOwnProperty(k) ) continue /* proactive Prototype kludge! */;
        this.options[k] = opt[k];
    }
    return this.options;
};

/**
    An internal helper object which holds several functions intended 
    to simplify the creation of concrete communication channel 
    implementations for WhAjaj.Connector.sendImpl(). These operations
    take care of some of the more error-prone parts of ensuring that
    onResponse(), onError(), etc. callbacks are called consistently 
    using the same rules.
*/
WhAjaj.Connector.sendHelper = {
    /**
        opt is assumed to be a normalized set of 
        WhAjaj.Connector.sendRequest() options. This function 
        creates a url by concatenating opt.url and some form of 
        opt.urlParam.
        
        If opt.urlParam is an object or string then it is appended 
        to the url. An object is assumed to be a one-dimensional set 
        of simple (urlencodable) key/value pairs, and not larger 
        data structures. A string value is assumed to be a 
        well-formed, urlencoded set of key/value pairs separated by 
        '&' characters.
        
        The new/normalized URL is returned (opt is not modified). If 
        opt.urlParam is not set then opt.url is returned (or an 
        empty string if opt.url is itself a false value).
        
        TODO: if opt is-a Object and any key points to an array, 
        build up a list of keys in the form "keyname[]". We could 
        arguably encode sub-objects like "keyname[subkey]=...", but 
        i don't know if that's conventions-compatible with other 
        frameworks.
    */
    normalizeURL: function(opt) {
        var u = opt.url || '';
        if( opt.urlParam ) {
            var addQ = (u.indexOf('?') >= 0) ? false : true;
            var addA = addQ ? false : ((u.indexOf('&')>=0) ? true : false);
            var tail = '';
            if( WhAjaj.isObject(opt.urlParam) ) {
                var li = [], k;
                for( k in opt.urlParam) {
                    li.push( k+'='+encodeURIComponent( opt.urlParam[k] ) );
                }
                tail = li.join('&');
            }
            else if( 'string' === typeof opt.urlParam ) {
                tail = opt.urlParam;
            }
            u = u + (addQ ? '?' : '') + (addA ? '&' : '') + tail;
        }
        return u;
    },
    /**
        Should be called by WhAjaj.Connector.sendImpl() 
        implementations after a response has come back. This 
        function takes care of most of ensuring that framework-level 
        conventions involving WhAjaj.Connector.options.ajax 
        properties are followed.
        
        The request argument must be the original request passed to 
        the sendImpl() function. It may legally be null for GET requests.
        
        The opt object should be the normalized AJAX options used 
        for the connection.
        
        The resp argument may be either a plain Object or a string 
        (in which case it is assumed to be JSON).
        
        This function takes care of the following:
        
        - Calling opt.afterSend()
        
        - If resp is a string, de-JSON-izing it to an object.
        
        - Calling opt.onSuccess()
        
        - Calling opt.onError() in several common (potential) error 
        cases.

        - If resp is-a String and opt.jsonp then resp is assumed to be
        a JSONP-form construct and is eval()d BEFORE opt.onResponse()
        is called. It is arguable to eval() it first, but the logic
        integrates better with the non-jsonp handler.

        The sendImpl() should return immediately after calling this.
        
        The sendImpl() must call only one of onSendSuccess() or 
        onSendError(). It must call one of them or it must implement 
        its own response/error handling, which is not recommended 
        because getting the documented semantics of the 
        onError/onResponse/afterSend handling correct can be tedious.
    */
    onSendSuccess:function(request,resp,opt) {
        if( WhAjaj.isFunction(opt.afterSend) ) {
            try {
                opt.afterSend( request, opt );
            } catch(e){}
        }
        var onError = WhAjaj.isFunction(opt.onError) ? opt.onError : function(){};
        if( ! resp ) {
            opt.errorMessage = "Sending of request succeeded but returned no data!";
            onError.apply( opt, [request, opt] );
            return false;
        }

        if( 'string' === typeof resp ) {
            try {
                resp = opt.jsonp ? eval(resp) : JSON.parse(resp);
            } catch(e) {
                opt.errorMessage = e.toString();
                onError.apply( opt, [request, opt] );
                return;
            }
        }
        try {
            if( WhAjaj.isFunction( opt.onResponse  ) ) {
                opt.onResponse( resp, request );
            }
            return true;
        }
        catch(e) {
            opt.errorMessage = "Exception while handling inbound JSON response:\n"
                + e
                +"\nOriginal response data:\n"+JSON.stringify(resp)
                ;
            ;
            onError.apply( opt, [request, opt] );
            return false;
        }
    },
   /**
        Should be called by sendImpl() implementations after a response
        has failed to connect (e.g. could not resolve host or timeout
        reached). This function takes care of most of ensuring that
        framework-level conventions involving WhAjaj.Connector.options.ajax
        properties are followed.
        
        The request argument must be the original request passed to 
        the sendImpl() function. It may legally be null for GET 
        requests.
        
        The opt object should be the normalized AJAX options used 
        for the connection. By convention, the caller of this 
        function "should" set opt.errorMessage to contain a 
        human-readable description of the error.
        
        The sendImpl() should return immediately after calling this. The
        return value from this function is unspecified.
    */
    onSendError: function(request,opt) {
        if( WhAjaj.isFunction(opt.afterSend) ) {
            try {
                opt.afterSend( request, opt );
            }
            catch(e){}
        }
        if( WhAjaj.isFunction( opt.onError ) ) {
            try {
                opt.onError( request, opt );
            }
            catch(e) {/*ignore*/}
        }
    }
};

/**
    WhAjaj.Connector.sendImpls holds several concrete 
    implementations of WhAjaj.Connector.prototype.sendImpl(). To use 
    a specific implementation by default assign 
    WhAjaj.Connector.prototype.sendImpl to one of these functions.
    
    The functions defined here require that the 'this' object be-a
    WhAjaj.Connector instance.
    
    Historical notes:

    a) We once had an implementation based on Prototype, but that 
    library just pisses me off (they change base-most types' 
    prototypes, introducing side-effects in client code which 
    doesn't even use Prototype). The Prototype version at the time 
    had a serious toJSON() bug which caused empty arrays to 
    serialize as the string "[]", which broke a bunch of my code. 
    (That has been fixed in the mean time, but i don't use 
    Prototype.)
    
    b) We once had an implementation for the dojo library, 
    
    If/when the time comes to add Prototype/dojo support, we simply
    need to port:
    
    http://code.google.com/p/jsonmessage/source/browse/trunk/lib/JSONMessage/JSONMessage.inc.js
    
    (search that file for "dojo" and "Prototype") to this tree. That 
    code is this code's generic grandfather and they are still very 
    similar, so a port is trivial.    
    
*/
WhAjaj.Connector.sendImpls = {
    /**
        This is a concrete implementation of 
        WhAjaj.Connector.prototype.sendImpl() which uses the 
        environment's native XMLHttpRequest class to send whiki 
        requests and fetch the responses.

        The only argument must be a connection properties object, as 
        constructed by WhAjaj.Connector.normalizeAjaxParameters().

        If window.firebug is set then window.firebug.watchXHR() is 
        called to enable monitoring of the XMLHttpRequest object.

        This implementation honors the loginName and loginPassword 
        connection parameters.

        Returns the XMLHttpRequest object.

        This implementation requires that the 'this' object be-a 
        WhAjaj.Connector.
        
        This implementation uses setTimeout() to implement the 
        timeout support, and thus the JS engine must provide that 
        functionality.
    */
    XMLHttpRequest: function(request, args)
    {
        var json = WhAjaj.isObject(request) ? JSON.stringify(request) : request;
        var xhr = new XMLHttpRequest();
        var startTime = (new Date()).getTime();
        var timeout = args.timeout || 10000/*arbitrary!*/;
        var hitTimeout = false;
        var done = false;
        var tmid /* setTimeout() ID */;
        //if( json ) json = json.replace(/ö/g,"\\u00f6") /* ONLY FOR A SPECIFIC TEST */;
        //alert( 'json=\n'+json );
        function handleTimeout()
        {
            hitTimeout = true;
            if( ! done )
            {
                var now = (new Date()).getTime();
                try { xhr.abort(); } catch(e) {/*ignore*/}
                // see: http://www.w3.org/TR/XMLHttpRequest/#the-abort-method
                args.errorMessage = "Timeout of "+timeout+"ms reached after "+(now-startTime)+"ms during AJAX request.";
                WhAjaj.Connector.sendHelper.onSendError( request, args );
            }
            return;
        }
        function onStateChange()
        { // reminder to self: apparently 'this' is-not-a XHR :/
            if( hitTimeout )
            { /* we're too late - the error was already triggered. */
                return;
            }

            if( 4 == xhr.readyState )
            {
                done = true;
                if( tmid )
                {
                    clearTimeout( tmid );
                    tmid = null;
                }
                if( (xhr.status >= 200) && (xhr.status < 300) )
                {
                    WhAjaj.Connector.sendHelper.onSendSuccess( request, xhr.responseText, args );
                    return;
                }
                else
                {
                    if( undefined === args.errorMessage )
                    {
                        args.errorMessage = "Error sending a '"+args.method+"' AJAX request to "
                                +"["+args.url+"]: "
                                +"Status text=["+xhr.statusText+"]"
                            ;
                        WhAjaj.Connector.sendHelper.onSendError( request, args );
                    }
                    else { /*maybe it was was set by the timeout handler. */ }
                    return;
                }
            }
        };

        xhr.onreadystatechange = onStateChange;
        if( ('undefined'!==(typeof window)) && ('firebug' in window) && ('watchXHR' in window.firebug) )
        { /* plug in to firebug lite's XHR monitor... */
            window.firebug.watchXHR( xhr );
        }
        try
        {
            //alert( JSON.stringify( args  ));
            function xhrOpen()
            {
                if( ('loginName' in args) && args.loginName )
                {
                    xhr.open( args.method, args.url, args.asynchronous, args.loginName, args.loginPassword );
                }
                else
                {
                    xhr.open( args.method, args.url, args.asynchronous  );
                }
            }
            if( json && ('POST' ===  args.method.toUpperCase()) )
            {
                xhrOpen();
                xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");
                // Google Chrome warns that it refuses to set these
                // "unsafe" headers (his words, not mine):
                // xhr.setRequestHeader("Content-length", json.length);
                // xhr.setRequestHeader("Connection", "close");
                xhr.send( json );
            }
            else /* assume GET */
            {
                xhrOpen();
                xhr.send(null);
            }
            tmid = setTimeout( handleTimeout, timeout );
            return xhr;
        }
        catch(e)
        {
            args.errorMessage = e.toString();
            WhAjaj.Connector.sendHelper.onSendError( request, args );
            return undefined;
        }
    }/*XMLHttpRequest()*/,
    /**
        This is a concrete implementation of 
        WhAjaj.Connector.prototype.sendImpl() which uses the jQuery 
        AJAX API to send requests and fetch the responses.

        The first argument may be either null/false, an Object 
        containing toJSON-able data to post to the back-end, or such an
        object in JSON string form.

        The second argument must be a connection properties object, as 
        constructed by WhAjaj.Connector.normalizeAjaxParameters().

        If window.firebug is set then window.firebug.watchXHR() is 
        called to enable monitoring of the XMLHttpRequest object.

        This implementation honors the loginName and loginPassword 
        connection parameters.

        Returns the XMLHttpRequest object.

        This implementation requires that the 'this' object be-a 
        WhAjaj.Connector.
    */
    jQuery:function(request,args)
    {
        var data = request || undefined;
        if( data ) {
            if('string'!==typeof data) {
                try {
                    data = JSON.stringify(data);
                }
                catch(e) {
                    WhAjaj.Connector.sendHelper.onSendError( request, args );
                    return;
                }
            }
        }
        var ajopt = {
            url: args.url,
            data: data,
            type: args.method,
            async: args.asynchronous,
            password: (undefined !== args.loginPassword) ? args.loginPassword : undefined,
            username: (undefined !== args.loginName) ? args.loginName : undefined,
            contentType: 'application/json; charset=utf-8',
            error: function(xhr, textStatus, errorThrown)
            {
                //this === the options for this ajax request
                args.errorMessage = "Error sending a '"+ajopt.type+"' request to ["+ajopt.url+"]: "
                        +"Status text=["+textStatus+"]"
                        +(errorThrown ? ("Error=["+errorThrown+"]") : "")
                    ;
                WhAjaj.Connector.sendHelper.onSendError( request, args );
            },
            success: function(data)
            {
                WhAjaj.Connector.sendHelper.onSendSuccess( request, data, args );
            },
            /* Set dataType=text instead of json for deeply archaic reasons which
                might no longer apply.
            */
            dataType: 'text'
        };
        if( undefined !== args.timeout )
        {
            ajopt.timeout = args.timeout;
        }
        try
        {
            var xhr = jQuery.ajax(ajopt);
            if( xhr && ('undefined'!==(typeof window)) && ('firebug' in window) && ('watchXHR' in window.firebug) )
            { /* plug in to firebug lite's XHR monitor... */
                window.firebug.watchXHR( xhr );
            }
            return xhr;
        }
        catch(e)
        {
            args.errorMessage = e.toString();
            WhAjaj.Connector.sendHelper.onSendError( request, args );
            return undefined;
        }
    }/*jQuery()*/,
    /**
        This is a concrete implementation of 
        WhAjaj.Connector.prototype.sendImpl() which uses the rhino 
        Java API to send requests and fetch the responses.

        Limitations vis-a-vis the interface:

        - timeouts are not supported.

        - asynchronous mode is not supported because implementing it
        requires the ability to kill a running thread (which is deprecated
        in the Java API).
    */
    rhino:function(request,args)
    {
        var self = this;
        var data = request || undefined;
        if( data ) {
            if('string'!==typeof data) {
                try {
                    data = JSON.stringify(data);
                }
                catch(e) {
                    WhAjaj.Connector.sendHelper.onSendError( request, args );
                    return;
                }
            }
        }
        var url;
        var con;
        var IO = new JavaImporter(java.io);
        var wr;
        var rd, ln, json = [];
        function setIncomingCookies(list){
            if(!list || !list.length) return;
            if( !self.cookies ) self.cookies = {};
            var k, v, i;
            for( i = 0; i < list.length; ++i ){
                v = list[i].split('=',2);
                k = decodeURIComponent(v[0])
                v = v[0] ? decodeURIComponent(v[0].split(';',2)[0]) : null;
                //print("RECEIVED COOKIE: "+k+"="+v);
                if(!v) {
                    delete self.cookies[k];
                    continue;
                }else{
                    self.cookies[k] = v;
                }
            }
        };
        function setOutboundCookies(conn){
            if(!self.cookies) return;
            var k, v;
            for( k in self.cookies ){
                if(!self.cookies.hasOwnProperty(k)) continue /*kludge for broken JS libs*/;
                v = self.cookies[k];
                conn.addRequestProperty("Cookie", encodeURIComponent(k)+'='+encodeURIComponent(v));
                //print("SENDING COOKIE: "+k+"="+v);
            }
        };
        try{
            url = new java.net.URL( args.url )
            con = url.openConnection(/*FIXME: add proxy support!*/);
            con.setRequestProperty("Accept-Charset","utf-8");
            setOutboundCookies(con);
            if(data){
                con.setRequestProperty("Content-Type","application/json; charset=utf-8");
                con.setDoOutput( true );
                wr = new IO.OutputStreamWriter(con.getOutputStream())
                wr.write(data);
                wr.flush();
                wr.close();
                wr = null;
                //print("POSTED: "+data);
            }
            rd = new IO.BufferedReader(new IO.InputStreamReader(con.getInputStream()));
            //var skippedHeaders = false;
            while ((line = rd.readLine()) !== null) {
                //print("LINE: "+line);
                //if(!line.length && !skippedHeaders){
                //    skippedHeaders = true;
                // json = [];
                //    continue;
                //}
                json.push(line);
            }
            setIncomingCookies(con.getHeaderFields().get("Set-Cookie"));
        }catch(e){
            args.errorMessage = e.toString();
            WhAjaj.Connector.sendHelper.onSendError( request, args );
            return undefined;
        }
        try { if(wr) wr.close(); } catch(e) { /*ignore*/}
        try { if(rd) rd.close(); } catch(e) { /*ignore*/}
        json = json.join('');
        //print("READ IN JSON: "+json);
        WhAjaj.Connector.sendHelper.onSendSuccess( request, json, args );
    }/*rhino()*/
};

/**
    An internal function which takes an object containing properties 
    for a WhAjaj.Connector network request. This function creates a new 
    object containing a superset of the properties from:

    a) opt
    b) this.options
    c) WhAjaj.Connector.options.ajax

    in that order, using the first one it finds.

    All non-function properties are _deeply_ copied via JSON cloning 
    in order to prevent accidental "cross-request pollenation" (been 
    there, done that). Functions cannot be cloned and are simply 
    copied by reference.
    
    This function throws if JSON-copying one of the options fails
    (e.g. due to cyclic data structures).
    
    Reminder to self: this function does not "normalize" opt.urlParam
    by encoding it into opt.url, mainly for historical reasons, but
    also because that behaviour was specifically undesirable in this
    code's genetic father.
*/
WhAjaj.Connector.prototype.normalizeAjaxParameters = function (opt)
{
    var rc = {};
    function merge(k,v)
    {
        if( rc.hasOwnProperty(k) ) return;
        else if( WhAjaj.isFunction(v) ) {}
        else if( WhAjaj.isObject(v) ) v = JSON.parse( JSON.stringify(v) );
        rc[k]=v;
    }
    function cp(obj) {
        if( ! WhAjaj.isObject(obj) ) return;
        var k;
        for( k in obj ) {
            if( ! obj.hasOwnProperty(k) ) continue /* i will always hate the Prototype designers for this. */;
            merge(k, obj[k]);
        }
    }
    cp( opt );
    cp( this.options );
    cp( WhAjaj.Connector.options.ajax );
    // no, not here: rc.url = WhAjaj.Connector.sendHelper.normalizeURL(rc);
    return rc;
};

/**
    This is the generic interface for making calls to a back-end 
    JSON-producing request handler. It is a simple wrapper around 
    WhAjaj.Connector.prototype.sendImpl(), which just normalizes the 
    connection options for sendImpl() and makes sure that 
    opt.beforeSend() is (possibly) called.
    
    The request parameter must either be false/null/empty or a 
    fully-populated JSON-able request object (which will be sent as 
    unencoded application/json text), depending on the type of 
    request being made. It is never semantically legal (in this API) 
    for request to be a string/number/true/array value. As a rule, 
    only POST requests use the request data. GET requests should 
    encode their data in opt.url or opt.urlParam (see below).
    
    opt must contain the network-related parameters for the request. 
    Paramters _not_ set in opt are pulled from this.options or 
    WhAjaj.Connector.options.ajax (in that order, using the first 
    value it finds). Thus the set of connection-level options used 
    for the request are a superset of those various sources.
    
    The "normalized" (or "superimposed") opt object's URL may be 
    modified before the request is sent, as follows:

    if opt.urlParam is a string then it is assumed to be properly 
    URL-encoded parameters and is appended to the opt.url. If it is 
    an Object then it is assumed to be a one-dimensional set of 
    key/value pairs with simple values (numbers, strings, booleans, 
    null, and NOT objects/arrays). The keys/values are URL-encoded 
    and appended to the URL.

    The beforeSend() callback (see below) can modify the options
    object before the request attempt is made.
   
    The callbacks in the normalized opt object will be triggered as
    follows (if they are set to Function values):
    
    - beforeSend(request,opt) will be called before any network 
    processing starts. If beforeSend() throws then no other 
    callbacks are triggered and this function propagates the 
    exception. This function is passed normalized connection options
    as its second parameter, and changes this function makes to that
    object _will_ be used for the pending connection attempt.
    
    - onError(request,opt) will be called if a connection to the 
    back-end cannot be established. It will be passed the original 
    request object (which might be null, depending on the request 
    type) and the normalized options object. In the error case, the 
    opt object passed to onError() "should" have a property called 
    "errorMessage" which contains a description of the problem.
    
    - onError(request,opt) will also be called if connection 
    succeeds but the response is not JSON data.
    
    - onResponse(response,request) will be called if the response 
    returns JSON data. That data might hold an error response code - 
    clients need to check for that. It is passed the response object 
    (a plain object) and the original request object.
    
    - afterSend(request,opt) will be called directly after the
    AJAX request is finished, before onError() or onResonse() are
    called. Possible TODO: we explicitly do NOT pass the response to
    this function in order to keep the line between the responsibilities
    of the various callback clear (otherwise this could be used the same
    as onResponse()). In practice it would sometimes be useful have the
    response passed to this function, mainly for logging/debugging
    purposes.

    The return value from this function is meaningless because
    AJAX operations tend to take place asynchronously.

*/
WhAjaj.Connector.prototype.sendRequest = function(request,opt)
{
    if( !WhAjaj.isFunction(this.sendImpl) )
    {
        throw new Error("This object has no sendImpl() member function! I don't know how to send the request!");
    }
    var ex = false;
    var av = Array.prototype.slice.apply( arguments, [0] );
    
    /**
        FIXME: how to handle the error, vis-a-vis- the callbacks, if 
        normalizeAjaxParameters() throws? It can throw if 
        (de)JSON-izing fails.
    */
    var norm = this.normalizeAjaxParameters( WhAjaj.isObject(opt) ? opt : {} );
    norm.url = WhAjaj.Connector.sendHelper.normalizeURL(norm);
    if( ! request ) norm.method = 'GET';
    if( WhAjaj.isFunction(norm.beforeSend) )
    {
        norm.beforeSend( request, norm );
    }
    //alert( WhAjaj.stringify(request)+'\n'+WhAjaj.stringify(norm));
    try { this.sendImpl( request, norm ); }
    catch(e) { ex = e; }
    if(ex) throw ex;
};

/**
    sendImpl() holds a concrete back-end connection implementation. It
    can be replaced with a custom implementation if one follows the rules
    described throughout this API. See WhAjaj.Connector.sendImpls for
    the concrete implementations included with this API.
*/
WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.XMLHttpRequest;
//WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.rhino;
//WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.jQuery;