Fossil

Check-in [c6c5ad13]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added my AJAX test code after accidentally deleting my local copy (thank goodness the test server still had a copy). See the README if you want to set it up locally under apache.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | json
Files: files | file ages | folders
SHA1: c6c5ad13644f711be7a18f83660fe9871a1e6136
User & Date: stephan 2011-09-21 21:17:14.784
Context
2011-09-21
21:23
added a FIXME, removed another. Now it's really bed time. ... (check-in: 8b814778 user: stephan tags: json)
21:17
Added my AJAX test code after accidentally deleting my local copy (thank goodness the test server still had a copy). See the README if you want to set it up locally under apache. ... (check-in: c6c5ad13 user: stephan tags: json)
20:43
/json/branch/list now requires g.perm.Read, like /brlist does. Time for bed... ... (check-in: a37c6a87 user: stephan tags: json)
Changes
Unified Diff Ignore Whitespace Patch
Added ajax/README. 














































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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.
Added ajax/cgi-bin/fossil-json.cgi.example. 






>
>

1
2

#!/path/to/fossil/binary
repository: /path/to/repo.fsl
Added ajax/index.html. 










































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244

<!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 WhAjaj.Connector()
};


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 );
};

jQuery(document).ready(function(){
    var ids = ['textPath', // list of HTML element IDs we use often.
            'taResponse',
            'taRequest',
            'taRequestOpt',
            'ajaxNotification',
            'responseContainer',
            'btnSend',
            'currentAuthToken'];
    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.cgi = new FossilAjaj();
    var opt = TheApp.cgi.ajaj.options;
    opt.beforeSend = function(req,opt) {
        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.endAjaxNotif();
    };
    opt.onResponse = function(resp,req) {
        var val;
        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.

<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/>
<strong>Quick-posts:</strong><br/>
<input type='button' value='HAI' onclick='TheApp.cgi.HAI()' />
<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='cap' onclick='TheApp.cgi.sendCommand("/json/cap")' />
<input type='button' value='branch/list' onclick='TheApp.cgi.sendCommand("/json/branch/list")' />
<input type='button' value='wiki/list' onclick='TheApp.cgi.sendCommand("/json/wiki/list")' />

<!--
<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</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>
Added ajax/js/fossil-ajaj.js. 














































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182

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

    Author: Stephan Beal (sgbeal@googlemail.com)

    License: Public Domain
*/

/**
    Constructor for a new 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.sendRequest() (and friends) instead 
    of the underlying WhAjaj.Connector API, since this class' API 
    contains SP-specific request-calling functions.
*/
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;
    
    if(payload || this.authToken) {
        req = {
            payload:payload || undefined,
            requestId:this.generateRequestId(),
            authToken:this.authToken || undefined
        };
    }
    ajajOpt = ajajOpt || {};
    if(command) ajajOpt.url = this.ajaj.derivedOption('url',ajajOpt) + command;
    if( 0 && this.authToken ) {
        if( req ) req.authToken = this.authToken;
        else { // GET request: extend ajajOpt.urlParam
            var urlArgs = ajajOpt.urlParam;
            if( 'string' === typeof urlArgs ) {
                ajajOpt.urlParam += '&authToken='+encodeUriComponent(this.authToken);
            }
            else if( 'object' === typeof urlArgs ) {
                ajajOpt.urlParam.authToken = this.authToken;
            }
            else {
                ajajOpt.urlParam = {authToken: this.authToken};
            }
        }
    }
    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;
        if( WhAjaj.isFunction( self.onLogin ) ){
            try{ self.onLogin(); }
            catch(e){}
        }
        if( WhAjaj.isFunction(oldOnResponse) ) {
            try { oldOnResponse.apply(thisOpt,[resp,req]); }
            catch(e) {}
        }
    };
    function doLogin(){
        //alert("Sending login request..."+WhAjaj.stringify(loginReq));
        self.sendCommand('/json/login', loginReq, ajajOpt);
    }
    if( 'anonymous' === name ){
      this.sendCommand('/json/anonymousPassword',null,{
          onResponse:function(resp,req){
            if(!resp || resp.resultCode){
                //alert("Error getting PW. "+WhAjaj.stringify(resp));
                try{ ajajOpt.onResponse(resp,req); }
                catch(e){}
                return;
            }
            else{
                //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) ) {
            try { oldOnResponse.apply(thisOpt,[resp,req]); }
            catch(e) {}
        }
    };
    this.sendCommand('/json/logout', false, 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', null, ajajOpt);
};
Added ajax/js/whajaj.js. 




















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017

/**
    This file provides a JS interface into the core functionality of
    a whiki CGI back-end.

    All functionality is part of a class named WhAjaj, and that class
    acts as namespace for the 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.
    
    FIXME: keys w/o '=', or with no value, "should probably" be 
    treated as boolean flags with a value of true.
*/
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.
        */
        method:'POST',

        /**
            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 AJAX 
            connection. Not all concrete WhAjaj.Connector.sendImpl() 
            implementations can support this.
        */
        loginPassword:undefined,

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

        /**
            If an AJAX request receives JSON data from the back-end, 
            that data is passed as a plain Object as the response 
            parameter. 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 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('AJAX 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 AJAX 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){}
    }
};

/**
    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.

        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 = JSON.parse(resp);
            } catch(e) {
                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*/
};

/**
    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( WhAjaj.isFunction(norm.beforeSend) )
    {
        norm.beforeSend( request, norm );
    }
    if( ! request ) norm.method = 'GET';
    //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 implementatios included with this API.
*/
WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.XMLHttpRequest;
//WhAjaj.Connector.prototype.sendImpl = WhAjaj.Connector.sendImpls.jQuery;