We described Erlang nodes in Chapter 11, where we also introduced distributed programming in Erlang. An Erlang node is identified by its name, which consists of an identifier with a hostname (in short or long form); each host can run a number of nodes, if their names are different.

The OtpNode class gives the JInterface representation of an Erlang node:

OtpNode bar = new OtpNode("bar");

This creates the Java object bar—which we’ll call a node—that represents the Erlang node bar, running on the host where the statement is executed.

You can create a process on this node by creating a mailbox, which is represented by a pid or can be registered to a name. To create the process, use:

OtpMbox mbox = bar.createMbox();

which gives the process a name on creation. Then, pass in the name as a string on construction:

OtpMbox mbox = bar.createMbox("facserver");

You can also do this separately from the creation of the mailbox using the following statement:

mbox.registerName("facserver");

This creates a named process called facserver. The process will act as a “factorial server,” sending the factorial of the integers that it receives to the processes that have sent the integers.

Once you’ve named the mailbox, you can access it using its name. If its pid is also required—perhaps by a remote Erlang node—use the self method on the mailbox:

OtpErlangPid pid = mbox.self();

The JInterface package contains a variety of classes that represent, in Java, various Erlang types. Their methods allow the conversion of native Java types to and from these representation types, supporting the conversion of values between the two languages, which is essential for them to work together effectively.

You saw an example of this in the preceding Java statement: the class OtpErlangPid gives the Java representation of an Erlang pid. The mapping between Erlang types of atoms, binaries, lists, pids, ports, refs, tuples, and terms is to the corresponding Java class OtpErlangAtom, ..., OtpErlangTuple, OtpErlangObject.

Floating-point types in Erlang are converted to either OtpErlangFloat or OtpErlangDouble; integral types are converted to OtpErlangByte, OtpErlangChar, OtpErlangShort, OtpErlangInt, OtpErlangUInt, or OtpErlangLong, depending on the particular integral value and sign.

To represent the two special atoms true and false, there is the OtpErlangBoolean class, and Erlang strings—which are lists of integers in Erlang—are described by OtpErlangString.

The details of these classes are in the JInterface documentation; we will use the classes in the next section as well as in the RPC example.

Erlang processes send and receive messages, and in JInterface, these operations are provided by the send and receive methods on a mailbox. The interchanged messages are Erlang terms, and are therefore represented by OtpErlangObjects in Java. The following Erlang send message:

Pid ! {ok, M}

in the mbox process is given by:

mbox.send(pid,tuple);

where the pid variable in Java corresponds to the Pid variable in Erlang, and tuple^[37] represents the Erlang term {ok, M}.

A message is received by:

OtpErlangObject o    = mbox.receive();

This statement differs from an Erlang receive in that it performs no pattern matching on the message. Deconstruction and analysis of the message follow separately; we’ll show this in the next example.

The following Erlang code sets up a factorial server on the node called bar on the host STC:

setup() ->
  spawn('bar@STC',myrpc,server,[]).

server() ->
  register(facserver,self()),
  facLoop().

facLoop() ->
  receive
    {Pid, N} ->
      Pid ! {ok, fac(N)}
  end,
  facLoop().

The server receives messages of the form {Pid, N} and sends the result {ok, fac(N)} back to the Pid. The next code sample accomplishes the same thing in Java:

1 import com.ericsson.otp.erlang.*;  // For the JInterface package
2 import java.math.BigInteger;       // For factorial calculations
3
4 public class ServerNode {
5
6    public static void main (String[] _args) throws Exception{
7
8       OtpNode bar = new OtpNode("bar");
9       OtpMbox mbox = bar.createMbox("facserver");
10
11       OtpErlangObject o;
12       OtpErlangTuple  msg;
13       OtpErlangPid    from;
14       BigInteger      n;
15       OtpErlangAtom   ok = new OtpErlangAtom("ok");
16
17       while(true) try {
18           o    = mbox.receive();
19           msg  = (OtpErlangTuple)o;
20           from = (OtpErlangPid)(msg.elementAt(0));
21           n    = ((OtpErlangLong)(msg.elementAt(1))).bigIntegerValue();
22           OtpErlangObject[] reply = new OtpErlangObject[2];
23           reply[0] = ok;
24           reply[1] = new OtpErlangLong(Factorial.factorial(n));
25           OtpErlangTuple tuple = new OtpErlangTuple(reply);
26           mbox.send(from,tuple);
27
28       }catch(OtpErlangExit e) { break; }
29    }
30 }

In the preceding example, the concurrent aspects are shown in bold in lines 8, 9, 18, and 26; the remaining code is used to analyze, deconstruct, and reconstruct data values, as well as providing the control loop.

The main program starts by running a node bar, and a process facserver on that node. In the main loop, lines 18–26, a message is received and replied to. The message received is an Erlang term, that is, an OtpErlangObject. This is cast to an OtpErlangTuple in line 19, and from this the pid of the sender (line 20) and the integer being sent (line 21) can be extracted. In line 21, the Erlang value is extracted as a long integer, but is converted to a Java BigInteger to allow an accurate calculation of the factorial.

The remainder of the code (lines 22–26) constructs the reply tuple and sends it. Line 22 constructs an array of objects, containing the (representation of the) atom ok (line 23) and the return value factorial(n) (line 24). This is then converted into a tuple (line 25), before finally being sent back to the client in line 26.

To interact with the running Java node, you can use the following code, calling myrpc:f/1 at the prompt:

-module(myrpc).
 ...
f(N) ->
  {facserver, 'bar@STC'} ! {self(), N},
    receive
      {ok, Res} ->
        io:format("Factorial of ~p is ~p.~n", [N,Res])
    end.

This client code is exactly the same as the code that is used to interact with an Erlang node, and a “Turing test”^[38] that sends messages to and from a node should be unable to tell the difference between a Java node and an Erlang node.

In this section, we will explain how to get programs using JInterface to run correctly on your computer.

First, to establish and administer connections between the Java and Erlang nodes it is necessary that epmd (the Erlang Port Mapper Daemon) is running when a node is created. You will recall epmd from Chapter 11. You can run it simply by typing epmd (epmd.exe on Windows), but you can test whether it is already running by typing the following:

epmd -names

This will list all the names of the running Erlang nodes on the host. This command is useful for checking whether a node you think should be running actually is running.

The system will create a node with the default cookie if none is supplied when the node is started. This may be OK, but if you need to create a node with a given cookie, use the following:

OtpNode bar = new OtpNode("bar", "cookie-value");

If a particular port needs to be used, this is the third argument of a three-argument constructor.

Referring back to the program in the section Putting It Together: RPC Revisited, line 1 of the program ensures that the JInterface Java code is imported, but since it is included in the OTP distribution and not in the standard Java, it is necessary to point the Java compiler and runtime to where it is held, which is in the following:

<otp-root>/jinterface-XXX/priv/OtpErlang.jar

In the preceding code, <otp-root> is the root directory of the distribution, given by typing code:root_dir() within a running node, and XXX is the version number. On Mac OS X the full path is:

/usr/local/lib/erlang/lib/jinterface-1.4.2/priv/OtpErlang.jar

This value is supplied thus to the compiler:

javac -classpath ".:/usr/local/lib/erlang/lib/
  jinterface-1.4.2/priv/OtpErlang.jar" ServerNode.java

and to the Java system:

java -classpath ".:/usr/local/lib/erlang/lib/
  jinterface-1.4.2/priv/OtpErlang.jar" ServerNode

The JInterface library has more extensive capabilities than you have seen so far:

These and other features are described in more detail in the online documentation.

The C node you just saw is running as a client: it can make connections to Erlang nodes. It can also run as a server mode; this requires first that the program creates a socket—listening on a particular port number—and then that it publishes the socket by means of epmd. This program can then accept connections from Erlang nodes.

The erl_interface library provides various other facilities, such as pattern matching on incoming messages, the registry system for storing key-value pairs, and a global naming scheme. All of these, plus the server-style node, are covered in the Interoperability Tutorial and in the user’s guide for the erl_interface library.

To open an Erlang port, you use the open_port/2 command:

open_port({spawn, Cmd}, Options)

This will run the command Cmd as an external program; this external program is spawned with the given list of Options. Here is a list of the main options available (you can find a complete list in the documentation for the erlang module):

For example, to run a Ruby program, echoFac.rb, the following commands need to be executed:

Cmd = "ruby echoFac.rb",
Port = open_port({spawn, Cmd}, [{packet, 4}, use_stdio, exit_status, binary]),

After these commands are executed, the variable Port contains the port identifier for the spawned Ruby program.

The connected process can communicate with the Port using port_command/2. Executing the following command in the connected process will send the Data to the Port:

port_command(Port, Data)

The message sent has the form {Port, {data, Data}}.

To connect a process with pid Pid to a port Port, the following call must be executed:

port_connect(Port, Pid)

This can be called by any process, but the old port owner will stay linked to the Port; the owner will need to call unlink(Port) to remove the link.

To close a port—and therefore to terminate communication with the external program—the connected process needs to execute the command port_close(Port).

To show these examples in action, here is a small Erlang program that calculates the factorial of 23 by sending the argument to Ruby and having it calculated in the Ruby program echoFac.rb, based on an echo example in the erlectricity library, discussed in the section Working in Ruby: erlectricity.

In the following example, the communication primitives are highlighted:

-module(echoFac).
-export([test/0]).

test() ->
  Cmd = "ruby echoFac.rb",
  Port = open_port({spawn, Cmd}, [{packet, 4}, use_stdio, exit_status, binary]),
  Payload = term_to_binary({fac, list_to_binary(integer_to_list(23))}),
  port_command(Port, Payload),
  receive
    {Port, {data, Data}} ->
      {result, Text} = binary_to_term(Data),
      Blah = binary_to_list(Text),
      io:format("~p~n", [Blah])
  end.

Running the test/0 function results in the following behavior:

1> echoFac:test(). 
"23!=25852016738884976640000"
ok
2>

We explain the remaining parts of the program in the next section.

Communication through a port uses binary data; therefore, program data needs to be converted to binary in some way or another before communication, and decoded on receipt. The bit syntax, described in Chapter 9, can be used here, as can a number of coding and decoding functions provided in the erlang module, including the following:

Returning to the earlier example:

test() ->
  Cmd = "ruby echoFac.rb",
  Port = open_port({spawn, Cmd}, [{packet, 4}, use_stdio, exit_status, binary]),
  Payload = term_to_binary({fac, list_to_binary(integer_to_list(23))}),
  port_command(Port, Payload),
  receive
    {Port, {data, Data}} ->
      {result, Text} = binary_to_term(Data),
      Blah = binary_to_list(Text),
      io:format("~p~n", [Blah])
  end.

The highlighted lines show the conversion in both directions. In creating the Payload, the integer 23 is converted to the string "23" by integer_to_list, and then to a binary <<"23">>, which in turn is paired with the atom fac and the pair is coded as a binary.

In the receive clause, the message from the Port is received in the standard form, {Port, {data, Data}}. The Data is decoded to a term of the form {result, Text}, and then the Text can itself be decoded using binary_to_list. This allows the data to be output to the terminal.

erlectricity is a Ruby library—a “gem”—that you can download and use with Ruby. It is available as source code from http://github.com/mojombo/erlectricity, and you can install it in Ruby using:

$ gem install mojombo-erlectricity -s http://gems.github.com

You can include the erlectricity library in a Ruby program by using a require statement at the head of the file.

At the heart of the library is the receiver.rb program, which provides the functionality to allow messages to be received by and sent from a Ruby program. This in turn depends on the implementation of ports in port.rb and matching in matcher.rb; coding and decoding data formats are provided in encoder.rb and decoder.rb for a variety of different Erlang types.

The library comes with a test suite, as well as examples, including a daemon that links Erlang to Campfire, via the Ruby implementation of the Campfire API, Tinder.

require 'rubygems'
require 'erlectricity'
require 'stringio'

def fac n
  if (n<=0) then 1 else n*(fac (n-1)) end
end

receive do |f|
  f.when(:fac, String) do |text|
    n = text.to_i
    f.send!(:result, "#{n}!=#{(fac n)}")
    f.receive_loop
  end
end

{:result ,"#{n}!=#{(fac n)}"}

1> echoFac:test().
"23!=25852016738884976640000"
ok

Write an implementation of the earlier factorial server example in C using a port, rather than a distributed Erlang node.

Reimplement the factorial server example using the interface to one of the following languages: Scheme, Haskell, C#, Python, or PHP.