Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.3.1.4
    • Fix Version/s: 10.3.2.1, 10.4.1.3
    • Component/s: Demos/Scripts
    • Labels:
      None

      Description

      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.

      1. d3118-v01.diff
        89 kB
        John H. Embretsen
      2. d3118-v01-stat.txt
        0.4 kB
        John H. Embretsen
      3. d3118-v02.diff
        89 kB
        John H. Embretsen
      4. d3118-v02-stat.txt
        0.4 kB
        John H. Embretsen
      5. derbylogo128_bluebg.png
        4 kB
        John H. Embretsen
      6. d3118-v03-stat.txt
        0.4 kB
        John H. Embretsen
      7. d3118-v03.diff
        90 kB
        John H. Embretsen
      8. d3118-v03_tenThreeBranch.diff
        90 kB
        John H. Embretsen

        Issue Links

        There are no Sub-Tasks for this issue.

          Activity

          Hide
          John H. Embretsen added a comment -

          Suggestions to refurbish the simple demo, based on an evaluation of the demo in 10.3.1.4:

          • demo/programs/simple/example.html:
            o Use "DERBY_HOME" environment variable instead of "DERBY_INSTALL" (align with scripts and docs)
            o Describe how to set DERBY_HOME on Win, Unix, Mac?
            o Provide command line examples in both Unix and Windows variants, or at least make it consistent
            o Don't start paths with the file separator (e.g. ), makes them look absolute when they are not
            o Display commands and console output in a different font style than surrounding text (use embedded CSS?)
            o Bottom text says "Apache Derby Version 10.1". Change to "Last updated to work with Derby 10.x"?
            o Fix libraries tables (current layout is confusing)
            o Overview: Rephrase "J2SE" and "J2ME" Java Virtual Machines (since 1.6 called Java SE and Java ME)
            o Overview: (embedded) "Only one application can access a database at a time." Cause of misunderstandings? Rephrase to avoid giving the impression that only one client application can connect at one time.
            o What's Included?: Change "derby.LOG" to "derby.log"
            o What's Included?: Include cleanup instructions (remove derby.log and derbyDB/ directory)
            o How to run... (embedded): Change reference to scripts from frameworks/ to bin/ (Fix included in patch for DERBY-3026)
            o How to run... (embedded): Update sysinfo description (completely outdated)
            o How to run... (server): Strip down server classpath to include derbynet.jar only (OK since 10.1.2.1)
            o How to run... (server): Change reference to scripts from frameworks/ to bin/ (Fix included in patch for DERBY-3026)
            o How to run... (server): sysinfo reports user-specified class (SimpleApp) as NOT FOUND when following instructions verbatim (i.e. when derby.jar is not in the classpath)
            o How to run... (server): Network Server console output is out of date
            o How to run... (server): Running as described does not work: "Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/derby/jdbc/EmbeddedSimpleDataSource"
          • demo/programs/simple/SimpleApp.java:
            o is J2ME spec check reliable? (lines 72-78)
            o stronger separation between embedded / java me / client code is needed
            o demo should use PreparedStatements for repeated executions

          Also, some general observations include:

          • demo/ dir should contain a readme file. Contains currently the directories databases/, programs/ and templates/ only, which may confuse users.
          • demo/programs/readme.html states "This directory contains example programs." Should specify which dir "this" is, since the html page can be reached via links from several places.
          Show
          John H. Embretsen added a comment - Suggestions to refurbish the simple demo, based on an evaluation of the demo in 10.3.1.4: demo/programs/simple/example.html: o Use "DERBY_HOME" environment variable instead of "DERBY_INSTALL" (align with scripts and docs) o Describe how to set DERBY_HOME on Win, Unix, Mac? o Provide command line examples in both Unix and Windows variants, or at least make it consistent o Don't start paths with the file separator (e.g. ), makes them look absolute when they are not o Display commands and console output in a different font style than surrounding text (use embedded CSS?) o Bottom text says "Apache Derby Version 10.1". Change to "Last updated to work with Derby 10.x"? o Fix libraries tables (current layout is confusing) o Overview: Rephrase "J2SE" and "J2ME" Java Virtual Machines (since 1.6 called Java SE and Java ME) o Overview: (embedded) "Only one application can access a database at a time." Cause of misunderstandings? Rephrase to avoid giving the impression that only one client application can connect at one time. o What's Included?: Change "derby.LOG" to "derby.log" o What's Included?: Include cleanup instructions (remove derby.log and derbyDB/ directory) o How to run... (embedded): Change reference to scripts from frameworks/ to bin/ (Fix included in patch for DERBY-3026 ) o How to run... (embedded): Update sysinfo description (completely outdated) o How to run... (server): Strip down server classpath to include derbynet.jar only (OK since 10.1.2.1) o How to run... (server): Change reference to scripts from frameworks/ to bin/ (Fix included in patch for DERBY-3026 ) o How to run... (server): sysinfo reports user-specified class (SimpleApp) as NOT FOUND when following instructions verbatim (i.e. when derby.jar is not in the classpath) o How to run... (server): Network Server console output is out of date o How to run... (server): Running as described does not work: "Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/derby/jdbc/EmbeddedSimpleDataSource" demo/programs/simple/SimpleApp.java: o is J2ME spec check reliable? (lines 72-78) o stronger separation between embedded / java me / client code is needed o demo should use PreparedStatements for repeated executions Also, some general observations include: demo/ dir should contain a readme file. Contains currently the directories databases/, programs/ and templates/ only, which may confuse users. demo/programs/readme.html states "This directory contains example programs." Should specify which dir "this" is, since the html page can be reached via links from several places.
          Hide
          John H. Embretsen added a comment -

          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.
          Show
          John H. Embretsen added a comment - 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.
          Hide
          John H. Embretsen added a comment -

          Patch is for trunk, but if all is well with it and people are willing (I know we're getting short on time), I would be happy to make a fix for 10.3.2 as well (the current patch may even merge to 10.3 without any major problems).

          Show
          John H. Embretsen added a comment - Patch is for trunk, but if all is well with it and people are willing (I know we're getting short on time), I would be happy to make a fix for 10.3.2 as well (the current patch may even merge to 10.3 without any major problems).
          Hide
          John H. Embretsen added a comment -

          Now that DERBY-3190 has been committed, I need to fix some minor conflicts caused by this patch. Will attach version 2 shortly.

          Show
          John H. Embretsen added a comment - Now that DERBY-3190 has been committed, I need to fix some minor conflicts caused by this patch. Will attach version 2 shortly.
          Hide
          John H. Embretsen added a comment -

          Attaching new patch (d3118-v02.diff) and SVN stat file replacing the v01 patch. The only difference is that this patch takes the recent commits for DERBY-3190 and DERBY-3187 into consideration, having resolved two potential conflicts in java/demo/demo.html and java/demo/navbar.html (trunk). No other changes relative to v01.

          Please review...

          Show
          John H. Embretsen added a comment - Attaching new patch (d3118-v02.diff) and SVN stat file replacing the v01 patch. The only difference is that this patch takes the recent commits for DERBY-3190 and DERBY-3187 into consideration, having resolved two potential conflicts in java/demo/demo.html and java/demo/navbar.html (trunk). No other changes relative to v01. Please review...
          Hide
          John H. Embretsen added a comment -

          When attaching the patch, I forgot that binary files are not automatically included. Now attaching derbylogo128_bluebg.png which should be placed in the directory java/demo/ and have mime-type image/png (if the patch is applied).

          This is the derby hat logo with blue background which the patch (d3118-v02.diff) puts on the menu page/frame of the demo programs html documentation.

          Show
          John H. Embretsen added a comment - When attaching the patch, I forgot that binary files are not automatically included. Now attaching derbylogo128_bluebg.png which should be placed in the directory java/demo/ and have mime-type image/png (if the patch is applied). This is the derby hat logo with blue background which the patch (d3118-v02.diff) puts on the menu page/frame of the demo programs html documentation.
          Hide
          John H. Embretsen added a comment -

          Attached new patch d3118-v03.diff with corresponding stat file. This patch replaces previous patches and includes the following changes (bugfixes) relative to the v02 patch:

          Changes to tools/release/build.xml:

          • README.txt is now also included in .tar.gz distributions (forgot about that in v01-v02)
          • README.txt is now included in the demo/ directory only (in a -bin release), not both demo/ and demo/programs/

          Again, please review...

          Show
          John H. Embretsen added a comment - Attached new patch d3118-v03.diff with corresponding stat file. This patch replaces previous patches and includes the following changes (bugfixes) relative to the v02 patch: Changes to tools/release/build.xml: README.txt is now also included in .tar.gz distributions (forgot about that in v01-v02) README.txt is now included in the demo/ directory only (in a -bin release), not both demo/ and demo/programs/ Again, please review...
          Hide
          Knut Anders Hatlen added a comment -

          Thanks for the patch, John. Committed revision 597661.

          Show
          Knut Anders Hatlen added a comment - Thanks for the patch, John. Committed revision 597661.
          Hide
          Knut Anders Hatlen added a comment -

          There was a conflict in java/demo/simple/example.html when I tried to merge the changes to 10.3, so I didn't back-port it.

          Show
          Knut Anders Hatlen added a comment - There was a conflict in java/demo/simple/example.html when I tried to merge the changes to 10.3, so I didn't back-port it.
          Hide
          John H. Embretsen added a comment -

          Thank you Knut Anders!

          I'm not completely sure why the patch was rejected against example.html in 10.3, but here's a new version (d3118-v03_tenThreeBranch.diff) generated from the head of the 10.3 branch instead of trunk. Would you like to try again?

          Show
          John H. Embretsen added a comment - Thank you Knut Anders! I'm not completely sure why the patch was rejected against example.html in 10.3, but here's a new version (d3118-v03_tenThreeBranch.diff) generated from the head of the 10.3 branch instead of trunk. Would you like to try again?
          Hide
          Knut Anders Hatlen added a comment -

          Thanks John! I have now committed your patch to 10.3 with revision 597835.

          Show
          Knut Anders Hatlen added a comment - Thanks John! I have now committed your patch to 10.3 with revision 597835.
          Hide
          John H. Embretsen added a comment -

          Excellent, thanks for the commits! Looks as expected from the head of 10.3 and trunk now, as far as I can see.

          A small nit I just discovered is that a sentence I updated in java/demo/demo.html is only valid for -bin distributions, not -src distributions:

          "In this distribution of Apache Derby, the directory demo/programs/ contains example databases and programs written in Java."

          We could assume that people using the -src distributions are clever enough to figure out the correct path (java/demo/) anyway, or alternatively change the text to something more accurate or generic. Many of the other demo docs assume the -bin layout anyway, so it's not a big deal, I think.

          Will close this issue soon, unless someone objects.

          Show
          John H. Embretsen added a comment - Excellent, thanks for the commits! Looks as expected from the head of 10.3 and trunk now, as far as I can see. A small nit I just discovered is that a sentence I updated in java/demo/demo.html is only valid for -bin distributions, not -src distributions: "In this distribution of Apache Derby, the directory demo/programs/ contains example databases and programs written in Java." We could assume that people using the -src distributions are clever enough to figure out the correct path (java/demo/) anyway, or alternatively change the text to something more accurate or generic. Many of the other demo docs assume the -bin layout anyway, so it's not a big deal, I think. Will close this issue soon, unless someone objects.

            People

            • Assignee:
              John H. Embretsen
              Reporter:
              John H. Embretsen
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development