miniSpace - 5 minutes tutorial

A minimalist coordination mechanism

miniSpace is a general-purpose coordination mechanism inspired after the Linda Coordination Language and JavaSpaces. It is by no means an attempt to implement any of those, we just implemented the minimum set of concepts we needed in our own projects.

You can think about a Space instance as being like a Map where its entries are lists of objects and its operations are fully synchronized.

There are three basic operations:

• void out (Object key, Object value)
  Put an object into the space. If an object under the given key already exists, the object is queued at the end of a list.
• Object rd (Object key)
  Reads an object from the space. Block until one is present under the given key.
• Object in (Object key)
  Take the object off the queue. Block until the object under the given key is present.

In addition to those three basic operations it also has a few handy methods:

• void out (Object key, Object value, long timeout)
  Place an object into the space using an expiration timeout. The entry is automatically removed upon expiration.
• Object rd (Object key, long timeout)
  Wait a maximum of timeout milliseconds for a given entry; otherwise, return null.
• Object in (Object key, long timeout)
  Wait a maximum of timeout milliseconds for a given entry; otherwise, return null
• Object rdp (Object key)
  Read an entry if it exists. (p for 'probe')
• Object inp (Object key)
  Take an entry if it exists. (p for 'probe')

Hello miniSpace

Let's have a look at a simple example, we will put two Strings in the Space under the key name "Test" (we call them 'queues') by using the out operation. The first string equals to "Hello ", and the second one equals to "World".

Then we will take and print one entry at a time off the "Test" queue by using the in operation.

Finally we will read (rd) that queue using the rdp (read-probe) operation. It should be null (because there were just two entries under the name 'Test' and we have already taken them off the Space).

  import org.jpos.space.*;

  Space sp = SpaceFactory.getSpace(); // get a reference to the default Space
  sp.out ("Test", "Hello ");          // put "Hello " in the "Test" queue
  sp.out ("Test", "World");           // put "World" in the "Test" queue
  System.out.print (sp.in ("Test"));  // should return the first entry
  System.out.print (sp.in ("Test"));  // should return the second entry
  if (sp.rdp ("Test") == null)        // should be null
    System.out.println (".");

  --- output ---
  Hello World.

 

We encourage you to play with the previous code and we suggest you perform some of the following variations in order to understand how it works:

• Use a timeout at read time
  Change the final sp.rdp ("Test") and use sp.rd ("Test", 5000) instead. You will see how it takes 5 seconds to print the final dot. You can try sp.inp instead of sp.in too.
• Use a timeout at write time
  Try to out an entry with a timeout, e.g.: sp.out("Test", "City", 1000L); Then play with some Thread.sleep(xxx) here and there and sp.rd ("Test") in order to verify that the entry is available for just one second.
• Play with different keys
  Write (out), take (in) and read (rd) entries using different keys other than "Test". Try with objects other than Strings.

Some use cases

• A simple ThreadPool
  You can implement a ThreadPool with a few lines of code, the workers would be a set of threads running a loop like this:

  
      public void run() {
         Space sp = SpaceFactory.getSpace();
         for (;;) {
            Runnable r = (Runnable) sp.in ("MyPool");
            try {
              r.run();
            } catch (Exception e) {
              e.printStackTrace();
            }
         }
      }
  
    

  When you need to run something controlled by the thread pool, you would just queue a Runnable object into the "MyPool" queue, e.g.:

  
     Space sp = SpaceFactory.getSpace();
     sp.out ("MyPool", MyRunnable);
  
    

• License control
  Imagine you have a system where you want to limit throughput to 10 outstanding transactions at any given point in time. At startup you could out 10 "tickets" into the Space under a well known name, then you could use code like this in order to control throughput:

  
     Object ticket = null;
     try {
        ticket = sp.in ("TransactionTickets");
        ...
        ...
        ...
     } finally {
        sp.out ("TransactionTickets", ticket); // back to the ticket pool
     }
    

• Simple cache
  You read some objects from a database that makes sense to cache for a few minutes, you just out them under a given name specifying a timeout, e.g.:

  
      Space sp = SpaceFactory.getSpace();
      for (;;) {
        BigDecimal exchangeRate = getExchangeRateFromDB(...);
        sp.out ("ExchangeRate", exchangeRate, 120000L);
        Thread.sleep (110000L);   // get a new one before it expires ...
      }
      
    

  Then any client code can just block waiting for a valid and up-to-date ExchangeRate object to be available in the space, e.g.:

  
       BigDecimal exchangeRate = (BigDecimal) sp.in ("ExchangeRate");
  
    

  or better yet, wait for a reasonable time for a valid exchange rate to be available in the Space (think database down) and throw an exception if it doesn't get available.

  
       BigDecimal exchangeRate = (BigDecimal) sp.in ("ExchangeRate", 10000L);
       if (exchangeRate == null)
          throw new XXXException ("Exchange rate is not available");
  
    

• Reading devices - a jPOSsy real world example
  We want to read a credit card at a POS terminal in order to initiate a transaction. We want that read to remain valid just for a short period of time, if the operator doesn't complete the transaction, we want that read to be discarded. We can do that without miniSpace in many different ways, but with miniSpace it's a no-brainer. There's a thread reading the cards and placing them in the space:

  
      for (;;) {
          CardData cd = readCardData(...);
          SpaceUtil.wipe (sp, "CARDDATA"); // clear buffer
          sp.out ("CARDDATA", cd, 60000L); // buffered for just 1 minute
      }
  
    

  Then at the UI level we can asynchroneously ask for the transaction type, amount, etc. At any point where we need the card data, we would just call:

       
       // gives the operator up to two minutes to swipe the card
       CardData cd = (CardData) sp.in ("CARDDATA", 120000L); 
       ...
       ...
  
    

The persistent Space

When you call SpaceFactory.getSpace() you are actually getting an instance of TSpace. That Space gets registered under the name tspace:default. So calling SpaceFactory.getSpace() is exactly the same as calling SpaceFactory.getSpace("tspace:default").

You can create as many Spaces as you want, and you can make them anonymous if you go directly to the Space constructur instead of using the SpaceFactory helper class.

There's a very useful space implementation called JDBMSpace. It is a persistent space implementation that uses a JDBM database as its back end. The result is that everything you write there will remain valid across JVM runs.

You can use a JDBMSpace by calling:

  Space sp = SpaceFactory ("jdbm:mypersistentspace");

  

  Space sp = SpaceFactory ("jdbm:mypersistentspace:/tmp/persistentspace");

  

What's next ?

You can get additional information in the project page at Google Code.