Eugene Hutorny » Java

Model-Document-Renderer Design Pattern

Eugene — Tue, 16 Mar 2010 07:25:38 +0000

Model-Document-Renderer is an evolution of Passive-View design pattern, suggested by Martin Fowler [1]. The difference is mainly in the terminology and in the suggested way of decomposing the application.
In this design pattern a web application is decomposed on Model, Document and Renderer (see Figure 1). It differs from ‘the talk of the town’ MVC (see Figure 2) by the fact that the View (1) degrades to simple renderer, loses (2) control and (3) dependency on the Model and thus becomes (4) application invariant. On the contrary, the Document (5) combines model-depended parts of the View and the Controller, implements (6) application-specific behaviour and (7) control on data flow.


Figure 1	Figure 2

Model

The Model in MDR is the same as in MVC: it provides application domain objects and implements their persistence.

Document

The Document provides access to a concrete part of the model and implements certain use cases. It is expected to be application-specific and output-format-irrelevant. Also, it should not depend on the container (e.g. application server), leaving these aspects to the Application. Document is responsible for:

getting proper business objects from the Model
applying proper template and renderer to the document data
presenting the rendered view to the user
capturing user’s action and data entered by the user
inferring the immediate document state from the data supplied by the user
updating the model when user selects appropriate action

Application

The Application (not shown on the diagrams) is what actually deployed to and called by the application server. The Application may include several documents, which Application distinguishes by the URI and selects for processing a request. The Application should not directly embed any business logic, model references or rendering functionality. It is responsible for selecting an appropriate document and cross-document navigation.

Renderer

Renderer is responsible for:

generating appropriate stream of tokens (HTML, XML, CSV, others)
properly decorating the data (escaping, quoting, etc)
localizing labels and captions
formatting the data according to the format patterns, specific for the selected template and/or the currently selected language

A passive template engine is one of possible implementations of the Renderer. A good theory applicable to template engines is given in [2]. It describes motivations for separating code and HTML and rules for strict separation. According to this theory, a template engine should implement four predicates: (1) attribute reference, (2) conditional inclusion, (3) recursive reference and (4) template application.

References

1. Passive View, Martin Fowler
http://www.martinfowler.com/eaaDev/PassiveScreen.html

2. Enforcing Strict Model-View Separation in Template Engines.
http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf

3. Web Presentation Patterns, Jonathan Snook
http://www.digital-web.com/articles/web_presentation_patterns/

Case study on web frameworks

Eugene — Fri, 12 Mar 2010 15:06:31 +0000

Goals

The goal of this case-study is to make a short overview of the development tools for developing web-based business applications. The tools must (should) satisfy the following criteria:

Best suits for developing server-side stateful applications with complex UI
Good support for localization/internationalization
Full isolation of applications – it should be possible (and simple) to deploy an application without (risk of) breaking other applications which run on the same production server.
Provide a mechanism for simple switching of web page appearance to “printer-friendly” or “mobile-device-friendly” look.
Use page templates in HTML so that designers can use WYSIWYG editors for making changes to the templates
Complete separation of code and HTML tags, so that changes in the application logic does not break the design

Overview

Software frameworks available for web-application are split onto three categories: (1) portals, (2) web application frameworks and (3) template engines (for definitions please follow the references to Wiki).

Portals

Portals are designed to provide good integration of applications within an enterprise. This is going against our goal to have subscriber’s applications as much isolated as possible. Although, in general, this goal is achievable, but, as shows our experience with JBoss Portal, such isolation takes extra human and hardware resources.
Portals are usually build on top of a web-development framework.

Application frameworks

Frameworks are designed to provide reusable functionality, design patterns, and offers highly-configurable environment.

Reusable functionality

To be truly useful, this functionality has to be learned by developers. Rich-on-functionality frameworks provide a lot more functionality but on the other hand requires more time to learn than simple ones. Open source frameworks usually poorly documented, which makes this learning curve much longer. As any software, frameworks contain bugs, and rich frameworks have even more bugs because it is made of bigger amount of source code. Accompanied with poor open source documentation, a simple issue may become a real obstacle just because it is hard to distinguish between a bug in framework and its misusage – system behaves in the way developers do not expect and no one can say whether this behaviour is correct or incorrect. Therefore experience is gained on trial-and-error path. This path makes the learning curve driving away from the application goals.

Design patterns

A typical framework is bound to few design patterns. These patterns were chosen by the vendor/developer of the framework and the reason for that choice is never or very rarely disclosed. Indeed, design patters have high impact on the product and the development process. Too concrete design patterns may not fit needs of a particular application. Too abstract design patterns give more chances to fail on mapping application. Proper design pattern will speedup the development process, improper – will slowdown.
Most of the available web-development frameworks are based on Model-View-Controller (MVC) (see definition in Wiki, good description can be found on [1]). It is not clear why this three-letter-design-pattern become so popular. Besides serious drawbacks of this pattern, every vendor has they own understanding of what is view and what is controller [2], which leads to various flavours of MVC, misimplementation and misusage of this design pattern.

Drawbacks of MVC

Paper [3] identifies the following drawbacks of MVC:

Increased complexity
Close coupling of views and controllers to model
Potential for excessive updates
Close coupling between view and controller

Framework comparison

Wiki lists [4] two dozens of web application frameworks. It does not seem possible to evaluate each of those, therefore we will relay on papers providing such comparisons: [5], [6], [7], [8]. As it appears, very few available frameworks provide good separation of concerns (code vs. HTML). This seems to be the consequence of using MVC as the design pattern and JSP as implementation of View. And even those few which claim good separation – Wicket and Trapestry forces to the component model, which will be an obstacle for producing printer-friendly version of pages.

Template Engines

List of Java template engines is given in [9]. Three of them that match our needs the best are Velocity, StringTemplate and IKAT. All of them use similar approach – use of special programming language for templates. With Velocity we had some experience and it has shown that debugging such templates is a difficult task. This experience we may propagate on the other engines that use a programming language in templates.

Conclusion

Existing frameworks and template engines, while giving advantage in some aspects of web programming, sacrifice the others, which makes the development process longer than expected, sometime even too long. It does not worth spending time on learning a framework which does not give obvious benefits in developing or maintaining the software.
As the experience has shown, implementing a home-grown Java template engine takes efforts comparable to learning a new framework.

References

1. Web Presentation Patterns, Jonathan Snook
http://www.digital-web.com/articles/web_presentation_patterns/

2. Whatsa Controller Anyway, KyleBrown,
http://c2.com/cgi/wiki?WhatsaControllerAnyway

3. Model View Controller
http://www.phpwact.org/pattern/model_view_controller

4. List of web application frameworks
http://en.wikipedia.org/wiki/List_of_web_application_frameworks

5. Java Web Framework Sweet Spots
https://appfuse-light.dev.java.net/framework-comparison/JavaWebFrameworkSweetSpots.pdf

6. Comparison of Java Web Frameworks, Neal Ford
http://bdn1.borland.com/article/borcon/files/6000/paper/6000.html

7. Comparing Web Frameworks, Matt Raible
http://static.raibledesigns.com/repository/presentations/ComparingJavaWebFrameworks.pdf

8. Comparison of web application frameworks
http://en.wikipedia.org/wiki/Comparison_of_web_application_frameworks

9. Open Source Template Engines in Java
http://java-source.net/open-source/template-engines

10. Enforcing Strict Model-View Separation in Template Engines.
http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf

11. Passive View, Martin Fowler
http://www.martinfowler.com/eaaDev/PassiveScreen.html

_{October 2007}

Exercise on implementing collaborations with ObjectTeams/Java

Eugene — Tue, 29 Dec 2009 15:41:10 +0000

Introduction

ObjectTeams/Java (OT/J) is an extension to Java programming language that facilitates roles and collaborations as the first class language constructs. This article is an exercise on using (OT/J) for implementing collaborations.

Subject area

This exercise considers two bank operations – money transfer and fund cashing. The course of events for these two operations is very similar in basic and differs in details. Considering this, it is implemented as an abstract withdraw routine leaving detail differences to concrete implementations.

An abstract withdraw routine

Figure 1

A withdraw routine executed in a bank allows to move funds from one account to another. The bank, which executes this operation, charges some fee, applied to the credit account and debited onto the bank’s operational account. When the currency of the operation is not the same as the bank’s native currency, the bank converts the fee to the native currency.
A collaboration diagram for this operation is given on Figure 1. The collaboration steps and reiterated below:

Calculate a fee for this operation
Charge the amount+fee from the credit account
Put the money on the debit account, which is expected to accept any currency
If the currency of the operation differs from the currency of the banks’ operational account conversion is applied to the fee
Put the fee is on the operational account

A function that implements this code is given below (for a complete class please refer to the source):

	protected final void withdraw(BigDecimal amount, CreditAccount creditAccount, DebitAccount debitAccount,
			OperationalAccount operationalAccount, CurrencyConverter currencyConvertor) {
		BigDecimal fee =  calculateFee(amount);
		creditAccount.credit(amount.add(fee));
		debitAccount.debit(amount,creditAccount.currency());
		if( creditAccount.currency() != operationalAccount.currency())
			fee = currencyConvertor.convert(creditAccount.currency(), operationalAccount.currency(), fee);
		operationalAccount.debit(fee);
	}

In this exercise, this method is implemented in scope of a team class Withdraw Collaboration and the parameter types are defined as role classes in the team. This class is pretty isolated and depends only on Currency class, so it can be reused in other applications. Details of the account implementations are hidden behind the roles.

Concrete withdrawal routines

A bank that implements concrete withdrawal routines, gives its clients two interfaces – the Cashier interface that allows people to get some cash from they accounts, and the Wire Operator interface that allows them to transfer funds from the account they have in this bank to any other account. In scope of this exercise, these two interfaces are implemented by two collaboration, both extending the Withdraw Collaboration. Each collaboration is instantiated in the bank for a given account and then returned to the client. Once the interface is provided, the client may execute more than one operation with the current account.
Since there could be a rather long thinking time, the bank can not provide an operational account at the time when the interface is acquired, but instead the operation account should be determined at the moment of transaction execution. To achieve this, these collaborations are extended with an additional role – Operator which provides access to the available operational account at the moment of transaction execution.
Additional complications with implementing the Cashier that there is not debit account available, since the money are given to a person and the person cannot accept a decimal value, he/she can only take cash, so the digits should be converted to cash. Code snippet for this operation is given below (for a complete class please refer to the source):

	public void giveCashTo(Person person, double amount) {
		BigDecimal value = new BigDecimal(amount);
		reserved = bank.acquireCash(value, account.currency());
		try {
			cashOperation(new BigDecimal(amount), account, person, bank, bank);
		}
		finally {
			if( reserved.value().signum() != 0 ) {
			// Recipient did not take the money
				bank.returnCash(reserved);
			}
		}
	}

To match the Person entity with the DebitAccount interface, a new role is defined as below:

	protected class CashRecipient extends DebitAccount playedBy Person {

		void takes(Cash cash) -> void takes(Cash cash);

		protected void debit(BigDecimal amount, Currency currency) {
			assert reserved.value() == amount && reserved.currency() == currency;
			takes(reserved);
		}
	}

Bank

In this exercise a bank has an internal operational account, and a safe, where all cash is kept. It provides methods for opening accounts (credit and current) and access to two already mentioned interfaces Cashier and Wire Operator. BankAccount is an protected inner class of the Bank to ensure that no one can create a bank account outside of a bank (for a complete class please refer to the source).

Cash

If everyone would be able to create cash in their own, there would be no need for banks and accounts . Also, when cash is being added or subtracted, its behavior differs very much from adding two numbers. To model these features of the cash, a dedicated class is provided. The only public constructor it provides creates zero cash. The add operation accepts Cash as the addendum and clears it after adding. The subtract operation accepts a number and creates a new cash for the amount of subtrahend. Also it provides an instruction to the garbage collector to report any occurrence of valuable cash in the garbage (for a complete class please refer to the source).

Modeling the plan

With the mentioned above classes (and some additional) we can now model Tom and Mary’s plan:
Entities that are assumed to exist:

	Bank spicer  = new Bank("JVM-Spicer,MN ", Currency.USD);
	Bank willmar = new Bank("OTJ-Willmar,MN", Currency.EUR);
	Bank bahama  = new Bank("Java-Bahamas  ", Currency.BSD);

	Person tom  = new Person("Tom ");
	Person mary = new Person("Mary");

The plan:

		Account credit = spicer.openCreditAccount(1000000, Currency.USD);
		Cashier cashier = spicer.cashier(credit);
		cashier.giveCashTo(tom, 970000);

		mary.takes(	tom.gives(965000, Currency.USD) );

		Account deposit = willmar.openAccount(mary.gives(960000,Currency.USD));

		Account bahamamama = bahama.openAccount(mary.gives(1000,Currency.USD));

		WireTransfer wire = willmar.wireOperator(deposit);
		wire.wireTo(bahamamama, 950000);

		cashier = bahama.cashier(bahamamama);
		cashier.giveCashTo(mary, 923000);

		tom.takes( mary.gives(461000, Currency.USD) );

All sources are available for downloading as a single archive under The GNU Lesser General Public License (LGPLv3).

Conclusion

Collaboration design pattern is a useful abstraction for designing the application. Implementing collaborations with a new, promising Java language extension facilitates using of the first class language constructs (teams) and significantly improves the separation of concerns letting the developer to concentrate on one task at a time.

Using Java langauge constructs to define static graphs and trees

Eugene — Wed, 09 Dec 2009 10:13:01 +0000

Graphs, networks and trees are commonly used to model application domains. In some cases these structures are highly dynamic and can not be defined at design time. Yet there are also cases when they are rather static and do not change during the application life cycle. An example of such static structure is a finite state automaton – defined as a part of design, it remains unchanged at the run-time.

However, programming languages do not provide facilities that would make creation of graphs (trees) an easy task. Most common approach is to use XML with a custom schema and encode a graph (a tree) with XML tags. Unfortunately, development tools does not provide the same degree of support for editing an XML file as they do for many wide spread programming languages – detecting typos as you type, reference navigation with one mouse click, etc. Additionally, using an XML requires a utility to process the XML and build a model corresponding to the definition. Another approach to define a graph – instantiating objects and establishing references among them “by hands”. The code created with this approach is burdened with poor readability and maintainability. An ideal solution would be using a domain specific language for these purposes, however cost of creating such a language is tremendous at present time.
This article suggests an approach on adapting the Java programming language for defining static graphs, trees.

The idea

If we look at Java classes, interfaces and references among them at the high level of abstraction, their appear to be a linked graph where classes/interfaces can be thought as nodes and references – as links between them. These thoughts, being turned inside out, lead to the following rationales: a graph can be represented as a set of interfaces where an interface represents a node and a reference to another interface represents a link. Such references, for instance, could be return types of methods defined in the interface.

Rationales

The following table lists rationales on graph representation.

FSA primitive	Represented as
State chart	A Java class that includes definition of all its states
State	An interface extending State interface
Set of On Enter actions	One or more methods returning void and annotated with @OnEnter
On Enter Action	A parameter type extending Action of a method mentioned above
Set of On Leave actions	One or more methods returning void and annotated with @OnLeave
On Leave Action	A parameter type extending Action of a method mentioned above
Transition	A method returning interface corresponding to the “To” state
Condition	A parameter type extending Condition of a method mentioned above
Action	A parameter type extending Action of a method mentioned above

Figure 1

Microwave automaton

Lets consider a simple microwave with one push-button and a knob timer. This microwave starts heating when the user pushes the button and the door is closed and the timer is set. Pushing button again stops heating, opening the door suspends heating until the door is closed again. A state chart for this microwave is shown on Figure 1. The following code snippet shows how this state chart can be represented with the rationales given above.

public class MicrowaveStateMachine {
  /**
   * In Door Open State MW waits until the door is closed
   */
  interface DoorOpenState extends State {
	  @OnEnter void enter	(DoDing a);                            	// on entering Door Open State issue a Ding action
	  WaitingState  idle   	(OnDoorClose e, IfTimerIsSet a);  		// on Door Close Event transit to Waiting State
	  HeatingState  resume 	(OnDoorClose e, IfTimerIsNotSet a); 	// on Door Close Event transit to Waiting State
	  DoorOpenState ignore 	(OnPushButton e, DoBeep a);          	// on Push Button Event issue a Beep and remain in DoorOpenState
	  @OnLeave void leave	(DoDong a);								// on entering Door Close State issue a Dong
  }
  /**
   * In Waiting State MW waits until a button is pushed
   * If timer is set, it starts heating, otherwise it beeps
   */
  interface WaitingState extends State {
	  HeatingState  start   (OnPushButton e, IfTimerIsSet c);		// on Push Button Event if timer is set transit to heating
	  WaitingState  beep    (OnPushButton e, IfTimerIsNotSet c, DoBeep a); // otherwise issue a Beep and remain in waiting
	  DoorOpenState open    (OnDoorOpen e);							// on Door Open Event transit to Door Open State
  }
  /**
   * In Heating state it actually heats.
   * On entering this state MW starts the heater and the cook timer;
   * On leaving this state MW stops the heater and suspends the cook timer
   */
  interface HeatingState extends State {
	  @OnEnter void enter	(DoStartHeater a, DoStartCookTimer t); 	// on entering HeatingState State issue Start Heater Action
	  WaitingState  timer	(OnCookTimerExpired e);					// on Timer Expired Event transit to Waiting State
	  WaitingState  stop	(OnPushButton e);						// on Push Button Event transit to WaitingState State
	  DoorOpenState open	(OnDoorOpen e);							// on Door Open Event transit to Door Open State
	  @OnLeave void leave	(DoStopHeater a, DoSuspendCookTimer b);	// on leave issue DoStopHeater
  }
}

Constructing run-time artifacts

Obviously, this is only definition and it requires, as well as an XML definition, some code to turn it into a run-time artifact. Java Reflection API provides all necessary means for examining the definition but producing a valuable output is an application specific task. In other words, the task is split on two concerns – (1) examining the definition and (2) generating the output. The source code sample attached to this article provides a utility class that implements first concern (Walker) and an application class (MicrowaveSample) that generates microwave automaton assembler code for a PICmicro MCU (see sample output below). Walker class exposes one method processAutomaton accepting a state chart definition class and communicates with MicrowaveSample via WalkerCallback interface implemented by MicrowaveSample.

;-----------------------------------------------------
DoorOpenState
    call DoDing
DoorOpenState_begin
    call sleepAndWaitEvents
DoorOpenState_0
    btfss OnDoorClose    ; resume
    bra DoorOpenState_1
    btfss IfTimerIsNotSet
    bra DoorOpenState_1
    call DoorOpenState_leave
    bra HeatingState
DoorOpenState_1
    btfss OnDoorClose    ; idle
    bra DoorOpenState_2
    btfss IfTimerIsSet
    bra DoorOpenState_2
    call DoorOpenState_leave
    bra WaitingState
DoorOpenState_2
    btfss OnPushButton    ; ignore
    bra DoorOpenState_3
    call DoBeep
    call DoorOpenState_leave
    bra DoorOpenState
DoorOpenState_3
DoorOpenState_end
    bra DoorOpenState_begin
DoorOpenState_leave
    call DoDong
    return
HeatingState
    call DoStartHeater
    call DoStartCookTimer
HeatingState_begin
    call sleepAndWaitEvents
HeatingState_0
    btfss OnPushButton    ; stop
    bra HeatingState_1
    call HeatingState_leave
    bra WaitingState
HeatingState_1
    btfss OnDoorOpen    ; open
    bra HeatingState_2
    call HeatingState_leave
    bra DoorOpenState
HeatingState_2
    btfss OnCookTimerExpired    ; timer
    bra HeatingState_3
    call HeatingState_leave
    bra WaitingState
HeatingState_3
HeatingState_end
    bra HeatingState_begin
HeatingState_leave
    call DoStopHeater
    call DoSuspendCookTimer
    return
WaitingState
WaitingState_begin
    call sleepAndWaitEvents
WaitingState_0
    btfss OnPushButton    ; start
    bra WaitingState_1
    btfss IfTimerIsSet
    bra WaitingState_1
    bra HeatingState
WaitingState_1
    btfss OnDoorOpen    ; open
    bra WaitingState_2
    bra DoorOpenState
WaitingState_2
    btfss OnPushButton    ; beep
    bra WaitingState_3
    btfss IfTimerIsNotSet
    bra WaitingState_3
    call DoBeep
    bra WaitingState
WaitingState_3
WaitingState_end
    bra WaitingState_begin

Figure 2

Extending state charts

Now, lets image that we have this microwave automaton in full production, and R&D department came up with a innovative and conceptual design of a microwave with two buttons and sales department insisted on adding a ‘polite reminder’ feature. State chart for the new microwave automaton is given on Figure 2 where blue color indicates new state and transitions and red cross denotes transition no longer needed. A big part of the state chart remains the same as in previous version one and, thus, can be reused in a new state chart. With the approach that this article suggests, a state chart can be extended by means of Java inheritance, e.g. new state chart extends the previous. With very little efforts the new automaton is defined as given below.

/**
 * State machine of a microwave oven with two buttons and polite reminder feature:
 * when cooked and door was not open - beep every N seconds during M minutes
 */
public class ModernMicrowaveStateMachine extends MicrowaveStateMachine {
	  /**
	   * This machine introduces several new events and actions
	   */
	  interface OnPushStopButton extends Event {}
	  interface OnPoliteBeepTimer extends Event {}
	  interface OnPoliteOffTimer extends Event {}
	  interface DoStartPoliteBeepTimer extends Action {}
	  interface DoStopPoliteBeepTimer extends Action {}
	  interface DoStartPoliteOffTimer extends Action {}
	  interface DoStopPoliteOffTimer extends Action {}
	  interface DoAddOneMinuteCookTimer extends Action {}

	  /**
	   * Alter the inherited Heating State
	   */
	  interface HeatingState extends MicrowaveStateMachine.HeatingState {
		  HeatingState	add		(OnPushButton e, DoAddOneMinuteCookTimer a);  // add one minute to the timer when push button is pressed
		  @Disable
		  WaitingState	timer	(OnCookTimerExpired e);					// disable this transition inherited from the old MW
		  CookedState   cooked	(OnCookTimerExpired e);					// introduce new transition on Timer Expired Event transit to CookedState State
		  WaitingState  stop	(OnPushStopButton e);					// on Push Stop Button Event transit to WaitingState State
		  @Disable
		  WaitingState  stop	(OnPushButton e);						// disable this transition inherited from the old MW
	  }
	  /**
	   * Add new state to provide polite beep reminder
	   */
	  interface CookedState extends State {
		  @OnEnter void onEnter	(DoStartPoliteBeepTimer a, DoStartPoliteOffTimer b ); // on enter start timers Polite Beep and Polite Off
		  DoorOpenState stop	(OnDoorOpen e);							// on Door Open Event transit to Door Open State
		  HeatingState  start1	(OnPushButton e, IfTimerIsNotSet i, DoAddOneMinuteCookTimer t); // on Push Button Event transit to WaitingState State
		  HeatingState  start	(OnPushButton e, IfTimerIsSet i);  		// on Push Button Event transit to WaitingState State
		  WaitingState  stop	(OnPushStopButton e); 					// on Push Stop Button Event transit to WaitingState State
		  WaitingState  idle	(OnPoliteOffTimer e); 					// stop beeping after M minutes
		  CookedState   beep	(OnPoliteBeepTimer e); 					// beep every N seconds
		  @OnLeave void onleave	(DoStopPoliteBeepTimer a, DoStopPoliteOffTimer b ); 	// on leave stop timers
	  }
}

There is one new annotation added: @Disabled. It is used to indicate a deletion of unused links that were inherited from the original chart. Output for this automaton is following

;-----------------------------------------------------
CookedState
    call DoStartPoliteBeepTimer
    call DoStartPoliteOffTimer
CookedState_begin
    call sleepAndWaitEvents
CookedState_0
    btfss OnPushButton    ; start
    bra CookedState_1
    btfss IfTimerIsSet
    bra CookedState_1
    call CookedState_leave
    bra HeatingState
CookedState_1
    btfss OnPushStopButton    ; stop
    bra CookedState_2
    call CookedState_leave
    bra WaitingState
CookedState_2
    btfss OnDoorOpen    ; stop
    bra CookedState_3
    call CookedState_leave
    bra DoorOpenState
CookedState_3
    btfss OnPoliteOffTimer    ; idle
    bra CookedState_4
    call CookedState_leave
    bra WaitingState
CookedState_4
    btfss OnPoliteBeepTimer    ; beep
    bra CookedState_5
    call CookedState_leave
    bra CookedState
CookedState_5
    btfss OnPushButton    ; start1
    bra CookedState_6
    btfss IfTimerIsNotSet
    bra CookedState_6
    call DoAddOneMinuteCookTimer
    call CookedState_leave
    bra HeatingState
CookedState_6
CookedState_end
    bra CookedState_begin
CookedState_leave
    call DoStopPoliteBeepTimer
    call DoStopPoliteOffTimer
    return
HeatingState
    call DoStartHeater
    call DoStartCookTimer
HeatingState_begin
    call sleepAndWaitEvents
HeatingState_0
    btfss OnPushButton    ; add
    bra HeatingState_1
    call DoAddOneMinuteCookTimer
    call HeatingState_leave
    bra HeatingState
HeatingState_1
    btfss OnPushStopButton    ; stop
    bra HeatingState_2
    call HeatingState_leave
    bra WaitingState
HeatingState_2
    btfss OnCookTimerExpired    ; cooked
    bra HeatingState_3
    call HeatingState_leave
    bra CookedState
HeatingState_3
HeatingState_end
    bra HeatingState_begin
HeatingState_leave
    call DoStopHeater
    call DoSuspendCookTimer
    return
DoorOpenState
    call DoDing
DoorOpenState_begin
    call sleepAndWaitEvents
DoorOpenState_0
    btfss OnDoorClose    ; resume
    bra DoorOpenState_1
    btfss IfTimerIsNotSet
    bra DoorOpenState_1
    call DoorOpenState_leave
    bra HeatingState
DoorOpenState_1
    btfss OnDoorClose    ; idle
    bra DoorOpenState_2
    btfss IfTimerIsSet
    bra DoorOpenState_2
    call DoorOpenState_leave
    bra WaitingState
DoorOpenState_2
    btfss OnPushButton    ; ignore
    bra DoorOpenState_3
    call DoBeep
    call DoorOpenState_leave
    bra DoorOpenState
DoorOpenState_3
DoorOpenState_end
    bra DoorOpenState_begin
DoorOpenState_leave
    call DoDong
    return
WaitingState
WaitingState_begin
    call sleepAndWaitEvents
WaitingState_0
    btfss OnPushButton    ; start
    bra WaitingState_1
    btfss IfTimerIsSet
    bra WaitingState_1
    bra HeatingState
WaitingState_1
    btfss OnDoorOpen    ; open
    bra WaitingState_2
    bra DoorOpenState
WaitingState_2
    btfss OnPushButton    ; beep
    bra WaitingState_3
    btfss IfTimerIsNotSet
    bra WaitingState_3
    call DoBeep
    bra WaitingState
WaitingState_3
WaitingState_end
    bra WaitingState_begin

Representing other graph and tree-alike structures

Although, this article is focused on finite state automatons, similar approach can be applied for defining other kind of graphs and trees. The author has a proof of concept for using nested classes as a representation of a web-application URI structure and mapping HTTP requests issued by very complex but strictly structured HTML forms.

Attachments

FSA-Sources

A convenient approach on keeping SQL in Java

Eugene — Tue, 24 Nov 2009 12:00:45 +0000

Where to keep SQL statements? This question arises almost for any more-less sophisticated Java application that accesses DBMS. Two most common approaches are: (1) as string constants in Java and (2) as text in external files. Both these approaches have significant drawbacks. Java strings get complicated when a string is too long to fit in one line, leading to a difficult to read and hard to maintain SQL code. SQL in external files are not easy to lookup and require some mapping technique to associate statement in the external file with a place in Java where it is needed. Also, as development goes, the text file adheres with more and more orphan SQL statements and there is no easy way to clean them up. This article suggests an approach that combines two mentioned above and inherits their strong sides.
The idea is very simple – keep SQL statements in the source Java file as comments following the definition of a string member, load them at run-time and assign to the corresponding member. The following example gives a grasp on this technique.

public class SQLpeople {
  public static final String sqlSELECTall = Comments.load();
  /*--
    SELECT * FROM people;
    --*/
}

To make it available at run-time, this source file should be packaged together with the class file. That’s everything you need to make SQL statements loaded…
Well, almost everything . One minor thing left is an implementation of Comments.load(). You may implement it in your own or download from SourceForge an open source implementation (under LGPLv3 license).

Dialectism

If your application is designed to run with different DBMS engines, maintaining SQL in different dialects may become a challenge. The Comments class proposes a solution as illustrated below:

public class SQLpeople {
  public static final String sqlSELECTtopN = Comments.load(getCurrentDBMS());
  /*--
    --: pgsql
    SELECT * FROM people LIMIT ?;
    --: mssql
    SELECT TOP ? * FROM people;
    --*/
}

Where getCurrentDBMS() is your static function that returns name of the current DBMS, and --: pgsql and --: mssql are discriminator values designating statements appropriate for different DBMS.

How it works

The Comments class just a friendly decorator created for the sake of convenience. Its method load() uses StackFrame to gather information about invocation point and passes name of the source file, line number (N), and class name to the CommentRetriever.retrieve(), which opens the source file as a resource stream, skips N lines, reads content until it finds --*/ in the line and then uses regex to extract content between /*-- and --*/. If the discriminator parameter is null, retrieve returns extracted content. Otherwise it finds designators --: and tests its equity against the parameter. If they are equal method returns content of the section between the current discriminator and the next one or end of the block. If block contains no discriminator equal to the parameter, it returns content before the first discriminator, unless default values are disabled by NODEFAULTS option.
That’s all you need to start using this class, for advanced topics please refer to Java docs.

Guidelines on authoring comments

There should be no characters between the end of the load() line and sequence /*-- that opens the block, except, of course, white spaces (space, tab, new line).

public class SQLpeople {
  /*
   * allowed comment
   */

  public static final String sqlSELECTall = Comments.load(); -- allowed comment

  /* disallowed comment */
  /*--
    SELECT * FROM people;
    --*/

}

Discriminator takes entire line, there should be no other text in this line

Errors

By default error messages are returned as output value and prepended with "--", are returned as the result of load() method. Although, this behavior can be opted (see Java docs for details).