Difference between revisions of "Statemachine DSL"

From OS.bee documentation
Jump to: navigation, search
(states)
(controls)
Line 571: Line 571:
 
*'''fields''' - A type of bean that holds data of input fields or labels from UI.
 
*'''fields''' - A type of bean that holds data of input fields or labels from UI.
 
*'''dataProvider''' - A type of bean that retrieves and stores data based on DTO.
 
*'''dataProvider''' - A type of bean that retrieves and stores data based on DTO.
*'''peripheral''' - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error.
+
*'''peripheral''' - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error. The supported peripherals are listed [[OS.bee_peripherals_for_JavaPOS|here]].
* StatemachineControlButtonEventType is including: keyboard | trigger | identity.
+
* '''StatemachineControlButtonEventType''' is including: keyboard | trigger | identity.
* StatemachineFieldType is including: Boolean | Integer| Long | Double | String | Date | SuggestText.
+
* '''StatemachineFieldType''' is including: Boolean | Integer| Long | Double | String | Date | SuggestText.
  
  

Revision as of 15:27, 29 January 2018

Introduction

State Machine

State Machine or extended finite-state machine (EFSM) is a mathematical model of computation and represents an abstract machine that can be in exactly one of a finite number of states at any given time. The State Machine can change from one state to another in response to external events. The change from one state to another is called a transition. A EFSM is defined by a list of its states, its initial state, and the conditions for each transition. The condition for a transition is called guard. There can be many guards protecting a transition to be triggered. Every guard is joined with a logical AND operation, so every guard must evaluate to true, to trigger a protected transition. Data operations can occur before a transition. They are called actions. Actions prepare the indicated state of the transition, calculate things or display information. The StatemachineDSL described in the following implements an EFSM where the FSM-block is represented by states, the A-block is called actions and the E-block is called guards.

Further reading

https://en.wikipedia.org/wiki/Finite-state_machine

https://en.wikipedia.org/wiki/Extended_finite-state_machine

https://en.wikipedia.org/wiki/UML_state_machine


Statemachine DSL

Statemachine DSL implements the state pattern (https://en.wikipedia.org/wiki/State_pattern) and interconnects UI model, FunctionLibrary, DTO and peripheral services like JavaPOS, ZVT protocol and others.

The main semantic elements of the StatemachineDSL are:

  • package - The root element that contains all the other elements. A model can contain multiple packages.
  • import declarations - Used to import external models or other Java classes.
  • statemachine - The container for the implementation of the EFSM following the state pattern.
  • events - Contains all user defined events.
  • event - Defines a single event by id. Events build the interconnection elements between controls and transitions.
  • controls - The container for all type of beans (https://en.wikipedia.org/wiki/JavaBeans) to be controlled by the state machine.
  • scheduler - A type of bean that can be triggered to emit a defined event after a defined delay.
  • keypad - A type of bean that builds a keypad containing one or more buttons to emit a defined event when pressed.
  • fields - A type of bean that holds data of input fields or labels from UI.
  • dataProvider - A type of bean that retrieves and stores data based on DTO.
  • peripheral - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error.
  • attribute - Defines different types for usage with control.
  • states - The container for all state definitions of this state machine.
  • state - A single state the machine can be at a point in time.
  • triggers - The container for all possible event processing blocks inside a state.
  • trigger - The action block following this trigger will be executed when one of its events occur.
  • actions - The container for all process instructions to be done in sequence inside this block. Optionally an action block can follow a transition.
  • transistion - The transition will be executed when all actions of this block were processed successfully.
  • guards - The container for guards protecting the following transistion.
  • guard - A condition that must evaluate to true that the following transistion will be processed.

Syntax

package definition

Syntax:

package <package name> [{
	statemachine <statemachine name> [describedBy <description string>]
	[functiongroup <function:FunctionLibraryStatemachineGroup>]
	initialState <StatemachineState>
	initialEvent <StatemachineEvent>
	events {
		event <event name>
		. . .
	}
	controls {
		StatemachineControl
		. . .
	}
	states {
		StatemachineState
		. . .
	}
	. . . 
}]


example:

package net.osbee.sample.foodmart.statemachines {
 	statemachine CashTerminal describedBy "Cash Register"  
	functiongroup CashRegister
	initialState IDLE
	initialEvent onStartUp 
	events {
		event onStartUp
		. . .
}
	controls {
		scheduler Schedulers {. . .}
		. . .
}
	states {
		state IDLE { . . .}
		. . .
	}
}
important definition
StatemachineActionFieldConcatenation

Syntax:

 <STRING> [+ <STRING> . . .]

or

<SignedNumber> [+ <SignedNumber> . . .]

or

<INTEGER> [+ <INTEGER> . . .]

or

<BOOLEAN> [+ <BOOLEAN> . . .]

or

StatemachineEvaluationType [+ StatemachineEvaluationType . . .]

or

translate <STRING> [+ translate <STRING> . . .]

or

get <StatemachineControlFieldAttribute> [+ get <StatemachineControlFieldAttribute> . . .]

or

operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation[,StatemachineActionFieldConcatenation. . . ]) [+ operation <function:FunctionLibraryOperation>. . .]

or

retrieve from <key ID>.<attribute ID> [+ retrieve from <key ID>.<attribute ID> . . .]

or

dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute> [+ dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute> . . .]

or

function <function:FunctionLibraryFunction> (StatemachineActionFieldConcatenation[,StatemachineActionFieldConcatenation . . . ])

or

event

or

paymentResponse from <StatemachinePeripheralDevicePT>


  • StatemachineEvaluationType is including: getIPAddress |getHostName | getNow | getUserAgentInfo | isTouchDevice | isHttps | getBrowserLocale | getUserName| getUserPassword | getUserEmail | getUserPosition | getUserPrintService | getSceenWidth | getScreenHeight | getTrigger .

example:

operation dopayment(retrieve from paymentMethod.last)
StatemachineActionFieldSource

Syntax:

 <STRING>

or

<SignedNumber>

or

<INTEGER>

or

<BOOLEAN>

or

StatemachineEvaluationType

or

translate <STRING>

or

get <StatemachineControlFieldAttribute>

or

function <function:FunctionLibraryFunction> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation. . . ])

or

retrieve from <key ID>.<attribute ID>

or

dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>

or

event

or

paymentResponse from <StatemachinePeripheralDevicePT>
  • StatemachineEvaluationType is including: getIPAddress | getHostName | getNow | getUserAgentInfo | isTouchDevice | isHttps | getBrowserLocale | getUserName| getUserPassword | getUserEmail | getUserPosition | getUserPrintService | getSceenWidth | getScreenHeight | getTrigger.


example:

function getPaymentTotal()
StatemachineFilter

Syntax:

  and ( [StatemachineFilter] , StatemachineFilter. . . )

or

or ( [StatemachineFilter] , StatemachineFilter. . . )

or

StatemachineCompareOperationEnum (dto <StatemachineControlDTOAttribute>.< dto:LDtoInheritedAttribute>, StatemachineActionFieldSource)

or

isBetween(dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, start StatemachineActionFieldSource, end StatemachineActionFieldSource)

or

isNull (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>)

or

isLike (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, StatemachineActionFieldSource [ignoreCase])

or

not ( StatemachineFilter )

or

matches (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, <filterString> [ignoreCase] [onlyMatchPrefix])
  • StatemachineCompareOperationEnum is including: equal | greater | less | greaterOrEqual | lessOrEqual.


example:

keystroke @paymentGiven and operation givenChanged()
StatemachineAction

Syntax:

blinkRate <rate INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
clearDevice <StatemachinePeripheralDeviceLineDisplay>

or

 
createWindow row <viewportRow INT> column <viewportColumn INT> height <viewportHeight INT> width <viewportWidth INT> windowHeight <windowHeight INT> windowWidth <windowWidth INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
cursorType StatemachineLineDisplayCursorType @<StatemachinePeripheralDeviceLineDisplay>

or

 
destroyWindow <StatemachinePeripheralDeviceLineDisplay>

or

 
deviceBrightness <brightness INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
displayBitmap id <bitmapId INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
displayText text StatemachineActionFieldConcatenation [type StatemachineLineDisplayTextType] @<StatemachinePeripheralDeviceLineDisplay>

or

 
displayTextAt text StatemachineActionFieldConcatenation row <row INT> column <column INT> [type StatemachineLineDisplayTextType] @<StatemachinePeripheralDeviceLineDisplay>

or

 
interCharacterWait <wait INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
marqueeFormat StatemachineLineDisplayMarqueeFormat @<StatemachinePeripheralDeviceLineDisplay>

or

 
marqueeRepeatWait <wait INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
marqueeType StatemachineLineDisplayMarqueeType @<StatemachinePeripheralDeviceLineDisplay>

or

 
marqueeUnitWait <wait INT>  @<StatemachinePeripheralDeviceLineDisplay>

or

 
scroll StatemachineLineDisplayScrollTextType <units INT> @<StatemachinePeripheralDeviceLineDisplay>

or

 
openDrawe <StatemachinePeripheralDeviceCashDrawer>

or

 
printBarcode data <data STRING> barcodeType StatemachinePOSPrinterBarcodeType @<StatemachinePeripheralDevicePOSPrinter>

or

 
printBitmap id <bitmapId INT> @<StatemachinePeripheralDevicePOSPrinter>

or

 
printCut text StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePOSPrinter>

or

 
printNormal text StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePOSPrinter>

or

 
printerBitmap id <bitmapId INT> name <name STRING> @<StatemachinePeripheralDevicePOSPrinter>

or

 
displayBitmap id <bitmapId INT> name <name STRING> @<StatemachinePeripheralDeviceLineDisplay>

or

 
paymentOpen host StatemachineActionFieldConcatenation port StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>

or

 
paymentClose @<StatemachinePeripheralDevicePT>

or

 
paymentAcknowledge @<StatemachinePeripheralDevicePT>

or

 
paymentReversal withPassword StatemachineActionFieldConcatenation ofReceipt StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>

or

 
paymentRegistration withPassword StatemachineActionFieldConcatenation configuration <configuration STRING> @<StatemachinePeripheralDevicePT>

or

 
paymentAuthorization ofAmount StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>

or

 
printReport <report:Report> [from <StatemachineStorage>]

or

 
set StatemachineActionFieldConcatenation @<StatemachineControlFieldAttribute>

or

 
remove <StatemachineControlFieldAttribute>

or

 
visible <StatemachineControlVisibility>

or

 
invisible <StatemachineControlVisibility>

or

 
clear <StatemachineControlFieldAttribute>

or

 
caption StatemachineActionFieldConcatenation @<StatemachineControlButtonAttribute>

or

 
image <image STRING> @<StatemachineControlButtonAttribute>

or

 
search StatemachineActionFieldConcatenation in <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>

or

 
store StatemachineActionFieldConcatenation with <key ID>.<Attribute ID>

or

 
schedule <StatemachineControlSchedulerAttribute>

or

 
operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ])

or

transition <StatemachineState> guard <function:FunctionLibraryGuard> [onFail caption <onFailCaption STRING> description <onFailDescription STRING> type StatemachineUserMessageType]{ StatemachineAction. . .}
  • StatemachineLineDisplayCursorType is including: none | fixed | block | halfblock | underline | reverse | other | blink.
  • StatemachineLineDisplayTextType is including: normal | blink | reverse | blinkreverse.
  • StatemachineLineDisplayMarqueeFormat is including: walk | place.
  • StatemachineLineDisplayMarqueeType is including: none | up | down | left | right | init.
  • StatemachineLineDisplayScrollTextType is including: up | down | left | right.
  • StatemachinePOSPrinterBarcodeType is including: upca | upcb | jan8 | ean8 | jan13 | ean13 | tf | itf | codeabar | code39 | code93 | code128 | upca_s | upce_s | upcd1 | upcd2 | upcd3 | upcd4 | upcd5 | ean8_s | ean13_s | ean128 | orca | ocrb | code128_parsed | gs1databar | gs1databar_e | gs1databar_s | gs1databar_e_s | pdf417 | maxicode | datamatrix | qrcode | uqrcode | aztec | updf417.
  • StatemachineUserMessageType is including: humanized | warning | error | tray | assistive .


example:

clearDevice LineDisplay
createWindow row 0 column 0 height 1 width 20 windowHeight 1 windowWidth 87 @LineDisplay
marqueeFormat walk @LineDisplay
   
marqueeType init @LineDisplay
marqueeRepeatWait 800 @LineDisplay
marqueeUnitWait 100 @LineDisplay
displayText text "OS.bee is the only software that adapts to your business rules, rather than vice versa." @LineDisplay
invisible login
visible numbers
clear passwordEntry
set 0.0 @paymentGiven
operation loadPLU(1.0,6.0)
paymentOpen host dto cashregister.payment_ip port dto cashregister.payment_port @VeriFone
events

Syntax:

	
events {
	event <event name>
	. . .
}
  • events - Contains all user defined events.
  • event - Defines a single event by id. Events build the interconnection elements between controls and transitions.


example:

events {
	event onStartUp
	. . .
}
controls

Syntax:

controls {
	StatemachineControl
	. . .
}


keypad <name ID> event StatemachineControlButtonEventType {
	button <name ID> [image <image STRING>] key <keystroke STRING>|id <identity INT>|event <StatemachineEvent>
	. . .
  }

or

fields <name ID> {
	 field <name ID> type StatemachineFieldType
	 . . .
	&
	 layout <name ID>
	 . . .
  }

or

dataProvider <name ID> {
	  dto <name ID> type <dto:LDto> [event <StatemachineEvent>]
	  . . . 
	&
	  filter <name ID> StatemachineFilter
  	  . . .
  }

or

 
scheduler <name ID> {
	scheduler <name ID> delay <delay INT> send <StatemachineEvent>
	. . .
  }

or

peripheral <name ID> { 
	lineDisplay <name ID>
	. . .
	posPrinter <name ID>
	. . .
	cashDrawer <name ID>
	. . .
	payment <name ID>
	. . .
  }
  • controls - The container for all type of beans (https://en.wikipedia.org/wiki/JavaBeans) to be controlled by the state machine.
  • scheduler - A type of bean that can be triggered to emit a defined event after a defined delay.
  • keypad - A type of bean that builds a keypad containing one or more buttons to emit a defined event when pressed.
  • fields - A type of bean that holds data of input fields or labels from UI.
  • dataProvider - A type of bean that retrieves and stores data based on DTO.
  • peripheral - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error. The supported peripherals are listed here.
  • StatemachineControlButtonEventType is including: keyboard | trigger | identity.
  • StatemachineFieldType is including: Boolean | Integer| Long | Double | String | Date | SuggestText.


example:

keypad NumericPad event keyboard {
	button zero key "0" 
	button one key "1"
	button two key "2" 
	button three key "3"
	button four key "4" 
	button five key "5"
	button six key "6" 
	button seven key "7"
	button eight key "8" 
	button nine key "9"
	button dzero key "00" 
	button dot key "." 
}
fields UiControl {
	layout numbers
	layout login
	layout paymentFields
	layout entry
	layout functions
	layout plu
	layout money
	layout method
	layout receipt 
	field passwordEntry type String
	field sku type SuggestText
	field paymentTotal type Double
	field paymentGiven type String
	field paymentChange type Double 
	field paymentPayed type Double 
	field qty type Double 
	field totalAmount type Double
	field amount type Double
	field price type Double 
	field productName type String
	field paymentTerminal type String
	field filterToggleStyle type String
	field blurEvent type EmbeddableEvent
	field focusEvent type EmbeddableEvent
	field contextEvent type EmbeddableEvent
}
dataProvider DataControl { 
	dto product type MproductDto 
	dto cashregister type CashRegisterDto 
	dto cashslip type CashSlipDto
	dto cashpayment type CashPaymentDto event onPaymentSelection 
	dto cashposition type CashPositionDto event onPositionSelection 
	dto cashpaymentmethod type CashPaymentMethodDto
	filter positionFilter equal(path cashposition.product.low_fat, true)
}
scheduler Schedulers {
	scheduler toAutoLogout delay 10000 send onLogout
	scheduler toStart delay 100 send onStartUp
	scheduler toDisplayTest1 delay 10000 send onDisplayTest1
	scheduler toDisplayTest2 delay 6000 send onDisplayTest2  
	scheduler toDisplayTest3 delay 4000 send onDisplayTest3  
	scheduler toDisplayTest4 delay 3000 send onDisplayTest4  
	scheduler toDisplayTest5 delay 4000 send onDisplayTest5  
	scheduler toDisplayTest6 delay 1000 send onDisplayTest6  
	scheduler toDisplayTest7 delay 1000 send onDisplayTest7  
	scheduler toDisplayTestFinish delay 2000 send onDisplayTestFinish  
	scheduler toDisplayIdle delay 100 send onDisplayIdle
	scheduler toPaymentTerminalRecovery delay 1000 send onPaymentTerminalRecovery
}
peripheral PeripheralControl {
	lineDisplay LineDisplay 
	posPrinter POSPrinter
	cashDrawer CashDrawer
	payment VeriFone
}
states

Syntax:

states {
	StatemachineState
	. . .
}
state <state name>{
	[triggers {
		trigger (<StatemachineEvent>. . .)
		[guards { 
			guard <function:FunctionLibraryGuard> [onFail caption <onFailCaption STRING> description <onFailDescription STRING> type StatemachineUserMessageType]
			. . .
		}]
		actions [transition <StatemachineState>] { 
			StatemachineAction
			. . .
		}
		. . .
	}] 
  &	[identity operation <function:FunctionLibraryOperation>	(StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ])]
  &	[keystroke @<StatemachineControlFieldAttribute> [and operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ]]]
}
  • states - The container for all state definitions of this state machine.
  • state - A single state the machine can be at a point in time.
  • triggers - The container for all possible event processing blocks inside a state.
  • trigger - The action block following this trigger will be executed when one of its events occur.
  • actions - The container for all process instructions to be done in sequence inside this block. Optionally an action block can follow a transition.
  • transistion - The transition will be executed when all actions of this block were processed successfully.
  • guards - The container for guards protecting the following transistion.
  • guard - A condition that must evaluate to true that the following transistion will be processed.
  • StatemachineUserMessageType is including: humanized |warning |error |tray |assistive.

example:

state IDLE { 
	triggers {
		trigger onStartUp
		actions transition LOCKED{
			clearDevice LineDisplay 
			displayText text translate "locked" @LineDisplay
			invisible entry
			invisible receipt 
			invisible FunctionPad
			invisible PaymentPad
			invisible PluPad
			invisible sku
			invisible plu
			invisible method
			invisible paymentFields
			invisible filterToggle
			visible login
			visible NumericPad 
			visible numbers
			visible functions
			visible erase
			visible delete
			visible ok
			printerBitmap id 1 name "OSbee" @POSPrinter
		}
	}
}
state MODIFY_PAYMENT {
	triggers {
		trigger onCancel 
		actions transition PAYMENT{
			transition PAYMENTTERMINAL_REVERSAL guard  canCancelPaymentTerminal {
				visible paymentTerminal
				invisible money
				invisible method
				invisible functions
				store event with paymentMethod.last
				paymentReversal withPassword 
				dto cashregister.payment_password 
				ofReceipt function getSelectedPaymentReceipt() @VeriFone
			}
			operation cancelPayment()
			invisible cancelit
			visible numbers
			visible erase
			visible delete
			visible money
			visible method
			operation computePayed()
			operation givenChanged()
			clearDevice LineDisplay
			displayTextAt text translate "total" row 0 column 0 @LineDisplay
			displayTextAt text translate "remain" row 0 column 10 @LineDisplay
			displayTextAt text function getPaymentTotal() row 1 column 0 @LineDisplay
			displayTextAt text function getPaymentRemain() row 1 column 10 @LineDisplay
		}
		trigger onBack
		actions transition PAYMENT{
			visible numbers
			invisible cancelit
			visible erase
			visible delete
			visible money
			visible method
		}
		trigger onPaymentSelection
		guards {
			guard hasNoPaymentSelection
		}
		actions transition PAYMENT {
			visible numbers
			invisible cancelit
			visible erase
			visible delete 
			visible money
			visible method
		}
		trigger onLogout
		actions transition IDLE{
			schedule toStart
		}
	}
}
state PAYMENTTERMINAL_FAILURE {
	triggers {
		trigger onPaymentTerm
		actions transition PAYMENT {
			invisible paymentTerminal
			visible money
			visible method
			visible functions
			operation givenChanged()
		}
	}
}

Copyright Notice

All rights are reserved by Compex Systemhaus GmbH. In particular, duplications, translations, microfilming, saving and processing in electronic systems are protected by copyright. Use of this manual is only authorized with the permission of Compex Systemhaus GmbH. Infringements of the law shall be punished in accordance with civil and penal laws. We have taken utmost care in putting together texts and images. Nevertheless, the possibility of errors cannot be completely ruled out. The Figures and information in this manual are only given as approximations unless expressly indicated as binding. Amendments to the manual due to amendments to the standard software remain reserved. Please note that the latest amendments to the manual can be accessed through our helpdesk at any time. The contractually agreed regulations of the licensing and maintenance of the standard software shall apply with regard to liability for any errors in the documentation. Guarantees, particularly guarantees of quality or durability can only be assumed for the manual insofar as its quality or durability are expressly stipulated as guaranteed. If you would like to make a suggestion, the Compex Team would be very pleased to hear from you.

(c) 2019 Compex Systemhaus GmbH