|Top Previous Next|
When using the FreeFlyer runtime API, it is entirely possible that the user will make mistakes in API configuration, in Mission Plan configuration, in programming, or otherwise. These errors result in exceptions being thrown at the API level, and an understanding of the exceptions that are thrown is critical to the development of applications that successfully utilize the runtime API.
The best way to capture exceptions with the runtime API is to use the try/catch functionality of the programming language for the interface you're using. From within the try/catch, if any exception is thrown, it will exit out of the try portion and immediately break into the catch portion, from which you can access the exception itself and obtain details on the failure. In the case of the runtime API, you will always have a RuntimeApiException thrown if a failure occurs within the context of the runtime API itself and not elsewhere in your programming. The following is a trivial C# example demonstrating using the try/catch functionality of C# to capture the RuntimeApiException.
Note: Most asynchronous exceptions are thrown when they are encountered in the asynchronous queue. Invalid argument or invalid engine exceptions, however, are caught up-front when the call is made. See the Asynchronous Programming guide for more information on asynchronous calls.
Some details that you can obtain from your exception include the result type. To obtain the result type, you might do the following in the catch portion of the above C# example.
Mission Plan Diagnostics
Exception handling within the runtime API captures errors that are experienced within the actual application code itself, but doesn't give any details about the Mission Plan. Your exception may be rooted in an error thrown at runtime in the FreeFlyer Mission Plan itself, and so there is a lot of value in being able to diagnose those errors without having to actually run your Mission Plan from FreeFlyer.exe. To do this, we leverage another capability of the runtime API, the GetMissionPlanDiagnosticsResult class.
The GetMissionPlanDiagnosticsResult class has four key properties associated with it, which all give you greater insight into the issues experienced in the Mission Plan itself.
The GetMissionPlanDiagnosticsResult class requires access to the RuntimeApiEngine class that experienced the error in order to provide further information on that error. It is especially apparent that should you be diagnosing exceptions in your application, you are likely doing it in the Catch block of a Try/Catch setup. Typically within the Catch block you will not have access to the RuntimeApiEngine class, and thus may be unable to diagnose your Mission Plan. It's not as simple as instantiating your RuntimeApiEngine outside of the Try/Catch blocks, however, as you will want to ensure that any exceptions thrown when attempting to create the engine are captured. There are effective ways to program around this, however, and one such example is provided below.
In the above example, we create the RuntimeApiEngine class outside the Try/Catch block and then dispose of it in a Finally block to ensure that it has been appropriately cleaned up. The text that gets written to the Console in this case is identical to the text that one would experience were they encountering this error in FreeFlyer.exe itself. An example of what one of these errors might look like follows.
A result type is not the same as an exception. When an error occurs with the runtime API, regardless of the type of error, a RuntimeApiException will be thrown. Meanwhile, that an exception has been thrown in itself may not be as useful as one would like. What is important is what the diagnosis of that exception is, and ultimately the nature of the exception, which is described by its result type. A host of different result types can be thrown by the runtime API's methods when called, and where each of the errors can appear depends on the method being used as well as how it interacts with FreeFlyer. The following table showcases all of the different result types supported by the runtime API, the specific issue they're trying to communicate, and a non-exhaustive list of some places where you might encounter an exception with that result type given in the context of the C# interface.