Ballerina offers a straightforward way to call the 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.
Ballerina bindings to Java code
You can write Ballerina code (Ballerina bindings) that lets you call the corresponding Java API as illustrated in the diagram below.
The Ballerina FFI explains how to write the Ballerina bindings manually. Learning to write them manually helps you to understand the inner workings of calling Java from Ballerina and how to customize the bindings generated by the Bindgen tool.
The Bindgen tool
Alternatively, you can use the Bindgen tool to generate these bindings automatically while eliminating the need for understanding the Ballerina FFI layer. It is a CLI tool that eases the process of generating Ballerina bindings for given Java APIs. For more details on how the Bindgen tool works, see The Bindgen tool. It also explains how to customize the bindings generated by the Bindgen tool.
Write Ballerina bindings
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.
Use the SnakeYAML Java library in Ballerina
The below sections explain how to use the Bindgen tool to generate Ballerina bindings for Java classes and how to use them.
SnakeYAML is a YAML parser for Java. This guide describes how to use this library to parse a YAML document using the Bindgen tool. You develop a Ballerina program that parses the given YAML file and writes the content to the standard output.
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.
Here, you have used four Java classes:
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 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
Verify the package
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.
Step 3 - Generate the Ballerina bindings
-mvnoption 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.
Step 4 - Write the Ballerina code
Now, you will 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.
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.
FileInputStream is the Ballerina class generated for the
- 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.ioBallerina 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
newFileInputStreamin the generated code. Each such function creates a new
java.io.FileInputStreaminstance. 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.FileInputStreamclass are mapped to methods in the generated Ballerina class. For more details on how other Java class members are mapped into Ballerina bindings, see Bindgen tool.
Next, you’ll handle the
error using a type guard.
Create the SnakeYAML entry point
org.yaml.snakeyaml.Yaml class is the entry point to the SnakeYAML API. The generated corresponding Ballerina class is
newYaml1() function is mapped to the default constructor of the Java class. Import the
org.yaml.snakeyaml Ballerina module as
Load the YAML document
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
Note: Even though you didn't explicitly generate the
java.lang.Objectclass, it has been generated automatically since it is exposed through the public APIs of generated classes.
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
Print the returned map instance
You can print the content of the
java.util.Map instance in the standard out as follows.
Complete the code
Below is the complete code. You can replace the contents in
main.bal with the following code.
Build and run this code.
Now, you need to pass the YAML file name as the first argument.