Carmenta Engine Java API
The Carmenta Engine Java API consists of:
Java JAR files with all the Carmenta Engine types.
Shared libraries (DLLs) with the native implementation of the Java classes.
An AWT GUI component that can be used in an AWT or Swing application.
Documentation showing how the API should be used (this document).
Reference documentation for all the Java types, both as HTML files and on Javadoc format.
Samples that show how to use the Java API.
Note that to use the Carmenta Engine Java API a Java development kit (JDK) must be downloaded and installed separately.
To build and run Java applications for Linux on Windows, using WSL, some packages located in the linux folder in the Carmenta Engine SDK directory, typically /mnt/c/Program Files/Carmenta Engine 5 SDK/linux, must be installed.
apt install ./carmenta-engine_*_amd64.deb ./carmenta-engine-java_*.deb
Architecture
With a few exceptions, the types in the Java API are built as thin, managed wrappers around the Carmenta Engine kernel implemented in native code. The class hierarchy closely corresponds to the Carmenta Engine object model seen in the other APIs and in Carmenta Studio.
There are several different types of classes and other types in the API:
Static classes are classes with only static methods, and are never instantiated. A good example is the Runtime class, which contains static methods for initialization and shutdown of Carmenta Engine.
Reference classes are those that inherit from EngineObject. Each instance of these classes internally holds a reference to a Carmenta Engine kernel object. Accessing properties or calling methods affect the kernel object directly.
All collections are implemented as concrete classes that implement the generic java.util.List<T> interface. The collection classes are reference classes, they inherit from EngineObject, and hold a reference to a collection instance in the Carmenta Engine kernel. Adding or removing objects to a collection directly modifies the kernel object.
Callback interfaces. Some classes may perform callbacks back to application code, using callback interfaces, for instance the custom operator and custom dataset classes. The application creates objects which implement the corresponding callback interfaces, and registers these with the API classes.
Carmenta Engine types should in general not be used as base classes. The following types are exceptions to this rule:
All built-in tools, for example StandardTool.
All custom object interfaces.
Using the Java API
Using Carmenta Engine modules
For each of the Carmenta Engine modules used by the application, the corresponding jar file must be added to the Java class path, both during compilation and in runtime. The jar files are called CE<module name>.Java.jar, and are installed into the Carmenta Engine bin directory (Windows) or /usr/share/java (Linux). Carmenta Engine does not support custom class loaders.
Each module uses its own package name, com.carmenta.engine.<module name>, all in lowercase. You can access the classes in a module directly using the fully qualified names, but its easier to add a few import statements. For example, if your Java class uses the Core, Operators and DataSets modules, you should import the following packages:
import com.carmenta.engine.core.*;
import com.carmenta.engine.operators.*;
import com.carmenta.engine.datasets.*;
Initialization and cleanup
Before calling any other Carmenta Engine code, your application must first call Runtime.Initialize.
Before terminating the application, you should release all references to any Carmenta Engine objects, and then call Runtime.Shutdown.
Object creation and destruction
Objects in Carmenta Engine can be created from the configuration file or using the API. Both reference classes and value classes are created using normal Java syntax, for instance:
Drawable drawable = ...
LayerCollection layers = ...
View v = new View(drawable, layers);
v.setWidth(10);
v.setCenter(new Point(20, 20));
Carmenta Engine Java objects are garbage-collected like any other Java objects. When an object is finalized, it will release its reference to the corresponding Carmenta Engine kernel object. Note that this means that kernel objects might sometimes be kept alive for a while, even if no active objects are referencing them. However, when the Java objects are finalized, the kernel objects will be destroyed (unless referenced from some other object, of course).
If you explicitly want to release the kernel reference without waiting for Java finalization, you can call the EngineObject.Dispose method.
Properties
Getter and setter method names for all properties are prefixed with get, is or set.
Collections
Collections in the Java API hold references to a corresponding kernel collection; modifying the API collection affect the kernel object directly. As an example, the following code will add a layer to the layer collection of a view:
myView.getLayers().add(aNewLayer)
The collection classes implement the standard java.util.List<T> interface. Methods taking collections as input parameters accept both Carmenta Engine and standard Java collections.
Enumerations
Enumerations are implemented as Java enum classes, with a few exceptions: Enumeration types that can be used as bit masks are represented as integers.
Events
The events and delegates found in the .NET API are available in Java as well, but has been adapted to the standard Java event listener pattern. Each .NET delegate corresponds to an event listener interface with a single method. Each .NET event corresponds to two methods addXxxListener and removeXxxListener that registers and unregisters listeners to the event.
Error handling
The Java API contains one exception class, EngineException that is thrown when an error occurs in the Carmenta Engine kernel. Errors that occur in the API layer typically use standard Java exceptions, like java.lang.NullPointerException, but some API calls throw EngineExceptions.
When using the MapControl, EngineExceptions can occur as a result of MapControl accessing the Carmenta Engine kernel. It is possible to get those errors through events instead of exceptions by handling the event MapControl.Error.
There are also errors that can occur anytime due to asynchronous code started by the kernel. Read more about these here Runtime.Error.
Samples
There are several Java samples available from the Programming Samples page.
Javadoc Documentation
The Carmenta Engine SDK includes a ZIP archive that contains Javadoc documentation. On Windows it can be found in the Carmenta Engine doc directory, on Linux the archive is located in the /usr/share/doc/carmenta directory.