Quick Start

In this section we will create a Monterey actor from a Maven archetype and use Brooklyn to deploy it in a Monterey network. Our actor will demonstrate how actors can preserve their state when being suspended and resumed.

Prerequisites

This guide requires you have the Java 6 JDK, curl, wget and Maven 3 installed.

You will also need to set up ssh authorized keys so you can ssh to localhost without a password. (Refer to Appendix for a quick howto.)

Note that Maven Archetypes are currently generated using the command line; Eclipse/STS archetype integration is not currently supported.

Projects generated using the command line can be subsequently imported into Eclipse/STS.

Eclipse/STS archetype integration is planned for the next release.

Create an actor project

Use Maven to generate a template Monterey actor project:

% mvn archetype:generate 
   -DarchetypeRepository=http://ccweb.cloudsoftcorp.com/maven/libs-release-local/
   -DarchetypeGroupId=monterey 
   -DarchetypeArtifactId=monterey-actors-archetype
   -DarchetypeVersion=4.0.0-SNAPSHOT

Provide the following details:

groupId: com.example
artifactId: suspend-resume-actor
version: hit return to accept the default (1.0-SNAPSHOT)
package: hit return to accept the default (com.example)
actorClass: SuspendResumeActor

When Maven has created your project check it builds correctly:

   % cd suspend-resume-actor
   % mvn clean package

Edit the SuspendResumeActor class

Our actor's state will simply be a count of the number of messages it has received.

Open src/main/java/com/example/SuspendResumeActor.java in your editor of choice and add a field to the SuspendResumeActor class to store this count:

   private long count;

Each time the actor receives a message it should increment count. We will also have it publish the latest count on a 'count' topic. Edit onMessage:

   public void onMessage(Object payload, MessageContext messageContext) {
       count++;
       context.publish("count", count);  // Publish the new count
   }

We initialise the actor's state in the start method by initialising count to zero and by having the actor subscribe to the 'topicX' topic:

   public void start(Object state) {
       count = 0;
       context.subscribe("topicX");
   }

When the actor is suspended we give Monterey a Serializable object containing the actor's state. In this case, simply the count:

   public Serializable suspend() {
       return count;
   }

The serialized state is then given to resume when the actor is restarted:

   public void resume(Object state) {
       count = (Long) state;
   }

The subscription to topicX made in start is automatically resubscribed.

No changes need to be made to the terminate method.

Confirm your actor project builds again and install it to your local Maven repository:

   % mvn clean install

Deploy your actor with Brooklyn

We will use Brooklyn to run the SuspendResume actor in a MontereyNetwork.

Use Maven to generate a template Monterey network alongside the suspend-resume actor:

   % cd ..
   % mvn archetype:generate 
      -DarchetypeRepository=http://ccweb.cloudsoftcorp.com/maven/libs-release-local/
      -DarchetypeGroupId=monterey 
      -DarchetypeArtifactId=monterey-brooklyn-archetype
      -DarchetypeVersion=4.0.0-SNAPSHOT

groupId: com.example
artifactId: suspend-resume-app
version: hit return to accept the default (1.0-SNAPSHOT)
package: hit return to accept the default (com.example)
actorClass: com.example.SuspendResumeActor
actorProjectArtifactId: suspend-resume-actor
actorProjectGroupId: com.example
actorProjectVersion: 1.0-SNAPSHOT
applicationClass: SuspendResumeLauncher

The archetype creates a simple network running on localhost with a single suspend-resume actor. Compile and run the network:

   % cd suspend-resume-app
   % mvn package
   % java -cp target/suspend-resume-app-1.0-SNAPSHOT.jar com.example.SuspendResumeLauncher

The network will take a few moments to initialise. If Brooklyn throws an exception with message 'Unable to cache bundle' confirm that you entered all the fields for the archetype correctly.

Brooklyn launches a management console that you can find at http://localhost:8081/dashboard/index. When you see 'Configuring Spring Security ...' in your terminal this console is available. Log in with username 'admin' and password 'password'.

Finally, kill your network with Ctrl+C.

Reference Application

The code for this example can be found in the Monterey v4 Examples GitHub repository.

Monterey

Brooklyn