Sodacan

Prerequisites

You'll need Java 21. The balance of Sodacan's dependencies are handled by Maven. See dependencies.

Maven Coordinates

The easiest way to get started is by adding a dependency on Sodacan in your project's POM:

<dependency>
  <groupId>sodacan</groupId>
  <artifactId>sodacan-core</artifactId>
  <version>0.1.2</version>
</dependency>

See Coordinates for additional tool configurations.

Sodacan can also be forked from github if desired.

A Simple First Program

A brief description of what you will do to get to your first working Sodacan Actor.

• In short, you will create a class with a main method in the usual way.
• You'll need to create at least one Actor. Your Actor will subclass AbstractActor and override just one method.
• In the main method you will declare a Sodacan configuration. Initially, the default configuration should be sufficient.
• Then, you will start the Host. Because this is a simple configuration, the Host will startup right away. It doesn't need to wait for a quorum of Hosts as would happen in a production Sodacan cluster.
• Next, you'll call a utility method that will inject your first message into the Host targeting the Actor defined above. Later, you'll see other ways to get messages into Sodacan.
• Finally, you'll close the Host. The close is a blocking call. It will wait until all messages have been delivered and a few other details, explained later, to finish before shutting down.

Sodacan is inherently asynchronous so even this first example may show slightly different behavior depending on system size, performance, and load. Also, if you were to set a breakpoint in the Actor, you'll see that the close process may display a message about waiting for n messages to finish, which is being blocked by your breakpoint.

OK, time for a little code to get things started. This example is small and will not resemble any of the subsequent examples. It's just enough to make sure that the setup is working properly. The full example can be found here

First, define an Actor:

	public static class MyActor extends AbstractActor {
		public static final String NAME = "myActor";
		public enum Action implements Verb { noop }
		public MyActor(Config config, ActorId actorId) {
			super(config, actorId);			
		}
		@Override
		public Stage processMessage() {
			System.out.println("**** In process message ****");
			return emptyStage;
		}
	}

Then the main method will start everything up:

	public static void main(String[] args) throws Exception {
		Config config = new SimpleBuilder()
				.registerActorType(MyActor.NAME, MyActor.class)
				.build();
		config.getHost().start();

This is where we inject our first message into Sodacan. The submitToNewActor method hides quite a bit of detail which will be exposed in subsequent examples.

		MessageUtils.submitToNewActor(config, MyActor.NAME, MyActor.Action.noop);

And, finally, the close:

		config.getHost().close();

Now that this is working, it's time for a genuine Hello World example.