Call Java code from Ballerina

Ballerina offers a straightforward way to call existing Java code from Ballerina. Although Ballerina is not designed to be a JVM language, the current implementation, which targets the JVM, aka jBallerina, provides Java interoperability by adhering to the Ballerina language semantics.

Write Ballerina bindings

The bindgen is a CLI tool, which eases the process of generating Ballerina bindings for given Java APIs. This guide shows you how to use it. For more details on how the bindgen tool works, see the Bindgen Tool.

The Package layout explains how to package Java libraries (JAR files) with Ballerina programs to produce self-contained executable programs. When you generate bindings for a Java library using the bindgen tool, this part is already handled.

The Ballerina FFI explains how to write these bindings manually. It is also a useful section for those who want to understand the inner workings of calling Java from Ballerina and for those who want to customize the bindings generated by the bindgen tool.

Use the SnakeYAML Java library in Ballerina

SnakeYAML is a YAML parser for Java. In this section, you will learn how to use this library to parse a YAML document using Ballerina.

You will develop a Ballerina program that parses the given YAML file and writes the content to the standard output.

Let’s get started.

Step 1 - write the Java code

It is recommended to always start by writing the Java code. It gives you an idea of the set of Java classes required to implement your logic. Then, you can use the bindgen tool to generate Ballerina bindings for those classes.

The Java code below uses the SnakeYAML API to parse the given YAML file.

Note: This is not the most idiomatic way of writing the Java code for this scenario.

import org.yaml.snakeyaml.Yaml;

import java.io.FileInputStream;
import java.io.InputStream;
import java.util.Map;

public class SnakeYamlSample {

    public static void main(String... a) {
	    String filename = a[0];
        try (InputStream inputStream = new FileInputStream(filename)) {
            Yaml yaml = new Yaml();
            Map<String, Object> obj = yaml.load(inputStream);
            System.out.println(obj);
        } catch (Exception e) {
            System.err.println("The file '" + filename + "' cannot be loaded. Reason: " + e.getMessage());;
        }
    }
}

Here, you have used four Java classes.

  • org.yaml.snakeyaml.Yaml
  • java.io.FileInputStream
  • java.io.InputStream
  • java.util.Map

You can see them in the imported class list.

Tip: You are encouraged to generate Ballerina bindings for these four classes as a start.

Now, you will create an environment for your Ballerina program.

Step 2 - set up the Ballerina package

Info: This section assumes that you have already read Package layout.

Create a Ballerina package

> bal new yaml_package
Created new Ballerina package 'yaml_package' at yaml_package.

Verify the package

> cd yaml_package
> bal build
Compiling source
	sameera/yaml_package:0.1.0

Generating executable
	target/bin/yaml_package.jar
> bal run target/bin/yaml_package.jar
Hello World!

Great! You are all set for the next step.

Add a sample YAML file

Copy the content below to a file named invoice.yml in the package root directory.

invoice: 34843
date   : 2001-01-23
bill-to: &id001
   given  : Chris
   family : Dumars
   address:
       lines: |
           458 Walkman Dr.
           Suite #292
       city    : Royal Oak
       state   : MI
       postal  : 48046
ship-to: *id001
product:
   - sku         : BL394D
     quantity    : 4
     description : Basketball
     price       : 450.00
   - sku         : BL4438H
     quantity    :
     description : Super Hoop
     price       : 2392.00
tax  : 251.42
total: 4443.52
comments: >
   Late afternoon is best.
   Backup contact is Nancy
   Billsmer @ 338-4338.\

Step 3 - generate the Ballerina bindings

In this step, you will use the bindgen tool to generate Ballerina bindings for the four classes that were listed in Step 1. If you want more information about the tool, see the Bindgen Tool.

> bal bindgen -mvn org.yaml:snakeyaml:1.25 org.yaml.snakeyaml.Yaml java.io.FileInputStream java.io.InputStream java.util.Map

Ballerina package detected at: /Users/sameera/yaml_package

Resolving maven dependencies...
snakeyaml-1.25.jar 100% [===============================================] 297/297 KB (0:00:01 / 0:00:00)

Updated the `Ballerina.toml` file with the new platform libraries.

The following JARs were added to the classpath:
	snakeyaml-1.25.jar

Generating bindings for:
	java.util.Map
	java.io.FileInputStream
	org.yaml.snakeyaml.Yaml
	java.io.InputStream

Generating dependency bindings for:
	org.yaml.snakeyaml.introspector.BeanAccess
	java.util.function.BiFunction
	org.yaml.snakeyaml.DumperOptions$FlowStyle
	...
	...
  • The -mvn option specifies the Maven dependency of the Java library required to generate bindings.
  • The argument list specifies the Java class names.

The bindgen tool generates bindings for:

  • the specified Java classes
  • the Java classes exposed in the public APIs of all the specified classes

Before you move on to the next step, verify the generated code.

> bal build
... 
...

Generating executable
	target/bin/yaml_package.jar

> bal run target/bin/yaml_package.jar
Hello World!

Step 4 - write the Ballerina code

Now, you’ll use the generated bindings and write the Ballerina code, which uses the SnakeYAML library. You can develop the Ballerina code corresponding to the Java code below step by step.

public class SnakeYamlSample {

    public static void main(String... a) {
        String filename = a[0];
        try (InputStream inputStream = new FileInputStream(filename)) {
            Yaml yaml = new Yaml();
            Map<String, Object> obj = yaml.load(inputStream);
            System.out.println(obj);
        } catch (Exception e) {
            System.err.println("The file '" + filename + "' cannot be loaded. Reason: " + e.getMessage());;
        }
    }
}

Create the FileInputStream

The goal here is to create a new java.io.FileInputStream instance from the filename. In Step 3, you generated bindings for the required Java classes. The following is the code snippet that does the job.

javaio:FileInputStream | javaio:FileNotFoundException fileInputStream = javaio:newFileInputStream3(filename);

Here, FileInputStream is the Ballerina class generated for the java.io.FileInputStream class.

  • Ballerina bindings for each Java package are mapped onto a separate Ballerina module by default. Therefore, you need to import them when using them inside other modules. Here, the java.io Ballerina module (mapping the corresponding Java package) is imported as javaio. However, if you wish to generate all the bindings inside a single directory, you can do so by using the [(-o|--output) <output-path>] command option.
  • You can find functions that start with newFileInputStream in the generated code. Each such function creates a new java.io.FileInputStream instance. Ballerina does not support function overloading. Therefore, the bindgen tool generates a separate Ballerina function for each overloaded method or constructor. Function names of the generated bindings will be improved in a future release.
  • All the public instance methods in the java.io.FileInputStream class are mapped to methods in the generated Ballerina class. You can refer the Bindgen Tool for more details on how other Java class members are mapped into Ballerina bindings.

Next, you’ll handle the error using a type guard.

if fileInputStream is javaio:FileNotFoundException {
	// The type of fileInputStream is FileNotFoundException within this block.
    io:println("The file '" + filename + "' cannot be loaded. Reason: " + fileInputStream.message());
} else {
	// The type of fileInputStream is FileInputStream within this block.
}

Create the SnakeYAML entry point

The org.yaml.snakeyaml.Yaml class is the entry point to the SnakeYAML API. The generated corresponding Ballerina class is Yaml. The newYaml1() function is mapped to the default constructor of the Java class. Import the org.yaml.snakeyaml Ballerina module as snakeyaml.

snakeyaml:Yaml yaml = snakeyaml:newYaml1();

Load the YAML document

You will be using the org.yaml.snakeyaml.Yaml.load(InputStream is) method to get a java.util.Map Java instance from the given java.io.InputStream. Since the Object Ballerina class (the mapping of java.lang.Object class) resides inside the java.lang module, import it as javalang.

Note: Even though you didn’t explicitly generate the java.lang.Object class, it has been generated automatically since it is exposed through the public APIs of generated classes.

javalang:Object mapObj = yaml.load(fileInputStream);

The org.yaml.snakeyaml.Yaml.load(InputStream is) is a generic method. The bindgen tool does not support Java generics at the moment. That is why the corresponding Ballerina method returns a java.lang.Object.

You can print the content of the java.util.Map instance in the standard out as follows.

io:println(mapObj);

Complete the code

Below is the complete code. You can replace the contents in main.bal with the following code.

import ballerina/io;
import yaml_package.java.io as javaio;
import yaml_package.java.lang as javalang;
import yaml_package.org.yaml.snakeyaml as snakeyaml;
 
public function main(string... args) returns error? {
   string filename = args[0];
   javaio:FileInputStream | javaio:FileNotFoundException fileInputStream = javaio:newFileInputStream3(filename);
   if fileInputStream is javaio:FileNotFoundException {
       io:println("The file '" + filename + "' cannot be loaded. Reason: " + fileInputStream.message());
   } else {
       snakeyaml:Yaml yaml = snakeyaml:newYaml1();
       javalang:Object mapObj = yaml.load(fileInputStream);
       io:println(mapObj);
   }
}

Build and run this code.

> bal build
Compiling source
	sameera/yaml_package:0.1.0

Generating executable
	target/bin/yaml_package.jar

Now, you need to pass the YAML file name as the first argument.

> bal run target/bin/yaml_package.jar invoice.yml
{invoice=34843, date=Mon Jan 22 16:00:00 PST 2001, bill-to={given=Chris, family=Dumars, address={lines=458 Walkman Dr.
Suite #292
, city=Royal Oak, state=MI, postal=48046}}, ship-to={given=Chris, family=Dumars, address={lines=458 Walkman Dr.
Suite #292
, city=Royal Oak, state=MI, postal=48046}}, product=[{sku=BL394D, quantity=4, description=Basketball, price=450.0}, {sku=BL4438H, quantity=null, description=Super Hoop, price=2392.0}], tax=251.42, total=4443.52, comments=Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.\}

In this section, how to use the bindgen tool to generate Ballerina bindings for Java classes and how to use them was explained.

For more information on various aspects related to Java interoperability in Ballerina, see Java interoperability.