AGI STK Engine (4DX) Blog

April 26, 2010

STK/STK Engine Plugins for Java

Filed under: Java, Plugin — Matt @ 8:29 am

The STK and STK Engine products have provided custom plug-in points in STK / STK Engine for many years now.  These custom plug-ins could be written in C#, C++, VBScript, JScript, and a few other languages.  However, the ability to write these plug-ins in Java was not available until STK / STK Engine 9.1.  General documentation for the AGI Java Plug-in API can be found online.  This article's goal is to provide a few in-depth details that will enable you to gain a greater understanding and more efficient use of this API.

In this post, I'd like to discuss some key points regarding the AGI Java Plug-in API, and some differences in terms of method calls and configuration from the other supported plug-in languages.  In this discussion we will use the Java Access Constraint Plug-in API as a reference, you may want to familiarize yourself with this documentation before continuing further with this article.

Java Plug-in Configuration:

Configuration of a Java Access Constraint plug-in does not require Microsoft COM registration as do the C#, C++, etc. plug-in versions.   However, Java Access Constraint plug-ins do require registration within a STK plug-in category XML file.  They specifically use the JavaPlugin element tag, rather than Plugin tag used for the plug-ins written in other languages, as can be seen below.  


Note the JavaPlugin tag must be a child node of an Access Constraint Plugincategory element.  This tag allows for setting up the run-time environment of the JRE that is embedded within the STK / STK Engine process, which is started at STK initialization time only if a JavaPlugin tag is found.  Specifically, the tag's ClassPath and ClassName attributes are collected and passed to the embedded JRE at initialization time.  If changes are made to any JavaPlugin tag, STK / STK Engine must be restarted to utilize these new changes.  The ClassName attribute provides the main class that implements the plug-in point's interface, for Java Access Constraint Plug-ins this is the IAgAccessConstraintPlugin interface.  The ClassPath attribute provides a semi-colon separated (;) path of all paths required by the Java plug-in at run-time.  The syntax of the ClassPath attribute should be familiar to you as it is the same as is required by the Java standard CLASSPATH environment variable or JRE -classpath argument value.  Note that all JavaPlugin tag ClassPath entries are concatenated together and passed as one classpath argument to the same embedded JRE in the order that the tags appear within the plug-in XML configuration file.  As such special care must be taken to be sure to resolve any possible run-time issues that may occur because your plug-in unintentionally loads and utilizes a class file from another plug-in's ClassPath attribute path due to classpath ordering.

Once the plug-ins are configured and compiled correctly STK / STK Engine will make them available for use by the STK Objects ( Satellite, Facility, Aircraft, etc.) for which the plug-in has indicated it is valid.  Below is an example of a Facility's plug-in panel, note that three Access Constraint Java Plug-ins that are shipped with STK and STK Engine are shown below.


Java Plug-in Code:

Some STK Plug-in API class objects provide methods that support what is known as "multiple out parameters" for languages such as C# and C++.  Not all languages provide this mechanism or the implementation use of such methods may not be clear in terms of readability or use within code.  As such, symmetrical methods have been provided that return the multiple return values as an array of values rather than via the argument list.  These methods have the same name as their "multiple out parameter" method counterpart, however, their name is suffixed by _Array.   The Java Access Constraint Plug-in API provides the _Array method implementation that returns an AgSafeArray that contains the return values.   For an example refer to the STK / STK Engine Java Access Constraint Plug-in sample entitled Extend_Plugin_AccessConstraint_NIIRS, within the evalutate method implementation.  You will notice the use of the relativePosition_Array method on the IAgAccessConstraintPluginObjectData interface.  Typically these arrays contain AgVariants whose type access methods can be used to retrieve the native java type values.  As is seen in the following code snippet:


Often plug-ins provide user configurable variables for use within their runtime computations.  This can be done within a Java plug-in by implementing the IAgUtPluginConfig interface.  When a Java plug-in is instantiated by the embedded JRE within STK / STK Engine, it is interrogated to determine if it provides configurable variables to the user similarly as do the other language plug-in APIs.  Please refer to the STK / STK Engine Plug-in documentation for details on the plug-in configuration panel.  Any information in the embedded JVM can be retrieved and displayed in the configuration panel, including information regarding the JVM instance state.  The following is the configuration retrieved from the Java.Config sample shipped with STK / STK Engine install.

Within a Java plug-in the getPluginConfigmethod is used to build a run-time in-memory configuration schema of the setter and getter methods that can be used to set/get the configurable variables within the Java plug-in.  Once again this works in the same manner as in the other language plug-in types.  However, there are two notable differences within the Java plug-in implementation of this feature.   The name of the method described within the IAgAttrBuilder add property method(s) must also must have a "get" or "set" prefixed to the method stem.   In other words, if you have setter/getter methods called getOpticalRatioand setOpticalRatio as shown below:


Then you must configure this within the add property method of the builder using "OpticalRatio" as the stem name of the getter/setter method as see below:


A second important note is that the getter/setter methods must return and accept a parameter of type java.lang.Object.  This is due to the inability to set the configuration method's specific variable JNI data type (Object or primitive type) within the IAgAttrbuilder add property method, thus it is necessary to provide a generic JNI signature to reflect and access the method from native code running within STK / STK Engine.  Such a configuration method (i.e. "OpticalRatio" ) would show up in the plug-in's configuration panel as follows, note the highlighted entry.

Java Plug-in Run-time:

At run-time, it is possible to get information from your plug-in within the STK / STK Engine message viewer or messaging event notification system, this information can be extremely useful for debugging.  Note that when using Java plug-ins, some internal STK / STK Engine logging will occur by default by instances of the plug-in Driver ( native to Java proxy ) and embedded JVM.   The below shows an example of some possible logging you will see in the message viewer or messaging event notification.


With this discussion, I hope I've provided you with greater detail of the Java Plug-in implementation that is provided with STK / STK Engine 9.1 and have empowered you with greater control and customization of AGI's STK / STK Engine products.


No Comments »

No comments yet.

RSS feed for comments on this post. TrackBack URL

Leave a comment

Powered by WordPress