Tutorial: Getting Started with Physhun and Physhun Modeler

• Tutorial Sources
• Tutorial Sources with all libraries

In this tutorial, we will model and implement a virtual soda vending machine. This machine works just like a real soda machine - it accepts money and vends the soda selected by the customer. If the selection is out of stock, the machine displays an out of stock message. If the selection costs more than the customer has put into the machine, it displays the appropriate message. If the customer selects "coin return", the machine returns the money that has been deposited. As we use Physhun Modeler to model our Process, it will generate an XML File containing the definitions for the State Model and all of its components. This XML file can be read in by Spring's ClassPathXmlApplicationContext to create an instance of the State Model at runtime. The full XML for the State Model can be seen here.

Before starting this tutorial, download and install Physhun and PhyshunModeler. Note that Physhun can be used without Modeler; you may develop your State Model XML files using whatever tool you prefer. Physhun Modeler allows you to develop your state models by laying them out graphically.

Physhun and Physhun Modeler can both be downloaded from the sourceforge project summary page at http://sourceforge.net/projects/physhun.

1. Define the ProcessObject and Event classes

For this example, we will define our own ProcessObject implementation. The ProcessObject should contain all of the necessary attributes for a meaningful business object. If your process object does not need any attributes other than state, you may use com.wazeegroup.physhun.framework.ConcreteProcessObject. Alternatively, the PhyshunXML package provides an out of the box process object all of whose attributes are stored in XML.

package soda;

import com.wazeegroup.physhun.framework.ConcreteProcessObject;

public class SodaTransaction extends ConcreteProcessObject {

    private float funds;
    private String lastMessage;

    public SodaTransaction(String id) {
        super(id);
    }

    public float getFunds() {
        return funds;
    }

    public void setFunds(float funds) {
        this.funds = funds;
    }

    public String getLastMessage() {
        return lastMessage;
    }

    public void setLastMessage(String lastMessage) {
        this.lastMessage = lastMessage;
    }

}

package soda.events;

public class SelectionButtonPressed {
    
    private String selection;

    public String getSelection() {
        return selection;
    }

    public void setSelection(String selection) {
        this.selection = selection;
    }

    public SelectionButtonPressed(String selection) {
        this.selection = selection;
    }
}

package soda.events;

public class FundsAdded {
    private float howMuch;

    public float getHowMuch() {
        return howMuch;
    }

    public void setHowMuch(float howMuch) {
        this.howMuch = howMuch;
    }

    public FundsAdded(float howMuch) {
        this.howMuch = howMuch;
    }
}

package com.wazeegroup.physhun.examples.soda.events;

public class CoinReturnPressed {
}

2. Start Physhun Modeler

3. Lay out the states and transitions for the state model.

To create a transition, mouse over the source state (the state from which the transition starts). You will see several colored "ports" appear. Click and drag from a port on the source state to a port on the target state. You will see an arrow appear pointing from the source state to the target state. If to add bends to the transition line (for cosmetic purposes), simply click and drag on the point on the transition line at which you wish to add a bend.

The state model we are defining for this example follows. NewTransaction is a start state, and "TransactionCancelled" and "TransactionComplete" are end states.

4. Define actions and conditions for state transitions

In this example, we don't have a real soda machine to interface with, so we will simply print what the soda machine hardware would normally do (display messages, vend soda, etc.).

First we'll configure the transition from "NewTransaction" to "TransactionInProgress": Double click the transition to open the transition editor. Set the condition to "Reference" and select "DefaultCondition" from the drop down list. DefaultCondition is a Global Condition (global conditions can be referenced my multiple transitions) that simply evaluates to true if no other transitions from that state evaluate to true. Since we don't need to execute any logic on this transition, we don't set an Action. View the transition editor for this transition.

Note the XML window in the Transition Editor (just above the "OK" and "Cancel" buttons. This is the Bean definition XML for the Transition. Modeler automatically defines this XML based on your selections in the Transition Editor; however, you may modify this XML directly if you need more control over the Bean definition.

Next we'll define the transition details for the transition from "TransactionInProgress" back to itself that occurs when money is added to the machine. The Condition for this transition is that a "FundsAdded" event occurs. To set this up, open the transition editor for the transition, set Condition type to "Inline Groovy" and click "Edit Condition". This will open the Inline Java Condition Editor. In this editor, you define the condition implementation using Groovy. Since the Groovy runtime will execute Java code generally without change, we can write our Condition and Action code as plain old Java. Because we want this transition to be a "Triggered" transition - that is, it is initiated by an event occurrence, mark the condition as a "Triggered Condition". Any transition with a Triggered Condition will only be evaluated for execution when an external event is sent to the process instance. In this example, the external event is sent to the process instance by the UI when money is put in the machine, a button is pushed or the coin return is pressed. See step 6 for more detail.



For the Action on this transition, we want to increment the total transaction funds by the amount that was added. In the transition editor, set the Action Type to "Inline Groovy" and select "Edit Action". The Action implementation follows:

• NewTransaction - TransactionInProgress
• TransactionInProgress self transition - Funds Added
• TransactionInProgress self transition - Selection Out Of Stock
• TransactionInProgress self transition - Selection Price Exceeds Funds
• TransactionInProgress - TransactionCancelled
• TransactionInProgress - TransactionComplete

5. Implement custom Action and Condition classes

6. Export process model

7. Bootstrap process execution

package soda;

import com.wazeegroup.physhun.engine.ProcessContainer;
import com.wazeegroup.physhun.framework.StateModel;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import soda.events.CoinReturnPressed;

public class RunExample {
    public static void main(String[] args) {
        SodaTransaction sodaTx = new SodaTransaction("mySodaTransaction");
        ClassPathXmlApplicationContext ctx = new ClassPathXmlApplicationContext(new String[]{"sodaModel.xml", "soda-processConfig.xml"});
        ProcessContainer container = (ProcessContainer)ctx.getBean("container", ProcessContainer.class);
        StateModel stateModel = (StateModel) ctx.getBean("stateModel");  //inflate and retrieve the stateModel bean.
        container.startProcess(sodaTx, stateModel);
        container.sendTriggerEventToProcess("mySodaTransaction", new soda.events.FundsAdded(0.1f)); // put in a dime
        container.sendTriggerEventToProcess("mySodaTransaction", new soda.events.SelectionButtonPressed("Coke")); //push the coke button
        container.sendTriggerEventToProcess("mySodaTransaction", new CoinReturnPressed());
    }
}

That's it; you should now have a working Virtual Soda Machine. If you are interested in more examples, including examples involving distributes transaction, download the examples package from the Sourceforge project page.