Hi,
Am 01.12.2005 14:22, Chris Ricks schrieb:
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.
We sure all know this, and "feel" with you ;)
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.
If this is simple ... I don't want to see complex solutions ;)
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.
Really cool idea.
But:
I think this needs a getter for pending requests ... so I can tell my
user, that he has 3 requests in the queue, while still waiting for the
first to continue.
Class.setMaxRequests(count) - Not really required for usage, but
possibly useful for people not wanting to have stupid numbers of
outstanding requests.
How would the send()-method (from below) react when a request is issued
that exceeds the number of maxRequests? Exception? Event? Returning
null? I'd say exception ... but that may be just my Java background
speaking.
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.
I opt for number 2. I think this is the more "natural" way to think
about timeouts. Most timeouts in programs work this way.
Class.setDefaultEncodingFunction(function_reference) - Default function
used to encode the data being sent. By default, I guess we'd send data
as is.
Or URL-encode it? For making POSTs easy. Or maybe it should be enough to
have a method like setUrlEncoding(boolean)?
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:
[...]
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.
I don't understand the use for this one.
* 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.
How do you choose which HTTP method to use?
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
Very important!
* 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.
How does the class decode the response-data? Is there a set of
predefined "decoders", as well as some sort of registerDecoder() method,
to enable custom decoders?
Like for SOAP ... eeek, forgive that I said the word ;)
* 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).
You probably included it with the last sentence, but I wanted to mention
it anyway. The status code is a very important property here.
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.
I think you covered everything that's important. Queuing and Timeouts
being the most important that are lacking from today's version. At least
from my point of view.
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. :-)
I agree fully!
I'd say, that I'm looking forward to this code. It sounds like you
really banged your head on this.
Very well thought out stuff.
Cheers
Benjamin
-------------------------------------------------------
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
Qooxdoo-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
