WAjaxControl `loadCount` is a misrepresentation or not correctly implemented

WAjaxControl has a private member int loadCount and relevant public accessors. The schema for WAjaxControl/ui:ajaxTrigger specifies an attribute @allowedUses which outputs the value of this property if it is greater than 0. Support for loadCount is only partially implemented in both sides of WComponents.

Limitation of the number of times a WAjaxTrigger is processed In addition @allowedUses/loadCount have never been implemented in WComponents Java or client code to enforce any numbers other than <= 0 (unlimited) or 1 (single use). The value of loadCount and any previous invocations of the WAjaxControl's trigger component's actionOnChange Action are not tested during the action phase (and maybe cannot be adequately tested at an abstract level). Any value greater than 0 is deemed within the client side code to indicate single use.

Proposal

I propose the following to remove this misrepresentation:

1. remove the implied support for a WAjaxControl that can be fired more than once but no more than n times by removing the private member int loadCount and replacing it with a more appropriate token (perhaps boolean loadOnce so we can retain the accessors setLoadOnce and isLoadOnce);
2. deprecate setLoadCount(int) in favour of setLoadOnce(boolean) and int getLoadCount() in favour of boolean isLoadOnce();
3. temporarily update setLoadCount(int) such that when int <= 0 call setLoadOnce(false) otherwise call setLoadOnce(true);
4. temporarily update getLoadCount() to return -1 if isLoadOnce() returns false otherwise return 1;
5. rename attribute @allowedUses to a more appropriate token (perhaps @single but suggestions are welcome);
6. update the renderer to check isLoadOnce() as the test for @allowedUses (therefore its renamed counterpart if we do that).

Alternative

We could support loadCount and therefore it would cease to be a misrepresentation in the API. This would entail at the very least:

1. client code providing full support for @allowedUses and de-registering an AJAX trigger after this number of invocations;
2. the Java API being enhanced to provide a means for a trigger's @allowedUses to be updated/reset in the client if a WAjaxControl/ui:ajaxTrigger is updated/replaced in an AJAX response so that the consuming application is able to decide if the load count is reset or inherited from the previous trigger lifecycle;
3. The action phase for WComponents provides a default implementation which keeps a count of the number of times a WAjaxControl has been invoked and stops actioning when loadCount is reached;
4. A default implementation is provided to re-populate target components in their previous state when the condition in 3 above is reached preventing further action (this is a belt-and-braces in case the count goes wrong in the client code).

I am not keen on taking this approach because we have never had a reasonable use-case where a particular WAjaxControl's trigger is required to be fired more than once but no more than n times. If this is ever required then the WAjaxControl/ui:ajaxTrigger could be set to be single use and then replaced in the subsequent target load as currently any ui:ajaxTrigger loaded will replace the ajax trigger in the trigger manager.

@jonathanaustin, @ricksbrown opinions?

[ricksbrown]

The ability to fire an ajax trigger N times was implemented a long time ago when AJAX was new and we didn't know how people would use it. Turns out they never use it to fire a trigger N times (with the exception of N=1 which is handled by lazy mode anyway).

All traces of it should be removed. The most important place is the Java API. Schema doesn't really matter. The client side code won't ever be invoked if the Java API is cleaned up.