Fork me on GitHub
Home | About | Projects | Articles | Resources
Home » Projects » Jandal

A Closer Look at Jandal Services

Jandal Service-Layer Components

W

hen you instantiate your Application, you can configure it with a ServiceSet, which is basically a map containing whatever Services your Controllers, States and EventProcessors might require at runtime. In this article I'm going to show you a simple example of a Service that provides read-only access to a collection of haiku poems. Note that if the Service allowed multiple users to modify the haiku collection, you would need to synchronise access to it. When you've read this article, take a look at Service Synchronisation, where I show you how to do that.

Example Application: RandomHaiku

RandomHaiku is a Jandal example application that cycles through haiku poems that are stored in a Jandal Service. Every time you click "Shall I compose another?", the application fetches the next haiku from the Service and displays it.

Sourcecode

HaikuMasterController.java

Shown below is the HaikuMasterController from the RandomHaiku example application. Initially, it is in its "waiting" state. When you request it to compose a haiku, it transitions to its "composed" state. On entry into that state, it fetches itself a RandomHaikuService (shown further down), from which it gets the next random haiku, which it then presents on an output.

public class HaikuMasterController extends Controller {

    public HaikuMasterController() throws JandalCoreException {
        super("haikuMaster");
    }

    protected void onStart() throws JandalCoreException {
        this.addInitialState(new State("waiting") {

            protected void onEntry() throws JandalCoreException {
                setOutput("template", "waiting.ftl");

                this.addViewEventProcessor(new EventProcessor("compose") {
                    protected void onEvent() throws JandalCoreException {
                        doTransition("composed");
                    }
                });
            }
        });
       
        this.addState(new State("composed") {

            protected void onEntry() throws JandalCoreException {
                setOutput("template", "composed.ftl");

                RandomHaikuService service = (RandomHaikuService) getService(RandomHaikuService.class
                        .getName());
                setOutput("haiku", service.getHaiku());

                this.addViewEventProcessor(new EventProcessor("another") {
                    protected void onEvent() throws JandalCoreException {
                        doTransition("composed");
                    }
                });
            }
        });
    }
}

RandomHaikuService.java

Here's that RandomHaikuService I was talking about. OK, so it doesn't randomly generate haiku; I mean, just think how bad a haiku would be if it was randomly generated by a computer!

public class RandomHaikuService extends Service {
    public RandomHaikuService() {
        super();
        currentHaiku = 0;
    }

    public String getHaiku() {
        currentHaiku = (currentHaiku + 1) % 5;
        switch (currentHaiku) {
        case 0:
            return "a smashed beer bottle\nfills the skate park with diamonds\nthesun in each one";
        case 1:
            return "silent at midnight\non the wall in the bathroom\na giant cranefly";
        case 2:
            return "in morning sunlight\nsteam from the cats yawn\nsmell of salmon";
        case 3:
            return "girlfriend not looking\nhis funny face\nfading";
        case 4:
            return "sudden speed wobble\nthe chips in the asphalt\nsharp and bright";
        case 5:
            return "outside the window\nleaves chattering on the path\nNor-Wester arrives";
        default:
            return "coffee on the bus\nin his rear-view mirror\nthe driver watching";
        }
    }

    private int currentHaiku;
}

A Service can do a bit more that I've shown here. Here are methods that the Service base class provides in Jandal 1.0, none of which are used in RandomHaikuService:

  • setSynchronized(yesNo) may be called from within your subclass to flag itself as requiring synchronisation, where a lock must first be acquired on it by any EventProcessor, State or Controller that wants to use it,
  • isSynchronized() returns true if the Service is flagged to require synchronisation,
  • applicationStarted(String appId) is called whenever an Application has started up, specifying the ID of the Application that started up, and
  • applicationStopped(String appid) is called whenever an Application has stopped.

The applicationStopped method is particularly valuable. It allows a Service to release any resources that it might be holding for an Application instance when the Application stops. Check out ServiceSynchronisation for more information on these methods.

RandomHaikuServiceSet.java

Just for completeness, here's the ServiceSet that contains our RandomHaikuService.

public class RandomHaikuServiceSet extends ServiceSet {
    public RandomHaikuServiceSet() {
        super();
        addService(new RandomHaikuService());
    }
}

The addService method is the only method provided by ServiceSet in Jandal and is used, as you can see, to plug Services into itself.