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 done
, fail
, progress
, and always
methods are used to attach event handlers to events.
The 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.
Use the Fail
Promise callback to run a function when a service call has failed. More information about the fail
callback is in the next section.
Use the 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 always
callback.
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.
Fail
CallbackIf 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:
The jqXHR
(jQuery XMLHttpRequest) object, which is a superset of the native XMLHttpRequest object.
The textStatus
string, which describes the type of error that occurred ("timeout", "error", etc.).
The 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.
The 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 Deferred
object.
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.
Loading Documents Using LEADTOOLS Document Library
Creating Documents with LEADTOOLS Document Library
Uploading Using the Document Library
Document Library Coordinate System
Loading Encrypted Files Using the Document Library
Parsing Text with the Document Library
Barcode Processing with the Document Library
Loading Images in the Document Library