zAu (ZK Client Engine 9.6.4 API)

java.lang.Object
- _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

Fields
Modifier and Type	Field and Description
`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

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addAuRequest(Desktop dt, Event aureq)` Add the AU request to the ajax queue.
`static void`	`ajaxErrorHandler(java.lang.Object req, int status, String statusText, int ajaxReqTries)` Implements this function to be called if the request fails.
`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 Array`	`getAuRequests(Desktop dt)` Returns all pending AU requests.
`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 boolean`	`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 (response, errCode)
```
    where response is an instance of response from Fetch API, 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 response.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 boolean shallIgnoreESC()
```
    Returns whether to ignore the ESC keystroke. It returns true if ZK Client Engine is sending an AU request
    
    Returns:
    
    boolean
  - 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
  - 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
  - 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.
  - addAuRequest
```
public static void addAuRequest(Desktop dt,
                                Event aureq)
```
    Add the AU request to the ajax queue.
    
    Parameters:
    
    dt -
    
    aureq - the request.
    
    Since:
    
    7.0.3
  - getAuRequests
```
public static Array getAuRequests(Desktop dt)
```
    Returns all pending AU requests.
    
    Parameters:
    
    dt -
    
    Returns:
    
    Array an array of Event
    
    Since:
    
    7.0.3
  - 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
  - ajaxErrorHandler
```
public static void ajaxErrorHandler(java.lang.Object req,
                                    int status,
                                    String statusText,
                                    int ajaxReqTries)
```
    Implements this function to be called if the request fails. The function receives four arguments: The XHR (XMLHttpRequest) object, a number describing the status of the request, a string describing the text of the status, and a number describing the retry value to re-send.
    For example,
```
zAu.ajaxErrorHandler = function (req, status, statusText, ajaxReqTries) {
    if (ajaxReqTries == null)
        ajaxReqTries = 3; // retry 3 times
        
    // reset the resendTimeout, for more detail, please refer to
    // http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_auto-resend-timeout_Element
    zk.resendTimeout = 2000;//wait 2 seconds to resend.
    
    if (!zAu.confirmRetry("FAILED_TO_RESPONSE", status+(statusText?": "+statusText:"")))
        return 0; // no retry;
    return ajaxReqTries;
}
```
    Parameters:
    
    req - the object of XMLHttpRequest
    
    status - the status of the request
    
    statusText - the text of the status from the request
    
    ajaxReqTries - the retry value for re-sending the request, if undefined means the function is invoked first time.
    
    Since:
    
    6.5.2

Class zAu

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ajaxSettings

cmd0

cmd1

Method Detail

onError

unError

confirmRetry

showError

getErrorURI

setErrorURI

setErrorURI

getPushErrorURI

setPushErrorURI

setPushErrorURI

processing

send

sendAhead

process

shallIgnoreESC

doCmds

beforeSend

encode

sendNow

addAuRequest

getAuRequests

createWidgets

ajaxErrorHandler