Operations to contact the LEADTOOLS Document Service return a jQuery
Promise object that must be used to act on events from the service call. The
always methods are used to attach event handlers to events.
Done Promise callback is used to run a function when a service call has completed successfully. In most situations, the
done callback function will include as a parameter the requested data from the Document Service. For example, getText will return a
Promise for a DocumentPageText object.
In addition, if the Document Service is configured to return other arbitrary user data, that data will be available as a second parameter to the
Done callback function. See DocumentFactory.ServiceUserData and LEADDocument.ServiceUserData for more information.
Fail Promise callback to run a function when a service call has failed. More information about the
fail callback is in the next section.
Always Promise callback to run a function after the service call is completed, regardless of the result. The
always callback is often used to clean up resources. No parameters are provided to the
Progress Promise callback is only used for uploading files and returns a DocumentUploadProgress object with the state and progress of the overall upload. See UploadFile, UploadFileDocument, UploadDocumentBlob, and UploadDocument for more information and examples.
If an error occurs during any service call, the
fail callback handler will execute all registered functions with the three parameters normally returned by a failed jQuery Ajax call:
jqXHR (jQuery XMLHttpRequest) object, which is a superset of the native XMLHttpRequest object.
textStatus string, which describes the type of error that occurred ("timeout", "error", etc.).
errorThrown string, which could be the textual portion of an HTTP Status (like "Internal Server Error") if it is available, a general error message, or null.
If the error occurred within the Document Service, all three of these parameters should have values. If the error occurred while parsing or delivering the data, only
errorThrown, the third argument, will have a value. If an UploadFile service call was aborted using the special
abort method, all of the parameters to the
fail callback will be null.
jqXHR object, if not null, may contain data used for creating a ServiceError object, which would include debugging information and messages to be displayed to the user. For more information, see ParseError. If an error occurs, the value sent through the request will be set in the ServiceError.UserData property of the object returned from ParseError.
The jQuery Promise object is a subset of the jQuery
Deferred object. Refer to the jQuery documentation for more information on Promises and the
The PrepareAjax event occurs before any request made by the document library client-side code to the server. This allows users to examine or modify the parameters passed. The event data contains detailed information on the call as well as the
JQueryAjaxSettings object being used. Any changes made to that object will be used in the request. For example, this will allow users to modify the headers of any request to set authorization headers as they wish.
The Document Service supports a "Service Heartbeat" feature. The defaults for this feature can be configured from each client application's "serviceConfig.json" file in the "heartbeatDefaults". If a timeout occurs, the IsTimeoutError value will be set to true.