Headius Enterprises

Non-null variable declaration in Java using instanceof patterns

2025-12-04T00:00:00+00:00

Ever since JRuby 10 upgraded to Java 21, I’ve been re-learning Java with all the excellent language enhancements of the past decade. One of my favorites has to be the instanceof pattern matching features added in Java 16. Today I also realized I can use an instanceof pattern to null-check and assign a variable at the same time.

Using instanceof to null-check

When checking if a value in Java is instanceof some type, we can get a false result in two cases:

The value is an instance of a type not equal to or descended from the specified type.
The value is null.

This second property turns instanceof into a weird sort of null-check when applied to a variable or method that matches the instanceof type, since we know the only false result must be when it’s null.

String foo = null;
IO.println(foo instanceof String) // prints "false";

Of course this is longer than just saying foo == null but so what? It works!

Using instanceof patterns for inline null checking

The above example doesn’t really have any practical use, which is probably why you never see folks talking about it. But when combined with an instanceof pattern, we can do something more fun.

// getString() is a method that might return null
if (firstCondition) {
    // something
} else if (getString() instanceof String string) {
    IO.println("length: " + string.length());
} else {
    IO.println("string is null");
}

We’ve just done an inline null check and variable declaration in the middle of an if ... else chain! The string value must be non-null in the length branch, so we can safely call methods on it. And we know it must be null if we end up in the final else.

But why?

Because it’s there?

Without instanceof patterns, you’d need to move everything after the firstCondition branch into the following else, declare a temporary variable for the value of getString(), and then do a nested null-checking branch. This pattern (pun intended) allows us to skip all that.

Is it better?

I can’t say. It’s frequently shorter, and requires less indented code.

Does it convey the intent to null-check?

Not if you don’t know about this “hidden” behavior of instanceof. That’s your fault, though!

Won’t it be slower than a null equality check?

Actually, I had this question too, so I fired up the HotSpot disassembler.

class Blah {
    String foo = System.getProperty("foo");
    void main() {
        for (int i = 0; i < 100000000; i++) {
            bar();
        }
    }
    void bar() {
        if (foo instanceof String string) {
            IO.println(string);
        }
    }
}

$ java -XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly Blah.java
OpenJDK 64-Bit Server VM warning: PrintAssembly is enabled; turning on DebugNonSafepoints to gain additional output
...

It turns out, HotSpot’s just as smart as I am!

Here’s what the field access and instanceof turn into for this case:

  0x0000000117153544:   ldr		w11, [x1, #0xc]
  0x0000000117153548:   lsl		x10, x11, #3
                          ;*getfield foo {reexecute=0 rethrow=0 return_oop=0}
                          ; - Blah::bar@1 (line 9)
  0x000000011715354c:   cbnz	x10, #0x117153568
  0x0000000117153550:   ldp		x29, x30, [sp, #0x20]
  0x0000000117153554:   add		sp, sp, #0x30
  0x0000000117153558:   ldr		x8, [x28, #0x28]
                          ;   {poll_return}
  0x000000011715355c:   cmp		sp, x8
  0x0000000117153560:   b.hi	#0x117153580
  0x0000000117153564:   ret

Instead of doing a more complex inheritance check, the foo field (loaded by lsl into the x10 register from the Blah class in x11) is compared with zero (if that’s not the case, cbnz branches to the println branch at 0x117153568), and then the rest of the instructions just tidy up and return from the bar() method.

Basically, because the only possible branch in the code is a null check, the JVM’s JIT will compile it as such.

So with the performance question out of the way, only one remains:

What do you think?

Join the discussion on r/java!

Warbled Sidekiq: Zero-install Executable for JVM

2025-10-23T00:00:00+00:00

In my previous post, I showed how to use Warbler to package a simple image-processing tool as an executable jar. This post will demonstrate how to “warble” a larger project: the Sidekiq background job server!

Warbling Sidekiq

Sidekiq is one of the most successful packaged software projects in the Ruby world. It provides high-scale background job processing for Ruby applications atop Redis, and it has been commercially successful via enterprise features and support arrangements. It also happens to work great with JRuby and takes advantage of our excellent parallel threading capabilities.

Seems like a perfect use case for Warbler!

The Easy Way

The easiest way to set up a new warbler configuration for an existing gem (that you may or may not control) is to create your own wrapper project.

I’ve started that for Sidekiq here: sidekiq-warbler.

You’ll notice the project is quite slim, containing only a few files for Warbler to package a Sidekiq executable JAR:

Gemfile and gemspec to specify dependencies. Note that this is not actually pushed as a gem, but Warbler currently auto-detects dependencies using these files.
config/warble.rb to specify the sidekiq executable as the “main” and “sidekiq” as the filename for the JAR. I’ve removed unused configuration options from the generated warble.rb.
Rakefile to load in rake tasks for warbler.
README.md with basic usage information.

Given this, the process is simple:

git clone https://github.com/headius/sidekiq-warbler.git
cd sidekiq-warbler
bundle
bundle exec rake jar

Let’s see it in action, using the “plain old Ruby” example from Sidekiq itself:

sidekiq-warbler $ bundle
Fetching gem metadata from https://rubygems.org/............
Resolving dependencies...
Bundle complete! 2 Gemfile dependencies, 15 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
sidekiq-warbler $ bundle exec rake jar
rm -f sidekiq.jar
Creating sidekiq.jar
sidekiq-warbler $ java -jar sidekiq.jar -r ../sidekiq/examples/por.rb


               m,
               `$b
          .ss,  $$:         .,d$
          `$$P,d$P'    .,md$P"'
           ,$$$$$b/md$$$P^'
         .d$$$$$$/$$$P'
         $$^' `"/$$$'       ____  _     _      _    _
         $:    ',$$:       / ___|(_) __| | ___| | _(_) __ _
         `b     :$$        \___ \| |/ _` |/ _ \ |/ / |/ _` |
                $$:         ___) | | (_| |  __/   <| | (_| |
                $$         |____/|_|\__,_|\___|_|\_\_|\__, |
              .d$$                                       |_|


INFO  2025-10-23T15:37:27.684Z pid=85096 tid=1ryk: Running in jruby 10.0.2.0 (3.4.2) 2025-08-07 cba6031bd0 OpenJDK 64-Bit Server VM 21.0.8+9-LTS on 21.0.8+9-LTS +indy +jit [arm64-darwin]
INFO  2025-10-23T15:37:27.684Z pid=85096 tid=1ryk: See LICENSE and the LGPL-3.0 for licensing details.
INFO  2025-10-23T15:37:27.684Z pid=85096 tid=1ryk: Upgrade to Sidekiq Pro for more features and support: https://sidekiq.org
INFO  2025-10-23T15:37:27.686Z pid=85096 tid=1ryk: Sidekiq 8.0.8 connecting to Redis with options {size: 10, pool_name: "internal", url: nil}
INFO  2025-10-23T15:37:27.707Z pid=85096 tid=1ryk: Sidekiq 8.0.8 connecting to Redis with options {size: 5, pool_name: "default", url: nil}
INFO  2025-10-23T15:37:27.710Z pid=85096 tid=1ryk: Starting processing, hit Ctrl-C to stop

It’s that easy!

Adding Official Warbler Support to Sidekiq

In cases where you own or control a given gem, you can also add support for Warbler directly to the project. I’ve done that on a branch of Sidekiq here: https://github.com/headius/sidekiq/tree/warbled

You’ll notice a few differences in the “official support” config/warble.rb:

# Hack to disable the "war" trait in Warbler
class Warbler::Traits::War
  def self.detect? = false
end
class Warbler::Traits::Rack
  def self.detect? = false
end

# Warbler web application assembly configuration file
Warbler::Config.new do |config|
  config.executable = "bin/sidekiq"
end

The “hack” here disables Warbler’s automatic detection of web applications, so that we can just produce a plain executable JAR file instead of a web application WAR file. I’ve filed an issue with Warbler to make this easier in the future: https://github.com/jruby/warbler/issues/587
The JAR file name is detected from the gem name (“sidekiq”) and we’re using a “main” script from the same gem, so the config is a bit simpler.

I’ve also tweaked Sidekiq’s Gemfile to pin Rails at 7.1 (we’re in the process of shipping 7.2 and 8+ support for JRuby) and disable some native CRuby extensions we don’t support (debug, vernier, ruby-prof).

The result is basically the same:

sidekiq $ bundle exec rake jar
rm -f sidekiq.jar
Creating sidekiq.jar
sidekiq $ java -jar sidekiq.jar
INFO  2025-10-23T16:01:50.836Z pid=86190 tid=1xca: ==================================================================
INFO  2025-10-23T16:01:50.837Z pid=86190 tid=1xca:   Please point Sidekiq to a Rails application or a Ruby file
INFO  2025-10-23T16:01:50.837Z pid=86190 tid=1xca:   to load your job classes with -r [DIR|FILE].
INFO  2025-10-23T16:01:50.837Z pid=86190 tid=1xca: ==================================================================
INFO  2025-10-23T16:01:50.837Z pid=86190 tid=1xca: sidekiq [options]
    -c, --concurrency INT            processor threads to use
    -e, --environment ENV            Application environment
    -g, --tag TAG                    Process tag for procline
    -q, --queue QUEUE[,WEIGHT]       Queues to process with optional weights
    -r, --require [PATH|DIR]         Location of Rails application with jobs or file to require
    -t, --timeout NUM                Shutdown timeout
    -v, --verbose                    Print more verbose output
    -C, --config PATH                path to YAML config file
    -V, --version                    Print version and exit
    -h, --help                       Show help

IPv4 vs IPv6

If you’re on a platform that supports IPv6 you may notice that JRuby (the JDK, really) will try to use IPv6 addresses and connections by default. On my system, the Redis server only bound itself to IPv4, preventing Sidekiq from being able to make that connection.

The magic flag to force the JDK to use IPv4 is -Djava.net.preferIPv4Stack=true. You can pass that directly to the java command, or use environment variable JDK_JAVA_OPTIONS as I do here:

sidekiq $ export JDK_JAVA_OPTIONS="-Djava.net.preferIPv4Stack=true"
sidekiq $ java -jar sidekiq.jar -r ./examples/por.rb
NOTE: Picked up JDK_JAVA_OPTIONS: -Djava.net.preferIPv4Stack=true


               m,
               `$b
          .ss,  $$:         .,d$
          `$$P,d$P'    .,md$P"'
           ,$$$$$b/md$$$P^'
         .d$$$$$$/$$$P'
         $$^' `"/$$$'       ____  _     _      _    _
         $:    ',$$:       / ___|(_) __| | ___| | _(_) __ _
         `b     :$$        \___ \| |/ _` |/ _ \ |/ / |/ _` |
                $$:         ___) | | (_| |  __/   <| | (_| |
                $$         |____/|_|\__,_|\___|_|\_\_|\__, |
              .d$$                                       |_|

...

Why Warble?

We’ve seen that it’s pretty easy to turn a larger app like Sidekiq into an executable JAR file, but what’s the real advantage here?

Some of that comes from running on JRuby, which you can get with or without Warbler (Sidekiq works well and is regularly tested on JRuby):

Better parallel scaling across cores, for both Sidekiq itself and any garbage produced along the way (JVM’s GCs are highly concurrent and super scalable).
Better tooling based on JVM profiling and monitoring features.

And the other features are specific to a “warbled” executable JAR file:

“Zero-install” other than needing a JDK on the host system.
No native libraries, no build tools, no additional dependencies.
Enterprise-friendly: they don’t have to know or care about Ruby to deploy your product.
IP-safe: Warbler can precompile Ruby code into JRuby’s bytecode format, making it very difficult to steal.

Basically, if you want to ship Ruby tools and applications for modern organizations, JRuby and Warbler are a great way to get there!

Your Turn

Obviously there’s enormous potential for Ruby tools and applications to be packaged and shipped using Warbler. If you’re interested in making this happen for you project, here’s the steps to take:

Make sure it runs on JRuby! Pure-Ruby libraries should “just work”, but more complicated apps may require alternative gems.
Decide what your command-line “main” should look like when run as an executable jar. This may simply be your existing bin script.
Follow docs on the Warbler project for configuring and warbling your app.
Profit! Enterprises love simple executable tools!

JRuby is clearly the future of Ruby in the enterprise, and Warbler is a huge part of that. I am always here to help you build and package Ruby applications with JRuby and Warbler. Follow the links below and let’s set up a chat or call to help you bring your apps to a wider world!

Join the discussion on r/ruby!

Packaging Ruby Apps with Warbler: Executable JAR Files

2025-10-21T00:00:00+00:00

Warbler is the JRuby ecosystem’s tool for packaging up Ruby apps with all dependencies in a single deployable file. We’ve just released an update, so let’s explore how to use Warbler to create all-in-one packaged Ruby apps!

Application Packaging for the Java World

The Java world has been creating distributable, “run anywhere” packages since Java was first released in 1996. Java source code is compiled to bytecode, stored in .class files and then archived together with metadata in JAR files (Java ARchive) that can be run as command-line executable files or as deployable web applications. A JAR file is just a zip file, laid out in a specific way to contain the code and resources your application or library needs, and essentially all libraries for the JVM get distributed as JAR files.

The JRuby distribution includes lib/jruby.jar, for example, which is where all of the internal JRuby Java and Ruby code is located:

jruby $ jruby -v
jruby 10.0.3.0-SNAPSHOT (3.4.5) 2025-10-10 0ea455e57a OpenJDK 64-Bit Server VM 21.0.8+9-LTS on 21.0.8+9-LTS +indy +jit [arm64-darwin]
jruby $ ls -l lib/jruby.jar
-rw-r--r--  1 headius  staff  16928929 Oct 14 12:59 lib/jruby.jar
jruby $ java -jar lib/jruby.jar -v
jruby 10.0.3.0-SNAPSHOT (3.4.5) 2025-10-10 0ea455e57a OpenJDK 64-Bit Server VM 21.0.8+9-LTS on 21.0.8+9-LTS +indy +jit [arm64-darwin]

When distributed as a deployable web application, the filename typically ends with “.war” (Web ARchive) and contains a combination of code, configuration, and other JAR files (dependencies of the app). Enterprise applications are packaged in “.ear” files (Enterprise ARchive) which will in turn contain jars and wars and additional configuration for enterprise Java servers. At the end of the day, though, they’re all just zip files laid out in a particular way.

Write Once, Run Anywhere

This is all possible because of the Write Once, Run Anywhere (WORA) promise of JVM bytecode: if your application runs on the JVM, you can write, compile, and package it once and deploy it anywhere without recompiling.

Compare this to the way external dependencies are managed in Ruby:

Gem files provide installable packaging for Ruby libraries, but they must be unpacked into a specific path on the filesystem to be usable.
Libraries with native code require separate binary gems for each platform or must be built at install time and installed on the filesystem.
Ruby itself must be built for each platform you plan to run it on, or downloaded as a platform-specific binary.

Wouldn’t it be nice if we could package Ruby applications for distribution without these hassles, in a way that enterprises and security-conscious companies can handle? That’s where Warbler comes in!

Warbler: packaging tool for JRuby applications

Warbler is the JRuby tool of choice for packaging Ruby applications for distribution. Given a Ruby utility or application, Warbler can:

Package your Ruby utility along with gem and jar dependencies (including JRuby itself) as a single executable JAR file.
Package your Rails, Hanami, Sinatra or other web application as a deployable WAR file (again with all dependencies included).
Add a mini-server to your WAR file so it can be run directly at the command line.
Precompile all Ruby code to JRuby’s bytecode format, to obfuscate and protect your intellectual property.

Let’s try a simple example to get started.

Warbler in Practice

We’ll be packaging a demo utility called image_voodoo_demo for these examples, based on the image_voodoo image-manipulation gem.

ImageVoodoo is a Ruby wrapper around the JDK’s built-in image-processing APIs (inspired by the ImageMagick gem), allowing JRuby users to scale, crop, thumbnail, greyscale, and apply other transformations to images without installing external libraries. This demo takes the example script from ImageVoodoo and turns it into a command-line utility called voodoo.

Here’s basic use of the voodoo command:

$ gem install image_voodoo_demo
Successfully installed image_voodoo_demo-0.1.0
Parsing documentation for image_voodoo_demo-0.1.0
Done installing documentation for image_voodoo_demo after 0 seconds
1 gem installed
$ voodoo PXL_20250802_162259596.jpg
wrote demo files to /Users/headius/work/jruby/PXL_20250802_162259596/
$ ls -1 PXL_20250802_162259596
border.jpg
cropped_thumb.jpg
cropped.jpg
reduced.jpg
resized.jpg
resized.png
thumb.jpg

If you’ve already got Ruby or JRuby installed, this workflow is fine. But what if you want to distribute this utility to someone with no knowledge of the Ruby ecosystem? Let’s package image_voodoo_demo as an executable JAR file!

Executable JAR Files

Java’s JAR files can be marked as “executable” by including metadata that configures a “main” entry point. In the case of JRuby, the “main” points to org.jruby.main.Main, which bootstraps JRuby and runs your code. Warbler can generate a JAR file for your Ruby tool that includes this configuration and launches your Ruby tool directly.

The simplest way to do this is to run Warbler from within the source repo for your utility.

image_voodoo_demo $ ls -1
exe
Gemfile
Gemfile.lock
image_voodoo_demo.gemspec
lib
Rakefile
README.md

image_voodoo_demo has a pretty standard gem layout, with a gemspec and Gemfile to specify dependencies and gem configuration.

image_voodoo_demo $ cat exe/voodoo
#!/usr/bin/env ruby

require 'image_voodoo/demo'

filename = ARGV[0]

ImageVoodoo::Demo.output_demo_files(filename)

image_voodoo_demo $ tail image_voodoo_demo.gemspec
  spec.bindir = "exe"
  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
  spec.require_paths = ["lib"]

  # Uncomment to register a new dependency of your gem
  spec.add_dependency "image_voodoo", "0.9.3"

  # For more information and examples about making a new gem, check out our
  # guide at: https://bundler.io/guides/creating_gem.html
end

The voodoo command just loads the demo code and executes it against ARGV[0], and the gemspec includes exe/voodoo as its sole executable.

With this layout and configuration, using Warbler is simple!

image_voodoo_demo $ gem install warbler
Fetching warbler-2.1.0.gem
Successfully installed warbler-2.1.0
Parsing documentation for warbler-2.1.0
Installing ri documentation for warbler-2.1.0
Done installing documentation for warbler after 0 seconds
1 gem installed
image_voodoo_demo $ warble
rm -f image_voodoo_demo.jar
Creating image_voodoo_demo.jar

We’ve just created an executable JAR containing everything needed for the voodoo command:

The code and executable for image_voodoo_demo
The image_voodoo gem
JRuby’s own JAR file and dependencies
The Ruby standard library

We run the jar with the java -jar command line:

image_voodoo_demo $ java -jar image_voodoo_demo.jar ~/Downloads/PXL_20250802_162259596.jpg
wrote demo files to /Users/headius/work/image_voodoo_demo/PXL_20250802_162259596/

It works!

Going Deeper

Here’s an abbreviated listing of the contents of the image_voodoo_demo.jar file:

image_voodoo_demo $ jar tf image_voodoo_demo.jar
JarMain.class
META-INF/
META-INF/MANIFEST.MF
META-INF/init.rb
META-INF/lib/
META-INF/lib/jruby-core-10.0.2.0-complete.jar
META-INF/lib/jruby-stdlib-10.0.2.0.jar
META-INF/main.rb
gems/
gems/bundler-2.6.9/
gems/bundler-2.6.9/exe/
gems/bundler-2.6.9/exe/bundle
gems/bundler-2.6.9/exe/bundler
gems/image_voodoo-0.9.3/
gems/image_voodoo-0.9.3/Gemfile
gems/image_voodoo-0.9.3/History.txt
gems/image_voodoo-0.9.3/Jars.lock
...
image_voodoo_demo/
image_voodoo_demo/Gemfile
image_voodoo_demo/Gemfile.lock
image_voodoo_demo/README.md
image_voodoo_demo/Rakefile
image_voodoo_demo/exe/
image_voodoo_demo/exe/voodoo
image_voodoo_demo/lib/
image_voodoo_demo/lib/image_voodoo/
image_voodoo_demo/lib/image_voodoo/demo/
image_voodoo_demo/lib/image_voodoo/demo.rb
image_voodoo_demo/lib/image_voodoo/demo/version.rb
specifications/
specifications/bundler-2.6.9.gemspec
specifications/image_voodoo-0.9.3.gemspec

JarMain.class is the “main” file for the JVM. It sets up the JRuby runtime and in-archive gem paths and then launches our executable voodoo command.
META-INF contains the JAR metadata along with any dependency libraries. In this case it just needs the jruby-core and jruby-stdlib jars to have a complete JRuby runtime available.
gems contains all dependency gems for this tool.
image_voodoo_demo naturally contains our demo tool’s source files.

Let’s customize the building of this jar a little bit.

Customizing Warbler

Warbler supports a number of configuration settings and can dump a dummy config file to config/warble.rb:

(Note: the config directory must exist to generate the config file; this will be fixed in warbler 2.1.1)

image_voodoo_demo $ warble config
cp /Users/headius/work/jruby/lib/ruby/gems/shared/gems/warbler-2.1.0/warble.rb config/warble.rb

Let’s say my image_voodoo_demo utility is super-proprietary IP but I need to deliver it to a customer for use on-premises. The configuration setting we’re looking for is features:

image_voodoo_demo $ head -12 config/warble.rb
# Disable Rake-environment-task framework detection by uncommenting/setting to false
# Warbler.framework_detection = false

# Warbler web application assembly configuration file
Warbler::Config.new do |config|
  # Features: additional options controlling how the jar is built.
  # Currently the following features are supported:
  # - *gemjar*: package the gem repository in a jar file in WEB-INF/lib
  # - *executable*: embed a web server and make the war executable
  # - *runnable*: allows to run bin scripts e.g. `java -jar my.war -S rake -T`
  # - *compiled*: compile .rb files to .class files
  # config.features = %w(gemjar)

We modify this line to config.features = %w[compiled] and re-run the warble command:

image_voodoo_demo $ warble
java -classpath "/Users/headius/work/jruby/lib/ruby/gems/shared/gems/jruby-jars-10.0.2.0/lib/jruby-core-10.0.2.0-complete.jar":"/Users/headius/work/jruby/lib/ruby/gems/shared/gems/jruby-jars-10.0.2.0/lib/jruby-stdlib-10.0.2.0.jar"  \
        org.jruby.Main -S jrubyc  "lib/image_voodoo/demo.rb" "lib/image_voodoo/demo/version.rb"
Ignoring prism-1.5.2 because its extensions are not built. Try: gem pristine prism --version 1.5.2
Ignoring resolv-0.6.2 because its extensions are not built. Try: gem pristine resolv --version 0.6.2
rm -f image_voodoo_demo.jar
Creating image_voodoo_demo.jar
rm -f lib/image_voodoo/demo.class lib/image_voodoo/demo/version.class

Our build has changed a bit, using JRuby’s jrubyc command-line compiler to precompile the image_voodoo_demo sources into JVM class files containing JRuby bytecode.

image_voodoo_demo $ jar tf image_voodoo_demo.jar | grep image_voodoo_demo/lib
image_voodoo_demo/lib/
image_voodoo_demo/lib/image_voodoo/
image_voodoo_demo/lib/image_voodoo/demo/
image_voodoo_demo/lib/image_voodoo/demo.class
image_voodoo_demo/lib/image_voodoo/demo.rb
image_voodoo_demo/lib/image_voodoo/demo/version.class
image_voodoo_demo/lib/image_voodoo/demo/version.rb

The .rb files here are just stubs to load the .class files:

image_voodoo_demo $ unzip image_voodoo_demo.jar image_voodoo_demo/lib/image_voodoo/demo.rb
Archive:  image_voodoo_demo.jar
replace image_voodoo_demo/lib/image_voodoo/demo.rb? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
  inflating: image_voodoo_demo/lib/image_voodoo/demo.rb
image_voodoo_demo $ cat image_voodoo_demo/lib/image_voodoo/demo.rb
load __FILE__.sub(/.rb$/, '.class')%

We can use the javap disassembler to see the contents of one of these precompiled class files. Good luck turning this back into source code!

image_voodoo_demo $ javap -c -classpath image_voodoo_demo.jar image_voodoo_demo/lib/image_voodoo/demo
Warning: File image_voodoo_demo.jar(/image_voodoo_demo/lib/image_voodoo/demo.class) does not contain class image_voodoo_demo/lib/image_voodoo/demo
Compiled from "lib/image_voodoo/demo.rb"
public class lib.image_voodoo.demo {
  public static {};
    Code:
       0: new           #11                 // class java/lang/StringBuilder
       3: dup
       4: invokespecial #14                 // Method java/lang/StringBuilder."<init>":()V
       7: ldc           #16                 // String \u0000\u0000\u0000\u0002\u0000\u0000\n®\b\tH\u0002\"\u0001\u0000S\u0001z\fimage_voodooÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0002\u0000t\u0000\u0000H\u0003\"\u0001\u0000S\u0001z\u0019image_voodoo/demo/versionÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0003\u0000t\u0000\u0001H\u00053t\u0000\u0002\u0001_\u0000u-t\u0000\u0002\u0001\u0007requireÿÿÿÿÿ\u0007Xt\u0006\u0000_\u0000I\u0001t\u0006\u0000\u0000\u0018lib/image_voodoo/demo.rb\u0006H\u00062t\u0000\u0001_\u0000\u0002H\u0018I\u0002t\u0006\u0000\u0000\u0018lib/image_voodoo/demo.rb\u0019-t\u0000\u0001\u0001ÿÿÿÿÿ\u0007\tXt\u0006\u0000_\u0000I\u0001t\u0006\u0000\u0000\u0018lib/image_voodoo/demo.rb\u00076S\u0003H\u0017I\u0002t\u0006\u0000\u0000\u0018lib/image_voodoo/demo.rb\u0018-:\u0001\u0002ÿÿÿÿÿ\u0011output_demo_filesÿÿÿÿÿ\b\t\ft\u0000\u0000ffU\u0001\u0000fÿÿÿÿÿt\u0000\u0000\nl\u0000\u0000t\u0000\u0000\u0000H\b?t\u0000\u0001s\u0001f$\u0000\u0002t\u0000\u0001ÿÿÿÿþl\u0000\u0000wS\u0004\u0000t\u0000\u0002-t\u0000\u0002\u0003\bfilenameÿÿÿÿÿ\u000bImageVoodooÿÿÿÿÿ\nwith_imageÿÿÿÿÿ0;L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\t\ft\u0005\u0000\u0001ff\nl\u0000\u0000t\u0005\u0000\u0001\u0000H\t?t\u0005\u0001\u0001s\u0001f#\u0000\u0002t\u0005\u0001\u0001\u0002l\u0003\u0001z\u0002.*ÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\t\u0000t\u0005\u0002\u0001Xl\u0002\u0000t\u0005\u0002\u0001H\n?t\u0005\u0003\u0001s\u0004f\"\u0000\u0005t\u0005\u0003\u0001\u0001l\u0002\u0000\u0000t\u0005\u0004\u0001\u0006L\u0007CL1_LBL\u0000t\u0005\u0004\u0001Xt\u0005\u0005\u0001N\u0001L\u0007CL1_LBL\u0001:L\u0007CL1_LBL\u0000?t\u0005\u0006\u0001s\u0004f\"\u0000\u0006t\u0005\u0006\u0001\u0001l\u0002\u0000\u0000t\u0005\u0007\u0001Xt\u0005\u0005\u0001t\u0005\u0007\u0001:L\u0007CL1_LBL\u0001H\u000b$\u0000\u0007l\u0000\u0000ÿÿÿÿþfdwS\u0005\u0000t\u0005\b\u0001H\f\u0017\u0000\bl\u0000\u0000ÿÿÿÿûfdfÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0000Èfÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0001\u0090fÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0002XwS\u0006\u0000t\u0005\t\u0001H\r$\u0000\tl\u0000\u0000ÿÿÿÿþf2wS\u0007\u0000t\u0005\n\u0001H\u000e\u0017\u0000\nl\u0000\u0000ÿÿÿÿýfdfÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0096wS\b\u0000t\u0005\u000b\u0001H\u0012Xt\u0005\r\u0001{\u0002:\u000bf\u0014:\fz\u0006FF0000ÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0012\"\u0000\rl\u0000\u0000\u0001t\u0005\r\u0001\u0002t\u0005\f\u0001Pt\u0005\u000f\u0001\u0002l\u0002\u0000z\u000b/border.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0012ÿÿÿÿþ\u000fft\u0018lib/image_voodoo/demo.rb\u0012\"\u0000\u000et\u0005\f\u0001\u0001t\u0005\u000f\u0001\u0000t\u0005\u000e\u0001H\u0013!\u0000\u000fl\u0000\u0000\u0001F?è\u0000\u0000\u0000\u0000\u0000\u0000\u0000t\u0005\u0010\u0001Pt\u0005\u0012\u0001\u0002l\u0002\u0000z\f/reduced.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0013ÿÿÿÿþ\u0010ft\u0018lib/image_voodoo/demo.rb\u0013\"\u0000\u000et\u0005\u0010\u0001\u0001t\u0005\u0012\u0001\u0000t\u0005\u0011\u0001H\u0014?t\u0005\u0015\u0001s\u0004f%\u0000\u0010t\u0005\u0015\u0001\u0000\u0000t\u0005\u0016\u0001Pt\u0005\u0014\u0001\u0005z\u0014wrote demo files to ÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0014t\u0005\u0016\u0001z\u0001/ÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0014l\u0002\u0000z\u0001/ÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0014ÿÿÿÿþ\u001eft\u0018lib/image_voodoo/demo.rb\u0014\"\u0001\u0011S\u0001t\u0005\u0014\u0001\u0000t\u0005\u0013\u0001-t\u0005\u0013\u0001<:L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\u0012t\u0005\u0017\u0001ct\u0005\u0018\u0001\u0002\u0001t\u0005\u0017\u00010t\u0005\u0018\u0001:L\u0007CL1_LBL\u0002\u0012\u0003imgÿÿÿÿÿ\u0004Fileÿÿÿÿÿ\bbasenameÿÿÿÿÿ\bfilenameÿÿÿÿÿ\u0003Dirÿÿÿÿÿ\u0006exist?ÿÿÿÿÿ\u0005mkdirÿÿÿÿÿ\u0011cropped_thumbnailÿÿÿÿÿ\twith_cropÿÿÿÿÿ\tthumbnailÿÿÿÿÿ\u0006resizeÿÿÿÿÿ\u0005widthÿÿÿÿÿ\u0005colorÿÿÿÿÿ\nadd_borderÿÿÿÿÿ\u0004saveÿÿÿÿÿ\u0007qualityÿÿÿÿÿ\u0003pwdÿÿÿÿÿ\u0004putsÿÿÿÿÿ\r;L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\ft\u0005\u0000\u0002ff\nl\u0000\u0000t\u0005\u0000\u0002\u0000H\u000bPt\u0005\u0002\u0002\u0002l\u0001\u0001z\u0012/cropped_thumb.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u000bÿÿÿÿþ\u0016ft\u0018lib/image_voodoo/demo.rb\u000b\"\u0000\u0002l\u0000\u0000\u0001t\u0005\u0002\u0002\u0000t\u0005\u0001\u0002-t\u0005\u0001\u0002<:L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\u0012t\u0005\u0003\u0002ct\u0005\u0004\u0002\u0002\u0001t\u0005\u0003\u00020t\u0005\u0004\u0002:L\u0007CL2_LBL\u0000\u0003\u0004img2ÿÿÿÿÿ\bbasenameÿÿÿÿÿ\u0004saveÿÿÿÿÿ\r;L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\ft\u0005\u0000\u0003ff\nl\u0000\u0000t\u0005\u0000\u0003\u0000H\fPt\u0005\u0002\u0003\u0002l\u0001\u0001z\f/cropped.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\fÿÿÿÿþ\u0010ft\u0018lib/image_voodoo/demo.rb\f\"\u0000\u0002l\u0000\u0000\u0001t\u0005\u0002\u0003\u0000t\u0005\u0001\u0003-t\u0005\u0001\u0003<:L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\u0012t\u0005\u0003\u0003ct\u0005\u0004\u0003\u0002\u0001t\u0005\u0003\u00030t\u0005\u0004\u0003:L\u0007CL3_LBL\u0000\u0003\u0004img2ÿÿÿÿÿ\bbasenameÿÿÿÿÿ\u0004saveÿÿÿÿÿ\r;L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\ft\u0005\u0000\u0004ff\nl\u0000\u0000t\u0005\u0000\u0004\u0000H\rPt\u0005\u0002\u0004\u0002l\u0001\u0001z\n/thumb.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\rÿÿÿÿþ\u000eft\u0018lib/image_voodoo/demo.rb\r\"\u0000\u0002l\u0000\u0000\u0001t\u0005\u0002\u0004\u0000t\u0005\u0001\u0004-t\u0005\u0001\u0004<:L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\u0012t\u0005\u0003\u0004ct\u0005\u0004\u0004\u0002\u0001t\u0005\u0003\u00040t\u0005\u0004\u0004:L\u0007CL4_LBL\u0000\u0003\u0004img2ÿÿÿÿÿ\bbasenameÿÿÿÿÿ\u0004saveÿÿÿÿÿ\u0010;L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\ft\u0005\u0000\u0005ff\nl\u0000\u0000t\u0005\u0000\u0005\u0000H\u000fPt\u0005\u0002\u0005\u0002l\u0001\u0001z\f/resized.jpgÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u000fÿÿÿÿþ\u0010ft\u0018lib/image_voodoo/demo.rb\u000f\"\u0000\u0002l\u0000\u0000\u0001t\u0005\u0002\u0005\u0000t\u0005\u0001\u0005H\u0010Pt\u0005\u0004\u0005\u0002l\u0001\u0001z\f/resized.pngÿÿÿÿþ\u0010\u0018lib/image_voodoo/demo.rb\u0010ÿÿÿÿþ\u0010ft\u0018lib/image_voodoo/demo.rb\u0010\"\u0000\u0002l\u0000\u0000\u0001t\u0005\u0004\u0005\u0000t\u0005\u0003\u0005-t\u0005\u0003\u0005<:L\u0015_GLOBAL_ENSURE_BLOCK_\u0000\u0012t\u0005\u0005\u0005ct\u0005\u0006\u0005\u0002\u0001t\u0005\u0005\u00050t\u0005\u0006\u0005:L\u0007CL5_LBL\u0000\u0003\u0004img2ÿÿÿÿÿ\bbasenameÿÿÿÿÿ\u0004saveÿÿÿÿÿ\t\u0007\u0000\u0003\u0000\u0000\u0000\u0000ÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000 \u0005ffffffffffff\u0000\bÿ\u0000\u0000\u0000\u0097\u0005\u0005\u0002\u0000\u000bImageVoodooÿÿÿÿÿ\u0000\u0000\u0000\u0000ÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000?øffffffffffff\u0000ÿ\u0000\u0000\u0000¥ÿ\u0000\u0000\u0000û\u0004\u0006\u0001\u0000\u0004Demoÿÿÿÿÿ\u0001\u0000\u0000\u0000ÿ\u0000\u0000\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000?øffffffffffff\u0000ÿ\u0000\u0000\u0001\u0001ÿ\u0000\u0000\u0001Q\u0003\u0007\u0003\u0000\u0011output_demo_filesÿÿÿÿÿ\u0002\u0000\u0001\bfilename\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000?ýffffffffffff\u0000ÿ\u0000\u0000\u0001nÿ\u0000\u0000\u0001¬\u0000\b\u0019\u0003fÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿ\u0012with_image &|img|1ÿÿÿÿÿ\u0003\u0001\u0002\u0003img\bbasename\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000?ýffffftffffff\u0000ÿ\u0000\u0000\u0001Üÿ\u0000\u0000\u0005\u0082\u0000\u000b\u0005\u0001fÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿ\u001acropped_thumbnail &|img2|2ÿÿÿÿÿ\u0004\u0001\u0001\u0004img2\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000 \u0000ffffftffffff\u0000ÿ\u0000\u0000\u0006cÿ\u0000\u0000\u0007=\u0000\f\u0005\u0001fÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿ\u0012with_crop &|img2|3ÿÿÿÿÿ\u0004\u0001\u0001\u0004img2\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000 \u0000ffffftffffff\u0000ÿ\u0000\u0000\u0007`ÿ\u0000\u0000\b4\u0000\r\u0005\u0001fÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿ\u0012thumbnail &|img2|4ÿÿÿÿÿ\u0004\u0001\u0001\u0004img2\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000 \u0000ffffftffffff\u0000ÿ\u0000\u0000\bWÿ\u0000\u0000\t)\u0000\u000e\u0007\u0001fÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿ\u000fresize &|img2|5ÿÿÿÿÿ\u0004\u0001\u0001\u0004img2\u0000ÿ\u0000\u0001\u0000\u0000\u0000\u0000\u0000ÿÿ\u0000\u0000 \u0000ffffftffffff\u0000ÿ\u0000\u0000\tLÿ\u0000\u0000\n\u008b
       9: invokevirtual #20                 // Method java/lang/StringBuilder.append:(Ljava/lang/String;)Ljava/lang/StringBuilder;
      12: invokevirtual #24                 // Method java/lang/Object.toString:()Ljava/lang/String;
      15: putstatic     #26                 // Field script_ir:Ljava/lang/String;
      18: return

  public static void main(java.lang.String[]);
    Code:
       0: invokestatic  #34                 // Method org/jruby/Ruby.newInstance:()Lorg/jruby/Ruby;
       3: astore_1
       4: aload_1
       5: aload_1
       6: getstatic     #26                 // Field script_ir:Ljava/lang/String;
       9: ldc           #36                 // String ISO-8859-1
      11: invokevirtual #42                 // Method java/lang/String.getBytes:(Ljava/lang/String;)[B
      14: ldc           #43                 // String lib/image_voodoo/demo.rb
      16: invokestatic  #49                 // Method org/jruby/ir/runtime/IRRuntimeHelpers.decodeScopeFromBytes:(Lorg/jruby/Ruby;[BLjava/lang/String;)Lorg/jruby/ir/IRScope;
      19: invokevirtual #53                 // Method org/jruby/Ruby.runInterpreter:(Lorg/jruby/ParseResult;)Lorg/jruby/runtime/builtin/IRubyObject;
      22: return

  public static org.jruby.ir.IRScope loadIR(org.jruby.Ruby, java.lang.String);
    Code:
       0: aload_0
       1: getstatic     #26                 // Field script_ir:Ljava/lang/String;
       4: ldc           #36                 // String ISO-8859-1
       6: invokevirtual #42                 // Method java/lang/String.getBytes:(Ljava/lang/String;)[B
       9: aload_1
      10: invokestatic  #49                 // Method org/jruby/ir/runtime/IRRuntimeHelpers.decodeScopeFromBytes:(Lorg/jruby/Ruby;[BLjava/lang/String;)Lorg/jruby/ir/IRScope;
      13: areturn

Future Topics

I’m trying to do more frequent, compact blog posts, so I’m not going to get into the more elaborate generation of deployable web archives today. Here’s a few topics I’ll try to cover in future posts:

Generating deployable WAR files from any rack-compatible web application.
Including jar dependencies from the JVM ecosystem as part of your tool.
Getting around the JVM requirement: using JVM packaging tools to combine your jar with a complete runnable JVM environment.

A good friend of the JRuby project – Mohit Sindhwani – also blogged about Warbler back in 2021. His company and many others use Warbler for commercial packaging of Ruby applications every day, ranging from simple command-line utilities all the way up to enterprise scale applications.

The Warbler project just had its first major release in almost a decade, so we’re currently updating it for modern JRuby, Ruby, and JVM features and requirements. There’s a lot of room for cleanup and new features!

If you’re interested in packaging your Ruby tools for easy, secure distribution to friends, family, or customers… please give Warbler a try and let us know how we can help you!

https://github.com/jruby/warbler

Join the discussion on r/ruby!

Updating Deprecations with Version Information

2025-10-10T00:00:00+00:00

Java 9 added the ability to mark a @Deprecated annotation with a “since” version, so we figured it was worth updating JRuby.

Deprecation in Java

Deprecation is the process of marking a feature as “no longer supported” or “on its way out”, usually in a programmatic way so users can see warnings at build time. Nearly all languages and ecosystems have some way to mark features, APIs, or libraries as deprecated.

In Java 1.4 and earlier, this was done via the @deprecated directive (note lower-case “d”) in JavaDoc, which was great for documentation users but required extra processing by source-level tools and was not visible to any tools at runtime.

Java 1.5 introduced a new annotation java.lang.Deprecated that is retained at runtime and requires only annotation-awareness to process. It has become a generally preferred way to mark classes, methods, and fields as deprecated. Unfortunately, it provided no additional information, like a date or version after which the feature should not be used, or whether it would eventually be removed.

Java 9 fixed that, by adding two attributes to the @Deprecated annotation: since, indicating when the deprecation first went into effect and forRemoval, indicating that the feature has been scheduled for removal. The since attribute is only informational, but a setting of forRemoval=true tells the compiler to complain about uses even more loudly (and perhaps fail the build).

Deprecation in JRuby

The modern era of JRuby extends back almost to the release of Java 1.5, so we’ve steadily added @Deprecated annotations throughout our codebase as we move away from old features and peculiarly-named methods. These deprecations are generally not visible to the average JRuby user, but if you use JRuby as an API or embed it into a larger Java application, you’ll get compile-time warnings for deprecated features.

With the release of JRuby 10, we now depend on a minimum of Java 21… which means we can also use the since tag. But what of all the existing deprecations?

Updating deprecations with “since”

This week, we decided it would be worth rewriting all “bare” @Deprecated annotations to include since information. The process required a few steps:

Get the source locations of all @Deprecated annotations that did not contain any attributes.
For each location, determine the first JRuby release in which the deprecation was shipped.
Update the deprecations to point at that version.

With a little Ruby and Git, here’s the script I came up with:

# scan all .java files in the dir specified by ARGV[0]
Dir[ARGV[0] + "/**/*.java"].each do |file|
  # read all lines from the file
  file_lines = File.readlines(file)

  file_lines.each_with_index do |line, i|
    line.gsub!(/@Deprecated\S*$/) do
      # use git blame to find the commit that introduced the annotation
      sha = `git blame -L #{i+1},#{i+1} #{file}`.split(" ")[0]

      # use git describe to get the first tag that contains that commit
      tag = `git describe --abbrev=0 --tags --contains #{sha}`.split("~")[0]

      # add that tag to a "since" attribute for the annotation
      "@Deprecated(since = \"#{tag}\")"
    end
  end

  File.write(file, file_lines.join(''))
  puts "processed #{file}"
end

Ups and downs

The PR I created is here: https://github.com/jruby/jruby/pull/9027

On the up side, this clearly indicates when each deprecation was added, so we can start to remove the oldest once (for some definition of “oldest”). It also gives better output to users so they know how long the feature they’re using has been deprecated.

On the down side, I had to manually fix several tags that were bogus or inaccurate (which maybe is a plus, really), and a piece of code was ever moved then the history is likely broken and the “since” version might be inaccurate. A improved version might also try to track file moves, but that was more than I needed here.

There’s also a small concern that we’ve basically just updated all of those @Deprecated lines, so any future blaming will have to dig deeper to find out when and why they were deprecated. But I kept this change as a single commit, so at worst you’ll have to git blame the parent commit in such cases.

What do you think?

Before I merged this, I asked if anyone could think of a good reason not to do it… and I got no responses. What do you think of this rewriting of @Deprecated annotations to include the version?

If you decide to proceed with a similar transformation, I hope this script is helpful! Remember you can always just run it with JRuby, and the easiest way to run JRuby for a simple script would be to use jbang:

jruby $ jbang run@jruby deprecated_since.rb core/src/main/java
processed core/src/main/java/org/jruby/AbstractRubyMethod.java
processed core/src/main/java/org/jruby/Appendable.java
processed core/src/main/java/org/jruby/BasicObjectStub.java
processed core/src/main/java/org/jruby/DelegatedModule.java
processed core/src/main/java/org/jruby/EvalType.java
...

Enjoy!

Join the discussion on r/ruby!

Join the discussion on r/java!

JRuby and Leyden: Even Better Startup

2025-09-26T00:00:00+00:00

At the end of my post on JRuby and JDK 25 startup time features, I teased a bit of the unreleased improvements from Project Leyden. It turns out the latest commits improve startup time even more, so it seems worth posting a quick follow-up!

Project Leyden is LIT

Of the many OpenJDK projects I follow, Leyden has been near the top as far as activity and interest. In the past month, there’s been 527 commits to all branches… over 15 commits per day. And this doesn’t include commits being done by contributors on their own repositories. It’s exciting to watch!

After my recent post, Aleksey Shipilëv reached out to me on Bluesky:

If you know Aleksey, you know to listen when he makes a suggestion. Naturally, I got to work building my own “premain” Leyden JDK build to try things out.

Baseline Startup

To refresh your memory, our previous best time — with AOTCache and JRuby’s “dev” mode (which disables many optimizations) — was a lovely little 423ms, down from an unaided 943ms.

We’ll try our baseline startup time training again, but this time I’ll leave off the --dev flag and let JRuby and the JVM fully optimize and record everything.

(Recall that the --nocache flag turns off JRuby’s automatic use of AppCDS, which is incompatible with AOTCache.)

Same training run:

$ jruby --nocache -J-XX:AOTCacheOutput=jruby.aot baseline_training.rb
...
Reading AOTConfiguration jruby.aot.config and writing AOTCache jruby.aot
AOTCache creation is complete: jruby.aot 110788608 bytes
Removed temporary AOT configuration file jruby.aot.config

Note this new AOTCache is 110MB, a full 50MB larger than the 60MB from before. There must be something good in there… let’s try it.

(To make things a bit easier to read, I’ll be using TIMEFMT="run time: %mE" to format zsh’s time command.)

$ time jruby --nocache -J-XX:AOTCache=jruby.aot -e 1
run time: 353ms

With the latest Leyden “premain” patches, JRuby’s base startup — sacrificing no features and no optimizations — is down to 353ms, over 16% faster than our previous best!

gem list

One thing I didn’t show in my previous post was the performance of gem list without explicitly training the AOTCache for gem list. Recall that without any help, gem list for 88 gems took 1546ms, and our best time was 815ms.

Here’s a gem list time with the latest Leyden “premain” AOTCache patches, trained only for baseline JRuby startup:

$ time jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
run time: 919ms

Not bad! A single, simple training run has reduced gem list time by 40%, and we’ve achieved a sub-second run time without specifically training the AOTCache for this command. This means you can use a simple training run for your JRuby development environment and still see a massive improvement in startup time for arbitrary Ruby commands.

Of course, we want to see what happens if we specifically train the updated AOTCache for gem list. Targeted training like is useful when you have one type of command you must run repeatedly, or in a serverless Amazon Lambda-style environment that needs to quickly launch a small tool.

The training run proceeds as before:

$ jruby --nocache -J-XX:AOTCacheOutput=jruby.aot gem_list_training.rb
...
Reading AOTConfiguration jruby.aot.config and writing AOTCache jruby.aot
AOTCache creation is complete: jruby.aot 175816704 bytes
Removed temporary AOT configuration file jruby.aot.config

And here’s the gem list run time with our custom AOTCache:

$ time jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
run time: 714ms

Another new record: we’re down to 714ms, beating the old record of 825ms by 13%, and we haven’t disabled any optimizations.

What’s Next?

Watch This Space

Even with these incredible results, I want to reiterate that it’s early days for Project Leyden.

We still haven’t achieved a “cold” gem list run time comparable to the 280ms from running it in-process in a loop, so clearly there’s optimizations happening that aren’t getting saved and restored.

And some of these AOTCache sizes might be prohibitively large; an uncached filesystem will take time to load up 100-200MB of AOTCache data, and that will be even worse if it’s loaded across the network.

But wow it’s exciting stuff. I have been telling JRuby users for years that “it’s not our fault” and “the JVM folks are working on it”. Finally, the dream of fast JRuby startup is coming true.

Other Options

My previous post neglected to mention other options for improving JRuby startup, like the Project CRaC “checkpoint and restore” feature I blogged about previously and alternative JVMs like IBM Semeru (aka “OpenJ9”) and its Shared Class Cache and JITServer features. We’ll explore those and other options in an upcoming post!

Join the discussion on Reddit!

JRuby and JDK 25: Startup Time with AOTCache

2025-09-24T00:00:00+00:00

JDK 25 is the newest LTS release since JDK 21, and it ships with a gaggle of amazing VM-level features. This post will cover one of the most important improvements for command-line ecosystems like JRuby’s: the AOTCache (ahead-of-time cache) and its ability to pre-optimize code for future runs.

We’ll explore how AOTCache can speed up your JRuby workflow, starting with a discussion of JRuby startup time challenges and finishing with “coming soon” features that didn’t quite make it into the JDK 25 release.

The Challenge of Fast Startup on the JVM

It’s worth taking a quick look at why startup time has been such a difficult challenge for JRuby, and how we’ve worked to improve it over the years.

Why does JRuby start up slowly?

Whenever folks ask me “what’s the main issue I’ll have migrating to JRuby” the answer is almost always “startup time”. If the startup time problem had been solved for us 20 years ago, JRuby would already be the de-facto production Ruby for most developers. So why haven’t we just fixed it?

The unfortunate answer is that it’s really not our fault.

Starting from Scratch

There’s many things about Ruby, JRuby, and the JVM that contribute to slow startup:

Ruby applications typically start from uncompiled source every time you run a command, and most of these commands load dozens or hundreds of source files. We have to re-parse and re-compile all that code every time.
JRuby’s internal representation of Ruby code starts out interpreted, to reduce the overhead of optimizing code that’s only run once. We delay full optimization until we know methods will be used repeatedly.
JRuby itself is compiled Java bytecode, which must be loaded into the JVM from the filesystem and interpreted by the JVM. Like JRuby’s mixed-mode runtime, the JVM defers optimization of that code until it can analyze and profile code. This means the JRuby parser, compiler, interpreter, core classes, and even our JIT compiler all start out “cold”.
The JDK itself is largely written in Java, so even the platform JRuby is built upon takes some time to optimize.

Even though we’ve made great improvements to JRuby’s startup, like [reducing memory allocation] and [deferring initialization of rarely-used state], we’re fighting an uphill battle. Most of the startup delay is due to the JVM itself.

Here’s JRuby 10 running a simple command line with no startup-time help on JDK 21:

jruby -e 1  1.63s user 0.08s system 181% cpu 0.943 total

It’s not the end of the world, but 943ms to basically run “hello, world” isn’t great.

Comparing with CRuby

Where JRuby has many layers of optimization, CRuby starts out with much of its code already optimized:

The parser, compiler, interpreter, and most of the core classes are written in C and start as native code.
The CRuby boot process has been refined for 30 years to start up as fast as possible.

As a result, CRuby takes about 45ms for its baseline startup (around 20x faster than JRuby’s time above).

This design does put some hard limits on CRuby’s runtime optimizations, but it also sets a high bar for JRuby. Challenge accepted! Let’s see what we can do to narrow that gap.

What happens once the JVM optimizes JRuby?

Fortunately for JRuby users, the JVM doesn’t take too long to kick in, and once it does we can start to see the true performance of JRuby.

Let’s try a more real-world example, running a fairly heavy command: gem list with about 88 gems.

gem_list_timing.rb

20.times {
  t = Time.now
  org.jruby.Main.main(%w[-S gem list].to_java(:string))
  $stderr.puts "iteration #{_1}: #{Time.now - t}"
}

This simple script runs in JRuby and basically just re-launches additional JRuby instances in the same process. Here’s the output of timings from stderr:

$ jruby gem_list_timing.rb > /dev/null
iteration 0: 1.0590579999999998
iteration 1: 0.435281
iteration 2: 0.39674800000000005
iteration 3: 0.40792199999999995
iteration 4: 0.358851
iteration 5: 0.327706
iteration 6: 0.356299
iteration 7: 0.383793
iteration 8: 0.306416
iteration 9: 0.29007
iteration 10: 0.301724
iteration 11: 0.391308
iteration 12: 0.302654
iteration 13: 0.2939
iteration 14: 0.300466
iteration 15: 0.301517
iteration 16: 0.285803
iteration 17: 0.316092
iteration 18: 0.28180099999999997
iteration 19: 0.280565

Even though the first iteration here is actually the second time JRuby has booted in this process (the JRuby running the script precedes it), we’re still taking over a second just to list installed gems. But the JVM optimizations kick in quickly, with the second iteration taking half as much time and the final iteration (still getting faster) taking a bit over one-quarter as much time.

Improving startup one step at a time

Clearly, JRuby can run simple commands fast once the JVM gets going. Our challenge has been finding ways to shorten that curve without sacrificing JRuby functionality. Let’s explore a few of these tricks.

Technique #1: Do Less

One of the simplest ways to eliminate startup-time overhead is to simply do less of it.

You can see in the diagram above that there are many phases to running JRuby code on the JVM:

We parse and compile Ruby to our intermediate representation (IR)
We interpret that Ruby IR for a while
Eventually, we compile our IR into JVM bytecode
The JVM interprets that bytecode for a while
An early, simple optimizer in the JVM turns that bytecode into semi-optimized native code
That native code continues to be profiled and analyzed
A later, profile-driven optimizer recompiles the bytecode into optimized native code

Of course by the time we reach that last stage, short commands may already have exited, and we’ve wasted a lot of effort optimizing code that hardly gets run.

Realizing that many commands in a typical Ruby workflow don’t require the highest-performing execution, we introduced a development mode flag: --dev

$ time jruby -e 1
jruby -e 1  1.63s user 0.08s system 181% cpu 0.941 total
$ time jruby --dev -e 1
jruby --dev -e 1  0.82s user 0.07s system 123% cpu 0.723 total

This example runs a trivial Ruby script that just evaluates the number 1 and exits. JRuby without any flags takes 941ms. When we use the --dev flag, however, that time reduces to 723ms. What’s happening here?

The --dev flag basically turns off several stages in the optimization pipeline, so we start running more quickly and avoid doing optimizations that won’t be useful:

JRuby’s bytecode compiler is disabled, so we just stay in the JRuby IR interpreter.
The JVM’s second-stage profiled optimizer is disabled, so it just generates simple native code for JRuby’s internal logic and the rest of the JDK.
There’s a few other tweaks that also have a small impact.

This has been, up until recently, the best way to improve JRuby startup. Let’s review a newer technique I blogged about a few months ago, the Application Class Data Sharing.

Technique #2: Preprocess JRuby and JDK code with AppCDS

Application Class Data Sharing (AppCDS) is an OpenJDK feature that allows you to save off some of the early boot-time work of loading and processing JVM class files, eliminating that processing for future runs. In my post Boosting JRuby Startup with AppCDS and AOT caching, I walk through the details of “AppCDS” and show how you can use it with JRuby.

Since then, we’ve released JRuby 10 and updates for JRuby 9.4 that will automatically use AppCDS to improve startup! This feature can be disabled with the --nocache flag. Let’s review startup performance with and without AppCDS.

# JRuby with no startup help
$ time jruby --nocache -e 1
jruby --nocache -e 1  1.61s user 0.08s system 182% cpu 0.925 total

# JRuby with AppCDS (on by default)
$ time jruby -e 1
jruby -e 1  1.28s user 0.06s system 191% cpu 0.702 total

# JRuby with "dev" mode only
$ time jruby --nocache --dev -e 1
jruby --nocache --dev -e 1  0.83s user 0.07s system 125% cpu 0.717 total

# JRuby with "dev" mode and AppCDS
$ time jruby --dev -e 1
jruby --dev -e 1  0.63s user 0.04s system 118% cpu 0.567 total

Now we’re talking! With AppCDS, base JRuby startup in normal mode (with full optimization still enabled) drops down to 702ms, less than “dev” mode alone. And JRuby with both AppCDS and “dev” mode gets down to 567ms!

At these speeds, startup time becomes almost a non-issue, but what about a heavier command like gem list?

# gem list with no startup help
$ time jruby --nocache -S gem list > /dev/null
jruby --nocache -S gem list > /dev/null  3.44s user 0.14s system 215% cpu 1.663 total

# gem list with AppCDS
$ time jruby -S gem list > /dev/null
jruby -S gem list > /dev/null  3.07s user 0.14s system 229% cpu 1.397 total

# gem list with "dev" mode only
$ time jruby --nocache --dev -S gem list > /dev/null
jruby --nocache --dev -S gem list > /dev/null  1.52s user 0.11s system 141% cpu 1.148 total

# gem list with "dev" mode and AppCDS
$ time jruby --dev -S gem list > /dev/null
jruby --dev -S gem list > /dev/null  1.31s user 0.09s system 145% cpu 0.967 total

Ok, for a more “real world” command line, we’re still slower than we’d like taking nearly a second just to list gems (similar to “iteration 0” in our looping test). We need to do better!

Technique #3: Upgrade the JDK

There’s a saying in the Java world: “If you want better performance… just wait a bit.” This reflects two truths about the JVM:

It might take a while to optimize, for many reasons spelled out above.
Newer releases of the JDK almost always run faster than older versions.

Let’s try the above AppCDS examples with JDK 25 instead of JDK 21:

# gem list with no startup help
$ time jruby --nocache -S gem list > /dev/null
jruby --nocache -S gem list > /dev/null  3.30s user 0.14s system 222% cpu 1.546 total

# gem list with AppCDS
$ time jruby -S gem list > /dev/null
jruby -S gem list > /dev/null  3.02s user 0.14s system 234% cpu 1.350 total

# gem list with "dev" mode only
$ time jruby --nocache --dev -S gem list > /dev/null
jruby --nocache --dev -S gem list > /dev/null  1.51s user 0.16s system 149% cpu 1.116 total

# gem list with "dev" mode and AppCDS
$ time jruby --dev -S gem list > /dev/null
jruby --dev -S gem list > /dev/null  1.40s user 0.13s system 158% cpu 0.966 total

There’s some modest improvements here just from upgrading:

gem list with no help reduces from 1663ms to 1546ms (7.1% improvement).
gem list with AppCDS reduces from 1397ms to 1350ms (3.4% improvement).
gem list with “dev” mode reduces from 1148ms to 1116ms (2.8% improvement).
gem list with both “dev” mode and AppCDS reduces from 0.967ms to 0.966ms (less than 1% improvement).

We’re seeing gains, but they’re not super impressive. But JDK 25 has an ace up its sleeve: AOTCache.

Technique #4: Save optimization data across runs

The features in JDK 25 build on the capabilities of AppCDS and add several enhancements compared to JDK 21:

AOTCache replaces AppCDS as the primary mechanism for improving startup (JEP 843: “Ahead-of-Time Class Loading & Linking” shipped in JDK 24)
Creating an AOTCache is made easier, with only one “training” step required (JEP 514: “Ahead-of-Time Command-Line Ergonomics”)
The AOTCache can now save optimization profiles from a training run to aid optimization of future runs (JEP 515: “Ahead-of-Time Method Profiling”)

Let’s try switching from AppCDS to the AOTCache.

First, we need to do a training run to allow the JVM to record optimization profiles. We’ll run JRuby in a loop within a single process and save the resulting AOTCache.

baseline_training.rb

100.times {
  ruby = org.jruby.Ruby.new_instance
  ruby.eval_scriptlet "1"
  print "."
  ruby.tear_down
}
puts

This time, rather than running JRuby’s main entry point, we create new JRuby runtime instances in a loop, evaluate some code, and tear them down. Doing this 100 times gives the JVM a chance to “learn” how JRuby boots up and executes.

To train with AOTCache, we disable AppCDS (--nocache) and use the JVM flag -XX:AOTCacheOutput=jruby.aot:

$ jruby --nocache -J-XX:AOTCacheOutput=jruby.aot baseline_training.rb
....................................................................................................
[5.678s][warning][aot] Skipping org/jruby/util/JDBCDriverUnloader: Duplicated unregistered class
[5.678s][warning][aot] Skipping org/jruby/util/JDBCDriverUnloader: Duplicated unregistered class
...
[5.681s][warning][aot] Skipping org/joda/time/base/BaseDateTime: Old class has been linked
[5.681s][warning][aot] Skipping jdk/proxy2/$Proxy28: Unsupported location
Temporary AOTConfiguration recorded: jruby.aot.config
Launching child process /Library/Java/JavaVirtualMachines/zulu-25.jdk/Contents/Home/bin/java to assemble AOT cache jruby.aot using configuration jruby.aot.config
Picked up JAVA_TOOL_OPTIONS: -Djava.class.path=: --add-opens=java.base/java.io=org.jruby.dist --add-opens=java.base/java.nio.channels=org.jruby.dist --add-opens=java.base/sun.nio.ch=org.jruby.dist --add-opens=java.management/sun.management=org.jruby.dist -Xss2048k -Djffi.boot.library.path=/Users/headius/work/jruby/lib/jni -Djava.security.egd=file:/dev/urandom --enable-native-access=org.jruby.dist --sun-misc-unsafe-memory-access=allow --module-path=/Users/headius/work/jruby/lib/jruby.jar -Djruby.home=/Users/headius/work/jruby -Djruby.lib=/Users/headius/work/jruby/lib -Djruby.script=jruby -Djruby.shell=/bin/sh -XX:AOTCacheOutput=jruby.aot -XX:AOTConfiguration=jruby.aot.config -XX:AOTMode=create
Reading AOTConfiguration jruby.aot.config and writing AOTCache jruby.aot
[0.285s][warning][aot] Skipping org/joda/time/tz/FixedDateTimeZone: Unlinked class not supported by AOTClassLinking
...
[0.286s][warning][aot] Skipping org/joda/time/DateTimeZone: Unlinked class not supported by AOTClassLinking
AOTCache creation is complete: jruby.aot 60653568 bytes
Removed temporary AOT configuration file jruby.aot.config
$

Now, we can run our previous tests, passing the JVM flag -XX:AOTCache=jruby.aot to use the generated AOTCache file:

# JRuby with AOTCache
$ time jruby --nocache -J-XX:AOTCache=jruby.aot -e 1
jruby --nocache -J-XX:AOTCache=jruby.aot -e 1  1.10s user 0.08s system 203% cpu 0.581 total

# JRuby with "dev" mode and AOTCache
$ time jruby --nocache --dev -J-XX:AOTCache=jruby.aot -e 1
jruby --nocache --dev -J-XX:AOTCache=jruby.aot -e 1  0.65s user 0.07s system 139% cpu 0.518 total

Wow! Baseline startup with AOTCache is almost as fast as AppCDS with “dev” mode (581ms vs 567ms), and AOTCache plus “dev” mode gives us our best time yet: 518ms!

We can see that gem list has similar improvements:

# gem list with AOTCache
$ time jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null  2.69s user 0.13s system 244% cpu 1.152 total

# gem list with "dev" mode and AOTCache
$ time jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null  1.39s user 0.11s system 173% cpu 0.861 total

Another record… gem list with 88 gems is now comfortably less than a second, at 861ms.

Can we do better by training our AOTCache using gem list?

gem_list_training.rb*

100.times {
  org.jruby.Main.main(%w[-S gem list].to_java(:string))
}

Yes we can!

$ time jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null  1.39s user 0.17s system 189% cpu 0.825 total

New record: 825ms!

Technique #5: Save optimized code!

But wait, there’s more!

The features of AOTCache that shipped with JDK 25 are obviously outstanding, and have delivered the best startup times yet for JRuby users. But the OpenJDK folks haven’t been standing still, and there’s even more coming!

Project Leyden is the OpenJDK project where this work has been going on, and in late August they released a second Early Access build containing previews of that work. Several features that didn’t make the cut are available for testing and experimentation:

AOT compilation of Java methods: Cache compiled native code.
AOT generation of Dynamic Proxies and reflection data: Cache optimized forms of commonly used JVM metaprogramming features.
AOT optimization for class lookup: Cache class lookup data to avoid doing the same lookups again.

The best part? We can try out these features just by downloading Leyden EA2 and training the AOTCache as before.

I present to you the fastest JRuby startup times ever seen on a standard JDK:

# baseline startup with AOTCache (Leyden EA2)
$ time jruby --nocache -J-XX:AOTCache=jruby.aot -e 1
jruby --nocache -J-XX:AOTCache=jruby.aot -e 1  0.55s user 0.06s system 131% cpu 0.462 total

# baseline startup with "dev" mode and AOTCache (Leden EA2)
$ time jruby --nocache --dev -J-XX:AOTCache=jruby.aot -e 1
jruby --nocache --dev -J-XX:AOTCache=jruby.aot -e 1  0.46s user 0.06s system 122% cpu 0.423 total

# gem list with AOTCache (Leyden EA2)
$ time jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
jruby --nocache -J-XX:AOTCache=jruby.aot -S gem list > /dev/null  1.82s user 0.11s system 186% cpu 1.035 total

# gem list with "dev" mode and AOTCache (Leyden EA2)
$ time jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null
jruby --nocache --dev -J-XX:AOTCache=jruby.aot -S gem list > /dev/null  1.07s user 0.09s system 142% cpu 0.815 total

JRuby baseline startup less than half a second!

Gem list down to only 815ms!

Amazing!

What’s Next?

JRuby Enhancements

Using all our tricks and the latest enhancements to the JVM, we’ve managed to improve JRuby startup time by a huge amount:

Baseline startup went from 943ms to 423ms
gem list went from 1663ms to 815ms

That’s over 50% faster startup across the board, with more improvements on the way!

Over the next few weeks, the JRuby team will be transitioning our automatic startup optimizations from AppCDS to AOTCache, to give users the best possible startup time for daily use. But you’ve already seen how you can experiment with these features today. Try it out and let us know how it goes!

Project Leyden Collaboration

We’re also going to be collaborating with the Project Leyden team to share our findings and help them to improve the AOTCache. We’re obviously very excited about this work, since it may finally solve the #1 complaint about using JRuby.

What will the Ruby world be like when JRuby users can have true parallelism, world-class garbage collection, and fast straight-line performance without compromising startup time?

We’re about to find out.

Join the discussion on Reddit!

3D Charts and More with JRuby and JFreeChart

2025-05-01T00:00:00+00:00

After playing with JFreeChart and JRuby and writing up a lovely blog post called “Beautiful Charts with JRuby and JFreeChart” it seems that some folks did not agree with my assessment of the charts as “beautiful” and others did not realize the power of what they’d just seen.

So, let’s see if this one grabs your attention. As before, this example is available in the headius/jruby-charts repository.

Orson Charts

Along with a comprehensive and configurable set of 2D chart formats, the JFreeChart project also ships Orson Charts, an equally extensive set of 3D chart renderers. The library has been designed to work alongside JFreeChart and has all the same support for file output and GUI integration.

So you don’t think my bar chart was beautiful? Ok, maybe you’re right. Let’s kick it up a notch!

Everything is Better in 3D

It took me about 30 minutes to port one of the Orson Charts demos, a 3D rendering of quarterly revenues for four application monitoring companies. I’ve made the following tweaks along the way:

Data is read in from a json file using the Ruby json library.
The GUI and interactive elements have been removed.
The chart is rendered to various file formats rather than to the screen.

The full source is here: 3D Bar Chart with JRuby and Orson Charts

Let’s jump in!

Adding the Dependencies

Orson Charts has a Maven artifact just like JFreeChart, so we add it to our Jarfile and re-lock the dependencies.

jar 'org.jfree:jfreechart:1.5.5'
jar 'org.jfree:org.jfree.chart3d:2.1.0'

Locking is done with lock_jars as before.

jruby-charts $ lock_jars

-- jar root dependencies --

      org.jfree:jfreechart:1.5.5:compile
      org.jfree:org.jfree.chart3d:2.1.0:compile

Jars.lock updated

Importing Classes for Cleaner Code

In my previous post, I mostly just referenced classes using their Java package + class format, but for this example we’ll import the classes ahead of time. This is an optional step; you can always just reference the classes directly.

If you want to be explicit about imports, you can use java_import which assigns a constant of the same name in the current namespace.

java_import java.awt.Color
java_import java.awt.Rectangle
java_import java.awt.image.BufferedImage
java_import javax.imageio.ImageIO
java_import org.jfree.chart3d.Chart3DFactory
java_import org.jfree.chart3d.data.DefaultKeyedValues
java_import org.jfree.chart3d.data.category.StandardCategoryDataset3D
java_import org.jfree.chart3d.interaction.StandardKeyedValues3DItemSelection
java_import org.jfree.chart3d.label.StandardCategoryItemLabelGenerator
java_import org.jfree.chart3d.legend.LegendAnchor
java_import org.jfree.chart3d.marker.CategoryMarker

You can also just assign the constants yourself, if you prefer.

Color = java.awt.Color
Rectangle = java.awt.Rectangle
BufferedImage = java.awt.image.BufferedImage

Generating the Dataset from JSON

My previous post used canned data hand-entered into the dataset object, but of course you will typically read data from a database or json-formatted data source. I have created a json data file based on the revenue demo’s data:

{
  "New Relic": {
    "Q2/19": 141.0,
    "Q3/19": 146.0,
    "Q4/19": 153.0,
    "Q1/20": 160.0,

We can read it in and populate a StandardCategoryDataset3D using idiomatic Ruby code.

require 'json'

dataset = StandardCategoryDataset3D.new
data = JSON.load(File.read("data/app_monitoring_revenue.json"))
data.each do |name, subset|
  values = DefaultKeyedValues.new
  subset.each { values.put(_1, _2) }
  dataset.add_series_as_row name, values
end

Let’s construct the chart now.

Creating and Configuring a 3D Bar Chart

The Orson Charts API feels familiar if you have used JFreeChart. This example does more customization and prettier rendering than my previous simple charts. Let’s walk through it.

chart = Chart3DFactory.create_bar_chart(
  "Quarterly Revenues",
  "Application & Performance Monitoring Companies",
  dataset, nil, "Quarter",
  "$million Revenues")
chart.chart_box_color = Color.new(255, 255, 255, 127)
chart.legend_anchor = LegendAnchor::BOTTOM_RIGHT

We use Chart3DFactory to create_bar_chart with a title, subtitle, dataset, row, column, and value axis labels (row axis left empty).

plot = chart.plot
plot.gridline_paint_for_values = Color::BLACK

renderer = plot.renderer
item_label_generator =
  StandardCategoryItemLabelGenerator.new(StandardCategoryItemLabelGenerator::VALUE_TEMPLATE)
item_selection = StandardKeyedValues3DItemSelection.new
item_label_generator.item_selection = item_selection
renderer.item_label_generator = item_label_generator

Here we set the gridline color to black and set up a basic renderer for the bar labels to hide the numeric values (we’re visualizing the data, not trying to render every value in text).

That’s about it to get the basic 3D bar chart ready! The original example also includes features like highlighting a specific column, interactively browsing the data, and other features that are more suited for a rich GUI application.

Generating Output

Let’s generate a PNG image from our chart. Unlike the previous examples, the BarChart3D class does not have a convenience method for creating and drawing into a BufferedImage, so we have a few extra lines of code here.

width, height = 600, 500
category_chart_image = BufferedImage.new(width, height, BufferedImage::TYPE_INT_RGB)
category_chart_graphics = category_chart_image.create_graphics
chart.draw(category_chart_graphics, Rectangle.new(width, height))

We create an RGB BufferedImage of the specified dimentions, get a Graphics2D object from it for writing, and tell the chart to draw itself into the specified area.

Now we can write it to a file.

category_chart_file = File.open("category_chart.png", "w")
ImageIO.write(category_chart_image, "PNG", category_chart_file.to_outputstream)

And we’ve got our chart!

Finally, we should at least pretend we’re writing production code and clean up the graphics context and the open file.

category_chart_graphics.dispose
category_chart_file.close

Bonus Round!

A number of commenters also seemed to miss the real point of my article: this is just one of thousands of libraries available to JRuby users. Maybe you don’t want this chart as a PNG and want to render it in a browser as SVG? No problem!

JFreeCharts SVG Support

Using exactly the same API, you can also output SVG. First, we’ll add the additional dependency to our Jarfile.

jar 'org.jfree:jfreechart:1.5.5'
jar 'org.jfree:org.jfree.chart3d:2.1.0'
jar 'org.jfree:org.jfree.svg:5.0.6'

After locking, we can require the libraries and render the exact same chart object to an SVG file.

require_jar 'org.jfree', 'org.jfree.svg', '5.0.6'
java_import org.jfree.svg.SVGGraphics2D

svg_graphics = SVGGraphics2D.new(width, height)
svg_graphics.defs_key_prefix = "jruby_charts"
chart.element_hinting = true
chart.draw(svg_graphics, Rectangle.new(width, height))
svg = svg_graphics.get_svg_element chart.id
File.write("category_chart.svg", svg)

And there it is!

But wait, there’s more!

JFreeCharts PDF Support

PDF generation has typically been a struggle for CRuby users, with only a few working libraries, some abandoned and most incomplete. JRuby users, on the other hand, have a large number of full-featured PDF libraries available to them. In this case, JFreeChart provides its own PDF support that integrates directly into the same API.

We just add and lock the dependency in our Jarfile:

jar 'org.jfree:jfreechart:1.5.5'
jar 'org.jfree:org.jfree.chart3d:2.1.0'
jar 'org.jfree:org.jfree.svg:5.0.6'
jar 'org.jfree:org.jfree.pdf:2.0'

And render the chart to PDF:

require_jar 'org.jfree', 'org.jfree.pdf', '2.0.1'
java_import org.jfree.pdf.PDFDocument

pdf_doc = PDFDocument.new
pdf_doc.title = "Application & Performance Monitoring Companies Revenue"
pdf_doc.author = "Charles Oliver Nutter";
page = pdf_doc.create_page(Rectangle.new(612, 468))
pdf_graphics = page.graphics2D
chart.draw(pdf_graphics, Rectangle.new(0, 0, 612, 468))
File.write("category_chart.pdf", pdf_doc.pdf_bytes)

The Bottom Line

The point of these posts is not to wow you with my amazing chart-designing skills. You can get your own hands dirty with these APIs and customize them to your heart’s content. I’m a programmer, not a graphic designer!

What I really want you get out of this is that it’s easy and fun to use these libraries in JRuby… without ever leaving Ruby. We’re talking about thousands of battle-tested, production ready tools that you can integrate into your applications today. No other Ruby implementation can give you that as quickly and easily.

JRuby is being actively developed by me and the rest of the JRuby team. We’re working full-time to deliver the best possible JVM Ruby runtime that we can. I just want to continue building tools that Rubyists like you will find useful!

So, what would you like to see next?

Join the discussion on Reddit!

Creating Beautiful Charts with JRuby and JFreeChart

2025-04-30T00:00:00+00:00

I recently returned from RubyKaigi where I had the opportunity to sit down with members of the Japanese Ruby community and show them a little bit of JRuby. One of the items that came up a few times was the difficulty of utilizing external libraries from Ruby: if it’s a C library, typically you have to either write a C extension or do the extra work of writing up an FFI binding.

If the library is not implemented in C or Ruby, things get even weirder.

One example is the Charty library, one of the more popular options for generating beautiful chart graphics on Ruby. But Charty actually wraps a Python library called matplotlib, and the bindings for CRuby literally load Python into the current process and call it via Ruby C API calls which then make Python C API calls. The horror!

Also recently, a Reddit Ruby post demonstrated the use of the QuickChart library, which is implemented in JavaScript… yuck! In this case, the call-out is via process launching to the QuickChart command line, but either way it’s not at really integrated into the Ruby app using it.

Is there a better way? You bet there is: use a JVM-based library from JRuby! This post will show you how to get started with JRuby’s Java integration and a few quick examples of using the JFreeChart library from Ruby code. I promise you won’t have to write a single line of Java, C, Python, or JavaScript.

JFreeChart

The JFreeChart library provides an extensive set of chart formats, with a huge array of rendering options and easy integration with either JVM-based GUI toolkits or simple image-file output. Unlike many of the other charting libraries, it also supports live updating of a given chart GUI, making it an excellent choice for desktop monitoring tools.

Building a GUI with JRuby is fun and easy, but for this post we’ll focus on just the chart and image generation parts of the API and how you can use them easily from Ruby.

JRuby’s Java Integration

The magic starts with JRuby’s Java integration layer. The simplest way to use a Java library is to basically pretend it’s a Ruby library, with a few tweaks along the way:

Download the library’s jar file and dependencies, or use jar-dependencies (part of JRuby’s standard library) to fetch them for you.
Require the jar file and dependencies manually (a simple require "myfile.jar" works in JRuby!) or by using require_jar from jar-dependencies.
Call the Java classes you’re interested from Ruby as if they were plain old Ruby classes. You can even import them, Java-style, but it’s often not necessary.

Let’s start with a simple example.

Calling into the java.lang.Runtime class

Assuming you’ve installed JRuby 10, you can start playing with JVM libraries directly from IRB. Let’s fire it up and make sure we’re running on JRuby.

$ irb
irb(main):001> RUBY_ENGINE
=> "jruby"
irb(main):002>

The JDK comes with a large number of built-in features, of course, and I like to use the java.lang.Runtime class for quick demonstrations. It provides methods to query a bit of information about the running JVM and the host operating system. Let’s “import” it into our session and call a few methods.

irb(main):002> rt = java.lang.Runtime.runtime
=> #<Java::JavaLang::Runtime:0x39a87e72>
irb(main):003> rt.available_processors
=> 8
irb(main):004> rt.free_memory
=> 222145360

There’s a few bits of magic here that make it really feel like Ruby:

JRuby defines a few top-level methods for common Java package roots like java, javax, org, and com. We use this to reference the Java package java.lang here and access the Runtime class.
Runtime defines a static method (similar to a Ruby class or singleton method) called getRuntime which gets the singleton instance of Runtime for the current JVM process. JRuby turns Java “getter” and “setter” methods into Ruby “attribute accessors”, so you can just call Runtime.runtime here.
The Ruby calls to available_processors and free_memory translate to the Java methods getAvailableProcessors and getFreeMemory in the same way. The original methods are still callable, but we add aliases for the Ruby-friendly names.

We can accomplish a tremendous amount with the libraries shipped in the JDK, ranging from simple database access to professional desktop GUI development.

If the libraries we want to use are not shipped with the JDK, however, we need to fetch them. It’s always possible to download the library’s “jar” file directly, but then you may also have to hunt down its dependency jars. A better way is to use JRuby’s jar-dependencies library.

jar-dependencies

Like Ruby gems get pushed to rubygems.org, Java libraries get published as jar files to Maven repositories, a global, federated repository of every version of every Java library known to man. In order to make it as easy as possible to use these libraries from JRuby, we’ve built extensive Maven tooling for both Ruby and Java applications.

The simplest way to load a JVM library from Maven into your JRuby app is to use jar-dependencies, a built-in tool for fetching and managing Java dependencies in either standalone applications or in gems.

For our examples, we want to fetch JFreeChart and its dependency libraries. If we search for it at search.maven.org, we can acquire its “Maven coordinates”.

The most recently-published artifact is jfreechart 1.5.5. From here we can see the coordinates we’re looking for:

The group ID, used for namespacing libraries, is org.jfree.
The artifact ID, which identifies the library, is jfreechart.
And the version we want is 1.5.5 (Maven strongly encourages always using specific versions).

Given that, we can set up our JFreeChart project.

JRuby and JFreeChart: Happy Together!

Without knowing anything about JFreeChart, I was able to load it up and get some simple examples working from IRB just last night. I was so impressed, I decided to write this blog post!

I’ve pushed this example as headius/jruby-charts on GitHub so you can follow along.

Using jar-dependencies to fetch JFreeChart

We’ll start by creating a jar-dependencies “Jarfile”, which is roughly equivalent to Bundler’s “Gemfile”:

jar 'org.jfree:jfreechart:1.5.5'

Similar to a Gemfile’s gem name and version, we specify the Maven coordinates of the library we want (separated by colons). Once we have this file, we can fetch and “lock” this dependency with the lock_jars command.

jruby-charts $ lock_jars

-- jar root dependencies --

      org.jfree:jfreechart:1.5.5:compile

Jars.lock created

This command fetches JFreeChart and any other dependencies to your local Maven repository, which by default is in ~/.m2/repository. In general, we recommend using jar-dependencies this way, so that your jars don’t conflict with other gems’ jars, and all applications on a given system use the same set of downloaded files. It’s also possible to fetch the jars and ship them inside your application or gem, but we’ll leave that example for another day.

Let’s get to the fun stuff: using JFreeChart from Ruby!

Generating a simple bar chart

Our first example will create a simple bar chart.

First, we need to load in the jars we just downloaded and locked.

# Use jar-dependencies, included with JRuby, to load JFreeChart
require 'jar-dependencies'
require_jar 'org.jfree', 'jfreechart', '1.5.5'

At this point all of the classes of JFreeChart are available to Ruby. We start by creating a DefaultCategoryDataset which will hold our bar chart data.

# Create an empty CategoryDataSet
bar_data = org.jfree.data.category.DefaultCategoryDataset.new

JFreeChart provides a wide array of dataset types that can source data from a database, a JVM-based collection object (which includes Ruby collections), or other forms of structured data. The “default” version works nicely for a simple example. Let’s fill it with some data.

# Add values to the dataset
bar_data.add_value 44, "Ben and Jerry's", "Flavors by creamery"
bar_data.add_value 31, "Baskin Robbins", "Flavors by creamery"
bar_data.add_value 11, "Cold Stone", "Flavors by creamery"

This bar chart will display a count of ice cream flavors from three well-known purveyors of the creamery arts. The add_value method here is addValue in Java, and takes a number, a column key, and a row key.

Given our dataset, we can now request that JFreeChart create a basic bar chart for us using the ChartFactory class.

# Create a bar chart with default settings
java_import org.jfree.chart.ChartFactory
bar_chart = ChartFactory.create_bar_chart "How Many Ice Cream Flavors?",
                                          "Creamery", "Flavors", bar_data

We import the ChartFactory class for convenience (which is basically equivalent to doing ChartFactory = org.jfree.chart.ChartFactory) and then call create_bar_chart to generate a bar chart with default settings. The arguments we pass are the name of the chart, the label for the X axis, and the label for the Y axis, and our dataset.

Now that we have a chart, we can use Java’s graphics APIs (provided with the JDK by default) to output a PNG file.

# Create a buffered image in memory at 500x500
bar_image = bar_chart.create_buffered_image 500, 500

# Write the image as a PNG to a file
bar_file = File.open("barchart.png", "w")
javax.imageio.ImageIO.write(bar_image, "PNG", bar_file.to_outputstream)

JFreeChart’s bar chart type knows how to create a Java2D BufferedImage, which we can then pass to ImageIO to write it out. In this case, we even use a Ruby File as the target, using a bit of JRuby magic that turns it into a Java OutputStream!

With our jar dependencies locked and our script written, we can simply run it with JRuby from a command line.

jruby-charts $ jruby examples/barchart.rb
2025-04-30 14:58:21.744 java[84148:2288876] +[IMKClient subclass]: chose IMKClient_Modern
2025-04-30 14:58:21.744 java[84148:2288876] +[IMKInputSession subclass]: chose IMKInputSession_Modern

Depending on your platform, you may see a little bit of “helpful” JVM output indicating that the graphics subsystem has been loaded.

Let’s see what we just made!

Just a few lines of code and we’re done! Such fun!

Everyone loves pie!

The Java integration walkthrough and bar chart example above should whet your appetite for doing cool things with JRuby, but I include a pie chart example here to show a few differences:

# Use jar-dependencies, included with JRuby, to load JFreeChart
require 'jar-dependencies'
require_jar 'org.jfree', 'jfreechart', '1.5.5'

# Create an empty PieDataset
pie_data = org.jfree.data.general.DefaultPieDataset.new

# Add values to the dataset
pie_data.insert_value 0, "Fun", 0.45
pie_data.insert_value 1, "Useful", 0.25
pie_data.insert_value 2, "Cool", 0.15
pie_data.insert_value 3, "Enterprisey", 0.10
pie_data.insert_value 4, "Exciting", 0.5

# Create a pie chart with default settings
pie_chart = org.jfree.chart.ChartFactory.create_pie_chart "Why JRuby?", pie_data

# Anti-alias the chart to look a bit cleaner
pie_chart.anti_alias = true

# Access the actual PiePlot to tweak additional settings
pie_plot = pie_chart.plot
pie_plot.set_explode_percent "Fun", 0.20

# Create a buffered image in memory at 500x500
pie_image = pie_chart.create_buffered_image 500, 500

# Write the image as a GIF to a file

pie_file = File.open("piechart.gif", "w")
javax.imageio.ImageIO.write(pie_image, "gif", pie_file.to_outputstream)

This example takes advantage of a few customizations provided by JFreeChart:

The edges of the pie are set to anti-alias for a cleaner look (pie_chart.anti_alias = true, which calls setAntiAlias).
We access the actual PiePlot object to “explode” one of the elements out of the pie.
Instead of a PNG, we output a GIF, just because. The standard Java ImageIO support can handle BMP, GIF, JPEG, PNG, TIFF, and WBMP, and there’s third-party support for everything else.

And here’s the resulting pie chart:

It’s as easy as pie!

Your Turn

In this post, you learned the following:

Basics of Java integration in JRuby
How to fetch and load Java libraries from Maven
A few simple ways to create charts with JFreeChart

We didn’t have to write a single line of Java code, and we didn’t have to call out to any nasty C, Python, or JavaScript libraries. The code you see and the libraries we loaded all run in the same JVM process alongside your Ruby code, and can be easily deployed to any system with a JDK. It’s really that simple!

JFreeChart is just one charting library out of many in the Java ecosystem, and there’s thousands of other useful libraries you can start using with JRuby today. Need to generate PDFs or Office documents? Try OpenPDF or Apache Poi. Need to integrate with unusual databases? JDBC has you covered with a standard API. Want to deploy a single binary for your entire application? JRuby’s Warbler project allows you to bundle everything up as a single jar file.

Ruby faces many challenges these days, and we’re solving them one at a time with JRuby and the JVM. I hope you will experiment with JRuby yourself and create something beautiful!

Join the discussion on Reddit!

JRuby 10, Part 1: What’s New

2025-04-09T00:00:00+00:00

I am very excited to introduce you to JRuby 10, our biggest leap forward since “JRuby 9000” was released almost a decade ago.

With up-to-date Ruby compatibility, support for modern JVM features, and a big cleanup of internal code and external APIs, we believe this is our most important release ever. This article will provide a first look at these improvements and help you get started on your JRuby 10 journey.

Moving Forward

With such a long time since our last major release, we decided JRuby 10 had to make some big moves. As a result, this is the most up-to-date and powerful JRuby release we’ve ever put together. Here’s a few of the major upgrades you’ll see when you move to JRuby 10.

Compatibility jump to Ruby 3.4

It’s been over three years since we released JRuby 9.4 with Ruby 3.1 compatibility, so naturally a version update was in order. Last year we decided it made the most sense for us to target Ruby 3.4, since it would be released late in 2024 around the time we hoped to wrap up JRuby 10.

That meant implementing Ruby 3.2, 3.3, and 3.4 features, and getting literally thousands of new tests and specs passing.

CRuby core class test results

JRuby 9.4 running Ruby 3.1 tests:

4888 tests, 1859373 assertions, 0 failures, 0 errors, 22 skips

JRuby 10 running Ruby 3.4 tests:

5461 tests, 1903359 assertions, 0 failures, 0 errors, 43 skips

Over the past month, we merged our JRuby 10 development branch back to main, and just this week we finally went “green” in CI after hundreds of hours of work. We’re confident this is the most compatible a JRuby “dot zero” release has ever been, and being current on Ruby compatibility means we’ve got more time to work on aggressive optimization plans.

Java up to 21

Like many projects in the Java world, we chose to maintain support for Java 8 for over a decade after it was released, due to challenging issues involving Java 9+ and the new restrictions of the Java Platform Module System. Even though we made sure JRuby supported the latest Java releases, we could only depend upon Java 8-level features. Meanwhile the JDK added powerful enhancements like native function calls (Project Panama) and lightweight threads (Project Loom).

For JRuby 10, we’re finally updating our minimum Java version… to the most recent “long term support” version 21. Many of the JRuby features described in this post are possible because of that move.

We’ve already started to integrate the features that Java 21 provides, and we’re looking forward to bringing ten years of JVM enhancements to Ruby users.

Full optimization by default

Starting with Java 7, JRuby has supported optimizing Ruby code using a feature called “invokedynamic”, which allows us to teach the JVM how Ruby code works. “Indy” is absolutely critical for Ruby performance on JRuby, but it has also taken time to evolve at the JVM level. Because of the extra startup and warmup time required to use indy on older JVMs, JRuby ran by default in a “middle tier” of optimization, using indy only for simple Ruby operations and using slower inline caching techniques for heavier ones. Users had to enable indy with the JRuby flag -Xcompile.invokedyamic.

But no longer!

JRuby 10 runs with full invokedynamic optimization by default. That means you’ll get the best available performance for your JRuby scripts and applications without passing any additional flags.

JRuby default red/black performance, 9.4 vs 10

$ jruby9.4 -v bench/bench_red_black.rb 5
jruby 9.4.12.0 (3.1.4) 2025-02-11 f4ab75096a OpenJDK 64-Bit Server VM 21.0.5+11-LTS on 21.0.5+11-LTS +jit [arm64-darwin]
0899240000000001
632956
604672
612468
5976049999999999
$ jruby -v bench/bench_red_black.rb 5
jruby 10.0.0.0-SNAPSHOT (3.4.2) 2025-04-09 e2909f9baf OpenJDK 64-Bit Server VM 21.0.5+11-LTS on 21.0.5+11-LTS +indy +jit [arm64-darwin]
651375
46118200000000004
363622
23990799999999998
177958

For development and testing environments, where aggressive optimizations are usually not helpful and just slow down command-line use, we provide other options…

Startup time improvements

The number one complaint from JRuby users has always been startup time (and to a lesser extent, warmup time of large apps). With the leap to Java 21, we’ve started to leverage a few new JVM features to get JRuby apps starting up more quickly:

OpenJDK’s “Application Class Data Store” (AppCDS) allows pre-caching code and metadata during startup to reduce the cost of future commands. JRuby’s main executable will automatically use the right AppCDS flags on Java 21+ to optimize and cache as much as possible. This has halved the startup time of a typical JRuby command, and there’s a lot more we can do to utilize this feature.
Project CRaC (Coordinated Restore at Checkpoint) is an experimental JVM feature that allows users to “checkpoint” a running process and launch multiple future processes by restoring that checkpoint. There’s limitations, such as only being able to restore a single process at a time, but when CRaC works for you it can reduce startup time of even large apps to just a few milliseconds. The JRuby launcher supports CRaC with a few flags described in my first “JRuby on CRaC” blog post.
Project Leyden is the next-generation “AppCDS”, also storing data like JIT-compiled native code and optimization profiles from previous runs. The goal of Leyden is to eventually save off everything needed to start right up with optimized code, skipping the slow early stages of execution. The JRuby Team will incorporate Leyden flags into our launcher as they become available (with preview support already in Java 24)… and JRuby users will just have to upgrade their JDK to take advantage.

These features combined with our reduced-overhead --dev flag mean JRuby starts up faster than ever before… fast enough to take most of the pain out of command-line development.

JRuby “hello world” startup time, 9.4 vs 10

[] jruby $ time jruby9.4 --dev -e 'puts "Hello, world!"'
Hello, world!
        0.99 real         1.13 user         0.10 sys
[] jruby $ time jruby --dev -e 'puts "Hello, world!"'
Hello, world!
        0.81 real         0.91 user         0.08 sys

Getting Started

Trying JRuby has never been easier! Here’s a quick walkthrough on getting JRuby into your development toolbox.

Install a JDK

The only requirement for JRuby 10 is a Java 21 or higher JDK installation. I personally like the OpenJDK “Zulu” builds from Azul, but there’s excellent and well-supported free binaries from the Eclipse project, Amazon, Microsoft, and Oracle.

Install the JDK in whatever way is most appropriate for your platform… usually that will mean a system-level package on Linux/BSD or an installer on MacOS and Windows. Then just point your JAVA_HOME environment variable at the JDK and JRuby’s launcher will figure out the rest.

Install JRuby

Most Rubyists will be familiar with Ruby managers and switchers like rbenv, rvm, or chruby. JRuby 10 preview snapshots can be usually be installed as “jruby-head” or “jruby-dev”, and after our release as “jruby-10” or just “jruby”.

JRuby is also a JVM-based project (“write once, run anywhere”, remember?), so installing it yourself is as easy as unpacking a tarball or zip and putting the bin dir in your PATH. There’s no build step and no build tools needed to start using JRuby today.

Users of chruby can unpack this tarball into ~/.rubies since it does not support “head” installs.

Try it out

JRuby supports the standard irb REPL, as well as other modern alternatives like pry. Once you have jruby -v working, you can gem install your favorite tools and test them out on JRuby. It’s really that easy.

$ irb
irb(main):001> JRUBY_VERSION
=> "10.0.0.0-SNAPSHOT"
irb(main):002> RUBY_VERSION
=> "3.4.2"
irb(main):003> java.lang.System.get_property("java.version")
=> "21.0.5"

Riding the Rails

Ruby without Rails would be like… well I guess it would still be Ruby, but there’s no doubt Rails is still the most popular use case for Ruby. JRuby has supported Rails since the 1.x era, and we’ve worked with the Rails and JRuby community to keep up with new releases and features. JRuby represents the best way to achieve single-process multicore scaling of Rails applications, and thousands of Rails users around the world rely on it to better utilize precious computing resources.

We’ll publish a post soon that describes how to get started with JRuby on Rails, all the way from generating an app to deploying on Puma or inside a Java application server.

Rails compatibility

Keeping up with Rails is no small feat, and with only a handful of contributors we have tended to lag a bit behind. JRuby currently has database support for ActiveRecord up to 7.1, and work is ongoing to support Rails 8. If you have an interest in helping the JRuby team update our ActiveRecord adapter (ActiveRecord-JDBC, which uses the pure-JVM Java DataBase Connectivity API), please let us know! We’re hoping to have full support for Rails 8 by this summer.

Generating an app

The typical Rails commands should all work on JRuby exactly the same as on standard CRuby, and with our startup time improvements and the –dev flag, we’re able to run those commands faster than any past JRuby version.

Config changes

Only minor configuration changes are required to run a Rails app on JRuby:

Switch to the appropriate ActiveRecord-JDBC adapter for your database, in database.yml and in your Gemfile.
Configure the Puma server for a number of threads based on the CPU cores available, using “2n+1” as a good rule of thumb.
Make sure there’s enough database connections in the pool for the number of Puma threads you configure.

Once you’ve generated a new app or made config changes to your existing app, just bundle and fire it up! JRuby is a true Ruby implementation, and we work very hard to ensure Ruby libraries and applications like Rails work the same as on CRuby.

Integrating with JVM Languages

Half the fun of JRuby comes from taking advantage of the Java platform. Here’s just a few examples of things you can’t do as easily or quickly on any other Ruby implementation.

Ruby on the JVM

We’ve always had a goal of keeping JRuby a standard “JVM language”, runnable on any Java build compatible with our minimum requirement. This means you can deploy JRuby on Linux, MacOS, and Windows, of course, but also unusual and exotic platforms like the BSDs, Solaris, and more. We also can run on any hardware supported by the JVM, which basically means any system with enough memory and at least 32 bit registers is fair game.

This also means JRuby can be deployed anywhere Java applications can be deployed, alongside enterprise Java apps using Spring or Jakarta EE. Ruby and Rails developers can expand their target market to any shop that hosts JVM-based apps… which dwarfs the number of shops that would be comfortable installing the libraries and development tools necessary to run CRuby. JRuby brings the Ruby world into the enterprise, and brings enterprise opportunities to every Rubyist.

JRuby versus Ruby running threaded “tarai” benchmark

$ jruby bench_ractors_tarai.rb
                      user     system      total        real
serial           21.580000   0.070000  21.650000 ( 21.395228)
threaded         32.690000   0.100000  32.790000 (  4.260730)

$ ruby3.4 --yjit bench_ractors_tarai.rb
                      user     system      total        real
serial           25.037682   0.060370  25.098052 ( 25.257134)
threaded         24.998077   0.055508  25.053585 ( 25.058869)

Calling into Java

Part of running on the JVM is being able to integrate other languages and their libraries into your JRuby apps. With JRuby, you can call Java, Scala, Clojure, Kotlin, and any other JVM language from Ruby with ease. Imagine bring the entire world of JVM languages and libraries to your Ruby app… what could you do when that kind of power?

Using Java’s Swing GUI API from Ruby

java_import javax.swing.JFrame

frame = JFrame.new("Hello Swing")
button = javax.swing.JButton.new("Klick Me!")
button.add_action_listener do |evt|
  javax.swing.JOptionPane.showMessageDialog(nil, <<~EOS)
    <html>Hello from <b><u>JRuby</u></b>.<br>
    Button '#{evt.getActionCommand()}' clicked.
  EOS
end

# Add the button to the frame
frame.get_content_pane.add(button)

# Show frame
frame.set_default_close_operation(JFrame::EXIT_ON_CLOSE)
frame.pack
frame.visible = true

Using JVM libraries

Of course in order to use more than just the standard JDK libraries, you need to be able to download and load them into your app. JRuby provides tools like jar-dependencies to let your JRuby gems use libraries published to Maven Central, Warbler to bundle your app and libraries into a single executable jar or war file (“Web ARchive”), and an enhanced require that loads Java JAR files right into your app. It’s the easiest and most fun way to explore all that the JVM has to offer.

Want to build a cross-platform desktop UI? The JVM has a half-dozen different frameworks for building GUI applications, and with JRuby-supported libraries like Glimmer and JRubyFX, you don’t have to give up Ruby to get there.

Hello World in Glimmer

include Glimmer

shell {
  text "Glimmer"

  label {
    text "Hello, World!"
  }
}.open

Interested in building Android apps for mobile or embedded applications? JRuby provides the Ruboto framework for building Android apps in Ruby without having to write a single line of Java or Kotlin.

This also puts you on the leading edge of emerging technologies. As the JVM platform evolves and new features like Leyden, CRaC, SIMD vector operations, GPU integration and native function support in Panama move from experimental to standard, your apps can start using them with a simple JDK upgrade.

You’ve even got a leg up on adding AI capabilities to your app; Ruby APIs for ChatGPT, Claude, Copilot and others are just starting to appear, but there’s dozens of existing JVM libraries for these LLMs and other bleeding edge AI technologies. You can start using AI in your Ruby apps today with JRuby!

What’s Next?

Over the coming weeks, I’ll publish more detailed posts on each of these areas to help you get started as a new JRuby user or to upgrade your existing JRuby applications. We are very proud of the work we’ve done to bring JRuby 10 to life, and I guarantee every Ruby shop can be faster and more scalable by taking advantage of JRuby and the JVM.

Ruby’s future depends on projects like JRuby and creative developers like you. Let’s show them what we can do!

Join the discussion on Reddit!

Boosting JRuby Startup with AppCDS and AOT caching

2025-02-13T00:00:00+00:00

Hello again friends! Today I’ll show how you can improve JRuby startup right today, as well as a sneak preview of some exciting new developments in this area!

Application Class Data Store (AppCDS)

I’m still ramping up my blogging efforts, but I wanted to share the results of recent experiments using JRuby with Application Class Data Store and the new AOTCache feature being previewed in JDK 24

Around the times of Java 1.7 or 1.8, teams at Sun (and then Oracle) started shipping a JDK feature called Class Data Sharing (CDS). This was a new, specialized cache file that could be used to “pre-load” much of the runtime metadata from starting a JVM-based application. Initially, this only included the JDK’s own class metadata, but by JDK 10 a new version of the feature was made available: Application CDS, basically a Class Data Store for your own applications.

We have experimented with this feature in JRuby over the years, but the user experience has been cumbersome and the file can get stale if you reinstall JRuby or switch to a different JDK. That appears to be improving with recent JDK releases.

Automatic CDS with JRuby 10

In JDK 21, we can now request that the AppCDS archive be generated automatically, and then use it each time we start up. Here’s JRuby without any help from AppCDS:

$ time jruby -e 1
  2.35s user 0.16s system 165% cpu 1.518 total
$ time jruby -e 1
  2.73s user 0.21s system 183% cpu 1.603 total
$ time jruby -e 1
  2.37s user 0.14s system 180% cpu 1.385 total
$ time jruby --dev -e 1
  1.14s user 0.10s system 118% cpu 1.045 total
$ time jruby --dev -e 1
  1.19s user 0.10s system 120% cpu 1.067 total
$ time jruby --dev -e 1
  1.17s user 0.11s system 123% cpu 1.034 total

And JRuby with experimental “automatic” CDS support:

$ time jruby -e 1
  1.81s user 0.11s system 184% cpu 1.044 total
$ time jruby -e 1
  1.95s user 0.12s system 192% cpu 1.078 total
$ time jruby -e 1
  1.80s user 0.11s system 188% cpu 1.011 total
$ time jruby --dev -e 1
  0.93s user 0.09s system 121% cpu 0.837 total
$ time jruby --dev -e 1
  0.95s user 0.09s system 119% cpu 0.878 total
$ time jruby --dev -e 1
  0.94s user 0.09s system 121% cpu 0.844 total

That’s a huge improvement you’ll get for free on JRuby 10! But today I also want to look at the new preview of AOT caching (Ahead Of Time data and code caching) in JDK24.

AOT Caching from Project Leyden

OpenJDK’s Project Leyden has been working for the past several years on bringing AOT (Ahead-of-Time compilation) to the JVM without the limitations of a closed-world system like GraalVM’s Native Image. The general feature is being called the “AOT cache”, but there’s a lot to unpack here.

AOT caching is similar to AppCDS in that it caches class files and their metadata, but it will eventually include optimization artifacts such as:

Code profiles from previous runs, so we can jump into optimization earlier;
Native code produced by the JIT for hot classes and methods during a training run;

These efforts are starting to bear fruit, and JDK24 includes the first version of AOT caching: Ahead-of-Time Class Loading and Linking.

How does this early version of AOT caching stack up against AppCDS?

JRuby and JDK24 AOTCache

So given our numbers above for JRuby startup, let’s try JRuby with JDK24’s AOT caching.

First we need to run JDK24 with AOT caching flags that record training data. In this case, I make JRuby start up additional instances of itself repeatedly in a loop. (The --nocache flag here disables automatic AppCDS)

$ jruby --nocache -J-XX:AOTMode=record -J-XX:AOTConfiguration=lib/jruby.aotconf -e '1000.times { r = org.jruby.Ruby.newInstance; r.evalScriptlet(%[require "rubygems"]); r.tearDown }'
$ jruby --nocache -J-XX:AOTMode=create -J-XX:AOTConfiguration=lib/jruby.aotconf -J-XX:AOTCache=lib/jruby.aot -e '100.times { org.jruby.Ruby.newInstance.tearDown }'
[2.506s][warning][cds] java.lang.ClassNotFoundException: DashE
[2.506s][warning][cds] Preload Warning: Cannot find DashE
[2.809s][warning][cds] Skipping jdk/internal/event/Event: JFR event class
AOTCache creation is complete: lib/jruby.aot

A few warnings later and we have an AOT cache of JRuby startup code. Here’s the same baseline -e 1 calls from above, but this time using the AOT cache:

$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot -e 1
  2.73s user 0.17s system 277% cpu 1.047 total
$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot -e 1
  2.87s user 0.16s system 286% cpu 1.058 total
$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot -e 1
  2.82s user 0.14s system 279% cpu 1.057 total
$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot --dev -e 1
  0.84s user 0.08s system 126% cpu 0.732 total
$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot --dev -e 1
  0.85s user 0.07s system 127% cpu 0.722 total
$ time jruby --nocache -J-XX:AOTCache=lib/jruby.aot --dev -e 1
  0.85s user 0.07s system 127% cpu 0.722 total

We have a new winner for JRuby startup time! (ignoring more restricted options like JRuby on CRaC, which will see a Part 2 post real soon!)

How Can I Use This Today?

JRuby 9.4 users on Java 11 or higher can use AppCDS today, and with JDK24 you can also experiment with AOT caching.

JRuby 9.4 and AppCDS

All you need to try AppCDS on JRuby is to generate the AppCDS archive (lib/jruby.jsa):

Make sure you’re running JDK11 or higher.
gem install jruby-startup
generate-appcds

$ gem install jruby-startup
Successfully installed jruby-startup-0.0.6
1 gem installed
$ generate-appcds
...
*** Success!

JRuby versions 9.2.1 or higher should detect /Users/headius/work/jruby/lib/jruby.jsa and use it automatically.
For versions of JRuby 9.2 or earlier, set the following environment variables:

VERIFY_JRUBY=1
JAVA_OPTS="-XX:G1HeapRegionSize=2m -XX:SharedArchiveFile=/Users/headius/work/jruby/lib/jruby.jsa"
$ time jruby --dev -e 1
  0.92s user 0.09s system 118% cpu 0.807 total
$ time jruby --dev -e 1
  0.93s user 0.09s system 121% cpu 0.838 total
...

The jruby.jsa file is automatically passed to the JVM when you start JRuby, boosting startup as seen at the top of this post. Newer JDKs will see a bigger improvement!

JRuby 9.4 and JDK24 AOT Caching

You’ll need to install a build of JDK24, which just dropped a release candidate last week (Feb 6).

The same flags shown above will work with JRuby 9.4, but there’s no --nocache flag to disable automatic CDS. Just make sure you delete the lib/jruby.jsa file before playing with AOT caching on JRuby 9.4.

Have fun, and let us know how it goes!