I2U2 (in particular Cosmic) code reorganization (or refactoring).

1. Motivations

1.1 Maintenance

	The cost of maintaining the current cosmic code, is higher than it needs to
	be. Our reaction time to bugs is sufficiently high and could make the rate
	of bug fixing lower than the rate of reported bugs. This is due to a few
	factors:
	
		* the lack of cohesiveness in the code causes identifying the particular
		parts affected by a certain bug difficult
		
		* changes in one place can cause undesired effects in unpredictable
		parts. This makes testing difficult and has the potential of increasing
		the number and rate of bugs. Since we are generally aware of this issue,
		we spend increased amounts of time trying to figure out all the possible
		consequences of a change.
		
		* some code is replicated over multiple files, but sometimes with small
		customizations that make it hard to observe subtle differences. There
		are times when replication is OK. This is the case with overall
		skeletons for HTML documents, because of the difficulty to automate the
		templating of such documents, and because doing so may make the
		documents less clear than spelling things out. HTML is well known. A
		custom template is not.
		
1.2 Improvements
		
	Adding new features is a painful process for the same reasons that make
	maintenance hard. Additionally, most of the Cosmic code lacks abstraction.
	Direct API calls to specific implementations and the assumption that the set
	of tools that were used first are the only set of tools that are ever
	going to be used (i.e. VDS1-VDC, VDL1, specific database layouts) make
	adapting to new tools hard.
		
1.3 Customization

	Customizing the code is also difficult, which may in turn make it difficult
	for others to use it, causing them to write their own. In particular
	separating the bits and pieces that are customizable for the ones that are
	not is not obvious. Of course, there are different level of customization,
	and some projects may have more needs than others, but the different levels
	should be separated better. It should be easy to do the easy things.
	
	The other difficulty in customizing the I2U2 code is due to the fact that
	components (e.g. JSP files) implementing conceptually connected operations
	are not isolated or easy to isolate. Some projects may not require all the
	functionality present in Cosmic. Knowing exactly what's needed and what's
	not needed to achieve a desired set of functions is a problem.
	
2. Suggestions

2.1 Separate presentation from content

	CSS2 support in most browsers has matured sufficiently to make it able to
	deal with most of our presentation needs. Furthermore, lack of CSS2 support,
	assuming that the content is properly organized, will not compromise the
	functionality of the site.
	
	CSS is suited at expressing properties of various HTML elements. HTML is
	suited at expressing structure. With this knowledge, an I2U2 developer can
	have an easier time identifying the correct place where a change needs to be
	done knowing which category the desired effect belongs to.
	
	In contrast to in-line styling or "presentation content" (<FONT>, use of
	tables for layouts that CSS can handle), CSS is re-usable. One can re-use
	the same stylesheet for multiple pages. This makes HTML code more compact
	and more usable.
	
2.2 Separate functionality from content

	Java has its advantages. Static checking ensures that API implementations
	conform to a clearly defined API interface and that API calls are correct
	(to a certain extent). In order to simplify development JSP trades such
	features (when it comes to embedded Java code) for a more fluid but harder
	to control programming style.
	
	In the spirit of clarity, code that "does" stuff should live in other places
	than code that "describes" stuff. And code that "does" stuff might as well
	benefit from typechecking and JavaDoc.
	
	Another benefit of this separation is that a set of API interfaces need to
	be defined. Such interfaces would expose to the JSP code the necessary
	information to display content and provide guidelines on the flow of things
	(e.g. is the user logged in? did the user already perform action x?) in
	abstract and clear ways (e.g. user.isLoggedIn(), user.hasPerformed(x)).
	Implementations of these API interfaces could then be used interchangeably,
	without the need to change the JSP code. Assuming that there are I2U2
	infrastructure developers and I2U2 elab developers, both could do their work
	without having to step on each other's toes very frequently. I2U2 core
	developers could fix problems or change implementations to more efficient
	ones, without breaking every developed elab.
	
	This would initially be done without changing implementations too much. This
	would allow us to preserve the current behavior, however good or bad, but
	give us more flexibility in changing it in the future.
	
2.3 Separate conceptually connected parts into components

	Things that have to do with user management (logging in, logging out, etc.)
	should go into one place. Things that deal with posters should go into a
	different place. In concrete terms (and "components" sounds more fancy than
	it should), these would be separate directories. This would make it easy to
	do two things:
	
		* Give an answer to the "I need functionality X. Do I need this file?"
		question.
	
		* Give an answer to "X is broken. What's the minimal set of files that I 
		should look at to find the problem?"
		
2.4 Develop More Rigorous Testing

	While tests do not give ultimate answers, they do provide some measurement.
	I think the road to provide automatic testing has already been paved a
	little. We should make sure that it gets done in a way that makes it
	reusable.
	
2.5 Documentation

	Documentation should include documentation for the APIs and a set of
	guidelines meant to hopefully prevent things from going messy in the future.
	In many cases messy happens because programmers are not aware of or are not
	familiar enough with certain components that they will then try to
	re-implement or misuse.
	
2.5 Clarifications
	
3. Problems

	There are a number of problems that may or may not apply to the above:
	
		* This is nonsense. Delusional. Things are fine.
		
			All interested parties should evaluate this.
			
		* The cost of doing this outweighs the benefits.
		
			All interested parties should evaluate this too.

		* This all sounds nice, but doing it is more difficult that it seems,
		and it will never get properly done. At the end of the day it will be
		the same or worse.
		
			We at least have the advantage that we know better what the code
			should do.
			
4. Rough Time Estimate

	The conversion of the current codebase will likely take about 2 months  (+/-
	1), and should be followed by an equal period of time of testing.