Developer's notes for SCR 511
Marnix Bindels, July 28 2006

To implement SCR 511: Display planning maps the following design has been put to
code:

- When planning, OSS stores the skymap at Generate files-time
- OSS stores the skymaps in the database, in some graphics format
- WEB retrieves the graphics from the database and shows them

Creating the skyplots is easy: starmap offers SkyShapes which can be drawn on a
BufferedImage by SkyMapPanel.drawShapes(). OSS has a new SkyShapeFactory that
creates an appropriate list of shapes for a revolution. The BufferedImage can be
stored in many ways. A new shape is the PlotSummary: a line of text will be 
written in a white box just below the plot. The exact text is free (see 
oss.plot.summary.text property) but augmented by rev data substitutions. The 
size is governed by another property: oss.plot.jpeg.height.

The DB has been extended with a table for images which includes columns ID,
mimetype, encoding and most importantly a CLOB column data to hold the image
data. Web references indicated that using ojdbc14.jar as available from Oracle
10.2.0.1.0 allowed storing CLOB data beyond 32K easily by using setString on a
PreparedStatement. This required the setTryBigStringForClob=true setting on the
connection which was set in the udpated ConnectionManager. Furthermore, the
column plot_id was added to the revolutionschedule table to associate an image
with a rev, indictating that the image is that rev's skymap. This allows other
kinds of images to be stored in the same table.

OSS's SchedulingDataModule (SDM) is responsible for storing the plot. I didn't
find encouraging hibernate hints on storing BLOBs or CLOBs, nor did I trust
mixing old-style sessions with hibernate sessions in the OSS commit/rollback
relying environment. So, the SDM stores the plots old skool: it calculates a
unique ID, insert or updates the images entry and links the revolutionschedule
to this new ID in the storeScheduleAndPlot() method which is called when the
SchedulingSession wants to save the schedule(s). The plot's BufferedImage is
transformed into a jpeg (should have been a GIF or PNG to minimize distortions).
In order to fit the jpeg in a CLOB, it is base64 encoded before stored in the
data column.

The webapp includes the images in the schedul.jsp. Binary data cannot be served
by jsp (see Aug 21, 2001's techtip and aug 23's update at
http://java.sun.com/developer/JDCTechTips/2001/tt0821_update.html ) and the
ImageServlet was introduced. The servlet has 2 entries: 1) serve image by
imageID and 2) serve plot by revno and posversion. When the browsing user
selects to have plots shown, schedule.jsp renders IMG tags referencing the
ImageServlet revno/posversion entry. The servlet uses hibernate mappings on
revolutionschedule and images to load the image data, which is decoded when the
encoding is base64, and writes the data on the outputstream using the mimetype
of the image record (which should enable switching to PNG at some time).

Using the new Oracle JDBC library identified a problem in existing code: when
a PLSQL proc is called, some code used a ResultSet r and called r.next(). this is
not allowed (anymore?) and output params can be accessed immediately with getObject
on the CallableStatement.

To store plots for older revolutions, use the savePlotsTest class. 
testPlotsForRange() will load a range of revolutions and store their plots in the
images table. You'll need to manually link the plots to the schedules, as 
storeScheduleAndPlot automatically increase the posversion! 
This query may come in handy:
	update revolutionschedule rs 
	set plot_id = 
		(select i.id 
		from images i 
		where i.name = to_char(rs.revno*100+rs.posversion)||'.jpg') 
	where exists (select i.id 
			from images i 
			where i.name = to_char(rs.revno*100+rs.posversion)||'.jpg');


The plot is also saved as JPEG when the user clicks Save summary and statistics.