[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ada2java
to Generate Java Classes
The ada2java
tool takes one or more Ada package specs
and produces as output a Java "binding" to these packages, implemented
through JNI.
The binding consists of a set of Java classes, with methods that access
the Ada package's visible entities.
More specifically, ada2java
generates two sets of source files
as output:
You will need to compile the Java files to bytecodes for execution on a JVM, and you will need to compile the Ada files to native code in a dynamic library.
This chapter explains how to use the ada2java
tool and
describes the mapping from package spec contents to Java classes.
2.1 Using the Tool 2.2 Compiling and Running the Generated Code 2.3 Pragma Annotate and ada2java
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ada2java
tool is invoked with at least one input file,
and any number of switches, in any order:
$ ada2java {switch | input-file} input-file {switch | input-file} |
Each input-file must be the name of a source file for an Ada package spec (including the extension).
The following switch values are allowed:
ada2java
.
The current directory will be used if this switch is not supplied.
The generated packages will need to be compiled into a dynamic library.
ada2java
. This can specify compiler switches, source
directories, etc.
ProjectFile must be a "flat" project
(sources from "with"ed projects are not yet supported).
gprbuild
to build the dynamic library:
$ gprbuild -p -P LibraryName.gpr |
which will generate a `lib/' subdirectory that contains the file
`libLibraryName.so' (Solaris, Linux) or `LibraryName.dll'
(Windows). This library will be loaded automatically whenever one of
the Java classes produced by ada2java
is loaded; there is
no need for the user to explicitly include an invocation of
System.loadLibrary
.
-link-method=register_natives
.
Register_Native
JNI function
(register_natives mode). Note that if the code is not in a shared library
but compiled with a main native subprogram, then only register_natives mode
will work.
Example:
$ ada2java -c mydir pack1.ads -b foo.bar |
This results in the placement of the Java binding classes in the relative directory `mydir/foo/bar/'.
Note that the actual directory containing the generated Java classes will need
to be on the CLASSPATH
environment variable in order to successfully
run a Java application that uses the binding.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
2.2.1 Issues with the Ada Generated Code 2.2.2 Compiling as an Ada Shared Library 2.2.3 Compiling as an Ada Main Subprogram 2.2.4 Compiling the Java Generated Classes
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Two sets of Ada units need to be compiled -- the original
packages and the generated "glue" code. The Ada
glue depends on the ajis
project installed in the `lib/gnat'
directory of the GNAT-AJIS installation.
It is highly recommended that you use the project generation switches `-L' (for a shared library) or `-M' (for an Ada main subprogram). However, even if these switches handle most cases, you may need to write your own build procedures to address more advanced usage. In such a situation please note that some compiler options may have an impact on the ajis library and thus need to be taken into consideration:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The most common architecture of an Ada / Java program, and a Java / Native program in general, is to compile the native code into a shared library, and then load that shared library at run time. In this case, the main entry point is a Java main method, written by the developer.
In order to implement this scheme, you will need to create a SAL (Stand-Alone Library) project containing the sources of the input packages plus the "glue", and use it to compile the library.
A simple standalone library project is generated if you use the `-L' switch. The generated project can then be compiled with gprbuild, for example:
$ ada2java my_package.ads -o ada -c java -P my_project.gpr -b base -L my_lib $ gprbuild -p -P ada/my_lib.gpr |
Note that the native library will then be loaded automatically by the generated Java glue code.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If compiling the native code into a shared library is not practical, an alternative is to create an Ada main subprogram embedding a Java Virtual Machine.
ada2java
provides an easy way to generate a project and an Ada main
subprogram, through the `-M' switch.
This switch takes the name of the
main as parameter and will generate an Ada main that will automatically create
a Java virtual machine, and then call a Java method defined as follows:
package <base_package>; public class <main_name> { public static void main (String [] args) { } } |
This class (and thus the method implementation) has to be provided by the developer. If it is not present, the main subprogram will fail with an error at run time.
The generated main will look into the CLASSPATH environment variable to find the Java classes when initializing the Java virtual machine. So for example, if that you provide the following class:
package java_code; import java_code.Test.Test_Package; public class Main { public static void main () { Test_Package.Call_Something (); } } |
using the following Ada API:
package Test is procedure Call_Something; end Test; |
with the appropriate `test.gpr' project referencing the Test
code,
you will be able to compile and run the code as follows:
$ ada2java test.ads -P test -b java_code -o ada -c java -M Main $ gnatmake -P ada/main.gpr $ CLASSPATH=`pwd`:`pwd`/java:$CLASSPATH $ export CLASSPATH $ javac java_code/Main.java $ ada/obj/main |
You can explicitly specify the name of the Java main class to use, through the `--main-class' switch, e.g.:
$ ada2java test.ads -P test -b java_code -o ada -c java \ > -M Main --main-class=some.main.My_Main |
In this case, the Ada main will look for a main subprogram in
some.main.My_Main
, instead of java_code.Main
.
Note that you may need to define the LPATH
, LD_LIBRARY_PATH
or
PATH
environment variables so that the code can be compiled against
`jvm.lib' or `libjvm.a', and then run with `jvm.dll' or
`libjvm.so'.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Java application needs to load the library before any of the
Ada subprograms are invoked.
If you did not supply the `-L' switch to ada2java
,
then you will need to do this explicitly; conventional style is to
invoke System.loadLibrary ("
library-name")
in a static initializer in the main Java class.
This step is automated if you use the `-L' switch, as described above.
Before running the Java code, you need to ensure that the
CLASSPATH
environment variable contains both the directory
of the generated Java code, and the JAR for the GNAT-AJIS-related
predefined classes. The latter archive exists as
$GNATAJIS_INSTALL_DIR/lib/ajis.jar
where
GNATAJIS_INSTALL_DIR
is the root directory for the GNAT-AJIS
installation.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ada2java
Pragma Annotate
(see GNAT Reference Manual)
has several uses in conjunction with the GNAT-AJIS tools,
each with the form:
pragma Annotate (AJIS, AJIS_annotation_identifier {, argument}); |
GNAT-AJIS annotation names are defined in the package AJIS.Annotations
,
which is a part of the ajis.gpr
project installed with GNAT-AJIS. You
need to have visibility on this package using a with
and possibly a
use
clause before being able to use these pragmas.
The following GNAT-AJIS annotation pragmas are supported:
Annotation_Renaming
-- 4.1 Dealing with Name Clashes
Assume_Escaped
--
4.2.6 Restrictions on Proxy-Owned Objects Passed to Subprograms
Attached
-- 4.8 Managing Attachment to Java Proxies
Monitor
-- 4.4 Thread Safety
Rename
-- 4.1 Dealing with Name Clashes
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |