[jira] Updated: (DERBY-3118) Simple demo is out of date

["John H. Embretsen (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/DERBY-3118?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

John H. Embretsen updated DERBY-3118:
-------------------------------------

    Attachment: d3118-v01-stat.txt
                d3118-v01.diff

Reviewers + committer needed!

Attaching a patch (d3118-v01.diff) which attempts to brush up our presentation of the "simple" demo (SimpleApp) in -bin distributions. My main goals have been to:

  a) Eliminate errors and outdated information in documentation and code
  b) Eliminate Java code that is generally discouraged in the community, such as
        - catch (Throwable) {}
        - leaving resources open if an error occurs
        - not using PreparedStatement for repeated executions of the same SQL statement
  c) Make it easier for users to find the demos, especially the simple demo. More work is needed for other demos.

We have seen a few examples of users grabbing the SimpleApp code and modifying/extending it, then running into errors. So we should at least try to keep the demo code up to our own standards. 

---> Please spend 15 minutes to review this patch and see if that goal has been reached.


This patch touches most lines of the SimpleApp.java code and the related html file, but the end result in terms of application behavior and HTML appearance is not that different. The patch also touches a few other related files and adds two new files: A derby logo for the HTML menu and a README.txt file describing the contents of the demo directory.

I have successfully run the demo test suite with this patch, and generated a -bin zip file (ant release) to verify the behavior in a -bin distribution layout. SimpleApp has been tested on Solaris 10 (Sun JDKs 1.4.2, 1.5 and 1.6) and Windows 2003 (Sun JDK 1.5). 

PATCH DETAILS:
---------------------------------

M      java/demo/csfull.css

 * changed the order of link styles to the recommended LoVeHAte pattern.
   Prior to this change, pseudo-class :hover could be overridden by :visited
   for visited links, which I assume was not intentional.
   See http://articles.techrepublic.com.com/5100-22_11-5279569.html.
 * changed link hover color to Teal instead of Fuchsia.
 * changed font-family of body tags to sans-serif because I think this looks
   much better on screen than "Times New Roman" (serif).
 * added style for IMG tags (no border around images)
 * added various styles for new tags/classes (e.g. var.envVar, var.property)

M      java/demo/readme.html

 * Added title and changed document type to Frameset to make it valid HTML.
 * Removed frame borders (looks cleaner, less 1996-ish).

A      java/demo/derbylogo128_bluebg.png

 * New file! Official Derby logo, but modified to have blue background instead 
   of transparent (for old browser support). Included in menu frame of 
   programs-readme.

M      java/demo/demo.html

 * Clarified introductory paragraph.
 * Mentioned that the simple demo can run in both embedded and client/server
   settings.

M      java/demo/simple/SimpleApp.java

 * Restructured the Javadoc and other comments. Added Javadoc for all methods,
   moved "how to run" Javadoc to the main() method.
 * Reduced access of instance variables from "public" to "private".
 * Removed periods from console output (was inconsistent).
 * parseArguments(): 
    - Made processing of input arguments more predictable. Since only one 
      optional argument is used, only the first argument provided will now be 
      considered; the rest will be ignored.
 * printSQLError():
    - Renamed to printSQLException() and made public.
    - Added printlns as described on the UnwindExceptionChain wiki page.
    - Printing error details to System.err instead of System.out.
 * go():
    - Extracted loading of the driver into a separate method.
    - Renamed table from "derbyDB" to "location" because it is confusing to
      use the same name for both the table and the database.
    - Added method reportFailure(String) to report data verification failures 
      instead of throwing generic Exceptions.
    - Catching SQLException instead of Throwable.
    - Matching the shutdown output to the code (shutting down Derby, not just 
      the database - embedded only).
    - Checking for the correct SQLState/error code when doing shutdown.
    - Using PreparedStatements for repeated statement executions.
    - Using a try-catch-finally pattern to teach newbies the recommended 
      approach to avoid OutOfMemoryErrors etc.
   
M      java/demo/simple/example.html

 * Removed unnecessary (correct me if I'm wrong) Javascript.
 * Making tag casing consistent (lowercase, compatible with the xhtml spec).
 * Removed unused and unnecessary <a name="something"> tags, renamed the rest
   to make it easier to review and hand-edit the HTML.
 * Re-formatted some of the HTML, making it more readable.
 * Added info that the demo is intended for J2SE 1.4.2 or newer.
 * Added table in overview section describing notation difference between
   Unix and Windows environments.
 * Re-indented list of generated files, reflecting the file hierarchy.
 * Describing how to use derbyrun.jar for starting the Network Server. Also
   mentioning other methods to start the server.
 * Using <pre> tags for sysinfo output instead of manual formatting.
   Output taken from sysinfo in 10.3.1.4.
 * Using <pre> tags for program output instead of using <blockquote> + <br>
 * Removed references to the setXXCP scripts in bin/, because these cannot be
   used in this context without modifications or setting some classpath manually
   anyway.

A      java/demo/README.txt

 * New text file which will end up in the demo/ directory of -bin distributions.
 * The file describes the contents of the demo/ directory, so that new users who
   enter the demo directory won't have to guess where to go next.
 * I was not sure where to place this file in the source tree, but I ended up
   putting it in java/demo/ with most of the other demo stuff.

M      java/demo/navbar.html

 * Added Derby hat logo on the top of the frame, linking to the installation's
   index.html page. Since Internet Explorer 6 (among others) does not support
   transparent PNG images (background turns grayish), this logo image has a 
   fixed background color matching the current background color of this 
   navigation page (blueish, #B0C4DE). Tried to convert the png image to a
   transparent gif, but then the hat didn't look so smooth anymore.
 * Stronger separation between links to individual demos and other links
   (added dashed border and some extra space).
 * Changed visible text of link to online docs overview.

M      java/testing/org/apache/derbyTesting/functionTests/master/SimpleApp.out

 * Updated the master file of the SimpleApp.java test in the simpledemo suite.

M      tools/release/build.xml

 * Including java/demo/README.txt in the demo/ folder of generated -bin archives.



> Simple demo is out of date
> --------------------------
>
>                 Key: DERBY-3118
>                 URL: https://issues.apache.org/jira/browse/DERBY-3118
>             Project: Derby
>          Issue Type: Improvement
>          Components: Demos/Scripts
>    Affects Versions: 10.3.1.4
>            Reporter: John H. Embretsen
>            Assignee: John H. Embretsen
>         Attachments: d3118-v01-stat.txt, d3118-v01.diff
>
>
> The simple demo and the related instructions in the demo/programs/simple/ directory of Derby -bin installations need to be refurbished. Having a working, informative and simple demo is highly valuable to new or prospective users, but the current state of the simple demo (and our demo offerings in general) is not something to be proud of. This issue describes both bugs and other improvement suggestions related to the simple demo.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.