Introduction

ABS Async API is an implementation of ABS models asynchronous message passing using the features available in Java 8. The design and implementation is driven by certain requirements and principles from the scope of ABS models and platform.

ABS Async API introduces an independent Java library that can be freely used in any Java 8 compatible code base. The API implementation provides certain interfaces that allows Java objects to interact to one another through a message passing mechanism and process messages in an asynchronous and event-driven approach. The implementation separates invocation of messages from execution of messages. An invocation of a message to an object assures the delivery of the message to the receiver while execution of a message is the specifics of the message is processed. Such separation increases the extensibility and pluggability of the implementation in each layer. Morever, it evidently influences the performance of message processing and utilization of resources such as underlying Java threads.

ABS Async API is designed in such way that is it ready to be used for ABS model code generations. An ABS model can transformed into an implementation language such as Java. As an ABS model may take advantage of asynchronous message passing, the generated code is expected to expose the same semantics. The ABS Async API allows code generators to generate code lines using the API library to implement the asynchronous message passing at the level of Java 8.

ABS Async API realizes a one-to-one mapping from ABS asynchronous message passing to a Java 8 implementation. Such mapping provides a base ground to be able to formally reason about and verify the code generated from ABS models on top of such API implementation.

Getting Started

1. Development Environment

To use ABS API you need to prepare an environment that supports Java features.

  1. Install a version of Java 8 from OpenJDK releases [Java8].

  2. If you develop on Eclipse, install a milestone version of next eclipse Luna [EclipseLuna].

  3. To support Java 8 syntax on eclipse Luna, you need to install a beta version of JDK8 support [EclipseLunaJava8].

2. Build from source

To use the API, you can either download the latest build [APILastBuild] or build it from source.

To build from source, assuming that Git is available, checkout the source:

git clone https://github.com/CrispOSS/abs-api

And then, make a build using Maven 3+:

mvn clean install

3. A first example

The first example demonstrates how to implement the “ping-pong” example using ABS API. Let IPing and IPong be interfaces that define the interfaces.

IPing and IPong interfaces
interface IPing {
	void ping();
}

interface IPong {
	String pong(String msg);
}

An implementation of either interface can turn into an actor given that it implements the interface abs.api.Actor:

Ping implementation as an actor
class Ping implements IPing, abs.api.Actor {
	public void ping() {
		// implementation details
	}
}

and the same goes for the other:

Pong implementation as an actor
class Pong implements IPong, abs.api.Actor {
	public String pong(String msg) {
		// implementation details
	}
}

In a context that an instance of Ping can be created using an instance of Pong, then the ping actor can send a message to pong an wait for the result:

Send a message to an actor and wait for the result
// somewhere inside `ping` method of Ping
Future<String> result = invoke(pong, "pong", pingMessage);
// continues to use
String pongMessage = result.get();

The above message is a direct request to call a specific method of interface IPing with the provided arguments. A message can also be an executable object:

Send a message using a lambda expression
Future<String> result = send(pong, () -> {
	return pingMessage;
});
String pongMessage = result.get();

An actor may refer to the sender of a message that it has received during an invocation of one of its methods:

The notion of the sender of a message
// inside a method
send(sender(), aNewMessage);

ABS Remote API

ABS API provides an extension modules to enable using actors in a distributed setting. In a distributed setting, each JVM instance contains a set of actors. The following properties holds when using the remote API:

  1. Location Reference Transparency: Actors are blind to the location of the reference that they use to communicate with other actors. Either in a local or remote setting, an actor may use an instance of Reference to refer to another actor. The referred actor may be local or remote and this is transparent for the calling actor.

  2. Communication Transparency: Actors send and receive messages. The transport of each message and how it is transferred to the receiver of the message is transparent to the sender of the message. The extension of ABS API provides a transparent way to provide a container of actors that can be accessed through HTTP. The communication of the messages through HTTP is handled by the Remote API implementation and abstracted from the user of the API.

In the following, we provide a simple actor Echo:

Echo.java
public class Echo implements Actor, Behavior {
	private static final long serialVersionUID = 1L;
	private final Logger logger = LoggerFactory.getLogger(getClass());
	private final Integer index;

	public Echo(Integer i) {
		this.index = i;
	}

	@Override
	public Object respond(Object message) {
		logger.error("echo#{} --- message: {} --- from: {}", index, message, sender());
		send(sender(), "an echo from " + index);
		return null;
	}
}

To demonstrate how this actor can be used with ABS Remote API, we create two separate actor servers:

Main1.java
public class Main1 {
	public static void main(String[] args) throws UnknownHostException {
		Properties props1 = new Properties();
		props1.put("host", "localhost");
		props1.put("port", "7777");
		ActorServer server1 = new ActorServer(props1);
		Echo e1 = new Echo(1);
		Actor a1 = server1.context.newActor("echo-1", e1);
		System.out.println(" === actor: " + a1.name());
	}
}

and also the second actor which is similar:

Main2.java
public class Main2 {
	public static void main(String[] args) throws UnknownHostException {
		Properties props2 = new Properties();
		props2.put("host", "localhost");
		props2.put("port", "8888");
		ActorServer server2 = new ActorServer(props2);
		Echo e2 = new Echo(2);
		Actor a2 = server2.context.newActor("echo-2", e2);
		a2.send(Reference.from("abs://echo-1@http://localhost:7777"), "a msg from echo-2");
	}
}

As the result of running the program, you can follow a trace of remote message. Note that the API for the actors do not change and its part of transparent implementation in the server. A complete source of this example is available at: https://github.com/CrispOSS/abs-api-remote-sample

References

The following is a list of references and citations in the manual.