Hi all,
Sorry about the delay on this - client projects (some of them web-based
and of benefit to this subject) have gotten in the way.
After much playing, here's my idea for the "simple" case I think any new
AJAX-enabling class should provide and how it should enable users to
carry out such requests.
I'll use "Class" to refer to the class, as I suck at names and would
much rather someone else make valid suggestions.
Firstly, there should be some class-level configurables:
Class.setDefaultSyncMode(mode) - Sets the default mode to either SYNC or
ASYNC, with ASYNC being the default setting if this method is never called.
Class.setDefaultFlightMode(mode) - Sets the default "flight" mode, with
3 possibilities:
1. Requests are issued as they are made and actually executed when
the user calls the appropriate method.
2. Requests are issued one at a time, with subsequent requests
returning an immediate error (similar to one of my favourite UNIX
errors, EWOULDBLOCK).
3. Requests are executed serially, so that requests are put in a
queue and each is executed as the last one completes.
The default for this setting is up for debate.
Class.setMaxRequests(count) - Not really required for usage, but
possibly useful for people not wanting to have stupid numbers of
outstanding requests.
Class.setDefaultTimeout(ms) - Set the default timeout for requests. What
"timeout" means here is something I invite suggestions on. The obvious
suggestions are:
1. A timeout occurs when no state transition occurs within ms
milliseconds.
2. A timeout occurs when the state transition from readyState 3
(loading) to readyState 4 (complete) takes longer than ms milliseconds.
By default, the default timeout being 0 (effectively, no timeout) is
something I'm betting most will agree with.
Class.setDefaultEncodingFunction(function_reference) - Default function
used to encode the data being sent. By default, I guess we'd send data
as is.
Now, with those out of the way, on to actually using it.
In line with Qooxdoo's event system, I propose the following set of events:
* initialised - Fires when the request actually starts
* connect - Fires when the request successfully connects to the server
* transferring - Fires when data transfer from the server begins
* success - Fires when the request successfully repeats
* failure - Fires when the request completes in an unsuccessful fashion
* complete - Fires when the request completes, regardless of outcome
All of these events really just wrap XMLHttpRequest's readyState
transitions.
Further events include (but may not be useful for the simple case):
* presend - Fires between the user instructing the request to start and
the request actually being made to the server. This could be used for
encoding of data or similar.
* functioncall - This will become clearer below, but the idea is that,
when performing RPC, this event would be fired between the user
requesting the RPC function call and the call actually being initiated.
This could be used for determining the URL the request should point to,
for instance.
* timeout - Fires when a timeout occurs.
One would attach events with addEventListener() as is done with all
other Qooxdoo widgets.
Given all this, the simple case code would simply be:
var req = new Class(url);
// Attach required event handlers
req.send(data);
Really, that's all that needs to be written. I expect that it will be
popular to have send accept the same arguments that XMLHttpRequest's
send method does.
In terms of object-level methods, I obviously want to provide
object-level methods for the default properties mentioned above, as well as:
* Class.cancel() - Cancel the request
* Class.dispose() - To fit in with Qooxdoo and to fix dopey browsers
(like IE)
* Class.resend() - This would simply be an alias for send if anyone sees
a good reason for it to go in.
* Class.getDecodedResponse(method) - The "method" parameter is to be
optional. If (for some bizzare reason) the method encoding data for
sending is different to the method used for receiving. If the "method"
parameter is not supplied, then the return value will be the result of
running the decoding method that was set as the default.
* Class.getResponseText() - Wraps XMLHttpRequest's responseText property
* Class.getResponseXML() - Wraps XMLHttpRequest's responseXML property
Other methods of note will simply be wrappers for XMLHttpRequest's other
methods for headers and other arguments passed to send (but stored as
properties for easy cloning and the like).
All comments and suggestions are invited and welcome! I've got a fair
bit of code that will come over easily and I'm sure I'm missing a few
things.
One small note on my current way of thinking here - I'm aiming to build
an extremely solid XMLHttpRequest-style class for Qooxdoo. Capabilities
such as gathering data from forms, suppressing back and forward buttons
and so on are not things I've thought about for the core class (unlike
Dojo, for example). I prefer to adopt Stroustrup's line of thinking, in
that a class should do what it does whilst being well suited to reuse
and versatility. Things such as those I've not given much thought to
belong, in my opinion, in utility classes. That said, I don't want to be
stubborn. :-)
Best regards,
Chris
-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems? Stop! Download the new AJAX search engine that makes
searching your log files as easy as surfing the web. DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click
_______________________________________________
Qooxdoo-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
