Remote Actors (Java)

Starting remote service in user code as a library

Here is how to start up the server and specify the hostname and port programmatically:

import static akka.actor.Actors.*;

remote().start("localhost", 2552);

// Specify the classloader to use to load the remote class (actor)
remote().start("localhost", 2552, classLoader);

Here is how to start up the server and specify the hostname and port in the ‘akka.conf’ configuration file (see the section below for details):

import static akka.actor.Actors.*;

remote().start();

// Specify the classloader to use to load the remote class (actor)
remote().start(classLoader);

Starting remote service as part of the stand-alone Kernel

You simply need to make sure that the service is turned on in the external ‘akka.conf’ configuration file.

akka {
  remote {
    server {
      service = on
      hostname = "localhost"
      port = 2552
      connection-timeout = 1000 # in millis
    }
  }
}

Stopping the server

import static akka.actor.Actors.*;

remote().shutdown();

Connecting and shutting down a client connection explicitly

Normally you should not have to start and stop the client connection explicitly since that is handled by Akka on a demand basis. But if you for some reason want to do that then you can do it like this:

import static akka.actor.Actors.*;
import java.net.InetSocketAddress;

remote().shutdownClientConnection(new InetSocketAddress("localhost", 6666)); //Returns true if successful, else false
remote().restartClientConnection(new InetSocketAddress("localhost", 6666)); //Returns true if successful, else false

Client message frame size configuration

You can define the max message frame size for the remote messages:

akka {
  remote {
    client {
      message-frame-size = 1048576
    }
  }
}

Client reconnect configuration

The Client automatically performs reconnection upon connection failure.

You can configure it like this:

akka {
  remote {
    client {
      reconnect-delay = 5            # in seconds (5 sec default)
      read-timeout = 10              # in seconds (10 sec default)
      reconnection-time-window = 600 # the maximum time window that a client should try to reconnect for
    }
  }
}

The client will automatically trying to reconnect to the server if the connection is broken. By default it has a reconnection window of 10 minutes (600 seconds).

If it has not been able to reconnect during this period of time then it is shut down and further attempts to use it will yield a ‘RemoteClientException’. The ‘RemoteClientException’ contains the message as well as a reference to the address that is not yet connect in order for you to retrieve it an do an explicit connect if needed.

You can also register a listener that will listen for example the ‘RemoteClientStopped’ event, retrieve the address that got disconnected and reconnect explicitly.

See the section on client listener and events below for details.

Remote Client message buffering and send retry on failure

The Remote Client implements message buffering on network failure. This feature has zero overhead (even turned on) in the successful scenario and a queue append operation in case of unsuccessful send. So it is really really fast.

The default behavior is that the remote client will maintain a transaction log of all messages that it has failed to send due to network problems (not other problems like serialization errors etc.). The client will try to resend these messages upon first successful reconnect and the message ordering is maintained. This means that the remote client will swallow all exceptions due to network failure and instead queue remote messages in the transaction log. The failures will however be reported through the remote client life-cycle events as well as the regular Akka event handler. You can turn this behavior on and off in the configuration file. It gives ‘at-least-once’ semantics, use a message id/counter for discarding potential duplicates (or use idempotent messages).

akka {
  remote {
    client {
      buffering {
        retry-message-send-on-failure = on
        capacity = -1                      # If negative (or zero) then an unbounded mailbox is used (default)
                                           # If positive then a bounded mailbox is used and the capacity is set using the property
      }
    }
  }
}

If you choose a capacity higher than 0, then a bounded queue will be used and if the limit of the queue is reached then a ‘RemoteClientMessageBufferException’ will be thrown.

Enabling secure cookie authentication

The first one is done by enabling the secure cookie authentication in the remote server section in the configuration file:

akka {
  remote {
    server {
      require-cookie = on
    }
  }

Now if you have try to connect to a server from a client then it will first try to authenticate the client by comparing the secure cookie for the two nodes. If they are the same then it allows the client to connect and use the server freely but if they are not the same then it will throw a ‘java.lang.SecurityException’ and not allow the client to connect.

Generating and using the secure cookie

The secure cookie can be any string value but in order to ensure that it is secure it is best to randomly generate it. This can be done by invoking the ‘generate_config_with_secure_cookie.sh’ script which resides in the ‘$AKKA_HOME/scripts’ folder. This script will generate and print out a complete ‘akka.conf’ configuration file with the generated secure cookie defined that you can either use as-is or cut and paste the ‘secure-cookie’ snippet. Here is an example of its generated output:

# This config imports the Akka reference configuration.
include "akka-reference.conf"

# In this file you can override any option defined in the 'akka-reference.conf' file.
# Copy in all or parts of the 'akka-reference.conf' file and modify as you please.

akka {
  remote {
    secure-cookie = "000E02050F0300040C050C0D060A040306090B0C"
  }
}

The simplest way to use it is to have it create your ‘akka.conf’ file like this:

cd $AKKA_HOME
./scripts/generate_config_with_secure_cookie.sh > ./config/akka.conf

Now it is good to make sure that the configuration file is only accessible by the owner of the file. On Unix-style file system this can be done like this:

chmod 400 ./config/akka.conf

Running this script requires having ‘scala’ on the path (and will take a couple of seconds to run since it is using Scala and has to boot up the JVM to run).

You can also generate the secure cookie by using the ‘Crypt’ object and its ‘generateSecureCookie’ method.

import akka.util.Crypt;

String secureCookie = Crypt.generateSecureCookie();

The secure cookie is a cryptographically secure randomly generated byte array turned into a SHA-1 hash.

Server side setup

The API for server managed remote actors is really simple. 2 methods only:

import akka.actor.Actors;
import akka.actor.UntypedActor;

class MyActor extends UntypedActor {
  public void onReceive(Object message) throws Exception {
    ...
  }
}
Actors.remote().start("localhost", 2552).register("hello-service", Actors.actorOf(HelloWorldActor.class));

Actors created like this are automatically started.

You can also register an actor by its UUID rather than ID or handle. This is done by prefixing the handle with the “uuid:” protocol.

server.register("uuid:" + actor.uuid, actor);

server.unregister("uuid:" + actor.uuid);

Session bound server side setup

Session bound server managed remote actors work by creating and starting a new actor for every client that connects. Actors are stopped automatically when the client disconnects. The client side is the same as regular server managed remote actors. Use the function registerPerSession instead of register.

Session bound actors are useful if you need to keep state per session, e.g. username. They are also useful if you need to perform some cleanup when a client disconnects by overriding the postStop method as described here

import static akka.actor.Actors.*;
import akka.japi.Creator;

class HelloWorldActor extends Actor {
  ...
}

remote().start("localhost", 2552);

remote().registerPerSession("hello-service", new Creator<ActorRef>() {
  public ActorRef create() {
    return actorOf(HelloWorldActor.class);
  }
});

Note that the second argument in registerPerSession is a Creator, it means that the create method will create a new ActorRef each invocation. It will be called to create an actor every time a session is established.

Client side usage

import static akka.actor.Actors.*;
ActorRef actor = remote().actorFor("hello-service", "localhost", 2552);

remote().start("localhost", 2553); // needed for replies

Object result = actor.sendRequestReply("Hello");

There are many variations on the ‘remote()#actorFor’ method. Here are some of them:

... = remote().actorFor(className, hostname, port);
... = remote().actorFor(className, timeout, hostname, port);
... = remote().actorFor(uuid, className, hostname, port);
... = remote().actorFor(uuid, className, timeout, hostname, port);
... // etc

All of these also have variations where you can pass in an explicit ‘ClassLoader’ which can be used when deserializing messages sent from the remote actor.

Server side setup

The API for server managed remote typed actors is nearly the same as for untyped actor:

import static akka.actor.Actors.*;
remote().start("localhost", 2552);

RegistrationService typedActor = TypedActor.newInstance(RegistrationService.class, RegistrationServiceImpl.class, 2000);
remote().registerTypedActor("user-service", typedActor);

Client side usage

import static akka.actor.Actors.*;
RegistrationService actor = remote().typedActorFor(RegistrationService.class, "user-service", 5000L, "localhost", 2552);
actor.registerUser(...);

There are variations on the ‘remote()#typedActorFor’ method. Here are some of them:

... = remote().typedActorFor(interfaceClazz, serviceIdOrClassName, hostname, port);
... = remote().typedActorFor(interfaceClazz, serviceIdOrClassName, timeout, hostname, port);
... = remote().typedActorFor(interfaceClazz, serviceIdOrClassName, timeout, hostname, port, classLoader);

Protobuf

Protobuf message specification needs to be compiled with ‘protoc’ compiler.

message ProtobufPOJO {
  required uint64 id = 1;
  required string name = 2;
  required bool status = 3;
}

Using the generated message builder to send the message to a remote actor:

actor.tell(ProtobufPOJO.newBuilder()
    .setId(11)
    .setStatus(true)
    .setName("Coltrane")
    .build());