Asynchronous Requests 

TerraExplorer API provides an asynchronous implementation for methods that involve time-consuming operations, such as executions in separate threads or initiation of HTTP requests. While these methods also have a legacy synchronous implementation, it is generally recommended to use the asynchronous one for optimal performance. Synchronous requests block the execution of the calling code, resulting in a "freezing" effect on the 3D Window and an unresponsive user experience. Asynchronous requests avoid this problem by providing a callback when the threaded execution is complete, allowing the browser or calling application to continue functioning normally while your request is being handled. Note that only asynchronous calls are supported for browser calls to TerraExplorer Fusion.

Each asynchronous method in the TerraExplorer API immediately returns either the ITerraExplorerAsync80 or the ICommandLineProcessAsync object, thereby ensuring that control is promptly handed back to the calling function. These objects provide a callback-based mechanism similar to the JavaScript promise and the C# Task that allows handling the various stages of the asynchronous operation.

The ITerraExplorerAsync80 object provides the following properties and methods:

§   OnResolve: This method includes a callback function that is called when the asynchronous operation is successfully resolved. If a corresponding synchronous method has a return value, it's passed as a parameter to the callback function.

§   OnReject: This method includes a callback function that is called when the asynchronous operation encounters an error or is rejected, allowing you to handle any failures or exceptions. It returns an error message.

§   OnProgress: This method includes a callback function that is called to report the progress of the asynchronous operation, providing updates on the ongoing task. This function is only implemented for ExecuteQueryAsync and QueryElevationBufferAsync.

§   State: This property returns the current state of the asynchronous operation (pending, fulfilled, rejected), allowing you to check its status.

§   Abort: This method can be used to abort or cancel the ongoing asynchronous operation if needed.

 

Example of asynchronous method that returns the ITerraExplorerAsync80 object

function CreateShapeAsync()

{

    var g_asyncObj = SGWorld80.Creator.CreateFeatureLayerAsync("ShapefileAsync", "FileName=C:\\Shapes\\countries.shp;TEPlugName=OGR;");

 

    g_asyncObj.OnResolve(function(layer){      

        layer.FeatureGroups.Point.DisplayAs = 18;

        layer.LoadAsync();              

    });

}

 

See "Wrapping TE Async Object with a JavaScript Promise" for an example of wrapping TE Async Object with a JavaScript promise.

 

The ICommandLineProcessAsync object provides the following methods:

§   OnStdout: This method is called when the command line process sends information to the standard output (stdout).

§   OnStderr: This method is called when launched command line process encounters an error.

§   OnExit: This method is called when the command line application exits.

§   Abort: This method can be used to abort or cancel the command line process.

 

Example of asynchronous method that returns the ICommandLineProcessAsync object

g_asyncObj = SGWorld.Creator.CreateCommandLineProcessAsync("my.exe param1 param2").OnStdout(function(stdout){

        g_stdout += stdout;

        g_asyncObj.Abort();

    }).Onstderr(function(stderr){

            g_stderr+=stderr;

    }).OnExit(function(exitCode){

        alert(exitCode);

        alert(g_stderr);

        alert(g_stdout);

    });