Implement JRuby methods in Java

Setting up the project

This example uses the Gradle build system. Its dependency management is capable of retrieving Java libraries from Maven central or JCenter and making them available to the project. External libraries for Ruby are distributed as gems that are archives containing the Ruby code, documentation and a gem specifier. Gradle by itself is not able to download them from rubygems.org nor is JRuby able to consume gem archives that are available in the classpath as Java can with Jars. Therefore we use the JRuby Gradle Plugin. This awesome plugin will automatically download and unpack all dependencies that are defined for the gems configuration. By default this plugin will manage the gems in the build/vendor directory and you can find the unpacked content in build/vendor/gems. Our required gems have to be available in the runtime classpath. Therefore we also copy them to the build/resources so that it is available during the test but also in the resulting jar.

The following simple build.gradle sets up the project to load the Semantic Logger gem and make it available to the embedded JRuby runtime.

plugins {
    id 'com.github.jruby-gradle.base' version '0.1.11' (1)
}

apply plugin: 'java'

sourceCompatibility = 1.8
version = '1.0'

repositories {
    jcenter()
}

dependencies {
    compile group: 'org.jruby', name: 'jruby-complete', version: '1.7.18'
    gems 'rubygems:semantic_logger:2.11.0' (2)
}

def gemFiles = fileTree(jruby.gemInstallDir) {
    include 'specifications/*.gemspec'
    include 'gems/*/lib/**'
}

task copyGems(type:Copy) { (3)
    from gemFiles
    into sourceSets.main.output.resourcesDir
    dependsOn jrubyPrepareGems
}

processResources.dependsOn copyGems (4)

Apply the JRuby Gradle Plugin. This plugin downloads the required gems to the directory build/vendor. The plugins configuration element leverages the Gradle Plugin Model to automatically download and apply community plugins.
Required gems are defined using the gems configuration. The groupId is always rubygems while the name of the dependency is the name of the gem.
The copyGems task copies the gem files from the `build/vendor`directory to the resources dir so that they are available in the in the test classpath and will be packaged in the resulting jar of this project.
Finally the copyGems task is hooked into the build so that it is invoked during the build.

The following Java program embeds the example from above in a simple Java program. It should write a log entry with the message Hello World to the console.

import org.jruby.Ruby;
import org.jruby.embed.ScriptingContainer;

public class LogHelloWorld {

    public static void main(String[] args) {

        ScriptingContainer scriptingContainer = new ScriptingContainer();
        Ruby ruby = scriptingContainer.getProvider().getRuntime();

        ruby.evalScriptlet("require 'semantic_logger'");

        ruby.evalScriptlet(
                "logger = SemanticLogger['Hello']\n" +
                "SemanticLogger.default_level = :debug\n" +
                "SemanticLogger.add_appender(STDOUT, :debug)\n" +
                "logger.info 'Hello World'\n" +
                "SemanticLogger.flush");
    }
}

After having set up the build we are now ready to implement our logging adapter by following the list mentioned above. A JUnit test will prove that our code works.

Inherit from SemanticLogger::Appender::Base

This task is straightforward. Instead of inheriting from Rubys Object class as shown in my last post we get a handle to the SemanticLogger::Appender::Base and define this one as the parent class. The Ruby appender class will be called Foo::Bar::JavaSemanticLoggerAppender. It will be backed by the Java class foo.bar.SemanticLoggingJavaAppender. Registration and adding the methods to the class will be done in the static method SemanticLoggingJavaAppender.registerType so that our Java implementation initially looks like this:

package foo.bar;

import ...

public class SemanticLoggingJavaAppender extends RubyObject {

    public static void registerType(Ruby ruby) {

        RubyModule semanticLoggerModule = ruby.getModule("SemanticLogger");
        RubyModule appenderModule = semanticLoggerModule.defineOrGetModuleUnder("Appender"); (1)

        RubyClass baseClass = appenderModule.getClass("Base"); (2)

        RubyModule fooModule = ruby.getOrCreateModule("Foo");
        RubyModule barModule = fooModule.defineModuleUnder("Bar");

        RubyClass extendedClass = barModule.defineClassUnder( (3)
                "JavaSemanticLoggerAppender",
                baseClass,
                new ObjectAllocator() {
                    @Override
                    public IRubyObject allocate(Ruby ruby, RubyClass rubyClass) {
                        return new SemanticLoggingJavaAppender(ruby, rubyClass);
                    }
                });

        extendedClass.defineAnnotatedMethods(SemanticLoggingJavaAppender.class); (4)
    }

    public SemanticLoggingJavaAppender(Ruby ruby, RubyClass rubyClass) {
        super(ruby, rubyClass);
    }

}

Get the module that contains the base class and that should contain our Ruby class.
Get the Ruby base class of our appender implementation.
Define the new Ruby appender class named Foo::Bar::JavaSemanticLoggerAppender that is backed by the Java class foo.bar.SemanticLoggingJavaAppender.
Make all methods annotated with @JRubyMethod of the class SemanticLoggingJavaAppender available to Ruby.

Now an appender can already be created and added to the Semantic Logger framework like this:

ScriptingContainer scriptingContainer = new ScriptingContainer(); (1)
ruby = scriptingContainer.getProvider().getRuntime();

ruby.evalScriptlet("require 'semantic_logger'"); (2)
SemanticLoggingJavaAppender.registerType(ruby); (3)
ruby.evalScriptlet(
        "SemanticLogger.add_appender Foo::Bar::JavaSemanticLoggerAppender.new"); (4)

Initialize the JRuby runtime.
Require the Semantic Logger gem, so we can use it in Ruby.
Register our appender class to the JRuby runtime.
Add a new appender to Semantic Logger that is an instance of our new class.

Implement the log method

When something is logged via Semantic Logger the method log is called on every appender passing a Log struct that contains all infos like the timestamp, the log level, the log message itself etc. So before we implement the log method we implement an interface LogEvent that will be the Java counterpart of the Ruby struct Log that is described in http://reidmorrison.github.io/semantic_logger/log_struct.html. Wrapping this struct behind the interface below is simply achieved using JavaEmbedUtils.rubyToJava().

package foo.bar;

import java.util.Date;

public interface LogEvent {

    String getLevel();

    String getThreadName();

    String getName();

    String getMessage();

    Object getPayload();

    Date getTime();

    float getDuration();

    Object getException();
}

Our appender should forward all log events to Java Util Logging. Therefore the log method will:

mask the argument using this interface
create a java.util.logging.LogRecord from this LogEvent.
log this LogRecord

package foo.bar;

import ...

public class SemanticLoggingJavaAppender extends RubyObject {

    private static List<LogEvent> logEvents = new ArrayList<LogEvent>();

    public SemanticLoggingJavaAppender(Ruby ruby, RubyClass rubyClass) {
        super(ruby, rubyClass);
    }

    @JRubyMethod(name = "log", required = 1) (1)
    public void handleLogEvent(ThreadContext context, IRubyObject log) {
        LogEvent logEvent =
            (LogEvent) JavaEmbedUtils.rubyToJava(context.getRuntime(), log, LogEvent.class); (2)

        LogRecord logRecord = createJULLogRecordFromLogEvent(logEvent); (3)

        Logger.getLogger(logEvent.getName()).log(logRecord); (4)
    }

    private LogRecord createJULLogRecordFromLogEvent(LogEvent logEvent) {
        Level level;
        switch (logEvent.getLevel()) {
            case "trace":
                level = Level.FINEST;
                break;
            case "debug":
                level = Level.FINE;
                break;
            case "info":
                level = Level.INFO;
                break;
            case "warn":
            case "error":
                level = Level.WARNING;
                break;
            case "fatal":
                level = Level.SEVERE;
                break;
            default:
                throw new IllegalArgumentException("Level: " + logEvent.getLevel());
        }
        LogRecord logRecord = new LogRecord(level, logEvent.getMessage());
        logRecord.setLoggerName(logEvent.getName());
        logRecord.setSourceClassName(logEvent.getName());
        return logRecord;
    }

    public static void registerType(Ruby ruby) { /* Already shown above */ }
}

The log event expects one argument. Therefore the @JRubyMethod annotation declares one required parameter. As the method called by Semantic Logger must be called log this name is set on the name argument to the @JRubyMethod annotation. The name of the Java method is irrelevant to JRuby in this scenario.
Get a Java handle for the Log struct so that we can access its fields.
Create a java.util.logging.LogRecord from the LogEvent.
Forward the log event to the corresponding JUL logger.

Implement the initializer

For us there is actually no need to connect to any external resources in this scenario. But in this case as we are in one way or another all Java developers we will nevertheless implement an object initializer that calls its super implementation. The base class SemanticLogger::Appender::Base has an object initializer that takes 2 optional arguments and a block:

A symbol for the level that can be passed to the appender to tell it that all lower log levels should be ignored.
A filter in form of a regexp or a proc that filters log events.
A block that should be used to format a log event.

It is the task of the appender to use all these parameters and in our constellation we don’t need it. But for demonstration purposes we want to implement this object initializer.

The object initializer in Ruby has the name initialize. Therefore the name argument to the @JRubyMethod annotation must have the value initialize. As the initializer takes up to 2 optional arguments and a block the value of the optional parameter must be 2 and the value of the required parameter must be 0. To invoke the super implementation we use the library method org.jruby.runtime.Helpers.invokeSuper. So the implementation of the initialize method looks like this:

package foo.bar;

import ...

public class SemanticLoggingJavaAppender extends RubyObject {

    public SemanticLoggingJavaAppender(Ruby ruby, RubyClass rubyClass) {
        super(ruby, rubyClass);
    }

    @JRubyMethod(name = "log", required = 1)
    public void handleLogEvent(ThreadContext context, IRubyObject log) {...}

    @JRubyMethod(name = "initialize", required = 0, optional = 2) (1)
    public void initAppender(ThreadContext context, IRubyObject[] args, Block block) { (2)

        Helpers.invokeSuper(context, this, getMetaClass(), "initialize", args, block); (3)

    }

    public static void registerType(Ruby ruby) {...}
}

As described above the method must be called initialize and it takes 0 required and 2 optional arguments. The block is not declared in the annotation because you can always pass a block to a Ruby method. If you want to have access to this block you simply add it to the methods argument list.
As we have optional arguments we get the parameters as an object array. The optional block is passed via the last parameter of type Block.
We invoke the super implementation of the initialize via Helpers.invokeSuper.

When calling invokeSuper we have to pass

the current ThreadContext
the reference to self or this
the Ruby class of this
the method name to be invoked which must match the name of the current method, i.e. initialize
the arguments to be passed to the super implementation
the block that should be passed to the super implementation as well.

In contrast to Helpers.invoke the method invokeSuper that we call looks at the current call that is being executed and tries to find a matching implementation in the ancestors.

Testing it

Testing our logging adapter is quite easy. We simply implement a JUL test handler that stores all LogRecords it receives in a list. The JUnit test case adds this handler to the JUL root logger, calls Semantic Logger to log a test message and finally checks if the test handler has received a matching LogRecord.

package foo.bar;

import ...

public class WhenJavaLoggerIsRegistered {

    private static Ruby ruby;

    private static Logger rootLogger = Logger.getLogger("");

    @BeforeClass
    public static void setupJRuby() { (1)
        ScriptingContainer scriptingContainer = new ScriptingContainer();
        ruby = scriptingContainer.getProvider().getRuntime();

        ruby.evalScriptlet("require 'semantic_logger'");
        SemanticLoggingJavaAppender.registerType(ruby);
    }

    @Before (2)
    public void setup() throws Exception {
        ruby.evalScriptlet("SemanticLogger.add_appender Foo::Bar::JavaSemanticLoggerAppender.new");
    }

    @After (3)
    public void cleanup() {
        ruby.evalScriptlet("SemanticLogger.appenders.each {|appender| SemanticLogger.remove_appender appender}");

        Stream.of(rootLogger.getHandlers())
            .filter(handler -> handler instanceof TestHandler)
            .forEach(rootLogger::removeHandler);
    }

    @Test
    public void should_invoke_appender() throws Exception {
        // Given:
        TestHandler testHandler = new TestHandler();    (4)
        LogManager.getLogManager().getLogger("").addHandler(testHandler);
        // When:
        ruby.evalScriptlet("SemanticLogger['Hello'].info 'Hello World'"); (5)

        ruby.evalScriptlet("SemanticLogger.flush");

        // Then:
        assertThat(testHandler.getAllLogRecords(), hasSize(1)); (6)
        assertThat(testHandler.getAllLogRecords().get(0).getLevel(), is(Level.INFO));
        assertThat(testHandler.getAllLogRecords().get(0).getMessage(), is("Hello World"));
        assertThat(testHandler.getAllLogRecords().get(0).getLoggerName(), is("Hello"));
    }
}

As shown before we setup the Ruby environment and register our logging adapter
Before every test we add an instance of the logging adapter as a handler for Semantic Logger
After every test we remove our Semantic Logger appender as well as our JUL test handler.
First step of the test is adding a test handler to JUL. If everything works fine this handler will receive a LogRecord.
This is what we test: We log something in Ruby using Semantic Logger.
Finally we check that everything worked as expected, the test handler should have received a LogRecord with the matching log level and message.

The rules behind it: Implementing Ruby methods in Java

The rules that have to be taken care of when implementing Ruby methods in Java are not too complicated but it is worth knowing them. You will also find them at https://github.com/jruby/jruby/wiki/JRubyMethod_Signatures.

For most use cases the @JRubyMethod annotation has 3 parameters:

name: This string contains the method name as it is available in Ruby.
required: This int contains the number of required parameters. That is parameters that have no defaults in Ruby.
optional: This int contains the number of optional parameters, that is parameters that have defaults. In contrast to Ruby there is no way to define the defaults in the method signature but it is up to the implementation to apply defaults for undefined parameters.

The Java method should conform to these rules:

The method should declare IRubyObject as its return type.
The name of the method is not important and has no relation to the name how it is called from Ruby.
The parameter list may start with a ThreadContext that gives access to the JRuby runtime and many other properties. Although optional I found it good practice to always declare this formal parameter.
If the method is static the next parameter should be an IRubyObject that points to self. This parameter is not declared for instance methods.
If the method has 1 or 2 required and no optional parameters 1 or 2 IRubyObject parameters follow.
In case of optional parameters or more than 3 required parameters the parameter list must contain an IRubyObject[] that will exactly contain as many arguments as were passed by the caller and not as this method supports.
If your implementation wants to handle Blocks the parameter list may be finalized by a parameter of type org.jruby.runtime.Block.

Note

The JRuby Wiki states that for up to 3 required and optional parameters you may define single IRubyObject parameters, but for me it always ended up in exceptions saying "Combining specific args with IRubyObject[] is not yet supported". Therefore with optional or more than three required parameters I always use the argument array, i.e. one parameter of type IRubyObject[].

Defining a Ruby method f that takes one required, no optional parameters and no Block could look like this:

@JRubyMethod(name="f", required=1)
public IRubyObject rubyMethodF(ThreadContext context, IRubyObject arg0) { ... }

A method with one required parameter, two optional parameters and a Block would look like this:

@JRubyMethod(name="g", required=1, optional=2)
public void rubyMethodG(ThreadContext context, IRubyObject[] args, Block block) {...}

Implement JRuby methods in Java

Setting up the project

Inherit from `SemanticLogger::Appender::Base`

Implement the log method

Implement the initializer

Implement the `flush` method

Testing it

The rules behind it: Implementing Ruby methods in Java

Implement JRuby methods in Java

Setting up the project

Inherit from SemanticLogger::Appender::Base

Implement the log method

Implement the initializer

Implement the flush method

Testing it

The rules behind it: Implementing Ruby methods in Java

Inherit from `SemanticLogger::Appender::Base`

Implement the `flush` method