Stateful - Revision history

JaroslavTulach at 05:13, 5 May 2010

2010-05-05T05:13:56Z

←Older revision		Revision as of 05:13, 5 May 2010
Line 4:		Line 4:
	in memory).		in memory).

-	In contrast to this a stateless object represents just one state for ~~the~~ its whole life-cycle.	+	In contrast to this a stateless object represents just one state for its whole life-cycle.
	Modeling this as an immutable object, whose fields are only initialized once during		Modeling this as an immutable object, whose fields are only initialized once during
	construction and then remain unchanged, seems to be the most straightforward design technique.		construction and then remain unchanged, seems to be the most straightforward design technique.

JaroslavTulach: /* A little bit of forgiveness */

2010-05-02T14:35:13Z

A little bit of forgiveness

←Older revision		Revision as of 14:35, 2 May 2010
Line 63:		Line 63:
	== A little bit of forgiveness ==		== A little bit of forgiveness ==

-	I am going to claim that [[stateful]] [[API]] is a [[:Category:APIDesignPatterns:Anti\|software antipattern]] (those we fight against [[stateful]] [[singleton]]s can easily agree). Splitting such ''phased'' [[API]] into individual interfaces for each phase shall be [[good]], [[rationalistic]] way of eliminating all associated problems.	+	I am going to claim that [[stateful]] [[API]] is a [[:Category:APIDesignPatterns:Anti\|software antipattern]] (those who fight against [[stateful]] [[singleton]]s can easily agree). Splitting such ''phased'' [[API]] into individual interfaces for each phase shall be [[good]], [[rationalistic]] way of eliminating all associated problems.

	However software engineering is not art, one cannot always start from scratch, with clean design. Sometimes one needs to maintain already created [[stateful]] [[API]]. In such situation any effort resembling the ''state machine'' checks can become more than welcomed. Such check is still a dirty, ugly, post-fix (made in the line of [[empiricism]]), but at least it helps to eliminate the most obvious misuse of such [[stateful]] [[API]].		However software engineering is not art, one cannot always start from scratch, with clean design. Sometimes one needs to maintain already created [[stateful]] [[API]]. In such situation any effort resembling the ''state machine'' checks can become more than welcomed. Such check is still a dirty, ugly, post-fix (made in the line of [[empiricism]]), but at least it helps to eliminate the most obvious misuse of such [[stateful]] [[API]].

JaroslavTulach: /* Call State Machine */

2010-05-02T14:33:29Z

Call State Machine

←Older revision		Revision as of 14:33, 2 May 2010
Line 38:		Line 38:
	correct or not. The project team was describing this with great enthusiasm		correct or not. The project team was describing this with great enthusiasm
	(deserved, tracking object state throughout program flow is tricky), but I was		(deserved, tracking object state throughout program flow is tricky), but I was
-	immediately thinking: This is not beautiful (in the sense of not [[rationalistic]])!	+	immediately thinking: This is not beautiful (in the sense of not being [[rationalistic]] solution)!
	Rather than writing poor [[stateful]] [[API]] and then trying to fix it with		Rather than writing poor [[stateful]] [[API]] and then trying to fix it with
	additional [[annotation]]s, one shall write [[good]] [[API]] to begin with!		additional [[annotation]]s, one shall write [[good]] [[API]] to begin with!

JaroslavTulach: /* Unforgiving Stateful Nightmare */

2010-05-02T14:31:59Z

Unforgiving Stateful Nightmare

←Older revision		Revision as of 14:31, 2 May 2010
Line 11:		Line 11:

	There is one common problem that everyone has to face when using [[API]]s based on [[stateful]] objects.		There is one common problem that everyone has to face when using [[API]]s based on [[stateful]] objects.
-	Often, depending on the object state only some methods of its public interface are accessible (e.g. can be called without throwing an exception). However not only these ''accessible'' methods are visible in [[Javadoc]]. All object's methods are visible in the public signature of its class and (without reading carefully its javadoc) it is not easy (and definitely not [[cluelessness\|clueless]]) to find out which of the methods can be called immediately ~~and in which order onces need to wait until the object switches to~~ different ''phase''.	+	Often, depending on the object state only some methods of its public interface are accessible (e.g. can be called without throwing an exception). However not only these ''accessible'' methods are visible in [[Javadoc]]. All object's methods are visible in the public signature of its class and (without reading carefully its javadoc) it is not easy (and definitely not [[cluelessness\|clueless]]) to find out which of the methods can be called immediately. As a result one may easily call inappropriate method designed for different ''phase''.

	Imagine a [[stateful]] [[API]] for displaying a progress:		Imagine a [[stateful]] [[API]] for displaying a progress:

JaroslavTulach: /* A little bit of forgiveness */

2010-05-02T14:14:10Z

A little bit of forgiveness

←Older revision		Revision as of 14:14, 2 May 2010
Line 69:		Line 69:
	If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).		If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).

-	Help your users to be [[clueless]]. They will reward you by not hating your [[API]]! Or at least their feelings are not going to be as negative as mine, whenever I have to deal with [http://bits.netbeans.org/dev/javadoc/org-netbeans-api-progress/~~overview-summary~~.html this one].	+	Help your users to be [[clueless]]. They will reward you by not hating your [[API]]! Or at least their feelings are not going to be as negative as mine, whenever I have to deal with [http://bits.netbeans.org/dev/javadoc/org-netbeans-api-progress/org/netbeans/api/progress/ProgressHandle.html this one].

	<comments/>		<comments/>

JaroslavTulach at 14:13, 2 May 2010

2010-05-02T14:13:08Z

←Older revision		Revision as of 14:13, 2 May 2010
Line 55:		Line 55:

	This is an [[API]] that naturally guides users through the whole life cycle		This is an [[API]] that naturally guides users through the whole life cycle
-	of an object. In each phase only appropriate methods are available. Only	+	of an object (to be fair, I have to mention that it solves only the initialization
		+	path, there is no easy way to make an already existing object ''obsolete'').
		+	In each phase only appropriate methods are available. Only
	such methods are shown in code completion inside an IDE. The possibility of		such methods are shown in code completion inside an IDE. The possibility of
	making an error is minimized.		making an error is minimized.
Line 67:		Line 69:
	If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).		If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).

-	Help your users to be [[clueless]]. They will reward you by not hating your [[API]]!	+	Help your users to be [[clueless]]. They will reward you by not hating your [[API]]! Or at least their feelings are not going to be as negative as mine, whenever I have to deal with [http://bits.netbeans.org/dev/javadoc/org-netbeans-api-progress/overview-summary.html this one].

		+	<comments/>

	[[Category:APIDesignPatterns]]		[[Category:APIDesignPatterns]]
	[[Category:APIDesignPatterns:Anti]]		[[Category:APIDesignPatterns:Anti]]
		+	[[Category:APIDesignPatterns:Clarity]]

JaroslavTulach: /* A little bit of forgiveness */

2010-05-02T08:02:36Z

A little bit of forgiveness

←Older revision		Revision as of 08:02, 2 May 2010
Line 63:		Line 63:
	I am going to claim that [[stateful]] [[API]] is a [[:Category:APIDesignPatterns:Anti\|software antipattern]] (those we fight against [[stateful]] [[singleton]]s can easily agree). Splitting such ''phased'' [[API]] into individual interfaces for each phase shall be [[good]], [[rationalistic]] way of eliminating all associated problems.		I am going to claim that [[stateful]] [[API]] is a [[:Category:APIDesignPatterns:Anti\|software antipattern]] (those we fight against [[stateful]] [[singleton]]s can easily agree). Splitting such ''phased'' [[API]] into individual interfaces for each phase shall be [[good]], [[rationalistic]] way of eliminating all associated problems.

-	However software engineering is not art, one cannot always start from scratch, with clean design. Sometimes one needs to maintain already created [[stateful]] [[API]]. In such situation any effort resembling the ''state machine'' checks can become more than welcomed. Such check is still a dirty, ugly, post-fix (made in the line of [[~~empricism~~]]), but at least it helps to eliminate the most obvious misuse of such [[stateful]] [[API]].	+	However software engineering is not art, one cannot always start from scratch, with clean design. Sometimes one needs to maintain already created [[stateful]] [[API]]. In such situation any effort resembling the ''state machine'' checks can become more than welcomed. Such check is still a dirty, ugly, post-fix (made in the line of [[empiricism]]), but at least it helps to eliminate the most obvious misuse of such [[stateful]] [[API]].

	If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).		If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).

JaroslavTulach: /* A little bit of forgiveness */

2010-05-02T08:02:16Z

A little bit of forgiveness

←Older revision		Revision as of 08:02, 2 May 2010
Line 61:		Line 61:
	== A little bit of forgiveness ==		== A little bit of forgiveness ==

-	~~TBD~~	+	I am going to claim that [[stateful]] [[API]] is a [[:Category:APIDesignPatterns:Anti\|software antipattern]] (those we fight against [[stateful]] [[singleton]]s can easily agree). Splitting such ''phased'' [[API]] into individual interfaces for each phase shall be [[good]], [[rationalistic]] way of eliminating all associated problems.
		+
		+	However software engineering is not art, one cannot always start from scratch, with clean design. Sometimes one needs to maintain already created [[stateful]] [[API]]. In such situation any effort resembling the ''state machine'' checks can become more than welcomed. Such check is still a dirty, ugly, post-fix (made in the line of [[empricism]]), but at least it helps to eliminate the most obvious misuse of such [[stateful]] [[API]].
		+
		+	If none of the above is available, then please at least follow credo of [[MartinRinard]]'s presentation [[Image:RinardOOPSLA06.pdf]] - ''don't throw needless exceptions unless you have to!''. Of course, during development strive for proper order of calls (e.g. ''start'' must be before ''progress''). But in production environment do your best to survive even wrong call order (which is easy in this case, just call the ''start'' automatically, if it has not been called yet).
		+
		+	Help your users to be [[clueless]]. They will reward you by not hating your [[API]]!
		+
		+
		+	[[Category:APIDesignPatterns]]
		+	[[Category:APIDesignPatterns:Anti]]

JaroslavTulach: /* Converting to stateless API */

2010-05-02T07:51:28Z

Converting to stateless API

←Older revision		Revision as of 07:51, 2 May 2010
Line 50:		Line 50:

	Such [[API]] makes use of uninitialized objects impossible. Either one is		Such [[API]] makes use of uninitialized objects impossible. Either one is
-	in in ''configuration phase'', and then there is no ''progress'' method,	+	in ''configuration phase'', and then there is no ''progress'' method,
	or one enters the ''progress phase'' and then it is obviously clear that		or one enters the ''progress phase'' and then it is obviously clear that
	the object has already been configured.		the object has already been configured.

JaroslavTulach: /* Call State Machine */

2010-05-02T07:50:48Z

Call State Machine

←Older revision		Revision as of 07:50, 2 May 2010
Line 29:		Line 29:
	== Call State Machine ==		== Call State Machine ==

-	During my last visit to Linz University I was presented to a research	+	During my last visit to [[Linz University]] I was presented to a research
	project to create an [[annotation]] based state machine [[javadoc]] enhancement.		project to create an [[annotation]] based state machine [[javadoc]] enhancement.
	The plan is simple. Why not annotate the methods with:		The plan is simple. Why not annotate the methods with:
Line 37:		Line 37:
	Then the compiler could check whether the order of calls for each object is		Then the compiler could check whether the order of calls for each object is
	correct or not. The project team was describing this with great enthusiasm		correct or not. The project team was describing this with great enthusiasm
-	(deserved, tracking ~~state during~~ object flow is ~~really~~ tricky), but I was	+	(deserved, tracking object state throughout program flow is tricky), but I was
	immediately thinking: This is not beautiful (in the sense of not [[rationalistic]])!		immediately thinking: This is not beautiful (in the sense of not [[rationalistic]])!
-	Rather than writing poor stateful [[API]] and then trying to fix it with	+	Rather than writing poor [[stateful]] [[API]] and then trying to fix it with
-	additional [[annotation]]s, one shall ~~rather~~ write [[good]] [[API]] to	+	additional [[annotation]]s, one shall write [[good]] [[API]] to begin with!
-	begin with!	+

	== Converting to stateless [[API]] ==		== Converting to stateless [[API]] ==