Hello Java and 4DX (STK Engine) enthusiasts!
Have you ever wondered how to use 4DX (STK Engine) in your Java applications? Have you wondered what are your options? Well look no further, this is the article for you!! Please note that I am assuming you are already familiar with Java, AWT/Swing, SWT, COM/OLE, and 4DX (STK Engine). I'll discuss the integration of 4DX (STK Engine) with the following APIs:
1) AWT/Swing API.
2) SWT OLE Win32 API
3) SWT_AWT Bridge API
4) Pure SWT based STK Java API
5) Summary of Java / 4DX (STK Engine) Integration Options:
Swing/AWT API:
The STK Java API was officially released with 4DX/STK on Windows 8.1 and 4DX on UNIX 7.0.2. Under the hood it leverages Sun Microsystems's AWT/Swing UI window framework and threading model. It provides a reference/binary implementation to access the STK Engine's Object Model and Map/Globe control API's with which it is released (1 to 1 version dependency). The Globe/Map controls are derived from AWT/Swing Component/JComponent, hence can be directly coded into a AWT/Swing application like any other AWT/Swing component. You can also access the thousands of Object Model and STKX classes/interfaces from Java, straight out of the box. What this means is you can begin right away to develop the domain logic of your very own Java AWT/Swing application utilizing AGI's 4DX (STK Engine) technology. The STK Java API hides all the details of communicating with the native code DLLs and Microsoft COM, and provides a regular Java look and feel to Java developers. For more details please refer to the 4DX (STK Engine) installation help and search for "STK Java API" and/or the following online links...
What is the STK Java API?
Why does the STK Java API exist?
What is included in the STK Java API?
How do I use the STK Java API?
What help is available for the STK Java API?
SWT OLE Win32 API:
The 4DX (STK Engine) installation provides sample applications for 4DX (STK Engine) integration with SWT without using the STK Java API. An example is provided here. While analyzing this sample one will notice that it makes use of SWT's OLE WIN32 API, specifically the OleControlSite, OleAutomation, OleFrame, OleListener, Variant, etc. within the org.eclipse.swt.ole.win32 package space. This SWT OLE Win32 API implementation is a generic API that can be used to embed any MS Active X Control within a SWT Java application on Windows ONLY. In addition, please note if one uses this SWT OLE Win32 feature within their Java application, one will have to write wrapper Java classes/interfaces to access each object provided by the 4DX (STK Engine) Object Model API using the OleAutomation class. Ultimately this could mean that thousands of Java classes/interfaces must be written before you begin to develop the domain logic of your own Java application. The example shows an attempt at starting to wrap some classes that are available in the STKX typelib. AGI development team does not recommend the use of this approach with the 4DX (STK Engine) if one is attempting to use a majority of the STK Engine Object Model, however, it could be a valid alternative if one is merely wishing to use only a handful of classes, interfaces, etc provided by the STK Engine Object Model. Remember, this API is not available on UNIX/Linux platforms.
SWT_AWT Bridge API:
The STK Java API is implemented using the Sun Microsystems's AWT/Swing UI window framework and threading model. However, thanks to those forward thinking developers of SWT, it is possible to integrate/merge a Java AWT/Swing based application with a SWT based application using the SWT_AWT Bridge class, which is documented here and SWT threading discussed here. An example of a SWT_AWT Bridge standalone application can be found here. An example of a SWT_AWT Bridge Eclipse Plugin application can be found here.
Please note if you read the above articles thoroughly, you will notice the mention of threading issues due to the Multiple Event threads/queues of the AWT Event Dispatch thread and the SWT UI Thread. As mentioned in the articles it is very important to schedule particular tasks to be done in the proper UI thread by invoking the UI thread's work scheduler. Specifically, in AWT, use the SwingUtilities.invokeLater() and invokeAndWait() methods. And for SWT, use the Display.asyncExec() and synExec() methods. Note, however, that if you issue an Object Model call from the SWT UI thread utilizing the SwingUtilities.invokeAndWait() call, which causes the STK Engine Map or Globe controls to issue event notification to its parent window toolkit (i.e. SWT in this case) then you might cause a dead lock to occur. Note that the STK Java API Object Model implementation uses the SwingUtilities.invokeAndWait() work scheduler to help ensure calls are executed in sequence on the AWT Event Dispatch thread. However, if the developer of the SWT application wraps each Object Model call or for better performance a set of Object Model calls in a SwingUtilities.invokeLater() call then the STK Java API will bypass the calls to the SwingUtilities.invokeAndWait() and thereby avoiding the possible deadlock issues between the AWT and SWT Event loops. The reason for this is that the SwingUtilities.invokeLater() call does not block the current thread it is issued from like the SwingUtilities.invokeAndWait() method does. However, if you are depending on the Object Model calls to complete before you continue processing within your SWT UI thread (i.e. to update SWT widget controls) then you will have to create a mechanism to check when the Object Model calls have completed.
Pure SWT based STK Java API:
AGI development is investigating into the development of a pure SWT based STK Java API for the Map(2D), Globe(3D), and Object Model to be released in a for a future version of STK. This pure SWT API will provide an alternative for the SWT_AWT bridge and the SWT OLE Win32 solutions for SWT based Java applications. This alternative will also theoretically bypass any of the SWT/AWT UI dead locks due to the fact that the implementation will run purely in the SWT UI thread and not at all in the AWT UI thread.
UPDATE: (04/23/09) Please see the new blog article detailing the SWT support in the STK Java API 9.0.
Summary of Java / 4DX (STK Engine) Integration Options:
As I discussed above there are several Java / 4DX (STK Engine) integration options available. Each alternative has advantages and disadvantages. I've attempted to summarize this blog article's discussion in the below table in hopes that it will help you choose the best option for your development plans/schedule. Thanks for reading and have a successful Java / 4DX (STK Engine) development cycle!
