_global_
Class zAu

java.lang.Object
  extended by _global_.zAu

public class zAu
extends java.lang.Object

The AU Engine used to send the AU requests to the server and to process the AU responses.


Field Summary
static Map ajaxSettings
          A map of Ajax default setting used to send the AU requests.
static AuCmd0 cmd0
          The AU command handler that handles commands not related to widgets.
static AuCmd1 cmd1
          The AU command handler that handles commands releated to widgets.
 
Method Summary
static String beforeSend(String uri, Event aureq, Desktop dt)
          Called before sending an AU request.
static boolean confirmRetry(String msgCode, String msg2)
          Called to confirm the user whether to retry, when an error occurs.
static void createWidgets(Array codes, Function fn, Function filter)
          Creates widgets based on an array of JavaScritp codes generated by Component.redraw() at the server.
static void doCmds(String dtid, Array rs)
          Process the specified commands.
static String encode(int j, Event aureq, Desktop dt)
          Returns the content to send to the server.
static String getErrorURI(int code)
          Returns the URI for the specified error.
static String getPushErrorURI(int code)
          Sets the URI for the server-push related error.
static void onError()
          Register a listener that will be called when the Ajax request failed.
static void process(String cmd, String data)
          Processes the AU response sent from the server.
static boolean processing()
          Returns whether ZK Client Engine is busy for processing something, such as mounting the widgets, processing the AU responses and on.
static void send(Event aureq, int timeout)
          Sends an AU request and appends it to the end if there is other pending AU requests.
static void sendAhead(Event aureq, int timeout)
          Sends an AU request by placing in front of any other pending request.
static boolean sendNow(Desktop dt)
          Enforces all pending AU requests of the specified desktop to send immediately
static void setErrorURI(int code, String uri)
          Sets the URI for the specified error.
static void setErrorURI(Map errors)
          Sets the URI for the errors specified in a map.
static void setPushErrorURI(int code, String uri)
          Sets the URI for the server-push related error.
static void setPushErrorURI(Map errors)
          Sets the URI for the server-push related errors specified in a map.
static java.lang.Object shallIgnoreESC()
          Returns whether to ignore the ESC keystroke.
static void showError(String msgCode, String msg2, String cmd, java.lang.Throwable ex)
          Called to shown an error if a severe error occurs.
static void unError()
          Unregister a listener for handling errors.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ajaxSettings

public static Map ajaxSettings
A map of Ajax default setting used to send the AU requests.


cmd0

public static AuCmd0 cmd0
The AU command handler that handles commands not related to widgets.


cmd1

public static AuCmd1 cmd1
The AU command handler that handles commands releated to widgets.

Method Detail

onError

public static void onError()
Register a listener that will be called when the Ajax request failed. The listener shall be
function (req, errCode)
where req is an instance of XMLHttpRequest, and errCode is the error code. Furthermore, the listener could return true to ignore the error. In other words, if true is returned, the error is ignored (the listeners registered after won't be called either).

Notice that req.status might be 200, since ZK might send the error back with the ZK-Error header.

To remove the listener, use unError().

Since:
5.0.4
See Also:
unError(), confirmRetry(_global_.String, _global_.String)

unError

public static void unError()
Unregister a listener for handling errors.

Since:
5.0.4
See Also:
onError()

confirmRetry

public static boolean confirmRetry(String msgCode,
                                   String msg2)
Called to confirm the user whether to retry, when an error occurs.

Parameters:
msgCode - the message code
msg2 - the additional message. Ignored if not specified or null.
Returns:
boolean whether to retry

showError

public static void showError(String msgCode,
                             String msg2,
                             String cmd,
                             java.lang.Throwable ex)
Called to shown an error if a severe error occurs. By default, it is an orange box.

Parameters:
msgCode - the message code
msg2 - the additional message. Ignored if not specified or null.
cmd - the command causing the problem. Ignored if not specified or null.
ex - the exception

getErrorURI

public static String getErrorURI(int code)
Returns the URI for the specified error.

Parameters:
code - the error code
Returns:
String the URI.

setErrorURI

public static void setErrorURI(Map errors)
Sets the URI for the errors specified in a map.

Parameters:
errors - A map of errors where the key is the error code (int), while the value is the URI (String).

setErrorURI

public static void setErrorURI(int code,
                               String uri)
Sets the URI for the specified error.

Parameters:
code - the error code
uri - the URI

getPushErrorURI

public static String getPushErrorURI(int code)
Sets the URI for the server-push related error.

Parameters:
code - the error code
Returns:
String the URI.

setPushErrorURI

public static void setPushErrorURI(Map errors)
Sets the URI for the server-push related errors specified in a map.

Parameters:
errors - A map of errors where the key is the error code (int), while the value is the URI (String).

setPushErrorURI

public static void setPushErrorURI(int code,
                                   String uri)
Sets the URI for the server-push related error.

Parameters:
code - the error code
uri - the URI

processing

public static boolean processing()
Returns whether ZK Client Engine is busy for processing something, such as mounting the widgets, processing the AU responses and on.

Returns:
boolean whether ZK Client Engine is busy

send

public static void send(Event aureq,
                        int timeout)
Sends an AU request and appends it to the end if there is other pending AU requests.

Parameters:
aureq - the request. If Event.target is null, the request will be sent to each desktop at the client.
timeout - the time (milliseconds) to wait before sending the request. 0 is assumed if not specified or negative. If negative, the request is assumed to be implicit, i.e., no message will be shown if an error occurs.

sendAhead

public static void sendAhead(Event aureq,
                             int timeout)
Sends an AU request by placing in front of any other pending request.

Parameters:
aureq - the request. If Event.target is null, the request will be sent to each desktop at the client.
timeout - the time (milliseconds) to wait before sending the request. 0 is assumed if not specified or negative. If negative, the request is assumed to be implicit, i.e., no message will be shown if an error occurs.

process

public static void process(String cmd,
                           String data)
Processes the AU response sent from the server.

Don't call it directly at the client.

Parameters:
cmd - the command, such as echo
data - the data in a JSON string.

shallIgnoreESC

public static java.lang.Object shallIgnoreESC()
Returns whether to ignore the ESC keystroke. It returns true if ZK Client Engine is sending an AU request

Returns:
Object

doCmds

public static void doCmds(String dtid,
                          Array rs)
Process the specified commands.

Parameters:
dtid - the desktop's ID
rs - a list of responses
Since:
5.0.5

encode

public static String encode(int j,
                            Event aureq,
                            Desktop dt)
Returns the content to send to the server. By default, it is encoded into several parameters and the data parameters (data_*) is encoded in JSON.

If you prefer to encode it into another format, you could override this method, and also implement a Java interface called org.zkoss.zk.au.AuDecoder\ to decode the format at the server.

If you prefer to encode it into URI, you could override beforeSend(_global_.String, zk.Event, zk.Desktop).

Parameters:
j - the order of the AU request. ZK sends a batch of AU request at once and this argument indicates the order an AU request is (starting from 0).
aureq - the AU request
dt - the desktop
Returns:
String the content of the AU request.
Since:
5.0.4

sendNow

public static boolean sendNow(Desktop dt)
Enforces all pending AU requests of the specified desktop to send immediately

Parameters:
dt -
Returns:
boolean whether it is sent successfully. If it has to wait for other condition, this method returns false.

createWidgets

public static void createWidgets(Array codes,
                                 Function fn,
                                 Function filter)
Creates widgets based on an array of JavaScritp codes generated by Component.redraw() at the server.

This method is usually used with Java's ComponentsCtrl.redraw, and Widget.replaceCavedChildren_(_global_.String, _global_.Array, _global_.String, _global_.String).

Notice that, since the creation of widgets might cause some packages to be loaded, the callback function, fn, might be called after this method is returned

Parameters:
codes - an array of JavaScript objects generated at the server. For example, smartUpdate("foo", ComponentsCtrl.redraw(getChildren());
fn - the callback function. When the widgets are created. fn is called with an array of Widget. In other words, the callback's signature is as follows:
void callback(zk.Widget[] wgts);
filter - the filter to avoid the use of widgets being replaced. Ignored if null
Since:
5.0.2

beforeSend

public static String beforeSend(String uri,
                                Event aureq,
                                Desktop dt)
Called before sending an AU request.

Default: append Widget.autag to uri.

It is designed to be overriden by an application to record what AU requests have been sent. For example, to work with Google Analytics, you can add the following code:


<script defer="true"><![CDATA[
var pageTracker = _gat._getTracker("UA-123456");
pageTracker._setDomainName("zkoss.org");
pageTracker._initData();
pageTracker._trackPageview();

var auBfSend = zAu.beforeSend;
zAu.beforeSend = function (uri, req, dt) {
 try {
  var target = req.target;
  if (target.id) {
   var data = req.data||{},
       value = data.items && data.items[0]?data.items[0].id:data.value;
   pageTracker._trackPageview((target.desktop?target.desktop.requestPath:"") + "/" + target.id + "/" + req.name + (value?"/"+value:""));
  }
 } catch (e) {
 }
 return auBfSend(uri, req, dt);
};
]]></script>

Parameters:
uri - the AU's request URI (such as /zkau)
aureq - the AU request
dt - the desktop
Returns:
String the AU's request URI.
Since:
5.0.2


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo