May 7, 2008

A context within the STK Object Model is an object holding the unit preferences, the Object Identify Cache (OIC) as well as access restrictions. Contexts are not directly accessible to the users, yet users can influence their behavior to a certain degree (see the following article "Root Object Isolation"). Any object created or accessible through the Object Model is associated with a context through which the object accesses the unit preferences to perform the unit conversion. The diagram below shows the two root objects sharing the same context.

STK Object Model: Root Object Isolation

In the version 8.1 we have introduced a new feature called ‘Root Object Isolation’. In a nutshell, the isolation is designed to provide a way for the 4DX developers to make multiple copies of the unit preferences. Here is a short example how to use the isolation to configure two distinct, non-overlapping unit preference sets. The code creates two independent root objects and configure each with its own set of unit preferences. This process is referred to as "isolation".

AgStkObjectRootClassrootA = new AgStkObjectRootClass();
root.UnitPreferences.SetCurrentUnit("DistanceUnit", "km");AgStkObjectRootClass rootB = new AgStkObjectRootClass();
rootB.Isolate(); // rootA and rootB are now using non-overlapping unit preferences, i.e. the changes to the unit preferences via object “rootA” do not interfere with the unit preferences of the object “rootB”.

Note: The isolation must be done right after a new root object is instantiated. Once the root object becomes “tainted”, i.e. changed, any attempts to isolate it will not succeed and will throw an exception.

The benefits of having multiple roots isolated from each other becomes more obvious when building enterprise applications where it is necessary to make individual components as independent and isolated from each other as possible. Another example where Isolation becomes a must-have is in a type of application that is constructed out of many components, for example the Application Framework. Each add-in, to prevent interfering with other add-ins, must isolate itself from the rest of the add-ins so that each one manipulates with its own private set of unit preferences. The following diagram shows two root objects isolated from each other:

Note: the references to the STK objects are local to the context so use the “Path” property of the IAgStkObject interface to compare two instances to find whether they represent the same object within STK engine.

STK Object Model: Restricted Contexts and STK Plug-ins

Contexts are also useful for the STK engine plug-ins. A while ago, while in the process of exposing the Object Model to the Constraint Plug-ins, we realized that simply giving a full read/write access is not an option and here is why. When computing the access constraints, the engine expects its state to stay the same before and after the access computation is completed. Now imagine a custom access constraint plugin which changes a position of a facility, re-propagates a satellite or does something else that changes the state of the application. So what, one may ask? Well, changes to the object’s position will trigger the access computations and the access plug-in will be called again, and again, and again… To address this, we have introduced a "restricted" context which purpose is to provide a safe mechanism for accessing the STK object state via the Object Model while protecting its state. How does this work?
When accessing the STK Object Model configured using a restricted context, the users are given read-only access to the STK Object Model objects and their methods and properties. Any attempt to change the application state by calling a method or changing a property value will result in an exception. The diagram below shows the restricted STK Object Model Root object accessed by the access constraint plug-in. Any action via the Object Model will first consult the associated context and throw an exception in case if the action is marked unsafe. So, if you are writing an access constraint plug-in and intent to use the Object Model, beware of the restricted contexts.