The ABS Foreign Language Interface

It is possible to connect ABS code to code written in other (foreign) languages. Currently only Java is supported. The connection is done by annotating ABS classes with the [Foreign] annotation, these classes must then be implemented in the foreign language.

The ABS Side

To declare a class as a foreign class one just have to annotate it with the [Foreign] annotation, which is defined in the ABS.FLI module. It is also necessary to define an interface which is implemented by the foreign class. Finally, the class must not have any class parameters.

Example

module Test;
import * from ABS.FLI;

interface Hello {
   String hello(String msg);
}

[Foreign]
class HelloImpl implements Hello {
   String hello(String msg) { 
      return "this is the default implementation, no foreign language was bound at runtime";
   }
}

{
   Hello h = new HelloImpl();
   h.hello("Hi there");
}

The foreign class must provide a default implementation for the implemented interface. This default implementation is used at runtime when no foreign implementation is used.

The Java Side

When the Java code for the ABS model has been generated, there will be an class Test.HelloImpl_c. This class has to be extended by a standard Java public class. The Java class must have a public parameterless constructor (or no explicit constructor). Now override the methods of the superclass which start with fli_ in the Java class.

Use the print methods defined in the FLIHelper class to print messages to the console. System.out.println will not be visible when the program is started from Eclipse.

Example

package myjavaflitest;

// included in the absfrontend.jar
import abs.backend.java.lib.types.ABSString;

// generated by the ABS Java backend
import Test.HelloImpl_c; 

public class FLITest extends HelloImpl_c {
   @Override
   public ABSString fli_hello(ABSString msg) {
      FLIHelper.println("I got "+msg.getString()+" from ABS");
      return ABSString.fromString("Hello ABS, this is Java");
   }
}

Connecting Java to ABS

After implementing the foreign class in Java, one must now connect the Java implementation to the corresponding ABS class. This is done at runtime when executing the generated Java code by using Java properties.

Using Conventions

The easiest way is to use convention. In that case the overriding Java class must be defined in a package that corresponds to the ABS module of the ABS class and must be named like the ABS class with a _fli suffix. For example, if an ABS class SomeClass is defined in a module My.Module then the Java class must be in a package My.Module and must be called SomeClass_fli. Methods start with "fli_" followed by the name of the ABS method.

Using System Properties

Instead of using the convention mechanism, one can use system properties. The properties have to be of the form:

abs.fli.class.ABSCLASSNAME=JAVACLASSNAME

where ABSCLASSNAME is the full qualified name of the ABS class, and JAVACLASSNAME is the full qualified name of the Java class.

To connect the above defined Java class one does the following:

java -cp .:absfrontend.jar -Dabs.fli.class.Test.HelloImpl=myjavaflitest.FLITest Test.Main

Using a separate Properties file

Another possibility is to specify the mapping of ABS classes to Java classes in a separate properties file. In that case the keys are just the full qualified ABS class names and the values are the full qualified Java class names. For example, a file abstojava.properties could look as follows:

Test.HelloImpl=myjavaflitest.FLITest 

Then use the system property abs.fli.properties to specify the name of the properties file:

java -cp .:absfrontend.jar -Dabs.fli.properties=abstojava.properties Test.Main

Note that the abstojava.properties file must be in the classpath, in that case in the current directory.

If there is a file named absfli.properties in the classpath, this file is taken automatically.

Debugging

It is possible to debug FLI by setting the system property -Dabs.fli.debug=true. For example:

java -cp .:absfrontend.jar -Dabs.fli.debug=true Test.Main