Overview of the DOME Plug-in API

DOME employs a plug-in API to communicate with third-party applications such as Excel, Matlab, various CAD tools, and any other application that exposes a programming interface. On one side of the API is DOME’s Java code. On the other side is a dynamically linked library (DLL) or shared library (for Linux/Unix) written in C++.

The plug-in API uses the Java Native Interface (JNI) to transport data and commands from the DOME environment to the plug-in libraries. The libraries in turn talk directly to the third-party applications using vendor-supplied API’s. Finally, the JNI transport is used to deliver any results back to DOME. A simple depiction of this interaction is shown in the following figure.

../../../_images/plugin-interaction.png

Plug-in Structure

The structure of a DOME plug-in was designed with the intention of being as uncomplicated as possible while shielding the author from having to understand JNI. On the Java side, all that is needed is a class (e.g., MyPluginCaller.java) containing one or more native methods. (A method is made native using the native keyword, much like static or public.) On the C/C++ side, a corresponding set of C functions (MyPluginCaller.cpp) is required.

The functions are generic enough to accommodate any plug-in. For this reason, the same functions are used for all plug-ins, and each function takes the same list of arguments. Only the names and the return values of the functions are different. The list is as follows:

void callVoidFunc (long ptr, int func, Object[] args)
boolean callBoolFunc   (long ptr, int func, Object[] args)
int callIntFunc    (…)
double callDoubleFunc (…)
String callStringFunc (…)
long callObjectFunc (…)
double[] callDoubleArrayFunc (…)
double[][] call2DimDoubleArrayFunc (…)

Each of these generic functions is used to access more specific functions located in the plug-in model and data classes. For example, all functions that return a void result are accessed through callVoidFunc, whereas all functions that return a boolean result are accessed through callBoolFunc, and so on.

The rest of the plug-in structure is illustrated in the figure below. In addition to the plug-in caller, there are three primary classes: the delegate (MyPluginDelegate), the model (MyPluginModel) and the data (MyPluginData). The delegate translates the input parameters from the generic functions into commands, model and data objects, and data values. The delegate also instantiates the model and data objects, and passes the commands and data values to those objects where the useful work is performed.

../../../_images/plugin-structure.png

Putting it together: an example using the CATIA plug-in

This section uses the completed CATIA plug-in to illustrate a working example of the plug-in structure. It starts with an example of how to prepare the Java and C++ classes involved in the JNI transport. This is followed by an execution sequence walkthrough, which demonstrates the plug-in programming template. Areas where the plug-in author is required to modify code will be pointed out here as well as in clearly marked comments in the source files.

Preparing the Java side

The CATIAPluginCaller class (in package mit.cadlab.dome3.plugin.catia) contains, in addition to the generic native functions described above, a set of user-defined constants, shown below. Each constant refers to a specific function in either the model class (CATIAModel.cpp) or data class (CATIAData.cpp) of the plug-in library. It is up to the plug-in author to decide which functions he or she needs and to create a constant for each. An abridged set of constants is shown below. These particular constants, which are mapped to functions that create, load, execute and destroy the plug-in model, are common to all the plug-ins developed thus far:

public static final int MODEL_INIT = 0;
public static final int MODEL_DESTROY = 1;
public static final int MODEL_LOAD = 2;
public static final int MODEL_UNLOAD = 3;
public static final int MODEL_IS_LOADED = 4;
public static final int MODEL_EXECUTE = 5;

Preparing the C++ side

Every plug-in requires a header file corresponding to the PluginCaller class. The header file is generated automatically using the javah utility. From the root directory where the class files are located (e.g., dome3/development/out), run the javah utility with the following usage:

javah mit.cadlab.dome3.plugin.catia.CATIAPluginCaller

A file named CATIAPluginCaller.h is produced and should be copied to the C++ project workspace. Looking inside this file, we see that the Java methods have been converted to C-style function prototypes. For example:

void callVoidFunc (long ptr, int func, Object[] args)

becomes:

JNIEXPORT void JNICALL Java_mit_cadlab_dome3_plugin_catia_CATIAPluginCaller_callVoidFunc (JNIEnv *, jobject, jlong, jint, jobjectArray);

Further, the constants are converted to preprocessor definitions. For example:

public static final int MODEL_INIT = 0;

becomes:

#define
mit_cadlab_dome3_plugin_catia_CATIAPluginCaller_MODEL_INIT 0L

To improve readability, the mit_cadlab_dome3_plugin_catia prefix was eliminated (using a text search and replace) from the constants. As a result, the line above gets reduced to:

#define CATIAPluginCaller_MODEL_INIT 0L

This naming simplification is recommended but entirely optional.

Note that the header file must be generated whenever the constants are modified, added or removed.

The C source file, CATIAPluginCaller.cpp, contains the bodies of the functions whose prototypes are CATIAPluginCaller.h. The source file may be reused for all plug-ins, with only minor modifications that are highlighted in the file.

Stepping through an execution sequence: Instantiating the model

The following walkthrough of an execution sequence demonstrates the programming pattern that is used in all the plug-in calls. This same pattern is replicated many times over, once for each different call (the CATIA plug-in uses more than forty.) Mastery of just a single sequence prepares new plug-in authors to develop their own set of calls.

The first step in executing any plug-in model is instantiating the model itself. This requires calling the model’s constructor (CATIAModel::CATIAModel), which has been assigned the constant MODEL_INIT.

Back on the Java side of the plug-in (in CATIAPlugin.java), we decide which generic function is appropriate for the operation at hand. This only requires that we know which type of object must be returned. When a new model or data object is instantiated, the callObjectFunc function is required:

long modelPtr;
Object[] arr = new Object[2];
arr[0] = file;
arr[1] = new Boolean(isVisible);
modelPtr = callObjectFunc(0, CATIAPluginCaller.MODEL_INIT, arr);

The first argument to callObjectFunc represents an existing object. Because the model is being created for the first time, no object is required and this argument is set to zero (or null). The second argument is the specific method to be called—in this case, the model constructor. The final argument is an array containing arguments required by the constructor. When the call has completed, a variable of type long will be returned and stored in modelPtr. The variable modelPtr represents a C++ pointer (casted to a long) to the newly created model object. It will be used in subsequent calls that act on the model.

Now we turn to the C++ side of the plug-in. Once callObjectFunc has been invoked, control is transferred to the corresponding function in CATIAPluginCaller.cpp. The plug-in author need not be concerned with the functions in CATIAPluginCaller.cpp. There is almost nothing in this file that requires modification. All that really matters is that the functions in CATIAPluginCaller.cpp invoke corresponding functions in CATIADelegate.cpp.

In this case, CATIADelegate::callObjectFunctions is invoked. Here, the constant identifying the specific function (the model constructor) to call is queried in a switch statement:

long callObjectFunctions (JNIEnv* env, jobjectArray args,
unsigned int iNumArgs, long iObjectPtr,
unsigned int iFunctionIndex)
{
  switch (iFunctionIndex)
  {
    case CATIAPluginCaller_MODEL_INIT:
        iObjectPtr = initializeModel (env, args, iNumArgs);
        break;
    .
    .
  }
      return iObjectPtr;
}

Assuming that the constant is MODEL_INIT, the initializeModel function will be invoked. As it unpacks the argument list passed in from Java, the initializeModel function performs necessary error checking. It ensures that the number of arguments is correct and that those arguments are of the proper type. Once satisfied, it instantiates a new CATIAModel object and returns the object pointer (casting it to a long) to be transported back to the Java side.

This is the basic pattern for the each of the plug-in calls. An author can start on a new plug-in by copying the CATIA plug-in source files and renaming the files (MyPluginCaller.cpp, MyPluginDelegate.cpp, etc.) Comments in the source files indicate where modifications are required.

It is worth discussing briefly how the Java-side arguments are unpacked. The file JNIHelper.cpp contains a function called getArgument that is used to extract individual parameters from an array of arguments passed in from Java. Continuing with our example, the argument list for the model constructor contains two arguments: a string containing the model’s file name and a boolean indicating whether the CATIA window should be displayed. These two parameters are extracted in the following calls to getArgument:

void* szFileName = NULL;
void* bIsVisible = NULL;
err1 = getArgument (env, args, 0, JAVA_STRING, szFileName);
err2 = getArgument (env, args, 1, JAVA_BOOLEAN, bIsVisible);

The variable args is the C++/JNI representation of the argument list. The parameters must be extracted in the order they appear in the list, which is determined in CATIAPlugin.java, the Java-side caller (refer to the example on page 4). Note that getArgument is a generic function that returns all extracted parameters as heap objects (e.g., new char[10]). This means that the resulting objects must be destroyed when they are no longer needed. The success of the getArgument operation is returned and should be analyzed before assuming the arguments were extracted properly.