Getting Started with Janey Spaces

Janey Spaces is an easy yet powerful library which simplifies the writing of networked applications. It is also very new, so there are significant areas where people can experiment and contribute to steer the direction that Janey Spaces takes in its development.

This guide will take you through how to write a Janey Spaces application given the current architecture. By architecture I mean the applications you need to run and how they communicate. It is likely that the architecture will change in future, but this should only impact how you instantiate the space (there is very little configuration). Your application logic will be identical regardless of the architecture due to the nature of the abstraction Janey Spaces provides.

A Janey Space requires one central “router” and multiple “clients” which connect to it. I use “router” instead of the term “server” to avoid confusion when one of your multiple clients actually hosts services in the Space, so may be considered a “server”. As far as Janey Spaces is concerned, your “server” and “client” are all Janey Space clients connected to a central router.

Each client can save/remove objects in the space, and can request to be kept informed of new objects matching a given IObjectKey. The router keeps track of requests and all object states, sending updates when necessary.

So start using the library, download the JaneySpaces files, and unzip and untar if necessary. The project is currently distributed as an Eclipse Project, which you can load by doing the following:

1. Open Eclipse.

2. Right click on your projects/workspace area.

3. Select “Import...”

4. Select “Existing Projects into Workspace”

5. “Select root directory”, navigating to where you unpacked the Janey Spaces source tree.

6. Import the projects!

This example is based on an example available in the Test package. You can create new examples by either adding them straight to the Test package or creating a new project and setting a dependency in Eclipse on Janey Spaces.

In this example, one application acts as a router and two clients. Note that in the single main method below we have two clients sending strongly-typed messages via a central router in less than 35 lines of code.

public class DistributedListen {
	public static void main(String[] args) throws IOException, InterruptedException {

		final int port = 3456;

		DistributedFactory.startXMLRouter(port);
		final IDistributedClient savingClient = DistributedFactory.startXMLClient(port);
		final IDistributedClient listeningClient = DistributedFactory.startXMLClient(port);

		// From here onwards you only use the IDistributedClient interface, and no longer worry about network or JaneySpaces architecture

		final String listenClientName = "Richard";

		savingClient.startTransaction().
			save(new Message("Hello", listenClientName)).
			commit();

		final IObjectKey<Message> listenKey = Message.createListenKey(listenClientName);

		listeningClient.startKeyListen(listenKey, new IObjectEventHandler<Message>() {
			public void invoke(Event t1, Message t2) {
				System.out.println("Received a message " + t2);
			}
		});

		listeningClient.startTransaction().
			save(listenKey).
			startKeyListen(listenKey).
			commit();

		for (;;) {
			Thread.sleep(1000);
		}
	}

The output of this application should be:

Received a message Hello to Richard

The first line starts the router on the given port. It listens for incoming connections and assumes they speak the “XML” version of the Janey Spaces protocol. However, if you want to set up a router with different settings, there are various static methods on DistributedFactory which provide greater flexibility. All the routing work will be executed on background threads, with no contention with any shared state with the two clients.

Next we create two clients, one for saving a message and one for listening for it. Again these are XML speaking clients connecting to the same tcp port as the router. The saving client saves a newly created Message object saying “Hello” to “Richard”. See below for the Message class. The listening client creates a “listen key”, IObjectKey<Message> which will match any Messages where the “to” field is set to “Richard”. Then the listen client registers this key for local listening, meaning that all messages arriving locally will be checked if they match, and if so the provided listener will be called. Then the listen client saves the listen key in the space and registers an interest in remote events matching that key. Now the router is configured to send all messages “to” “Richard” to us!

Now, before we started listening for messages, the message to Richard had already been saved in the Janey Space. This does not mean however that the recipient has missed the message. The message is still floating in the Janey Space, as the saver has not removed it, so when the listener requests messages from the router, it will be immediately sent any objects in the space which match the IObjectKey. This reduces the “temporal coupling” between servers and clients, since you will very rarely rely or worry about timing events in the Space.

Let's take a closer look at the object which actually resides in the space. The Message class below consists of two fields (its state) which are propagated to all interested clients by the router. It is not technically a POJO. The “to” field is marked with a @Key annotation, which informs Janey Spaces that you will want to route objects based on this field, and the class itself is marked @Distributed.

Advanced - In this case, being a string the space treats the field as a “value-type” to use C# terminology, meaning .equals and .hashcode are used for indexing to achieve value equality. However, if it were a reference to another object then “==” and IdentityHashCode() would be used instead, to achieve reference or identity equality.

The createListenKey() method is the most complex and least attractive part of this application. It creates an IObjectKey<Message> which effectively says “match when the 'to' field = the 'to' specified by the caller”. Note that the Strings assigned in the map must have the same names as the fields on the type, unfortunately Java does not (yet) support static Field object lookups as it does for Class objects.

Only fields which are marked as @Key can be indexed like this. JaneySpaces is not smart enough (yet) to do the routing of isolated POJO objects, and requires a few annotations to derive some meaning from the object. However, any POJO objects which are referenced by your annotated class will be routed as you expect.

Please also note the private default constructor. For Janey Spaces to instantiate the object on the recipients VM, it must currently invoke this constructor, although fortunately it can be private to avoid accidentally creating invalid Message objects later on.

	@Distributed
	private static class Message {
		private final String message;

		@Key
		private final String to;

		public Message(String message, String to) {
			this.message = message;
			this.to = to;
		}

		private Message() {
			to = null;
			message = null;
		}

		@Override
		public String toString() {
			return message + " to " + to;
		}

		public static IObjectKey<Message> createListenKey(String to) {
			final Map<String, Object> keys = new HashMap<String, Object>();
			keys.put("to", to);
			return ObjectKeyUtils.createLookupKey(Types.getIType(Message.class), keys);
		}
	}

And it's as simple as that! The messages sent over the space are strongly typed, and adding additional fields to your network protocol is as easy as adding fields to a class in Java. Janey Spaces also resolves the references between objects (including POJOs) so that entire object graphs are made available on the local VM.

As I said in the introduction, JaneySpaces is very new, and I am very happy to hear thoughts and suggestions regarding how the library can be improved in future. The api is meant to be as straightforward to use as possibly without becoming 'leaky' and for this reason I am very enthusiastic for other developers to give it a go.

Also, if you have any error messages when using the library email me immediately. Error handling is one significant area for improvement, and I do not want users wasting time over stack traces when they could be contributing with bug reports.