JSpasm

A Java™ package for implementing event-driven systems with state machines

Current status

The current stable release is v2.2, which was made available for download 31-Mar-2006. It was developed and tested under Java 1.4.2.

Enhancements since the previous 2.1 release include:

Enhancements since the previous 1.1 release include:

We want to hear from you

Have you used JSpasm in a non-trivial application? If so, we'd like to hear from you. Tell us what you like and don't like about JSpasm - your feedback will help us improve the package. Contact us using the link in the sidebar. And, if you're using JSpasm in a production environment, please consider making a donation to support our development and documentation efforts.

Downloading JSpasm

The links on the left allow you to browse the package API Javadocs and to download Jar files:

JSpasm has no dependencies on other packages.

Getting started

Start by reading the Package Description page (there's a link under "Documentation" in the sidebar to the left). This document gives an overview of the package and describes how to get started in designing a state-based system and then implementing it in Java using JSpasm. We've tried to cover use of all of the package features without spending too long on each, so you might consider this document a "quick-start" guide. (The same document appears in the Overview section of the Javadocs, by the way.) As noted below, we're working on a more comprehensive user manual at the moment.

If you want to see some real code, take a look at the source of the JSpasmTest program in the test & demo package. While this program is of limited use it does at least show how a JSpasm system using multiple state models is created and then run using many live entities. Read the source via the "Browse the sources" link at left, or (better still) download the package Jar and extract the source.

Some background

What is an event-driven system?

An event-driven system is one designed to wait for signals that indicate that certain conditions have arisen and then to process those signals to decide what actions to take.

Application programs for windowing operating systems are usually event-driven; the events signal things like key presses and mouse clicks. Computerized telephone exchanges are driven by events such as someone taking the phone off the hook or pressing buttons to dial a number. There are many other examples.

What is a state machine?

A state machine is a system in which an entity can be in one of a number of predefined states at any given time, and which changes state in response to events. Action code associated with the state is executed as part of the state change and performs the operations necessary to support the application's requirements.

There's a good article about state machines on Wikipedia.

What is JSpasm?

JSpasm is a 100% pure Java™ package that makes it easy to develop applications, libraries or other packages based on state machines.

JSpasm allows you to develop systems that contain multiple state models and large numbers of entities working within those state models in parallel. It also includes features designed to improve performance on SMP systems.

JSpasm is designed to be small and memory-efficient, making it suitable for applications running with limited memory in PDAs, cellphones and so on. The binary-only Jar is about 23KBytes.

What kinds of applications are suited to the state model approach?

The state approach offers a solution to certain scalabilty problems that can arise in Internet servers. A typical model for server applications involves creating a thread to accept incoming connections; as each connection from a client is established, the accepting thread creates a handler thread associated with the new socket. This can lead to a large number of active threads being created on a busy system. However, most operating systems impose limits on the number of threads that can exist at any given time and so it is possible for a busy server to exhaust the available threads. In addition, complex synchronization may be required and this reduces the overall efficiency and throughput of the server.

The java.nio package eases this problem somewhat by providing non-blocking I/O operations that allow a single thread to handle multiple sockets. However it is left to application developers to devise a framework for handling large numbers of sockets with a limited number of threads.

JSpasm provides such a framework. By associating a state model entity with each connection it becomes simple to handle large numbers of connections without requiring a thread for each.

Another area where the state approach fits well is text parsing; many compilers and interpreters for computer languages and other application-specific scripting languages use lexical analyzers that are state-based. As a more concrete example, consider the SAX parser for XML, in which a reader class scans the XML stream and calls user-supplied handlers as tags are identified. If those handlers generate events into a JSpasm engine backed by a model that describes the valid sequence of XML tags, it becomes quite simple to create a package that will scan and process application-specific XML.

The state approach is also well suited to embedded real-time systems. As an example, telephone exchanges are designed around a set of industry-standard state models and in general operate internally as large, multi-entity state machines.

Where does the name "JSpasm" come from?

The original package was going to be called something like, "Scalable High-Performance State Machine", which would have had an acronym (if you can call it that) of "SHPSM". That doesn't exactly roll off the tongue but if you try to pronounce it in English it comes out sounding something like "Shpuzm". From that came "Spasm" and then to make it more obvious that it's a Java package we put the J on the front. There you have it :)

What's next for JSpasm

The next work lined up is to make source modifications to create a Java™ 5 source version.

A high priority at this time is to write a comprehensive user manual that will show developers how to design systems based on state models using tools such as state model and call sequence diagrams, etc. and then how to implement those models using JSpasm to create working systems. Note: This effort has been delayed and unless user demand is indicated, this manual may never be completed.

We're in the process of developing an add-on package to simplify creating a server using the java.nio package's non-blocking I/O features. The idea is that developers will be able to set up a server using JSpasm and java.nio with a minimum of coding. This effort is at the design stage at this time.

We are also planning to extend the test program so that it performs a far more comprehensive set of tests on the core classes. The current test program does a good job of checking that event generation and delivery works correctly under all thread schemes, but does no checking to ensure that all possible error conditions are detected and reported.

We're also considering an uprated benchmark program that will compare performance under each thread scheme. This will help users select the best scheme for their platform when using systems that allow simultaneous multi-threaded operation (that is, systems with multiple processors, multi-core processors and/or processors with chip-level multithreading, also known as "hyperthreading").

Under the current version of JSpasm it's simple for entities to generate events to be delivered to other entities running in the same engine. What's not so simple is generating events for entities running in another engine instance. We're looking at ways to make it much simpler for entities to generate events for entities that are in other engines within the same JVM, or running in another process on the same system, or on another system. The first of these is quite simple to implement and improves the flexibility of the package, so we may do this in a future version. Inter-process and inter-system event transport is more of a challenge, so while we're looking at this we may not implement anything unless feedback from users indicates that there is a need for it.