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:

1. getting proper business objects from the Model
2. applying proper template and renderer to the document data
3. presenting the rendered view to the user
4. capturing user’s action and data entered by the user
5. inferring the immediate document state from the data supplied by the user
6. 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:

1. generating appropriate stream of tokens (HTML, XML, CSV, others)
2. properly decorating the data (escaping, quoting, etc)
3. localizing labels and captions
4. 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/

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:

1. Best suits for developing server-side stateful applications with complex UI
2. Good support for localization/internationalization
3. 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.
4. Provide a mechanism for simple switching of web page appearance to “printer-friendly” or “mobile-device-friendly” look.
5. Use page templates in HTML so that designers can use WYSIWYG editors for making changes to the templates
6. 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:

1. Increased complexity
2. Close coupling of views and controllers to model
3. Potential for excessive updates
4. 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}

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:

1. Calculate a fee for this operation
2. Charge the amount+fee from the credit account
3. Put the money on the debit account, which is expected to accept any currency
4. If the currency of the operation differs from the currency of the banks’ operational account conversion is applied to the fee
5. 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.

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.

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.

[picmicro collapse="true"]
;—————————————————–
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
[/picmicro]

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

[picmicro collapse="true"]
;—————————————————–
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
[/picmicro]

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

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 --: <discriminator> 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).

A dimmer is an electronic device that controls alternate voltage applied to a lamp through delivering a selected portion of the mains sinusoid. Engineer, designing a dimmer needs to estimate how big this portion should be to get a desired luminance level. This article uses a model of incandescent lamp, tungsten resistivity, and human eye spectral efficiency to derive dependency of produced luminous flux over the voltage, gives a simple analytical function that describes this dependency with good accuracy (±2% comparing to the model).

Download PDF version of this article

Structured Abstract

Definitions

Process of controlling some output value (such as voltage U or luminous flux L) we will denote as a control function , defined on the control parameter :

(1)

Each of  monotonously increase on the defined range. Control functions defined on a different (other than ) argument we will denote in this article as .

Commonly used are linear () and logarithmic () control functions. To implement a desired control function , we needs to know what is  dependency. 
The following chapters give an attempt to derive  using a model suggested in (Agraval 1996).

Incandescent Lamp Model

An incandescent lamp is characterized with few nominal values: P_N – power consumption, U_N – nominal voltage, L_N – nominal luminous flux, produced by the lamp at nominal voltage. The flux is produced by filament, incandesced to nominal working temperature T_N.
When lower voltage U<U_N is applied, operating temperature T of filament is lower T_N and therefore it produces less luminosity L.

Filament Resistance

Power, consumed by a lamp, is expressed with Ohm low:

(2)

where  defines dependency of filament resistance over the temperature relatively to its nominal resistance R_N, which can be evaluated via P_N and U_N:

(3)

Dependency  for tungsten is not linear in the working range of temperatures (1000-2500K). For this model we will use polynomial approximation of tungsten resistance ρ, [Harang 2003]:

(4)

 can be expressed via  as the following:

(5)

Filament Temperature

During operation, filament radiates electromagnetic energy and dissipates heat via conduction and convection. To estimate radiation, filament is modeled [Agraval 1996] as a simple non-ideal blackbody that obeys Plank’s radiation law:

(6)

where  is power radiated between wavelength  and ,  - tungsten emittance, and A is filament area. The total power emitted over all wavelengths is:

(7)

where σ is the Stefan-Boltzman constant and  is average emittance over all wavelengths, which is approximated as a second order polynomial (Harang 2003):

(8)

In a steady-state operation, power applied to the lamp is in balance with power radiated and dissipated to outside ambient. Dissipation has two constituents – conduction and convection. Agraval in [Agraval 1996] has suggested a reasonable way of accounting dissipation as a factor of input power:

(9)

Solving (8) for P:

(10)

Substituting left side of (10) with right side of (2):

(11)

Using (11), we may derive :

(12)

Figure 1 illustrates dependency

Figure 1. Dependency of T on fraction of applied voltage ξ_U for different T_N

Luminance

Not all power radiated by filament has its effect on luminous flux. Some of the energy is absorbed by bulb glass and dissipated as heat. Although, this absorption depends on λ, we will simplify this absorption to a constant factor η<1.

Major part of the emitted energy is not visible to human eye. This is described as spectral efficiency function S(λ), approximated as the following [Agraval 1996]:

(13)

Thus, total luminous flux produced by a lamp can be defined as:

(14)

where

(15)

Thereby, control function  can be expressed as a function of T:

(16)

For working range of temperatures and visible area, emissivity є(λ,T) can be approximated as the following [Larrabee 1957]:

(17)

where T is in °K and λ in nm. Substituting (17) in (16) and integrating numerically (16) we get dependency, shown on Figure 2:

Figure 2. Dependency ξ_L(T) for different T_N

Solving Luminance vs. Voltage

Using T as a parametric variable, we may numerically compute (11), (15) and graphically solve dependency ξ_L(ξ_U), as shown on Figure 3:

Figure 3. Dependency ξ_L(ξ_U) for different T_N

As Figure 3 indicates, ξ_L(ξ_U) is affected by a design factor – nominal temperature T_N.

Approximation

Figure 4. Dependency ξ_L(ξ_U³)

As it appears (see Figure 4), dependency ξ_L(ξ_U³) looks quite linear for ξ_U³>0.2 and has some higher-order dependency for ξ_U³<0.2. Therefore we will try approximating ξ_L(ξ_U) as two polynoms:

(18)

Value ξ_Lat x=1 is equal to 1 by nature of ξ, therefore c can be expressed via k:

(19)

To solve a and x₀ we will require continuality of  and its derived function , this gives us two equations with three unknowns:

(20)

Solving (20) for a and x₀ we get them expressed via k:

(21)

Thereby,  depends on a single constant k, which is then wiggled around to find a value giving lowest RMS deviation . Table 1 lists selected values for few most common nominal temperatures T_N, Figure 5 illustrates this dependency, and Figure 6 shows modeled curves and values, approximated with (20).

Table 1. k values for some T_N

Figure 5. k variations over T_N

Figure 6. Modeled curves and approximated values (marks)

Since designer of a dimmer may not exactly know nominal temperature of the dimmed lamp, kcan be selected for an average nominal temperature. Suggested value k=1.05 gives ±2% error (against the model) for T_N in range 2800-3100 °K. For this k, equation (20) becomes practically concrete:

(22)

Sine Wave Dimmer

A sine wave dimmer implemented with pulse-width modulation controls applied voltage with a cycle duty, which we will denote as control function ξ_t. Modulation frequency is usually chosen much higher than mains frequency. Therefore, RMS of output voltage is proportional to cycle duty, and control function ξ_U as simple as:

(23)

To make ξ_L(p), linear on parameter p, function ξ_t(p) should be defined as the following:

(24)

Applying (24) to equation (22) we get

(25)

Phase Control Dimmer

When implementing an AC dimmer based on phase control technique, one needs to tabulate cycle duty values ti as a function of desired luminance level pi. 
Following the same approach, we introduce control function ξ_t:

(26)

where t is cycle duty (time when the switch is on) and tM is the mains half period, and f is the mains frequency. Average power  applied to the lamp, can be evaluated as the following:

(27)

where UA is voltage amplitude. Integrating (27) we can define ξ_P as the following

(28)

Considering that , and substituting (28) to (22) we may estimate .

Figure 7. Dimmer control functions ξ_L and ξ_U

Applying approach used in (24) function ξ_t(p) is defined as following:

(29)

Although, reverse function of (28) is not solvable analytically, it can be solved numerically.

Conclusions

As a result of numerical modeling, the following approximation functions are suggested:

• Estimation of produced luminous flux over the voltage:

L = L0 * ((U/U0 < 0.575) ? 1.369 * (U/U0) ^ 4 : (1.05 * (U/U0) ^ 3 - 0.05);

• Tabulation of cycle duty over the control parameter p

t = (p < 0.1496) ? (0.925 * (p) ^ -4) : (0.984 * (p + 0.05) ^ -3);

References

Agraval D.C., Leff H.S., Monon V.J. (1996)
"Efficiency and efficacy of incandescent lamps"
American Journal of Physics, May 1996, Volume 64, Issue 5, pp. 649-654
http://scitation.aip.org/getabs/servlet/GetabsServlet?prog=normal&id=AJPIAS000064000005000649000001&idtype=cvips&gifs=yes

Harang O., Kosch M. J. (2003) "Absolute Optical Calibration Using a Simple Tungsten
Bulb"
Sodankylä Geophysical Observatory Publications, 2003, pp. 92:121-123
http://spaceweb.oulu.fi/28AM/proc_papers/27_harang_et_al_calibration_with_tungsten_bulb.pdf

Larrabee R.D. (1957) "The spectral emissivity and optical properties of tungsten"

Research Laboratory Of Electronics, Massachusetts Institute of Technology
http://dspace.mit.edu/bitstream/1721.1/4755/1/RLE-TR-328-04734719.pdf

(Note: In ErWin 7.3 templates look very different from 7.2, but nevertheless, I believe, similar approach still can be applied).

Trick 1. Use Oracle 10.x as the target DBMS

PostgreSQL has common ideology with Oracle and, in my opinion, is the best choice for PostgreSQL needs.

Trick 2. Fix syntax differences
I have encoundered two syntax differences – in the order designator in the column specifier of CREATE INDEX statement and extra parenthesis in ALTER TABLE ADD CONSTRAINT

Following samples illustrate what causes PostgreSQL to fail with generated code:

CREATE INDEX Publisher_xIF1 ON Publisher (PublisherID ASC);

ALTER TABLE Publisher
ADD (CONSTRAINT Publisher_fObject FOREIGN KEY (ObjectID) REFERENCES Object(ObjectID) ON DELETE CASCADE);

This can be fixed by altering ErWin FE template as the following:

2.1. Copy and rename Oracle.erwin_fe_template to Postgre.erwin_fe_template and then open it in a text editor.

2.2. Find SPItemBegin = KeyGroupMembers 2.3. Below that find and remove line containing [" " PropertyValueX("Key Group Sort Order")]
2.4. Find"ADD " "(" IsNotNullX(ExecuteX("FKConstraint"),"") ")" 2.5. Remove "(" ")", so it looks like the following:"ADD " IsNotNullX(ExecuteX("FKConstraint"),"") 2.6. Switch you project to use this template (Tools>Forward Engineer>Scema Generation; Database template – Browse; select Postgre.erwin_fe_template) These two tricks are essential to produce valid SQL code from an ErWin model that contain no Oracle specific features, like table partitions, logging, validation, etc. If you already have an Oracle model which you prefer to keep intact and still be able to generate SQL for Postgress, you will need to void all parts of FE template responsible for Oracle specific features.
Trick 3. Implement use of INHERITS for subtype relationships This part is optional and necessary if you really need to use table inheritance. 3.1. Find first occurrence of [ExecuteX("EndOfStatementX")] after SPItemBegin = Create Entity
3.2. Add [ExecuteX("Extra Properties")] before [ExecuteX("EndOfStatementX")] [ExecuteX("Table Properties")] [ExecuteX("Extra Properties")] [ExecuteX("EndOfStatementX")]
3.3. At the end of the file add
SPItemBegin = Extra Properties 10000: {# ForEachVectorReferenceX("Child Relations Ref") { [ IsPropertyEqual("Type","9") " INHERITS(" [ PushReferenceX("Parent Entity Ref") [ [OwnerX"."]PhysicalNameX ] PopX ] ")" ] } #} SPItemEnd

Read more about SISAM – SImple SAMpler and SISAN – SImlpe Signal Analyse

Example3 – Designing MIHA – Multi Input Hall Automaton

Introduction

There are two common approaches for light switching in halls and staircases – off-timers and intermediate switching schemes (please excuse me if terminology is wrong). Off timers turn light on when user pushes a button and turn off when specified time elapsed. Intermediate switching schemes toggle lights when user toggles any switch (of two). Each approach has its own advantages and disadvantages, however, both approaches require special switches, which could be an undesired constraint for interior design. See, for example, Intermediate lighting switch, Stair case timer, Multifunction staircase timer

Requirements (user’s needs)

Implement a light-control appliance that:

• combines off-timer and intermediate switchers
• provides support for at least 3 switches
• supports regular light switches as well as push-buttons
• provides settable 0.5-10 min timer range with a simple user interface for entering value

MIHA Design Description

Key Design Decisions:

• Implement the appliance (named MIHA) as a VELOOS application running on a PIC microcontroller
• Store application configuration in EEPROM during device programming
• Use potentiometer for specifying timeout

Architecture
MIHA consists of the following units (see architecture diagram on Figure 1):

Mapping Architecture to Implementation. Mapping from architectural units to implementation units is straightforward – all MIHA units are directly mapped to operating system objects, inter-unit communications are mapped to messaging. All MIHA objects are configurable with EEPROM data. To make design flexible, object configuration embeds acceptor handle. The latter two decisions establish a generality which is captured as two abstract classes: PDO – a configurable Process Data Object PDD – a dynamically bound PDO (See class diagram on Figure 2)		Figure 1.
		Figure 2.

Moduling

Major advantage provided by VELOOS is ability to design and implement loosely coupled objects. The following practice can be applied to get full advantage of loose coupling:

• A unit should be made up of (at least) two files: (1) .inc containing interface and (2) .asm – implementation
• Each unit should implement one class or a hierarchy of closely related classes.
• A unit should not instantiate objects of reenterable or configurable classes. Instead it should publish class name in the interface.
• A unit may instantiate object of a non-reenterable class. In this case it should publish object name and encapsulate class name.

Sharing RAM among objects

Decoupling objects via messaging mechanism provides a very explicit and straightforward watershed for scoping variables – everything that should survive between two messages is a part of object state and should be allocated in udata section, everything that may be discarded after handling the message is a temporary variable and can be allocated in udata_ovr section.

Using Timer for Resource Access Arbitration

Class Potentiometer Parameter Input (PPI) implements time-quantified approach for sharing ADC among several instances – time is sliced on N quants, each instance may access hardware only if TIME mod N equals to channel number. To simplify computing TIME mod N, N can be chosen as power of 2. In this example N = 16.

Multi-input Debouncer On timer event Debouncer polls the port three times in a row and applies majority logic to determine current switch state. This approach eliminates sporadic spikes than may be present in a noisy environment. For each assigned pin it maintains a counter. This counter is incremented whenever pin level is high and decremented if low. Counter is maintained in range 0..16, e.g. when it reaches the boundary it is not changed. When counter reaches upper threshold (12) logical output state is changed to 1 and to 0 when it reaches lower threshold. This is a software model of an RC-integration connected to a Schmidt trigger. Few samples of switch bouncing are shown on figures on right. The switches are regular light switches manufactured by VIKO. Hardware Schematic MIHA schematic is shown on Figure 6. Relay, loaded on PIC12, should have actuating current up to 25 mA. Resistors R1-R4 are used for pull-up and can be roughly 1 kOhm. In an environment with strong EMI their can be reduced to avoid pickup. Package Content The package includes three projects to build this application for three different devices – PIC12F675, PIC16F690, PIC18F248. It is licensed to public under the Open Software License Download MIHA Sources v.1.0		Figure 3.
		Figure 4.
		Figure 5.
		Figure 6.

Actuators and Generators are implemented as instances of Actuator and Generator classes. Yet another class in this example protocol driver parses the incoming via software USART commands and forwards it to a corresponding object. Command format is: command[data,[data]]; COM port settings: 2400, 8bit no parity, 1 stop bits.
USART is implemented in software and uses INT0 and TMR1 interrupts for timing bits.
Command language consist of 8 commands (H..O)

• H,I,J control an actuator,
• K,L control a generator,
• N all actuators do OFF, susped all generators
• O all actuators do ON, resume all generators.

H,I,J commands accepts ’0′ and ’1′ as a parameter to execute OFF or ON command respectively. K,L commands should be supplied with pulse and pause duration

For example:

• H0 Actuator 1 do OFF
• LUA Turn on generator 1 with 85 ms pulse and 65 ms space

Example 3 Sources

Hardware Scematics. Connect loads to GP0,GP1,GP4,GP5 (not shown on the schematic)

Simulation Results