StatefulJ Framework

The StatefulJ Framework leverages StatefulJ FSM, StatefulJ Persistence and Spring Data to seamlessly integrate StatefulJ into your Application. Using Annotations to define your State Model, StatefulJ will auto generate the FSM infrastructure, bind with the optional Endpoint Providers and manage all State Persistence.

Installation

Installing StatefulJ Framework is dependent on the technologies within your stack.
The StatefulJ Frameworks is comprised of Persisters and optional Binders .

StatefulJ provides a set of optional Binders.
Binders “bind” Endpoint Providers to the StatefulJ Framework.
The Binders are responsible for forwarding incoming requests from the Endpoint Providers as events along with the accompanying input. The StatefulJ Framework supports the following Endpoint Providers:

• SpringMVC
• Jersey
• Camel

However, Binders aren’t required. You can invoke the StatefulJ framework directly. For information, consult Inject the StatefulFSM

Persisters interacts within the underlying databases. StatefulJ supports the following Persisters:

• JPA (SQL)
• MongoDB

So, depending on your stack, you will need to include the following dependencies into your Maven project:

Binders

SpringMVC

<dependency>
	<groupId>org.statefulj.framework</groupId>
	<artifactId>statefulj-framework-binders-springmvc</artifactId>
	<version>3.0</version>
</dependency>

Jersey

<dependency>
	<groupId>org.statefulj.framework</groupId>
	<artifactId>statefulj-framework-binders-jersey</artifactId>
	<version>3.0</version>
</dependency>

Camel

<dependency>
	<groupId>org.statefulj.framework</groupId>
	<artifactId>statefulj-framework-binders-camel</artifactId>
	<version>3.0</version>
</dependency>

Persisters

JPA

<dependency>
	<groupId>org.statefulj.framework</groupId>
	<artifactId>statefulj-framework-persistence-jpa</artifactId>
	<version>3.0</version>
</dependency>

Mongo

<dependency>
	<groupId>org.statefulj.framework</groupId>
	<artifactId>statefulj-framework-persistence-mongo</artifactId>
	<version>3.0</version>
</dependency>

Coding

To integrate the StatefulJ Framework, you define your State Model. To create a State Model, you will need to:

• Instantiate the Stateful Factory
• Define your Stateful Entity
• Define your States
• Define your StateController
• Define your Events
• Define your Transitions
• Inject the StatefulFSM

Instantiate the Stateful Factory

The Stateful Factory will inspect the StateControllers, bind with with Endpoint Providers and construct the State Model. In order for the Stateful Factory to discover the StateControllers, you must ensure that you have correctly defined your Spring Component Scans to include the StateController’s package or individually define each StatefulController bean via Spring XML or Java Config.

XML Configuration

 	<bean id="statefulJFactory" class="org.statefulj.framework.core.StatefulFactory" />

Java Configuration

	@Bean
	public StatefulFactory statefulJFactory() {
		return new StatefulFactory();
	}

Jersey Binding

For Jersey Binding, you must initialize an instance of StatefulJResourceConfig by extending StatefulJResourceConfig and mapping a root path.

@ApplicationPath("/ajax")
public class JerseyConfig extends StatefulJResourceConfig {
	
}

Define your Stateful Entity

A Stateful Entity is a Class that is persisted, managed by Spring Data and contains a State field.
The State Field defines the current State of the Entity and is managed by StatefulJ Framework.
The state field is annotated with the @State annotation.
For your convenience, you can inherit from either the StatefulEntity Class (JPA) or StatefulDocument Class (Mongo). This will automatically define a state field annotated with the @State Annotation.

Stateful Entity (JPA)

// Stateful Entity
//
@Entity
public class Foo extends StatefulEntity {
	
	@Id
	@GeneratedValue(strategy=GenerationType.SEQUENCE)
	Long id;	

	public Long getId() {
		return id;
	}
	
	public void setId(Long id) {
		this.id = id;
	}
	
}	

Stateful Document (Mongo)

// Stateful Document
//
@Document
public class Foo extends StatefulDocument {
	
	@Id
	String id;	

	public String getId() {
		return id;
	}
	
	public void setId(String id) {
		this.id = id;
	}
	
}	

Note: StatefulJ Framework determines the type of Persister to use for an Entity by the Entity’s association with a SpringData Repository. As such, you will need to define a Repository like so:

public interface FooRepository extends JpaRepository<Foo, Long> {
	
}

public interface FooRepository extends MongoRepository<Foo, String> {
	
}

Define your States

A State defines the state value for an Entity and is of type String. It is recommended that you define your States as public static constants within your Stateful Entity Class.

// Stateful Entity
//
@Entity
public class Foo extends StatefulEntity {
	
	// States
	//
	public static final String NON_EXISTENT = "Non Existent";
	public static final String ACTIVE = "Active";
	public static final String UPGRADE_PENDING = "Upgrade Pending";
	public static final String UPGRADED = "Upgraded";

	@Id
	@GeneratedValue(strategy=GenerationType.SEQUENCE)
	Long id;	

	public Long getId() {
		return id;
	}
	
	public void setId(Long id) {
		this.id = id;
	}
	
}	

Define your Stateful Controller

Stateful Controller defines the set of Transitions for the Stateful Entity. It is defined by annotating the Class with the @StatefulController Annotation. The @StatefulContoller defines the Stateful Entity the Controller is managing.

@StatefulController(
	clazz=Foo.class,
	startState=NON_EXISTENT
)
public class FooController {
}

Domain Entity Support

If you are designing applications using a Domain Driven Design (DDD) architecture, then you will want to integrate StatefulJ directly into the Domain Entity or Aggregate Root. If the StatefulController is bound to an Entity, then when StatefulJ fetches/creates the Entity, it will automatically perform Dependency Injection on the Domain Entity. As such, you will not need to define your Entity as @Configurable to perform dependency injection

@StatefulController(
	clazz=Foo.class,
	startState=NON_EXISTENT
)
public class Foo {
}

Define your Events

An Event is simply a String that directs the StatefulJ Framework how to bind an Endpoint to the Framework. The format of the Event is <binder>:<event>

@StatefulController(
	clazz=Foo.class,
	startState=NON_EXISTENT
)
public class FooController {

	// Events
	//
	public static final String CREATE_FOO = "springmvc:post:/foo";
	public static final String GET_FOO = "springmvc:get:/foo/{id}";
	public static final String UPGRADE_REQUEST = "springmvc:post:/foo/{id}/upgrade";
	                                             "springmvc:post:/foo/{id}/upgrade";
	public static final String UPGRADE_APPROVED = "upgrade.approved";
	public static final String SUBSCRIPTION_REVOKED = "camel:vm:subscription.revoked";
	

}

Define your Transitions

A Transition is a reaction to an Event directed at a Stateful Entity. The Transition can involve a possible change in State and a possible Action.

In the StatefulJ Framework, a Transition is a method in the Stateful Controller annotated with the @Transition annotation.

When a Transition is invoked, the StatefulJ Framework will call the associated method.
If the StatefulController is a Controller (vs a Domain Entity), then the first two parameters of the method are always:

1. Stateful Entity
2. The Event

Note: When the StatefulJ Framework binds the Endpoint, it reads all the Annotations on the method and all the Parameters after the StatefulEntity and Event and then propagates these parameters to the Endpoint. So, you can define your Transition with the parameters and annotations that you normally would for the Endpoint.

@StatefulController(
	clazz=Foo.class,
	startState=NON_EXISTENT,
	noops={
		@Transition(from=UPGRADE_PENDING, event=UPGRADE_APPROVED, to=UPGRADED)
	}
)
public class FooController {

	// Events
	//
	public static final String CREATE_FOO = "springmvc:post:/foo";
	public static final String GET_FOO = "springmvc:get:/foo/{id}";
	public static final String UPGRADE_REQUEST = "springmvc:post:/foo/{id}/upgrade";
	public static final String UPGRADE_APPROVED = "upgrade.approved";

	@Transitions({
		@Transition(from=NON_EXISTENT, event=CREATE_FOO, to=ACTIVE),
		@Transition(from=ACTIVE, event=UPGRADE_REQUEST, to=UPGRADE_PENDING),
		@Transition(event=GET_FOO)
	})
	public String details(Foo foo, String event, Model model) {
		model.addAttribute("foo", foo);
		return "foo-details";
	}
}

If the StatefulController is a Domain Entity, then the first parameter is:

1. The Event

@StatefulController(
	clazz=Foo.class,
	startState=NON_EXISTENT
)
public class Foo {

	// Events
	//
	public static final String UPGRADE_APPROVED = "upgrade.approved";
	
	@FSM
	StatefulFSM<Foo> fsm;
	
	public approveUpgrade() {
		fsm.onEvent(UPGRADE_APPROVED);
	}
	
	@Transition(from=UPGRADE_PENDING, event=UPGRADE_APPROVED, to=UPGRADED)
	private void doNotifyOfUpgrade(String event) {
		FooObserver.notifyUpgrade(new UpgradeEvent(this));
	}
}

Propagating Events and Non-Determinism

If your method returns a String, and that String is prefixed with event:, then the return value will be treated as an Event and re-propagated. This can be used to implement Non-Deterministic Transitions. For example, you can define a Transition without a to and in the associated method do further conditionals to determine an event to propagate. The returned event can then determine the actual State change.

	@Transition(from=STATE_A, event=EVENT_A)
	private String doNonDeterministic(Foo foo, String event) {
		if (foo.getBar().equals("b")) {
			return "event:" + EVENT_B;
		} else {
			return "event:" + EVENT_C;
		}
	}

	@Transitions({
		@Transition(from=STATE_A, event=EVENT_B, to=STATE_B),
		@Transition(from=STATE_A, event=EVENT_C, to=STATE_C)
	})
	private void doDeterministic(Foo foo, String event) {
		System.out.println("Event = " + event);
		System.out.println("State = " + foo.getState());
	}

Inject the StatefulFSM

The StatefulJ Framework provides the ability to route Events directly to the FSM. This is done by invoking the onEvent method of the associated StatefulFSM class. To obtain a reference to the StatefulFSM, you annotate a reference with the @FSM annotation. The StatefulJ Framewok will automatically inject the StatefulFSM based off the declared Generic Type. If there is more than one StatefulController that qualifies, then you can provide the bean Id of the specific StatefulContoller.

@FSM
StatefulFSM<Foo> fsm;

public void upgradeApproved(Foo foo) {
	fsm.onEvent(foo, UPGRADE_APPROVED);
}