Author: chaase3
Date: Thu Oct  2 11:39:09 2008
New Revision: 701206

URL: http://svn.apache.org/viewvc?rev=701206&view=rev
Log:
DERBY-3200:  Developer's Guide: Add examples showing use of SQL authorization with user authentication

Made additional fixes to topics suggested by reviewer, mainly for clarity and adherence to programming conventions.

Patch: DERBY-3200-8.diff

Modified:
    db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita
    db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita

Modified: db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita?rev=701206&r1=701205&r2=701206&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita Thu Oct  2 11:39:09 2008
@@ -20,7 +20,7 @@
 -->
 <reference id="rdevcsecure26537" xml:lang="en-us">
 <title>User authentication and authorization embedded example</title>
-<shortdesc>The following program, <codeph>AuthExampleEmbedded.java</codeph>,
+<shortdesc>This example, <codeph>AuthExampleEmbedded.java</codeph>,
 shows how to turn on, use, and turn off user authentication using
 <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
 built-in user authentication and user authorization using the embedded
@@ -28,9 +28,12 @@
 <prolog></prolog>
 <refbody>
 <section>
-<p>See <xref href="cdevcsecure36595.dita#cdevcsecure36595"></xref> for
-information on using SQL authorization, which allows you to use ANSI SQL
-Standard GRANT and REVOKE statements. See 
+<p>This example is a single long program. A similar example that uses the client
+driver, in
+<xref href="rdevcsecureclientexample.dita#rdevcsecureclientexample"></xref>,
+uses one program to set properties and a second program to perform database
+operations. Either example would work equally well in the other format.</p>
+<p>See 
 <xref href="rdevcsecuresqlauthembeddedex.dita#rdevcsecuresqlauthembeddedex"></xref>
 for an example similar to this one that uses SQL authorization.</p>
 <p>The program does the following:</p>
@@ -59,8 +62,8 @@
 <p>When you run <codeph>AuthExampleEmbedded</codeph>, make
 sure that <codeph>%DERBY_HOME%\lib\derby.jar</codeph> (or
 <codeph>$DERBY_HOME/lib/derby.jar</codeph>) is in your classpath. For example,
-you might use the following command:</p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derby.jar AuthExampleEmbedded</userinput></p>
+you might use the following command on a UNIX system:</p>
+<p><userinput>java -cp .:${DERBY_HOME}/lib/derby.jar AuthExampleEmbedded</userinput></p>
 </section>
 <example><title>Source code for <codeph>AuthExampleEmbedded.java</codeph></title>
 <codeblock>import java.sql.*;
@@ -331,8 +334,11 @@
         s.close();
     }
 
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException)
@@ -344,7 +350,11 @@
         System.exit(1);
     }
 
-    //  Iterate through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");

Modified: db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita?rev=701206&r1=701205&r2=701206&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita Thu Oct  2 11:39:09 2008
@@ -20,21 +20,24 @@
 -->
 <reference id="rdevcsecureclientexample" xml:lang="en-us">
 <title>User authentication and authorization client example</title>
-<shortdesc>The following pair of programs,
+<shortdesc>This example consists of a pair of programs,
 <codeph>AuthExampleClient1.java</codeph> and
-<codeph>AuthExampleClient2.java</codeph>, shows how to turn on, use, and turn
-off user authentication using
+<codeph>AuthExampleClient2.java</codeph>, which show how to turn on, use, and
+turn off user authentication using
 <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
 built-in user authentication and user authorization using the client
 driver.</shortdesc>
 <prolog></prolog>
 <refbody>
 <section>
-<p>See <xref href="cdevcsecure36595.dita#cdevcsecure36595"></xref> for
-information on using SQL authorization, which allows you to use ANSI SQL
-Standard GRANT and REVOKE statements. See
+<p>This example uses one program to set properties and a second program to
+perform database operations. A similar example that uses the embedded
+driver, in
+<xref href="rdevcsecure26537.dita#rdevcsecure26537"></xref>, is a single long
+program. Either example would work equally well in the other format.</p>
+<p>See
 <xref href="rdevcsecuresqlauthclientex.dita#rdevcsecuresqlauthclientex"></xref>
-for examples similar to these that use SQL authorization.</p>
+for an example similar to this one that uses SQL authorization.</p>
 <p>The first program, <codeph>AuthExampleClient1.java</codeph>, does the
 following:</p>
 <ol>
@@ -64,15 +67,15 @@
 <p><userinput>javac AuthExampleClient2.java</userinput></p>
 <p>Before you run the programs, start the
 <ph conref="../conrefs.dita#prod/productshortname"></ph> Network
-Server as described in "Activity 4: Create and run a JDBC program using the
-client driver and Network Server" in
+Server as described in step 2 of "Activity 4: Create and run a JDBC program
+using the client driver and Network Server" in
 <ph conref="../conrefs.dita#pub/citgetstart"></ph>. When you run the
 programs, make sure that
 <codeph>%DERBY_HOME%\lib\derbyclient.jar</codeph> (or
-<codeph>$DERBY_HOME/lib/derbyclient.jar</codeph>) is in your classpath. Run the
-programs using commands like the following:</p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClient1</userinput></p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClient2</userinput></p>
+<codeph>$DERBY_HOME/lib/derbyclient.jar</codeph>) is in your classpath. For
+example, you might use the following commands on a Windows system:</p>
+<p><userinput>java -cp .;%DERBY_HOME%\lib\derbyclient.jar AuthExampleClient1</userinput></p>
+<p><userinput>java -cp .;%DERBY_HOME%\lib\derbyclient.jar AuthExampleClient2</userinput></p>
 </section>
 <example><title>Source code for <codeph>AuthExampleClient1.java</codeph></title>
 <codeblock>import java.sql.*;
@@ -221,8 +224,11 @@
         s.close();
     }
 
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException)
@@ -234,7 +240,11 @@
         System.exit(1);
     }
 
-    //  Iterates through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");
@@ -387,8 +397,11 @@
         }
     }
 
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException)
@@ -400,7 +413,11 @@
         System.exit(1);
     }
 
-    //  Iterates through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");

Modified: db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita?rev=701206&r1=701205&r2=701206&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita Thu Oct  2 11:39:09 2008
@@ -20,15 +20,21 @@
 -->
 <reference id="rdevcsecuresqlauthclientex" xml:lang="en-us">
 <title>User authentication and SQL authorization client example</title>
-<shortdesc>The following pair of programs,
+<shortdesc>This example consists of a pair of programs,
 <codeph>AuthExampleClientSQLAuth1.java</codeph> and
-<codeph>AuthExampleClientSQLAuth2.java</codeph>, show how to use SQL
+<codeph>AuthExampleClientSQLAuth2.java</codeph>, which show how to use SQL
 authorization, in addition to 
 <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
 built-in user authentication and user authorization, with the client driver.</shortdesc>
 <prolog></prolog>
 <refbody>
 <section>
+<p>This example uses one program to set properties and a second program to
+perform database operations. A similar example that uses the embedded
+driver, in
+<xref href="rdevcsecuresqlauthembeddedex.dita#rdevcsecuresqlauthembeddedex"></xref>,
+is a single long program. Either example would work equally well in the other
+format.</p>
 <p>See <xref href="cdevcsecure36595.dita#cdevcsecure36595"></xref> for more
 information on using SQL authorization, which allows you to use ANSI SQL
 Standard GRANT and REVOKE statements. Compare this example to the one in
@@ -78,15 +84,15 @@
 <p><userinput>javac AuthExampleClientSQLAuth2.java</userinput></p>
 <p>Before you run the programs, start the
 <ph conref="../conrefs.dita#prod/productshortname"></ph> Network
-Server as described in "Activity 4: Create and run a JDBC program using the
-client driver and Network Server" in
+Server as described in step 2 of "Activity 4: Create and run a JDBC program
+using the client driver and Network Server" in
 <ph conref="../conrefs.dita#pub/citgetstart"></ph>. When you run the
 programs, make sure that
 <codeph>%DERBY_HOME%\lib\derbyclient.jar</codeph> (or
-<codeph>$DERBY_HOME/lib/derbyclient.jar</codeph>) is in your classpath. Run the
-programs using commands like the following:</p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClientSQLAuth1</userinput></p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClientSQLAuth2</userinput></p>
+<codeph>$DERBY_HOME/lib/derbyclient.jar</codeph>) is in your classpath.  For
+example, you might use the following commands on a UNIX system:</p>
+<p><userinput>java -cp .:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClientSQLAuth1</userinput></p>
+<p><userinput>java -cp .:${DERBY_HOME}/lib/derbyclient.jar AuthExampleClientSQLAuth2</userinput></p>
 </section>
 <example><title>Source code for <codeph>AuthExampleClientSQLAuth1.java</codeph></title>
 <codeblock>import java.sql.*;
@@ -256,8 +262,11 @@
         s.close();
     }
  
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException) 
@@ -269,7 +278,11 @@
         System.exit(1);
     }
 
-    //  Iterate through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");
@@ -524,8 +537,11 @@
         }
     }
 
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException)
@@ -537,7 +553,11 @@
         System.exit(1);
     }
 
-    //  Iterate through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");

Modified: db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita?rev=701206&r1=701205&r2=701206&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita Thu Oct  2 11:39:09 2008
@@ -20,15 +20,19 @@
 -->
 <reference id="rdevcsecuresqlauthembeddedex" xml:lang="en-us">
 <title>User authentication and SQL authorization embedded example</title>
-<shortdesc>The following program, 
-<codeph>AuthExampleEmbeddedSQLAuth.java</codeph>, shows how to use SQL
-authorization, in addition to 
+<shortdesc>This example, <codeph>AuthExampleEmbeddedSQLAuth.java</codeph>,
+shows how to use SQL authorization, in addition to 
 <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
 built-in user authentication and user authorization, with the embedded
 driver.</shortdesc>
 <prolog></prolog>
 <refbody>
 <section>
+<p>This example is a single long program. A similar example that uses the client
+driver, in
+<xref href="rdevcsecuresqlauthclientex.dita#rdevcsecuresqlauthclientex"></xref>,
+uses one program to set properties and a second program to perform database
+operations. Either example would work equally well in the other format.</p>
 <p>See <xref href="cdevcsecure36595.dita#cdevcsecure36595"></xref> for more
 information on using SQL authorization, which allows you to use ANSI SQL
 Standard GRANT and REVOKE statements. Compare this example to the one in
@@ -74,8 +78,8 @@
 <p>When you run <codeph>AuthExampleEmbeddedSQLAuth</codeph>, make
 sure that <codeph>%DERBY_HOME%\lib\derby.jar</codeph> (or
 <codeph>$DERBY_HOME/lib/derby.jar</codeph>) is in your classpath. For example,
-you might use the following command:</p>
-<p><userinput>java -cp ${CLASSPATH}:${DERBY_HOME}/lib/derby.jar AuthExampleEmbeddedSQLAuth</userinput></p>
+you might use the following command on a Windows system:</p>
+<p><userinput>java -cp .;%DERBY_HOME%\lib\derby.jar AuthExampleEmbeddedSQLAuth</userinput></p>
 </section>
 <example><title>Source code for <codeph>AuthExampleEmbeddedSQLAuth.java</codeph></title>
 <codeblock>import java.sql.*;
@@ -470,8 +474,11 @@
         s.close();
     }
 
-    /** Exception reporting methods
-     *   with special handling of SQLExceptions
+    /** 
+     * Report exceptions, with special handling of SQLExceptions,
+     * and exit.
+     *
+     * @param e an exception (Throwable)
      */
     static void errorPrintAndExit(Throwable e) {
         if (e instanceof SQLException)
@@ -483,7 +490,11 @@
         System.exit(1);
     }
 
-    //  Iterate through a stack of SQLExceptions
+    /**
+     * Iterate through a stack of SQLExceptions.
+     *
+     * @param sqle a SQLException
+     */
     static void SQLExceptionPrint(SQLException sqle) {
         while (sqle != null) {
             System.out.println("\n---SQLException Caught---\n");

Modified: db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita?rev=701206&r1=701205&r2=701206&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita Thu Oct  2 11:39:09 2008
@@ -21,7 +21,7 @@
 <reference id="rdevcsecuresqlauthexs" xml:lang="en-us">
 <title>User authentication examples using SQL authorization</title>
 <shortdesc>
-The following examples show how to use SQL authorization in 
+These examples show how to use SQL authorization in 
 conjunction with <ph conref="../conrefs.dita#prod/productshortname"></ph>'s 
 built-in user authentication and user authorization.
 </shortdesc>