svn commit: r432771 - /db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita

[ka...@apache.org]

Author: kahatlen
Date: Fri Aug 18 16:13:06 2006
New Revision: 432771

URL: http://svn.apache.org/viewvc?rev=432771&view=rev
Log:
DERBY-1717: Working With Derby task file twwdactivity4.dita is
invalid, results in missing text

To be valid DITA, this topic should be coded as a three-step task,
where each step has a series of substeps. I have taken the liberty of
doing this. I have also taken the liberty of correcting the
punctuation and syntax problems that I found.

Patch contributed by Kim Haase.

Modified:
    db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita

Modified: db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita?rev=432771&r1=432770&r2=432771&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/twwdactivity4.dita Fri Aug 18 16:13:06 2006
@@ -22,7 +22,7 @@
 <title>Activity 4: Create and run a JDBC program using the Client driver and
 Network Server</title>
 <shortdesc>This section demonstrates the ease with which a program that embeds
-Derby can be modified for a client / server implementation using the Derby
+Derby can be modified for a client/server implementation using the Derby
 Network Server. A Derby client program, <codeph>WwdClient.java</codeph>, is
 created by changing a few lines of the <codeph>WwdEmbedded.java</codeph> program.
 The client program can be run in multiple command shells allowing simultaneous
@@ -44,12 +44,15 @@
 the Derby Network Server and display Network Server messages. The <codeph>Client-Shell</codeph> is
 used to edit, compile and run the newly created <codeph>WwdClient.java</codeph> program.
 The <varname>CLASSPATH</varname> environment variable is set in <codeph>Client-Shell</codeph> to
-support the client JDBC program.<p><b>Creating the WwdClient program</b></p></context>
+support the client JDBC program.</context>
 <steps>
-<step><cmd>Open a command window that we'll call the <codeph>Client-Shell</codeph>.
-Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory.</cmd>
-</step>
-<step><cmd>Make a copy of the <codeph>WwdEmbedded.java</codeph> program called <codeph>WwdClient.java</codeph></cmd>
+<step><cmd><b>Create the WwdClient program.</b></cmd>
+<substeps>
+<substep><cmd>Open a command window that we'll call the <codeph>Client-Shell</codeph>.</cmd>
+</substep>
+<substep><cmd>Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory.</cmd>
+</substep>
+<substep><cmd>Make a copy of the <codeph>WwdEmbedded.java</codeph> program called <codeph>WwdClient.java</codeph>.</cmd>
 <stepxmp><dl><dlentry>
 <dt>On Windows platforms:</dt>
 <dd><codeblock frame="topbot"><b>copy WwdEmbedded.java WwdClient.java</b>
@@ -58,16 +61,16 @@
 <dt>On UNIX Korn Shell platforms:</dt>
 <dd><codeblock frame="topbot"><b>cp WwdEmbedded.java WwdClient.java</b>
 </codeblock></dd>
-</dlentry></dl></stepxmp></step>
-<step><cmd>Open the <codeph>WwdClient.java</codeph> file in your favorite
+</dlentry></dl></stepxmp></substep>
+<substep><cmd>Open the <codeph>WwdClient.java</codeph> file in your favorite
 text editor and update the class name to reflect the new filename:</cmd><stepxmp><codeblock
 frame="topbot"><b>Original declaration</b>
      public class WwdEmbedded
 
 <b>New declaration</b>
      public class <b>WwdClient</b>
-</codeblock></stepxmp></step>
-<step><cmd>Edit the <cite>DEFINE VARIABLES SECTION</cite> of the program so
+</codeblock></stepxmp></substep>
+<substep><cmd>Edit the <cite>DEFINE VARIABLES SECTION</cite> of the program so
 the <varname>driver</varname> variable contains the name of the Derby Client
 Driver class and the <varname>connectionURL</varname> variable contains the
 hostname and a port number of the Network Server.</cmd><stepxmp><codeblock
@@ -80,20 +83,32 @@
      String driver = <b>"org.apache.derby.jdbc.ClientDriver"</b>;
      ...
      String connectionURL = <b>"jdbc:derby://localhost:1527/"</b> + dbName + ";create=true";
-</codeblock></stepxmp></step>
-<step><cmd>Compile the application.</cmd><stepxmp><codeblock frame="topbot"><b>javac WwdClient.java</b>
+</codeblock></stepxmp></substep>
+<substep><cmd>Compile the application.</cmd><stepxmp><codeblock frame="topbot"><b>javac WwdClient.java</b>
 </codeblock><note type="important">Only a command prompt will be displayed
 if the compilation is successful. The binary file <codeph>WwdClient.class</codeph> will
-be created. If a syntax error is displayed modify the line indicated so it
+be created. If a syntax error is displayed, modify the line indicated so it
 is identical to the example.</note></stepxmp><info><p>That's all there is
-to it.</p></info></step>
-</steps>
-<example><title>Setting up the client / server environment</title>Before running
-the <codeph>WwdClient</codeph> program the Network Server needs to be started.
-To do this open a command window that we'll call the <codeph>Server-Shell</codeph>.
-Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory
-and set the <varname>DERBY_HOME</varname> environment variable. Start the
-Network Server:<dl><dlentry>
+to it.</p></info></substep>
+</substeps>
+</step>
+<step><cmd><b>Set up the client/server environment.</b></cmd>
+<info><p>Before you run the <codeph>WwdClient</codeph> program, the Network 
+Server needs to be started.</p>
+</info>
+<substeps>
+<substep>
+<cmd>Open a command window that we'll call the <codeph>Server-Shell</codeph>.</cmd>
+</substep>
+<substep>
+<cmd>Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory.</cmd>
+</substep>
+<substep>
+<cmd>Set the <varname>DERBY_HOME</varname> environment variable.</cmd>
+</substep>
+<substep>
+<cmd>Start the Network Server:</cmd>
+<stepxmp><dl><dlentry>
 <dt>On Windows platforms:</dt>
 <dd><codeblock frame="topbot"><b>java -jar %DERBY_HOME%\lib\derbynet.jar start</b>
 
@@ -103,10 +118,23 @@
 <dd><codeblock frame="topbot"><b>java -jar $DERBY_HOME/lib/derbynet.jar start</b>
 
 <i>Server is ready to accept connections on port 1527.</i></codeblock></dd>
-</dlentry></dl><title>Running the client program</title><p>Return to the <codeph>Client-Shell</codeph> window.
-If not already defined set the <varname>DERBY_HOME</varname> environment variable.
-Next set the <varname>CLASSPATH</varname> environment variable to include
-the location of the file <codeph>derbyclient.jar</codeph>:<dl><dlentry>
+</dlentry></dl></stepxmp>
+</substep>
+</substeps>
+</step>
+<step><cmd><b>Run the client program.</b></cmd>
+<substeps>
+<substep>
+<cmd>Return to the <codeph>Client-Shell</codeph> window.</cmd>
+</substep>
+<substep>
+<cmd>If it is not already defined, set the <varname>DERBY_HOME</varname> environment variable.
+</cmd>
+</substep>
+<substep>
+<cmd>Set the <varname>CLASSPATH</varname> environment variable to include
+the location of the file <codeph>derbyclient.jar</codeph>:</cmd>
+<stepxmp><dl><dlentry>
 <dt>On Windows platforms:</dt>
 <dd><codeblock frame="topbot"><b>set CLASSPATH=%DERBY_HOME%\lib\derbyclient.jar;.</b>
 </codeblock></dd>
@@ -115,10 +143,13 @@
 <dd><codeblock frame="topbot"><b>export CLASSPATH=$DERBY_HOME/lib/derby.jar:.</b>
 </codeblock></dd>
 </dlentry></dl><note type="important">Include the dot (<b>.</b>) at the end
-of the command so that your current working directory is included in the <varname>CLASSPATH</varname>.</note><dl>
-<dlentry>
-<dt>Run the client program:</dt>
-<dd><codeblock frame="topbot"><b>java WwdClient</b>
+of the command so that your current working directory is included in the <varname>CLASSPATH</varname>.</note>
+</stepxmp>
+</substep>
+<substep>
+<cmd>Run the program:</cmd>
+<stepxmp>
+<codeblock frame="topbot"><b>java WwdClient</b>
 
 <i>org.apache.derby.jdbc.ClientDriver loaded.
 Connected to database jdbcDemoDB
@@ -146,35 +177,39 @@
 <b>exit</b>
 
 <i>Closed connection
-Working With Derby JDBC program ending.</i></codeblock></dd>
-</dlentry></dl></p></example>
-<postreq><b>Activity notes</b><p>In a client / server environment the client
+Working With Derby JDBC program ending.</i></codeblock>
+</stepxmp>
+</substep>
+</substeps>
+</step>
+</steps>
+<postreq><b>Activity notes</b><p>In a client/server environment, the client
 program is often used from other computers on the network. Whenever a system
-accepts connections from other computers there is a chance for abuse. To maintain
-security the Derby Network Server defaults to only accepting connections from
+accepts connections from other computers, there is a chance of abuse. To maintain
+security, the Derby Network Server defaults to accepting connections only from
 clients running on the local machine (<codeph>localhost</codeph>). Before
 this or any other Derby client program can access Network Server from another
-machine additional steps should be taken to secure the Network Server environment.
-Once secured the Network Server can be safely configured it to accept connections
-from other machines. Refer the <cite>Network Server security</cite> and <cite>Running
+machine, additional steps should be taken to secure the Network Server environment.
+Once secured, the Network Server can be safely configured to accept connections
+from other machines. Refer to the <cite>Network Server security</cite> and <cite>Running
 the Network Server under the security manager</cite> sections of the <cite>Derby
 Server and Administration Guide</cite> for important information on securing
 the Network Server and enabling network connections.</p><p>With Network Server
-started you can run the client program simultaneously in multiple windows.
-To demonstrate this open two command windows and perform the steps of the <cite>Running
-the client program</cite> section in each window. Both clients will operate
-without a problem. In contrast it would not be possible for a program that
+started, you can run the client program simultaneously in multiple windows.
+To demonstrate this, open two command windows and perform the substeps of the <cite>Run
+the client program</cite> step in each window. Both clients will operate
+without a problem. In contrast, it would not be possible for a program that
 uses the embedded driver (e.g. <codeph>WwdEmbedded</codeph>) to access the
-database until the database or the Network Server is shutdown. </p><p>You
-may have noticed that the client program does not shutdown the database. This
-is because the database is a shared resource in a client / server environment
-and, in most cases, should only be shutdown when the Server is shutdown. If
-multiple clients are accessing the database and one shuts down the database
+database until the database or the Network Server is shut down. </p><p>You
+may have noticed that the client program does not shut down the database. This
+is because the database is a shared resource in a client/server environment
+and, in most cases, should only be shut down when the Server is shut down. If
+multiple clients are accessing the database and one shuts down the database,
 the remaining clients will encounter a failure the next time they attempt
 an SQL command.</p><p>Derby's two architectures have caused confusion for
 some new Derby users. They mistakenly think that embedded is a single user
 configuration. This is not true. The embedded driver supports multiple simultaneous
-connections, performs locking and provides performance, integrity and recoverability.
+connections, performs locking, and provides performance, integrity and recoverability.
 Any application using the embedded driver can open multiple Derby connections
 and then provide a means for multiple users to interact with the database
 on each connection. The Derby Network Server is an example of such an application.</p></postreq>