: junc++ion generate

JunC++ion GUI Reference

The code generator GUI is a wonderful tool for interactively defining your solution to a particular Java/C++ integration problem. It provides a graphical user interface that you can use to interactively define the scope of your cross-language integration project.

You can set transformation options, specify the Java types that you wish to expose to C++, and generate the proxy types right from within the application. The GUI—a screenshot can be seen below—is a modern Swing-based application that supports multiple concurrent integration models via a tabbed document interface. A screenshot of the code generator GUI

An integration model is represented as a multi-pane document in the code generator application Window. The two dominant panes in a model are the Navigation Pane (the tree view on the left), and the Model Properties Pane (the grid view on th right). You can have more than one model open at a time but we recommend that you limit yourself to one open model unless you have need for the referenced models feature.

Navigation Pane

The Navigation pane contains a tree view of the imported Java types. You can use filter buttons and a typename filter to control the types that are bing displayed. As with most code generator controls, simply hovering your mouse pointer over the buttons will get you a short description.

A marked up screenshot of the navigation pane's filter options.The filter controls are initialized to only show you packages and public types. If you wish to see additional model elements, for example default accessible types, you will need to enable the appropriate control. Whenever a control is activated, the corresponding model elements are displayed.

Name filtering works as you would expect: simply start typing a name in the text field. The displayed model will adjust to show you only types matching your filter text. Don't forget to erase your filter if you want to go back to seeing all elements!

You can also search the tree view for elements by name. Simply click in the tree pane and start typing. You will see a tooltip containing your search text and the tree navigation controls (arrow keys, etc.) will skip all non-matching elements. Hit the ESC key to go back to normal navigation mode.

A screenshot of the navigation pane's tree view The navigation pane's tree view provides visual cues about the generation state and other Java element characteristics. Let's look at a little more detail. You can see the circular icons that represent different kinds of Java types. There are different icons for class, interface and enum types. The type icons may be decorated with little symbols or letters that provide additional information about the type. The letter A stands for an abstract type (omitted for interface types because they are always abstract), the letter F stands for a final type, the letter S stands for static, etc. The little arrow symbol is used to signal that a type has been marked as a callback type.

You can hover over a type to see a tooltip that contains information about its origin and whether (and where) we could find source code for it.

The most important question for you is whether a type is enabled or not. You will only receive a proxy type for an enabled type. Enablement is indicated by displaying the typename in a bold font. Any type not shown in bold will not result in a proxy type.

We also use colors to give you an indication about the reason for a type's enablement. A blue type indicates that it is enabled because you explicitly enabled it via a command. A red type indicates that you explicitly disabled it via a command. Black types are enabled because you directly asked for them via an import command. Gray types are types that the current enablement rules caused to be enabled when an import command was executed.

In the image above, the Thread type was explicitly imported into the model and is therefore marked as generating. Runnable, RuntimeException and the other gray types are enabled because the import rules deemed them important for the Thread type (the Tread type references these types via public members of its API). The StringBuilder type was not deemed important by the import rules, for example because it is only referenced by an imported type's private members, but the user decided to explicitly enable it anyway. Similarly, the nested UncaughtExceptionHandler type was deemed important by the import rules but the user decided to disable it.

A lot of the visual cues don't matter for the code generation outcome. Only bold vs. non-bold determines which proxy types will be the result of your code transformation. The colors, symbols and decorations are just there to provide you with additional information and can be highly relevant as you try to create a robust model that you don't have to adjust frequently in the presence of a changing Java code base.

Model Properties Pane

The Model Properties pane contains a table of properties that apply to the entire integration model. Model properties are arranged hierarchically by general areas of concern, but you can use the control buttons at the top to reorder them alphabetically. Model Properties Pane Every model property has a unique name (see the Model File Reference for more details). Model properties govern virtually all aspects of code generator behavior. Via model properties you can control for example:

Not all model properties are exposed in the GUI, but all model properties can be configured via setmodelproperty() commands in the model file or via command line property overrides.

For properties that are exposed in the code generator GUI, pressing F1 will open the documentation page for the currently focused model property in the default browser.

Model State Pane

The sequence in which you do things can matter a great deal to the outcome of your transformation. The model state, which will eventually be persisted as a model file, is basically a recording of the commands into which your GUI actions were translated. Any action that alters the model state is appended to the model. The image below shows the model state after the user first set the model name, then the path where the code generator looks for Java source files, and then imported a jar file into the model. Screenshot of a model state

It is of course totally irrelevant whether your set the model name or the userSourcePath first. It is not irrelevant whether you set the userSourcePath first and then import some Java types or whether you first import some Java types and then set the userSourcePath.

In general, you should work in the following sequence:

  1. Set all model properties to their desired values.
  2. Import the Java types you are interested in.
  3. (Optionally) modify the generation status of select Java types, methods, and fields.

Don't worry about getting this totally right the first time. It is quite common to make an edit to a property only to realize that you have a typo in and then make a corrective edit. The model state will faithfully record both changes. Before integrating the code generation into your production build you probably want to clean up your model file a bit.

The model file is saved in clear text format, just as shown in the model state screenshot, and you can easily edit it to delete extraneous commands or bring the commands in the right order without having to start over with a new model. Please note that you will have to close and reload the model to have your changes take effect for code generation.

Tool and Menubar

The tool and menubars are where you can locate some of the most common commands that you will normally want to perform on a model or model element. Hovering your mouse pointer over the toolbar buttons will provide you with a short description of the button's purpose. The most important commands are outlined in the table below.

 

Command
Description
Import type icon
Import Type(s) from Classpath
Open a dialog that allows you to specify type names or patterns that should be imported into the current model. The code generator will attempt to locate matching types from the configured system and user classpaths.
Import types from path icon
Import Type(s) from Files
Open a file dialog that allows you to select class, jar or zip files. The intent will be deemed to be that all contained classes are potentially of interest and they will be treated as if they had been individually imported.
Enable element icon
Enable Selected Element(s)
Enable the elements currently selected in the model's tree view. Enabling elements means that you indicate interest in having a corresponding proxy element in the generated C++ code.
Disable element icon
Disable Selected Element(s)
Disable the elements currently selected in the model's tree view. Disabling elements means that you indicate that you have no interest in having a corrsponding proxy element in the generated C++ code.
Enable callback icon
Enable Callback Support
Enable the generation of callback support for the eligible selected elements in the model's tree view.
Disable callback icon
Disable Callback Support
Disable the generation of callback support for the eligible selected elements in the model's tree view.
Enable native icon
Enable Native Method Support
Enable the generation of native method implementations for the eligible selected elements in the model's tree view.
Disable native icon
Disable Native Method Support
Disable the generation of native method implementations for the eligible selected elements in the model's tree view.