Guide: Using Ceylon’s Null‑Safe Types When Calling Java Libraries

Desired outcome

You have a Ceylon module that can call a Java library, treat any values that may be null as explicit nullable types, and guarantee that resources such as streams or connections are closed reliably. After following this guide you will be able to compile the module without null‑related warnings and run it without encountering a NullPointerException caused by the Java side.

Prerequisites

• Java Development Kit (JDK) version 8 or newer installed and java -version returns a valid version.
• Ceylon SDK version 1.3.3 (or any 1.x release) installed; the ceylon command is available on your PATH.
• A Java library you wish to use, provided as a JAR file or Maven artifact. For the example we assume a library named example-java-lib version 1.0.0 that provides a class com.example.JavaService with a method String getData() that may return null.
• Basic familiarity with editing text files and running commands in a terminal.

Procedure

1. Create a new Ceylon project

   Choose a directory for your work, e.g., ~/ceylon-java-interop. Inside that directory run the Ceylon project initializer:

   ceylon new com.example.myproject

   This creates a module descriptor module.ceylon and a source layout src/com/example/myproject. Adjust the module name if you prefer a different identifier.

2. Add the Java library as a dependency

   Edit module.ceylon to declare a dependency on the Java JAR. If the library is available in a Maven‑compatible repository you can use the import maven directive; otherwise place the JAR in a lib folder and reference it with a import java clause.

   // module.ceylon
   module com.example.myproject "1.0.0" {
       import java.base "8";
       import maven "example-java-lib" "1.0.0";
       // if using a local JAR:
       // import java "lib/example-java-lib.jar";
   }

   Save the file.

3. Write Ceylon code that calls the Java method safely

   Create a source file src/com/example/myproject/run.ceylon with the following content. The key points are:

   • The return type of getData() is declared as String? (nullable) to reflect that the Java method may produce null.
   • We use a do block to manage a java.io.FileWriter resource, ensuring it is closed even if an error occurs.
   • Pattern matching (exists) checks for a non‑null value before using it.

   // run.ceylon
   import com.example.JavaService
   import java.io { FileWriter }
   
   void run() {
       // Create an instance of the Java class
       JavaService service = JavaService();
       
       // Call the Java method; the Ceylon compiler treats the result as nullable
       String? raw = service.getData();
       
       // Safely handle the possible null
       if (exists raw) {
           // Use the non‑null value
           println("Received data: " + raw);
           
           // Example resource management with a 'do' block
           do (FileWriter fw = FileWriter("output.txt")) {
               fw.write(raw);
               fw.write("\n");
           } // fw is automatically closed here
       } else {
           println("Java service returned null; nothing to write.");
       }
   }
   
   // Module entry point
   shared void hello() {
       run();
   }
   

   Save the file.

4. Compile the module

   From the project root run:

   ceylon compile com.example.myproject

   If the Java library is not on the classpath, the compiler will emit an error about missing types. Ensure the JAR is reachable via the Maven repository or the lib folder as described in step 2.

5. Run the compiled module

   Execute:

   ceylon run com.example.myproject

   Observe the console output. If the Java method returns a non‑null string, you should see the message "Received data: …" and the file output.txt created with that content. If it returns null, you will see the "Java service returned null" message and no file will be created.

Expected checks

• Compilation finishes with exit code 0 and no warnings about possible null dereferences.
• At runtime, the program does not throw a NullPointerException originating from the Java call.
• When the Java method returns a non‑null value, the file output.txt contains exactly that value followed by a newline.
• When the Java method returns null, no file is created and the program terminates normally.

Recovery options

If you need to revert changes:

1. Delete the generated output.txt file (if it exists).
2. Remove the project directory ~/ceylon-java-interop to erase all source, compiled binaries, and dependency caches.
3. Optionally, uninstall the Ceylon SDK if you no longer need it, though this is not required for simple cleanup.

These steps return the workspace to its pre‑guide state.