jiface

Erlang's JInterface in Idiomatic Clojure

Contents

• Introduction
• Dependencies
• Building
• Documentation
• Usage
• Running Tests
• Erlang, Clojure, and JInterface
• Donating
• License

Introduction ↟

This project provides a solution to the Clojure JInterface Problem. While JInterface is an invaluable tool for projects that need to have JVM and Erlang VM languages communicating with each other, it is rather verbose and cumbersome to do so in Clojure. The syntactical burden is often enough to discourage experimentation and play (essential ingredients for innovation). The primary goal of jiface is to make it easier to write Clojure programs that need to communicate with Erlang nodes (including LFE and Elixir).

For a comparison of JInterface, the low-level jiface API, and the high-level clojang API, see the APIs summary page.

Changes ↟

For details on breaking changes made between jiface releases, see the changes page.

Dependencies ↟

• Java
• Erlang (epmd in particular)
• lein

The default (and tested) version combinations are as follows:

jiface	JInterface	Erlang Release	Erlang Version (erts)
0.6.1	1.9.1	21.3	10.3
0.6.0	1.9	21.0	10
0.5.0	1.8.1	20.3	9.3
0.4.0	1.7.1	19.2, 19.3	8.2, 8.3
0.3.0	1.7.1	19.2	8.2
0.2.0	1.7.1	19.1, 19.2	8.1, 8.2
0.1.0	1.6.1	18.2, 18.3	7.2, 7.3

While other version combination may work (and existing versions may be updated to work with different onces), those are the only ones which are supported.

Versions notes:

• The lein dep for the jiface 0.6.1 release is [clojang/jiface "0.6.1-1"]
• The lein dep for the JInterface 1.9.1 release is [clojang/erlang-jinterface "1.9.1-3"]

Building ↟

rebar3 is used for the top-level builds of the project. It runs lein under the covers in order to build the Clojure code and create the jiface.jar file. As such, to build everything -- LFE, Erlang, and Clojure -- you need only do the following:

• rebar3 compile

If you wish to build your own JInterface .jar file and not use the one we've uploaded to Clojars, you'll need to follow the instructions given in the documentation here:

• Building JInterface for Clojure

Documentation ↟

Project documentation, including jiface API reference docs, Javadocs for JInterface, and the Erlang JInterface User's Guide, is available here:

• http://clojang.github.io/jiface/current/

Of particular note:

• jiface User's Guide - A translation of the JInterface User's Guide (Erlang documentation) from Java into Clojure
• JInterface User's Guide - The JInterface documentation provided in Erlang distributions
• JInterface Javadocs - Javadoc-generated API documentation built from the JInterface source code

High-level API docs:

• Clojang User's Guide - An adaptation of the jiface User's Guide for the mid-level idiomatic Clojure API

Usage ↟

Using jiface in a project is just like any other Clojure library. Just add the following to the :dependencies in your project.clj file:

For the Erlang/LFE side of things, you just need to add the Github URL to your rebar.config file, as with any other rebar-based Erlang VM project.

As for actual code usage, the documentation section provides links to developer guides and API references, but below is quick example.

Start LFE in distributed mode:

$ lfe -sname clojang-lfe
Erlang/OTP 18 [erts-7.3] [source] [64-bit] [smp:4:4] [async-threads:10] ...

   ..-~.~_~---..
  (      \\     )    |   A Lisp-2+ on the Erlang VM
  |`-.._/_\\_.-';    |   Type (help) for usage info.
  |         g (_ \   |
  |        n    | |  |   Docs: http://docs.lfe.io/
  (       a    / /   |   Source: http://github.com/rvirding/lfe
   \     l    (_/    |
    \   r     /      |   LFE v0.11.0-dev (abort with ^G)
     `-E___.-'

(clojang-lfe@mndltl01)>

Then start up a jiface Clojure REPL:

$ lein repl

And paste the following:

(require '[jiface.otp.messaging :as messaging]
         '[jiface.otp.nodes :as nodes]
         '[jiface.erlang.types :as types]
         '[jiface.erlang.tuple :as tuple-type])
(def node (nodes/node "gurka"))
(def mbox (messaging/mbox node))
(messaging/register-name mbox "echo")
(def msg (into-array
           (types/object)
           [(messaging/self mbox)
            (types/atom "hello, world")]))
(messaging/! mbox "echo" "gurka" (types/tuple msg))
(messaging/receive mbox)

When you paste the receive function, you'll get something like this:

#object[com.ericsson.otp.erlang.OtpErlangTuple
        0x4c9e3fa6
        "{#Pid<gurka@mndltl01.1.0>,'hello, world'}"]

In the LFE REPL, you can send a message to your new Clojure node:

(lfe@mndltl01)> (! #(echo gurka@mndltl01) `#(,(self) hej!))
#(<0.35.0> hej!)

Then back in Clojure, check the sent message and send a response:

(def data (messaging/receive mbox))
(def lfe-pid (tuple-type/get-element data 0))
(messaging/! mbox lfe-pid (types/tuple msg))

Then, back in LFE, flush the REPL's process mbox to see what has been sent to it:

(lfe@mndltl01)> (c:flush)
Shell got {<5926.1.0>,'hello, world'}
ok

Running Tests ↟

All the tests may be run with just one command:

$ rebar3 eunit

This will not only run Erlang and LFE unit tests, it also runs the Clojure unit tests for jiface.

Clojure Test Selectors

If you would like to be more selective in the types of jiface tests which get run, you may be interested in reading this section.

The jiface tests use metadata annotations to indicate whether they are unit, system, or integration tests. to run just the unit tests, you can do any one of the following, depending upon what you're used to:

$ lein test
$ lein test :unit
$ lein test :default

To run just the system tests:

$ lein test :system

And, similarly, just the integration tests:

$ lein test :integration

To run everything:

$ lein test :all

This is what is used by the rebar3 configuration to run the jiface tests.

Erlang, Clojure, and JInterface ↟

If you are interested in building your own JInterface .jar file for use with a Clojure project, be sure fo check out the jinterface-builder Clojang project. The project README has everything you need to get started.

Donating ↟

A donation account for supporting development on this project has been set up on Liberapay here:

• https://liberapay.com/clojang/donate

You can learn more about Liberapay on its Wikipedia entry or on the service's "About" page.

License ↟

Copyright © 2018 The Clojang Project

Copyright © 2016-2017 Duncan McGreggor

Distributed under the Apache License Version 2.0.