11. Using AJIS

11.1. Creating and Building an AJIS Project

11.1.1. Audience

This document is intended for users already somewhat familiar with Eclipse, the JDT, and GNATbench. Some familiarity with AJIS may be useful.

11.1.2. Before You Begin

Install AJIS (remember to set the path and classpath). Make sure that the version of AJIS matches the compiler date and the minimum requirements for the GNATbench AJIS integration.

Install the “make” utility if it is not already installed. Windows users can download the GNU version via the “Miscellaneous/Utils” section of the “Downloads” page on GNAT Tracker. The file to download is named “gnumake-3.79.1-pentium-mingw32msv.exe” or something similar (i.e., the version number could be different). Once downloaded, rename the file to “make.exe” and put it somewhere on your path.

Consider disabling automatic builds, at least until the new Ada project has been fully configured.

Optionally, set Eclipse to refresh resources on access (as of Eclipse 3.7). This is a workspace preference. It is changed via the Window -> Preferences menu; the specific property is on the General / Workspace page. Occasionally you will still need to manually refresh the Java projects that have corresponding Ada interfaces generated, but this preference can help.

11.1.2.1. Important

Before you create an Ada project for use with Java and AJIS, first create a new client Java project using the JDT. This Java project will be used for primary Java development. Prior project creation is not strictly required but will be convenient because the Ada new-project wizard can automatically make the modifications to the client Java project required for the sake of the Ada project. Otherwise, you will have to modify the Java project yourself.

11.1.3. Create an Ada Project for AJIS

Once the client Java project exists, you are ready to create the new Ada AJIS project.

First, open the New Project Wizard with File -> New -> Project, then select “Ada Project for AJIS” under the Ada category.

New Project Wizard with AJIS project selected

In the resulting wizard page, name the new Eclipse project:

naming the new AJIS project

Then on the next wizard page specify the GNAT project unit name. The names can be the same but need not be. However, the GNAT project unit name must be a legal Ada identifier.

the GNAT project unit name for new AJIS project

On the next page, specify the name for the dynamic library that will contain your Ada code. This dynamic library will be produced when the Ada project is built, and is used by the client Java project.

../../_images/library.png

On the next page, specify the names of the folders where the AJIS-generated code will be placed. Enter two, one each for the Ada and Java code. The names may also be paths to the folders. Folders that do not exist will be created by the wizard. Relative paths are treated as subdirectories of the Eclipse project root within the workspace.

../../_images/binding_dirs.png

Next, specify the name of the Java package that will contain the generated Java code. Alternatively, you can perform this step by editing this Ada project’s properties later, after the wizard completes.

../../_images/base_package_name.png

Then select the toolchain used to build the project. Presumably you will want the native Ada toolchain.

../../_images/toolchain.png

Next select the existing client Java project that will use the Ada dynamic library created by this new Ada project. The Java project must be configured to reference this dynamic library and generated Java code. This configuration step will be performed automatically if a project is selected. Alternatively, you can either perform this step manually with the JDT Build Path dialogs, or edit this Ada project’s properties.

../../_images/wizard_client_project.png

Click “Select Project” to open a project selection dialog and choose an open Java project in the current workspace. Then press OK.

../../_images/project_selection_dialog.png

The selected project will then appear in the wizard dialog page.

../../_images/wizard_client_project_selected.png

(If the AJIS jar file is not found on the system classpath the user is asked to select the file. Note that this should have been set as part of the AJIS installation.)

Press Finish and the wizard will complete. At this point, the new Ada project is almost, but not quite, ready to be built. Ada sources must be specified so that the corresponding Java interfaces can be generated by AJIS. These Ada sources don’t necessarily exist yet – certainly not within the project we just created – so we specify them after the wizard completes.

11.1.4. Final Project Setup Steps

The last steps to be taken are to 1) populate the project with Ada sources, and 2) select a subset of them to be used as interfaces for the client Java code. These interface packages will be passed to AJIS (ada2java) during the Ada project build so that corresponding Java code is produced to call the Ada code.

11.1.4.1. Populating with Ada Sources

The wizard creates an empty directory named “src” to contain Ada source files. Use of this directory is optional; you could use others, or just use the project root. We suggest using explicit source directories, however, for the sake of keeping everthing simple. New source directories can be created via the GNATbench New Source Folder toolbar button. Using that facility will automatically update the GNAT project file contents so that the resulting source directories are known to the builder.

Once the source folders are to your liking you may use the editor to create the Ada source files. Alternatively, existing source directories and files outside the workspace may be imported through the Eclipse Import wizard. Imported source directories must be specified manually in the GNAT project file since the New Source Folder wizard is not used to create them.

This example describes how to import two existing source files into the default source folder.

Right-click the “src” directory of the project and select “Import” and then “File System.”

../../_images/import_file.png

Select a directory containing source files. Check the boxes corresponding to the necesssary files.

../../_images/import_files2.png

After you press “Finish” the project should look something like this (although some names will vary). Note the two source files under “src” that have been imported.

../../_images/project_after_import.png

In this example, the source files are hello.ads:

package Hello is

   function Greeting (Item : in Integer) return String;

end Hello;

and hello.adb:

with Ada.Characters.Latin_1;
with Ada.Numerics.Long_Elementary_Functions;

package body Hello is

   function Greeting (Item : in Integer) return String is
   begin
      return "Hello from Ada! Java passed "
         & Integer'Image (Item)
         & Ada.Characters.Latin_1.LF
         & "which has square root "
         & Long_Float'Image
            (Ada.Numerics.Long_Elementary_Functions.Sqrt
               (Long_Float (Item)));
  end Greeting;

end Hello;

11.1.4.2. Selecting Interface Files

The user must select which Ada specification files will be used by the Java application in the client Java project. The AJIS tools create Java source files corresponding to the selected Ada specification files. Select only the files which are needed directly in Java, as specified by the AJIS documentation.

To do so, open the Project Properties for the project. (Right-Click -> Properties or Alt+Enter). Expand the category “GNATbench Properties” and select “Ada/Java Interface Files”.

../../_images/no_interfaces_selected.png

Click “Add File” and an operating-system-dependent file selection dialog will appear. Navigate to the location of the Ada specification files.

../../_images/interfaces_browsing.png

Select one or more files and press “OK”. The selected files will appear in the list.

../../_images/one_interface_file.png

11.1.4.3. IMPORTANT NOTE

At least one Ada interface file must be selected before the project can be successfully built.

11.1.5. Building the Ada Project

Set the scenario variable name “Externally_Built” to “false” using the Scenario Variable view. This setting will allow the AJIS library to be rebuilt if necessary. A rebuild would be required, for example, if a different toolchain (e.g., the Android cross-compiler) had been used with AJIS most recently. Once it is rebuilt with the right toolchain you can set the scenario variable back to “true,” or just leave it set to “false” all the time; it will only be rebuilt if necessary.

Now the project is ready to be built, e.g., with Project -> Build Project. Doing so will invoke AJIS to generate the Java sources corresponding to the Ada packages you specified in the wizard, compile the Ada code as usual, and generate the dynamic library. Note that these individual steps are only taken if necessary. When no significant changes have been made to the project the builder will not do more than determine that fact.

Commands to clean and rebuild (i.e., a clean followed by a build) are supported. Individual Ada file compilation is available via the context menu.

Next, refresh the Java project, whose linked resources have been changed by the Ada build. (This can be accomplished by selecting the project in the Navigator or Explorer and pressing F5.)

../../_images/java_refreshed.png

In the “generated_java” source folder of the Java project, there are now several packages, some of which correspond to the Ada packages selected as interfaces files (in the above example, the Java package com.example.Hello.Hello). The others (Ada.Exceptions, Ada2Java, and Standard) are always created, and are responsible for loading the library and interfacing between Ada and Java.

At this point a Java application can be written, with some sources referencing the Ada code through the generated Java interface code.

In our example, this is the main method of the Java application code:

public static void main(String[] args) {
        java.util.Scanner input = new java.util.Scanner(System.in);
        System.out.println(Hello_Package.Greeting(input.nextInt()).toString());
}

Note that you will need to import the Java code interfacing to Ada, using the normal Java “import” statement. The usual JDT tools can facilitate that, as ususal.

The Java project can now be built and run through the standard Eclipse and JDT tools.

Congratulations! You have created and built an Ada/Java application.

11.1.5.1. Alternative Ways to Select the Client Java Project

If you did not use the wizard to choose a client Java project (or just wish to change it), you may do so by editing the Ada project properties as described below. Alternatively, you can use the JDT Build Path dialog of the client Java project itself.

Under the Project Properties for the project, select “Client Java Project”.

../../_images/property_no_project_selected.png

Click “Select Project” and choose an open Java project in the list presented.

../../_images/project_selection_dialog.png

Once the selection is made press OK to return to the properties page.

../../_images/property_project_selected.png

Press OK to close the page. As a result, the properties editor does three things to the Java project:

a. It creates a link to the generated Java code so that the Java project can build with those sources included.

b. It configures the Java project’s build path to use the dynamic library. (This is a per-source-folder setting.)

c. It configures the Java project’s build path to reference ajis.jar, a library necessary for building against the generated Java code. If the file is not found on the system classpath, which should have been set after the AJIS installation, the user will be asked to select the file.

11.1.5.2. IMPORTANT NOTE

The user may return to this property and change the selected project. Changes to the previously selected project will not be undone. The user should modify or remove that project so that it does not contain its links to the Ada project.

11.2. Using AJIS Examples

GNAT-AJIS version 17.0 or later contains a GNATbench version of the examples at <GNAT-AJIS-INSTALL-PATH>/share/examples/ajis/GNATbench.

If you have such version installed, you can follow this procedure to have the examples available in your workspace.

11.2.1. Before You Begin

Install AJIS (remember to set the path and classpath). Make sure that the version of AJIS matches the compiler date and the minimum requirements for the GNATbench AJIS integration.

Install the “make” utility if it is not already installed. Windows users can download the GNU version via the “Miscellaneous/Utils” section of the “Downloads” page on GNAT Tracker. The file to download is named “gnumake-3.79.1-pentium-mingw32msv.exe” or something similar (i.e., the version number could be different). Once downloaded, rename the file to “make.exe” and put it somewhere on your path.

Consider enabling automatic builds (see menu Project > Build Automatically), to have the AJIS examples for GNATbench projects automatically built after import.

11.2.2. Import AJIS examples for GNATbench projects into workspace

First, run File > Import… menu. Select Ada/AJIS Examples import wizard.

AJIS Examples import wizard selected

Click Next > button

The AJIS Examples page will display the operation to process during the import operation.

If AJIS examples folders are found in workspace, a warning is displayed. You can overwrite or reset these folders. Press Cancel if you want to keep the folders unchanged and cancel import operation.

import AJIS examples page configuration

Click Finish button to import the projects

11.2.3. Build AJIS examples for GNATbench projects

If automatic build is enabled (see menu Project > Build Automatically), all the imported projects will be built automatically.

Otherwise select all imported AJIS examples Ada projects in Project Explorer view, and then run Project > Clean… menu. Ask to clean only selected projects, and to start immediately a build of the selected projects.

clean then build ada projects

Then, do the same for all imported AJIS examples Java projects

11.2.4. Run or Debug AJIS examples for GNATbench projects

All the examples have Run or Debug configurations. (*.launch files)

Select a launch configuration and select Run (Ctrl+F11) or Debug (F11) command.

run or debug application or library.

11.3. Using the AJIS Integration

11.3.1. Installing the Required Tools

First install “AJIS for GNATbench” feature that can be found in “AdaCore Plugins for Eclipse/CDT” category.

Then install AJIS. Remember to set the path and classpath, as described by the AJIS User’s Guide. The AJIS tools are responsible for generating the Java source files and configuring how the library is built, as well as creating Ada sources that are needed by the library.

11.3.2. Creating a Library and Sources

An AJIS Ada Project creates a dynamic library and a set of Java source files that invoke code in that library.

In order to do that, the user must select the Ada specification source files for which Java source files that will be generated. These specification files are sometimes referred to as “Interface Files.” Any methods needed to make use of the generated library should be available in interface files.

Not all Ada language features are supported by the underlying AJIS tools, so not all specification files may be selected as interface files. See the AJIS documentation for more information.

Interface file selection is available as an interactive project property under the GNATbench Project Properties category. At least one interface file must be selected for an AJIS Ada Project to be built.

The generated Java code includes several Java packages. The user may specify a new base package that contains the generated packages. If such a package is not specified, the packages will be generated and rooted in the default package.

For example, if the base package is com.example, and an Ada package named devices is an interface file, then the generated Java would be in package com.example.devices.

Java base package selection is available as an interactive project property under the GNATbench Project Properties category.

11.3.3. Using the Library and Java Sources

A Java project that uses the library must be configured to use the generated sources as well. This Java project is called the “client” project.

The directory containing the generated Java sources must be on the classpath. In Eclipse, this is done by creating a new source folder that contains the generated Java code.

The generated Java sources depend on a Java library distributed with AJIS; it is named ajis.jar. The full path to this jar (not just the directory containing it) must also be found on the classpath. In Eclipse, this is done by adding the jar as an External Jar on the Java build path.

The directory containing the dynamic library must be on the java.library.path property. In Eclipse, the property is set when the source folder has a “Native library location” set.

When the client Java project is run, Eclipse will calculate the classpath and library path automatically.

Although these operations can be performed manually using the Java Build Path dialogs, all three can be performed automatically by the Ada AJIS Project tools. The feature is available both at the end of the New Project wizard and as a project property named Client Java Project under the GNATbench Project Properties category .

When a Java project is selected there, GNATbench attempts to modify the Java project’s Build Path settings such that it:

  • Contains a new source folder that is linked to the folder containing the generated Java

  • Specifies the directory containing the dynamic library as that source folder’s “Native library location”

  • References ajis.jar. It checks the system’s classpath to determine the jar’s location; if the classpath has not been set, it asks the user for the location.

However, there is no way to automatically undo the above configuration steps. If desired, the user must invoke the Java Build Path dialogs to either undo the settings or change them to use a different project. The automatic configuration will fail if a previous automatic configuration has not been undone.

11.4. Manual Configuration of Java Build Path

11.4.1. Setup

  1. Link the source folder

    Under the Java Project Properties, select “Java Build Path” and then the “Source” tab.

    1. Click “Link Source” and navigate to the generated Java directory in the Ada project.

    2. Expand the generated directory and select the Native library location. Edit it and select the directory containing your native library (usually the “lib” directory of the generated Ada directory).

../../_images/java_source_path.png
  1. Include the ajis.jar library on the build path.

    Switch to the “Libraries” tab and click “Add External JARs…”, then navigate to the ajis.jar file in the AJIS installation directory.

../../_images/java_external_lib.png

Hint

You might have put it on the system classpath per the AJIS installation instructions.

11.4.2. Teardown

  1. Remove the source folder from the build path.

    Under the Java Project Properties, select “Java Build Path” and then the “Source” tab.

    Remove the generated Java source directory from the build path by selecting it and using the button on the right.

  2. Remove the ajis.jar library from the build path.

    Switch to the “Libraries” tab, select ajis.jar, and click the “Remove” button. Click “OK” to close the “Java Build Path” dialog and confirm the changes.

  3. Delete the linked source folder from the client Java project.

11.5. Usage Notes

11.5.1. Versions

The installed version of the AJIS tools should be gnat-ajis-7.1.0w-20120611-* or later (although some earlier versions may work).

AJIS must be used with a compiler from the same date.

Install the “make” utility if it is not already installed. Windows users can download the GNU version via the “Miscellaneous/Utils” section of the “Downloads” page on GNAT Tracker. The file to download is named “gnumake-3.79.1-pentium-mingw32msv.exe” or something similar (i.e., the version number could be different). Once downloaded, rename the file to “make.exe” and put it somewhere on your path.

11.5.2. Modifying the Ada Sources

The user may change the Ada source files. If changes are made to any of the Ada source files which are selected as interface files, the generated Java sources will be automatically changed by the next build of the Ada project.

This allows the user to make changes as necessary.

11.5.3. Exporting the Java Project

The Java project may be deployed outside of Eclipse using the normal JDT tools. Both ajis.jar and the generated library will still be required to run the project, but the ajis.jar library can be bundled in with the Java sources. These steps describe how to ensure that ajis.jar is included in the application jar.

  1. Export the Java Project as a Runnable Jar.

../../_images/export_runnable.png
  1. Select a launch configuration and export destination.

  2. For library handling, select either “extract” or “package” to bundle in the required jar files.

../../_images/jar_export_both.png

The exported jar can be run from the command line; it still requires the path to the native library, which is set with the property java.library.path. For example, given that /home/jrogers/runtime-GNATbench/Hello_World/binding/generated_ada/lib/ contains the dynamic library, the command would be:

$ java -Djava.library.path=/home/jrogers/runtime-GNATbench/Hello_World/binding/generated_ada/lib/ -jar example.jar

Note

Do not directly set the java.library.path property when running the application in Eclipse; this is done by Java tools. Instead, use the Java Build Path page of the Project Properties or specify a Target Project from the Ada project properties.

11.5.4. Optional additional arguments to ada2java

ada2java is the executable that generates the source files used to interface between Ada and Java. It has a number of options, some of which may be useful to clients.

These Ada projects are makefile-driven, so the makefile calls ada2java. If the user would like to pass additional options to ada2java, the macro named CUSTOM_OPTIONS in “config.mk” may be changed. “config.mk” is imported by the Makefile and is not modified by GNATbench. $(CUSTOM_OPTIONS) is appended to the end of the call to ada2java. It defaults to the empty string, but it may contain some options allowed by ada2java. It should not contain interface files or include options that conflict with options already specified in the project’s Makefile.

Several options relating to aliasing and memory may be of interest in some cases.

11.5.5. Cleaning

Note that cleaning the Ada project removes the compilation objects (*.ali and *.o files) but also the generated Java files.

11.5.6. Limitations

At present, only one AJIS project can be used per Java project.

11.5.6.1. Operating Systems

Linux and Unix-like operating systems are supported. Windows users must install Cygwin for equivalent functionality.

11.5.6.2. The .gpr file

The gpr file should not be manually modified except to change the Source_Dirs, which can be done using the GNATbench toolbar and menu.

The gpr file may not have additional dependencies beyond the defaults (AJIS and JNI). Rather than reference another project, simply add its sources to the Source_Dirs attribute.

11.5.6.3. Scenarios

The project contains several scenario variables by default. No new scenarios may be added.

Build may be set to either Production or Debug.

External_Build should be set to true. If it is set to false the AJIS and JNI libraries are rebuilt. In most cases this is unnecessary.

OS is referenced when AJIS and JNI are built, and does not affect the library built by this project.

LIBRARY_KIND is a scenario variable referenced by AJIS and JNI. By default its value is ignored and static libraries are produced and included in the encapsulated dynamic library created by this project.

If the user does not wish to create an encapsulated dynamic library,

  1. Unset the macro variable FORCE_ENCAPSULATED in the Makefile.

  2. Set External_Build to false. AJIS and JNI will be built as static libraries.

  3. Clean and build (or rebuild). The AJIS and JNI libraries will be rebuilt as dynamic libraries. The project’s library will be dynamic but not encapsulated.

The GNATbench integration features only support encapsulated dynamic libraries by default.

11.5.6.4. Interface files

The AJIS tools do not support all Ada language features. This restricts which files may be used as interface files. See the AJIS documentation for more information.

11.5.6.5. Supported builders

This makefile must use gprbuild. It does not respect the setting that uses gnatmake instead. This is because other libraries are needed to provide the Ada runtime, AJIS, and JNI. These libraries are included in the dynamic library using the encapsulated library functionality of gprbuild; gnatmake does not support this feature at the time of this writing.