• Home
  • Events
  • About
  • JavaFX Abacus Tutorial, Part VII – proper structure with OpenDolphin

    This is the seventh part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    Until part six, we have developed a nice-looking and basically functional abacus. It isn’t yet fully functional since the overflow rule is missing: when pushing balls to right and we come to the last available ball, we must push all balls on the current rail back to the left and add a ball in the rail above. You can see this effect in the video around the 1:50 timestamp. We could do this work just as manually as one does it with a physical abacus but it would be much more convenient if the application could do it for us – imagine how much easier it would be to calculate 999’999 + 1 if we had an automatic overflow (video).

    With this new requirement we have reached the limit where it no longer feels appropriate to

    • have all view and controller logic as well as starter configuration in one class
    • have controller logic working directly on the view without any model.

    Now, we could go the route of creating model classes like Board and Rail and Ball and work with observable lists and bindable properties (and I advice you give this approach a try) but that would mean that we model the domain while at the same time we make the domain aware of the view’s presentation technology (because of all the additional observable/bindable work).
    Let’s go for different approach, where we use presentation models with the help of OpenDolphin.

    Enter OpenDolphin

    OpenDolphin gives us a very clean structure with a clear separation of the following modules

    • client: only containing the view; depends on the view technology (JavaFX) and optionally on shared
    • server: only containing controller logic (actions), optionally depends on shared
    • shared: optionally share constants between client and server, depends on nothing
    • combined: starter configuration that depends on all the above

    There is a huge number of benefits that come with OpenDolphin but for the sake of brevity, we will only use a few of them. We can see a first obvious benefit from only looking at the dependency structure: the actions have no access to the view. The view and the view technology isn’t even on the classpath! No longer can you “accidentally” reach out from a controller onto a view. But how can an action do its work then?

    Presentation models are synchronized between client and server.
    Actions work on presentation models (CRUD operations).
    Views bind against presentation models and send commands to the controller.
    Presentation models are generic, i.e. we do not have to implement any specific class.

    Setting up

    Creating the modules and the dependencies may sound like a lot of work but there is a template that we have used to create the current codebase. The template is available from DolphinJumpStart where we used the dist/jumpstart-maven.zip, unzipped it to dolphinized, and changed the application name in the maven POMs.

    There also is a Gradle variant but if you are using Gradle, you will probably find your way around anyway.

    Abacus_Project_ViewTo get started, you best point your favorite IDE to the root pom.xml and let the IDE create a project for you.

    Tip: with multiple modules and source roots, it is often more convenient to use the “package view” (see screenshot on the right) than the classical directory view.

    Lifting the curtain

    AbacusStarter is the class with a main method that you use for starting the application. It sets up OpenDolphin with the in-memory mode since we currently run client and server in the same JVM (we can add remoting later). It also registers the AbacusDirector, which works a bit like a movie director: it tells what “actors” are in the play.

    After the setup, the AbacusStarter starts the show.

    And ” ACTION ! “

    We have two actions: the CreateBallsAction that initially creates a presentation model for each ball in the abacus, and the ToggleAction that is called when a ball is clicked.

    The gist of the CreateBallsAction creates a presentation model for each row/column combination:

    In the presentation model, we think in terms of “digits on a scale” and whether that digit is switched “on”. The view in contrast – which is only one of many possible views – uses the concept of balls sitting on a rail.

    The ToggleAction is a bit more involved as it contains two command handlers: one for toggling a digit (and its neighbors), and one for the overflow rule.

    The important point to note here is that the server knows, which ball has been touched on the client for toggling, because there is a special presentation model with the constant name PM_TOUCHED which is shared between client and server.

    The overflow rule is a value change listener on the server side that is triggered whenever a “leftmost” digit in switched to “on”.

    We get the nice effect that the overflow rule works separately from the toggling and that the proliferated overflow as in “99 + 1″ comes automatically.

    The separation of the overflow rule in this manner is not quite as easy to achieve without OpenDolphin. One has to ensure a proper sequence of events: pushing the ball to the right, moving the ball in the rail above, moving all balls in the current row to the left. It is all-too easy to fall for a “sham solution” that occasionally leaves balls in the wrong position because they are first moved left and then to the right.
    OpenDolphin guarantees a proper event sequence – even though it executes all actions asynchronously.

    Simple View

    This leaves us with the AbacusApplication JavaFX view. It has been slimmed down to the bare essentials: displaying the presentation models, calling the toggle command when needed.
    Two points are of main interest: the start method and the click handler.
    The start method now looks as follows:

    Note that we create the touchedBall presentation model on the client side and we are sending the CMD_CREATE_BALLS command to the server. Only when that command is finished, we have all necessary presentation models on the client to bind against. Therefore, we provide an OnFinishedHandler that is called when the command has finished with all newly available presentation models.

    The click handler is now registered like so:

    When a ball is clicked we first have to update the touchedBall state before we send the toggle command. Updating via apply essentially copies all values from the ballPm over to the touchedBall presentation model.

    But wait – the toggle action (see above) changes that value of the touchedBall – not of the ballPm that was copied. How is the change propagated back?
    That is because of the qualifier that we have set when creating the presentation models. This qualifier has been copied as well and when a value changes, all presentation models with the same qualifier are updated to the same value.
    Such a construction is only possible because all OpenDolphin presentation models live in a managed object space. OpenDolphin is always in total control of all presentation models, can retrieve them by id or other features, and cares for consistent updates.

    Finally

    This has of course only been a short introduction to OpenDolphin – or better not an introduction at all but a very special use case that can only show a very small fraction of its capabilities.
    I hope you found it useful and it made you curious to find out more.

    I planned this series to have 7 posts, which means we have now completed the curriculum. Congratulations!

    However, our final solution is so versatile, it would be a shame not to make use of it.
    It is has become simple to test the application logic (set/assert the presentation models), use other number systems (binary abacus anyone?), or make more use of cool JavaFX features to dramatically change the visual representation by solely changing the view. So don’t be surprised if you hear about post (8/7) in the near future.

    Please send me your questions/ideas/suggestions on twitter
    @mittie

    Share and Enjoy: These icons link to social bookmarking sites where readers can share and discover new web pages.
    • DZone
    • Y!GG
    • Webnews
    • Digg
    • del.icio.us
    • DotNetKicks
    • Facebook
    • Google Bookmarks
    • Newsrider
    • Twitter
    • YahooBuzz

    1 Comment »

    1. Daynacook said,

      July 25, 2013 @ 8:22

      Thanks for posting this. Very nice recap of some of the key points in my talk. I hope you and your readers find it useful! Thanks again
      ———————

    RSS feed for comments on this post

    Leave a Comment


    7 − = two

    css.php