[Erlang Systems]

3 The Java Interface

This section describes the Java interface to Jive and includes the following topics:

3.1 Erlang Variable Types

Jive provides wrapper classes for each defined Erlang variable type: integer, float, string, list, tuple, atom, and pid. The Java Jive API provides a detailed description of the Java Interface.

3.1.1 EVar

EVar is an abstract class that is a super class of all other Erlang wrapper classes. Most notably, this class contains a method type() which returns the type of the variable.

3.1.2 EInteger

The EInteger class is a wrapper for an Erlang integer. The EInteger has the type EINTEGER.

To create a new EInteger:

EInteger tmp = new EInteger(int value);

To retrieve the integer value:

int val = tmp.value();

3.1.3 EFloat

The EFloat class is a wrapper for an Erlang float. The EFloat has the type EFLOAT.

To create a new EFloat:

EFloat tmp = new EFloat(double value);

To retrieve the double value:

double val = tmp.value();

3.1.4 EString

The EString class is a wrapper for an Erlang string. The EString has the type ESTRING.

To create a new EString:

EString tmp = new EString(String string);

To retrieve the String value:

String string = tmp.value();

To retrieve the length of the String:

int length = tmp.length();

3.1.5 EAtom

The EAtom class is a wrapper for an Erlang atom. The EAtom has the type EATOM.

To create a new EAtom:

EAtom tmp = new EAtom(String val);

To retrieve the Atom value:

String val = tmp.value();

To retrieve the length of the Atom:

int length = tmp.length();

3.1.6 EBinary

The EBinary class is a wrapper for an Erlang binary. The EBinary has the type EBINARY.

To create a new EBinary:

EBinary tmp = new EBinary(byte data[]);

To retrieve the byte array:

byte data[] = tmp.value();

To retrieve the length of the Binary:

int length = tmp.length();

3.1.7 EList

The EList class is a wrapper for an Erlang list. The EList has the type ELIST.

To create a new EList:

EList tmp = new EList();
// to
EList tmp = new EList(EVar var1, EVar var2, EVar var3,
                      EVar var4, EVar var5, EVar var6);
      

To create a new EList from an array of EVar:

List tmp = new EList(EVar vars[]);

To retrieve the array of EVars:

EVar vars[] = tmp.value();

To retrieve the length of the List:

int length = tmp.length();

To retrieve an enumeration of the EVars in the List:

EVar evar[] = tmp.elements();

To retrieve an EVar at a specified index:

EVar evar = tmp.elementAt(1);

3.1.8 ETuple

The ETuple class is a wrapper for an Erlang tuple. The ETuple has the type ETUPLE.

To create a new ETuple:

ETuple tmp = new ETuple();
// to
ETuple tmp = new ETuple(EVar var1, EVar var2, EVar var3,
                        EVar var4, EVar var5, EVar var6);

To create a new ETuple from an array of EVar:

ETuple tmp = new ETuple(EVar vars[]);

To retrieve the array of EVars:

EVar vars[] = tmp.value();

To retrieve the length of the Tuple:

int length = tmp.length();

To retrieve an enumeration of the EVars in the Tuple:

EVar evar[] = tmp.elements();

To retrieve an EVar at a specified index:

EVar evar = tmp.elementAt(1);

3.1.9 EProcess

The EProcess class is the Java wrapper for an Erlang Pid. The wrapper does not contain the Erlang Pid itself. Instead, it contains an internal integer value which allows the Erlang Jive server to find the corresponding Erlang Pid.

An EProcess class can be returned from the Erlang server, or as a result of spawning a process with the ESock module. An Erlang process can also be spawned automatically when creating an EProcess object.

EProcess p = new EProcess(String module, String name, EList Args);
EProcess p = new EProcess(EAtom module, EAtom name, EList Args);
      

Warning!

The creation of an EProcess object can throw a JiveException which must be caught.

3.2 EApplet

The EApplet class is a subclass of the Applet class. It will initiate the connection with the server and provide some useful methods, which are described below.

The EApplet class will connect to a port given by the port parameter, which must be specified within the <APPLET>, </APPLET> tags on the HTML page.

<APPLET CODE="...">
<PARAM NAME=PORT VALUE=4711>
</APPLET>
    

When creating a subclass based on EApplet, the init() method must be called in the EApplet class. The init method performs the connection with the server and creates the self Pid.

class Test extends EApplet {
  public void init() {
    super.init();
    /* Your code here! */
  }
}

By default, the Applet connects to the server when start() is called by the Applet, and disconnects from the server when stop() is called. To override these methods, you should call super.start() and super.stop() if you want the Applet default behaviour in addition to the customized functionality.

public void start() {
  super.start();
  /* Your code here! */ 
}
public void stop() {
  super.stop();
  /* Your code here! */
}

If you want to change the way the client connects/disconnects, do not call the start() and stop() methods in EApplet. Call the connect() and disconnect() methods instead.

The EApplet also provides six important methods:

ESock getESock();
This is a method which returns the socket module (see The Run-time Environment).
EProcess self();
This is a method which returns the self Pid. This is an EProcess object used to send messages to Java from Erlang. It should be supplied to those Erlang processes/functions which send messages back to a Java client.
EReceiver receiver();
This is a method which returns the EReceiver object. The EReceiver object is used to register a class implementation of the EReceive interface which makes it possible to receive messages sent from Erlang to a Java client.
void connect();
This method connects to the server.
void disconnect();
This method disconnects from the server.
boolean connected();
This method checks if the Applet is connected to the server.

3.3 EApplication

The EApplication is used when building stand-alone Java Applications. The EApplication has the same functionality as EApple. Refer to the Jive examples and the Java Jive API documentation for more details.

3.4 The Runtime Environment

The Jive runtime environment has the functionality to connect an Applet/Application to an Erlang server. The runtime environment is only instantiated once and can be retrieved with the static method ERuntime runtime = ERuntime.getRuntime();

At this time, the runtime environment only contains the socket module ESock, which is used for socket communication with the Erlang server. This will probably change in future versions of Jive.

3.4.1 The Socket Module

ESock is used for the socket communication with an Erlang server. The ESock object can be obtained by using the runtime environment, or by using a method in EApplet.

ERuntime runtime = ERuntime.getRuntime();
ESock eSock = runtime.getESock();

If inside an Applet:

ESock eSock = getESock();

3.4.2 Making an Erlang Apply

The ESock object provides methods for making an Erlang apply on the Erlang server side:

EVar reply = eSock.apply(String module, String name, EList args);
EVar reply = eSock.apply(EAtom module, EAtom name, EList args);

Warning!

An apply call can generate a JiveException which must be caught.

3.4.3 Spawning an Erlang Process

Erlang processes can be spawned by creating a new ESock module, or by creating a new EProcess object. The following two examples illustrate the different methods:

EProcess p = eSock.spawn(String module, String name, EList args);
EProcess p = eSock.spawn(EAtom module, EAtom name, EList args);
EProcess p = new EProcess(String module, String name, EList args);
EProcess p = new EProcess(EAtom module, EAtom name, EList args);

Warning!

Spawning of a process can generate a JiveException that must be caught.

3.4.4 Sending a Message to Erlang

Messages can be sent to Erlang processes by using functionality in the ESock class, or the EProcess classes. For obvious reasons, it is only possible to call processes which are represented by an EProcess object. The following examples illustrate:

eSock.send(EProcess p, EVar message);
p.send(EVar message);

Warning!

Sending a message can generate a JiveException whichmust be caught.

3.4.5 Receiving a Message from Erlang

Each class which needs to receive messages from the Erlang server must implement the REeceive interface. The method which has to be implemented is:

public void receive(EVar var);

In the following example, a class Test implements the EReceive interface and declares the receive method to print out the message if it is an Erlang string.

class Test implements EReceive {
  public void receive(EVar var) {
    if (var.type() == EVar.ESTRING) {
      String text = ((EString)var).value();
      System.out.println("Got string: "+text);
    }
  }
}

The EReceive object can be obtained with the receiver() method in EApplet:

EReceive test = (EReceive) new Test();
EReceiver receiver = receiver();
EInteger testID = receiver.register(test);

The EInteger, together with the self Pid, are supplied to the Erlang process to enable it to send messages that will be received by the Test object.

new EProcess ("module","function",new EList(testID,self()));

Copyright © 1991-98 Ericsson Telecom AB