You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by jt...@apache.org on 2006/04/27 01:01:45 UTC
svn commit: r397327 - in /db/derby/docs/trunk: ./ src/workingwithderby/
Author: jta
Date: Wed Apr 26 16:01:44 2006
New Revision: 397327
URL: http://svn.apache.org/viewcvs?rev=397327&view=rev
Log:
DERBY-913 : Add chapters 3 and 4, update Ch 1 and 2, and update build.xml
so the Working With Derby doc builds properly on case sensative systems
like Linux. Committed patch by Stanley Bradbury <St...@gmail.com> .
Added:
db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita (with props)
db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita (with props)
db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita (with props)
Modified:
db/derby/docs/trunk/build.xml
db/derby/docs/trunk/src/workingwithderby/WorkingWithDerby.ditamap
db/derby/docs/trunk/src/workingwithderby/cwwdactivities.dita
db/derby/docs/trunk/src/workingwithderby/rwwdcopyright.dita
db/derby/docs/trunk/src/workingwithderby/twwdIntro.dita
db/derby/docs/trunk/src/workingwithderby/twwdactivity1.dita
db/derby/docs/trunk/src/workingwithderby/twwdactivity1_Setup.dita
Modified: db/derby/docs/trunk/build.xml
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/build.xml?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/build.xml (original)
+++ db/derby/docs/trunk/build.xml Wed Apr 26 16:01:44 2006
@@ -36,7 +36,7 @@
<target name="html.workingwithderby" depends="init">
<antcall target="html.dita">
<param name="manual.name" value="workingwithderby"/>
- <param name="manual.ditamap" value="workingwithderby.ditamap"/>
+ <param name="manual.ditamap" value="WorkingWithDerby.ditamap"/>
</antcall>
</target>
@@ -113,7 +113,7 @@
<target name="pdf.workingwithderby" depends="init">
<antcall target="pdf.dita">
<param name="manual.name" value="workingwithderby"/>
- <param name="manual.ditamap" value="workingwithderby.ditamap"/>
+ <param name="manual.ditamap" value="WorkingWithDerby.ditamap"/>
</antcall>
</target>
@@ -173,7 +173,7 @@
<target name="monohtml.workingwithderby" depends="init,pdf.workingwithderby">
<antcall target="monohtml.dita">
<param name="manual.name" value="workingwithderby"/>
- <param name="manual.fo" value="workingwithderby.fo"/>
+ <param name="manual.fo" value="WorkingWithDerby.fo"/>
</antcall>
</target>
Modified: db/derby/docs/trunk/src/workingwithderby/WorkingWithDerby.ditamap
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/WorkingWithDerby.ditamap?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/WorkingWithDerby.ditamap (original)
+++ db/derby/docs/trunk/src/workingwithderby/WorkingWithDerby.ditamap Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
- "../dtd/map.dtd">
+ "map.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
@@ -16,15 +16,15 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<map collection-type="sequence" linking="normal" title="Working With Derby - partial (Intro and Activity 1)">
+<map collection-type="sequence" linking="normal" title="Working With Derby">
<topicmeta>
<copyright>
<copyryear year="2006"/>
<copyrholder>Apache Software Foundation</copyrholder>
</copyright>
<prodinfo>
-<prodname>Working With Derby - partial (Intro and Activity 1)</prodname>
-<vrmlist><vrm version="10.3"/></vrmlist>
+<prodname>Working With Derby - (partial: Chap 1 - 4)</prodname>
+<vrmlist><vrm version="10.2"/></vrmlist>
<brand>Apache Derby</brand></prodinfo>
</topicmeta>
<topicref href="rwwdcopyright.dita" navtitle="Copyright"></topicref>
@@ -34,5 +34,10 @@
<topicref href="twwdactivity1_Setup.dita" navtitle="Activity 1: Run SQL using the Embedded driver">
<topicref href="twwdactivity1.dita" navtitle="Creating the database and running SQL">
</topicref>
+</topicref>
+<topicref href="twwdactivity2.dita" navtitle="Activity 2: Run SQL using the Client Driver">
+</topicref>
+<topicref href="twwdactivity3_Setup.dita" navtitle="Activity 3: Run a JDBC program using the Embedded driver">
+<topicref href="rwwdactivity3.dita" navtitle="The WwdEmbedded program"></topicref>
</topicref>
</map>
Modified: db/derby/docs/trunk/src/workingwithderby/cwwdactivities.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/cwwdactivities.dita?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/cwwdactivities.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/cwwdactivities.dita Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
- "../dtd/concept.dtd">
+ "concept.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
@@ -39,11 +39,10 @@
then view a list of the records in the table. Walk through the code to understand
the basic structure of a JDBC program that accesses a Derby database. The <codeph>CLASSPATH</codeph> variable
and connection URL attribute <codeph>;shutdown=true</codeph> are introduced.</p></dd>
-<dd><p><b>Activity 4:</b> Modify the Java JDBC program to work in a Client-Server.
-The program will load the client driver and connect to the database via the
-Derby Network Server. Compile the altered program and test that it operates
-as it did in the previous activity. Verify that two instances of the program
-can be used at the same time.</p></dd>
+<dd><p><b>Activity 4:</b> Modify the Java JDBC program to load the client
+driver and connect to the Derby Network Server. Compile the altered program
+and test that it operates as it did in the previous activity. Verify that
+two instances of the program can be used at the same time.</p></dd>
</dlentry></dl>
</conbody>
</concept>
Added: db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita?rev=397327&view=auto
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita (added)
+++ db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita Wed Apr 26 16:01:44 2006
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "reference.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<reference id="rwwdactivity3" rev="1.1" xml:lang="en-us">
+<title>The WwdEmbedded program</title>
+<shortdesc>This section describes the <codeph>WwdEmbedded</codeph> program,
+highlighting details specific to accessing a Derby database from a JDBC program.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>WwdEmbedded.java<indexterm>code description</indexterm><indexterm>org.apache.derby.jdbc.EmbeddedDriver</indexterm></indexterm>
+<indexterm>Database<indexterm>shutdown</indexterm></indexterm><indexterm>JDBC</indexterm>
+<indexterm>SQLException</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section>The <codeph>WwdEmbedded.java</codeph> program is described here.
+Most of the code related to the database activities performed is included
+but you may find it helpful to open the program file and follow along in a
+text viewer or editor. The <cite>SECTION NAMES</cite> referred to in this
+text can be found in the comments within the program code and serve as cross-reference
+points between this document and the java program. The program utilizes routines
+from the <codeph>WwdUtils</codeph> class. The utility class code is not described
+here but is available for review in the file <codeph>WwdUtils.java</codeph></section>
+<section><title>Initialize the program</title> <cite>INITIALIZATION SECTION</cite>:
+The initial lines of code identify the Java libraries used in the program
+then set up the Java class <codeph>WwdEmbedded</codeph> and the <codeph>main</codeph> method
+signature. Refer to a standard Java programming guide for information on these
+program constructs.<codeblock frame="topbot">import java.sql.*;
+public class WwdEmbedded
+{
+ public static void main(String[] args)
+ {</codeblock></section>
+<section><title>Define key variables and Objects</title><cite>DEFINE VARIABLES
+SECTION</cite>: The initial lines of the <codeph>main</codeph> method define
+the variables and Objects used in the program. This example uses variables
+to store the information needed to connect to the Derby database. Using variables
+for this information makes it easy to adapt the program to other configurations
+and other databases.<ul>
+<li><varname>driver</varname> - stores the name of the Derby embedded driver.</li>
+<li><varname>dbName</varname> - stores the name of the database.</li>
+<li><varname>connectionURL</varname> - stores the Derby connection URL that
+will be used to access the database.</li>
+<li><varname>createString</varname> - stores the SQL CREATE statement for
+the <varname>WISH_LIST</varname> table .</li>
+</ul><codeblock frame="topbot">String driver = "org.apache.derby.jdbc.EmbeddedDriver";
+String dbName="jdbcDemoDB";
+String connectionURL = "jdbc:derby:" + dbName + ";create=true";
+String createString = "CREATE TABLE WISH_LIST "
+ + "(WISH_ID INT NOT NULL GENERATED ALWAYS AS IDENTITY "
+ ...
+ + " WISH_ITEM VARCHAR(32) NOT NULL) " ;</codeblock></section>
+<section><title>Start the Derby engine</title><cite>LOAD DRIVER SECTION</cite>:
+Loading the Derby embedded JDBC driver starts the Derby database engine. The <codeph>try</codeph> and <codeph>catch</codeph> block
+(the Java error handling construct) catches the exceptions that may occur.
+A problem here is generally due to an incorrect CLASSPATH setting. <codeblock
+frame="topbot">String driver = "org.apache.derby.jdbc.EmbeddedDriver";
+...
+try{
+ Class.forName(driver);
+} catch(java.lang.ClassNotFoundException e) {
+...
+}</codeblock></section>
+<section><title>Boot the database</title><cite>BOOT DATABASE SECTION</cite>:
+The DriverManager class loads the database using the Derby connection URL
+stored in the variable <codeph>connectionURL</codeph>. This URL includes the
+parameter <varname>;create=true</varname> so the database will be created
+if it does not already exist. The primary <codeph>try</codeph> and <codeph>catch</codeph>
+block begins here. This construct handles errors for the database access code
+.<codeblock frame="topbot">String connectionURL = "jdbc:derby:" + dbName + ";create=true";
+...
+try {
+ conn = DriverManager.getConnection(connectionURL);
+... <i><most of the program code is contained here></i>
+} catch (Throwable e) {
+...
+}</codeblock></section>
+<section><title>Set up to execute SQL</title><cite>INITIAL SQL SECTION</cite>:
+Program objects needed to perform subsequent SQL operations are initialized
+here and a check is made to see if the required data table exists.<p>The statement
+object <codeph>s</codeph> is initialized. If the utility method <codeph>WwdUtils.wwdChk4Table</codeph> does
+not find the <varname>WISH_LIST</varname> table it is create by executing
+the SQL stored in the variable <varname>createString</varname> via this statement
+object. </p><codeblock frame="topbot">s = conn.createStatement();
+if (! WwdUtils.wwdChk4Table(conn))
+{
+ System.out.println (" . . . . creating table WISH_LIST");
+ s.execute(createString);
+}</codeblock>The insert statement used to add data to the table is bound to
+the prepared statement object <codeph>psInsert</codeph>. The prepared statement
+uses the <codeph>?</codeph> parameter to represent the data that will be inserted
+by the user. The actual value that is inserted is <codeph>set</codeph> later
+in the code prior to executing the SQL. This is the most efficient way to
+execute SQL statements that will be used multiple times.<codeblock frame="topbot">psInsert = conn.prepareStatement
+ ("insert into WISH_LIST(WISH_ITEM) values (?)");
+</codeblock></section>
+<section><title>Interact with the Database</title><cite>ADD / DISPLAY RECORD
+SECTION</cite>: This section uses the utility method <codeph>WwdUtils.getWishItem</codeph> to
+gather information from the User. It then utilizes the objects setup previously
+to insert the data into the <varname>WISH_LIST</varname> table and then display
+all records. A standard <codeph>do</codeph> loop causes the program to repeat
+this series of steps until <userinput>exit</userinput> is entered. The data
+related activities performed in this section are:<p>The <codeph>setString</codeph> method
+sets the substitution parameter of the <codeph>psInsert</codeph> object to
+the value entered by the User then <codeph>executeUpdate</codeph> is called
+to perform the database insert.<codeblock frame="topbot">psInsert.setString(1,answer);
+psInsert.executeUpdate();
+</codeblock></p><p>The statement object <codeph>s</codeph> is used to select
+all the records in the <varname>WISH_LIST</varname> table and store them in
+the ResultSet <varname>myWishes</varname>.<codeblock frame="topbot">myWishes = s.executeQuery("select ENTRY_DATE, WISH_ITEM
+ from WISH_LIST order by ENTRY_DATE");
+</codeblock>The <codeph>while</codeph> loop reads each record in turn by calling
+the <codeph>next</codeph> method. The <codeph>getTimestamp</codeph> and <codeph>getString</codeph> methods
+return specific fields in the record in the proper format. The fields are
+displayed using rudimentary formatting.<codeblock frame="topbot">while (myWishes.next())
+{
+ System.out.println("On " + myWishes.getTimestamp(1) +
+ " I wished for " + myWishes.getString(2));
+}</codeblock>Close the ResultSet to release the memory being used.<codeblock
+frame="topbot">myWishes.close();
+</codeblock></p></section>
+<section><title>Shutdown the Database</title><cite>DATABASE SHUTDOWN SECTION</cite>:
+When an application starts the Derby engine it should shutdown all databases
+prior to exiting. The attribute <codeph>;shutdown=true</codeph> in the Derby
+connection URL performs the shutdown. The shutdown process cleans up records
+in the transaction log to insure a faster startup the next time the database
+is booted. <p>This section verifies that the embedded driver is being used
+then issues the shutdown command and catches the shutdown exception to confirm
+the database shutdown cleanly. The shutdown status is displayed before the
+program exits.</p><codeblock frame="topbot">if (driver.equals("org.apache.derby.jdbc.EmbeddedDriver")) {
+ boolean gotSQLExc = false;
+ try {
+ DriverManager.getConnection("jdbc:derby:;shutdown=true");
+ } catch (SQLException se) {
+ if ( se.getSQLState().equals("XJ015") ) {
+ gotSQLExc = true;
+ }
+ }
+ if (!gotSQLExc) {
+ System.out.println("Database did not shut down normally");
+ } else {
+ System.out.println("Database shut down normally");
+ }
+}</codeblock><note type="important">The <codeph>XJ015</codeph> error is the
+only exception thrown by Derby that signifies an operation succeeded. All
+other exceptions indicate an operation failed.</note></section>
+<section><title>The errorPrint and SQLExceptionPrint methods</title><cite>DERBY
+EXCEPTION REPORTING CLASSES</cite>: The two methods at the end of the file, <codeph>errorPrint</codeph> and <codeph>SQLExceptionPrint</codeph>,
+are generic exception reporting routines that can be used with any JDBC program.
+This type of exception handling is required because often multiple exceptions
+(<codeph>SQLException</codeph>) are chained together then thrown. A <codeph>while</codeph> loop
+is used to report on each error in the chain. These classes are used by calling
+the <codeph>errorPrint</codeph> method from the <codeph>catch</codeph> block
+of the code that accesses the database. <codeblock frame="topbot">// Beginning of the primary catch block: uses errorPrint method
+} catch (Throwable e) {
+ /* Catch all exceptions and pass them to
+ ** the exception reporting method */
+ System.out.println(" . . . exception thrown:");
+ errorPrint(e);
+}</codeblock>The <codeph>errorPrint</codeph> routine prints a stack trace
+for all exceptions except a <codeph>SQLException</codeph>. All SQLExceptions
+are passed to the <codeph>SQLExceptionPrint</codeph> method.<codeblock frame="topbot">static void errorPrint(Throwable e) {
+ if (e instanceof SQLException)
+ SQLExceptionPrint((SQLException)e);
+ else {
+ System.out.println("A non SQL error occured.");
+ e.printStackTrace();
+ }
+} // END errorPrint </codeblock>The <codeph>SQLException</codeph> method
+iterates through each of the exceptions on the stack. For each error the codes,
+message then stacktrace are printed. <codeblock frame="topbot">// Iterates through a stack of SQLExceptions
+static void SQLExceptionPrint(SQLException sqle) {
+ while (sqle != null) {
+ System.out.println("\n---SQLException Caught---\n");
+ System.out.println("SQLState: " + (sqle).getSQLState());
+ System.out.println("Severity: " + (sqle).getErrorCode());
+ System.out.println("Message: " + (sqle).getMessage());
+ sqle.printStackTrace();
+ sqle = sqle.getNextException();
+ }
+} // END SQLExceptionPrint </codeblock>If you wish to see the output produced
+by this method enter a wish list item with more than 32 characters like: <userinput>I
+wish to see a JAVA program fail</userinput>.</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/workingwithderby/rwwdactivity3.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/workingwithderby/rwwdcopyright.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/rwwdcopyright.dita?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/rwwdcopyright.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/rwwdcopyright.dita Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "../dtd/reference.dtd">
+ "reference.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
Modified: db/derby/docs/trunk/src/workingwithderby/twwdIntro.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/twwdIntro.dita?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdIntro.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/twwdIntro.dita Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
- "../dtd/task.dtd">
+ "task.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
@@ -46,7 +46,7 @@
materials.</p><p>Performing the Working With Derby activities does require
that Java and Derby software be installed on the computer and the ability
to enter computer operating system commands. Specifically:<ul>
-<li>A Java SDK version 1.3 or higher</li>
+<li>A Java development kit version 1.3 or higher</li>
<li>The binary (<codeph>bin</codeph>) installation of Apache Derby</li>
<li>A basic knowledge of the computer command line interface<ul>
<li>how to start a command shell or window</li>
@@ -57,22 +57,22 @@
activities:</p></context>
<steps>
<step><cmd>Verify that the JAVA_HOME environment variable is set and points
-to a Java SDK version 1.3 or higher.</cmd><info>Open a command window and
-run the command <codeph>java -version</codeph> using the appropriate syntax
-for your system:</info><stepxmp><codeblock frame="topbot"><b><apiname>On Windows platforms:</apiname></b>
-C:\> "%JAVA_HOME%\bin\java" -version
-
-<b><apiname>On UNIX Korn Shell platforms:</apiname></b>
-$ "$JAVA_HOME/bin/java" -version
-
-</codeblock></stepxmp><stepresult>The output from the command will look something
-like this:<codeblock frame="topbot"><i>java version "1.4.2_04" Java(TM) 2 Runtime Environment,
+to a Java development kit version 1.3 or higher.</cmd><info>Open a command
+window and run the command <codeph>java -version</codeph> using the appropriate
+syntax for your system:</info><stepxmp><dl><dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b>"%JAVA_HOME%\bin\java" -version</b></codeblock></dd>
+</dlentry><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b>"$JAVA_HOME/bin/java" -version</b></codeblock></dd>
+</dlentry></dl></stepxmp><stepresult>The output from the command will look
+something like this:<codeblock frame="topbot"><i>java version "1.4.2_04" Java(TM) 2 Runtime Environment,
Standard Edition (build 1.4.2_04-b05) Java HotSpot(TM)
Client VM (build 1.4.2_04-b05, mixed mode)</i></codeblock>The output you see
may be different from what is shown here because the <userinput>java -version</userinput> command
outputs vendor-specific information. If the command produced an error or the
-version listed is not 1.3 or higher please install a Java SDK before continuing.</stepresult>
-</step>
+version listed is not 1.3 or higher please install a Java development kit
+before continuing.</stepresult></step>
<step><cmd>Note the filesystem path to the Derby installation (referred to
as <b>DERBY_HOME</b>).</cmd><info>If Derby is not installed or cannot be found
please install a copy now. The most recent version of Derby can be downloaded
Modified: db/derby/docs/trunk/src/workingwithderby/twwdactivity1.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/twwdactivity1.dita?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdactivity1.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/twwdactivity1.dita Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
- "../dtd/task.dtd">
+ "task.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
@@ -29,30 +29,30 @@
<steps>
<step><cmd>Run the Derby IJ tool.</cmd><stepxmp><dl><dlentry>
<dt>On Windows platforms:</dt>
-<dd><codeblock frame="topbot"><userinput>java -jar %DERBY_HOME%\lib\derbyrun.jar ij</userinput>
+<dd><codeblock frame="topbot"><b><userinput>java -jar %DERBY_HOME%\lib\derbyrun.jar ij</userinput></b>
<i><systemoutput>ij version 10.2</systemoutput></i>
</codeblock></dd>
</dlentry></dl><dl><dlentry>
<dt>On UNIX Korn Shell platforms:</dt>
-<dd><codeblock frame="topbot"><userinput>java -jar $DERBY_HOME/lib/derbyrun.jar ij</userinput>
+<dd><codeblock frame="topbot"><b><userinput>java -jar $DERBY_HOME/lib/derbyrun.jar ij</userinput></b>
<i><systemoutput>ij version 10.2</systemoutput></i></codeblock></dd>
</dlentry></dl></stepxmp></step>
<step><cmd>Create the database and open a connection to it using the embedded
-driver.</cmd><stepxmp><codeblock><userinput>CONNECT 'jdbc:derby:firstdb;create=true';</userinput></codeblock></stepxmp>
+driver.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>CONNECT 'jdbc:derby:firstdb;create=true';</userinput></b></codeblock></stepxmp>
</step>
<step><cmd>Create a table with two columns using standard SQL.</cmd><stepxmp><codeblock
-frame="topbot"><userinput>CREATE TABLE FIRSTTABLE
+frame="topbot"><b><userinput>CREATE TABLE FIRSTTABLE
(ID INT PRIMARY KEY,
- NAME VARCHAR(12));</userinput>
+ NAME VARCHAR(12));</userinput></b>
<i><systemoutput>0 rows inserted/updated/deleted</systemoutput></i></codeblock></stepxmp>
</step>
-<step><cmd>Insert three records.</cmd><stepxmp><codeblock frame="topbot"><userinput>INSERT INTO FIRSTTABLE VALUES
- (10,'TEN'),(20,'TWENTY'),(30,'THIRTY');</userinput>
+<step><cmd>Insert three records.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>INSERT INTO FIRSTTABLE VALUES
+ (10,'TEN'),(20,'TWENTY'),(30,'THIRTY');</userinput></b>
<i><systemoutput>3 rows inserted/updated/deleted</systemoutput></i></codeblock></stepxmp>
</step>
<step><cmd>Perform a simple select of all records in the table.</cmd><stepxmp><codeblock
-frame="topbot">ij> <userinput>SELECT * FROM FIRSTTABLE;</userinput>
-<i><systemoutput> ID |NAME
+frame="topbot"><b><userinput>SELECT * FROM FIRSTTABLE;</userinput></b>
+<b></b><i><systemoutput> ID |NAME
------------------------
10 |TEN
20 |TWENTY
@@ -60,23 +60,23 @@
3 rows selected</systemoutput></i></codeblock></stepxmp></step>
<step><cmd>Preform a qualified select of the record with column ID=20.</cmd>
-<stepxmp><codeblock frame="topbot"><userinput>SELECT * FROM FIRSTTABLE
+<stepxmp><codeblock frame="topbot"><b><userinput>SELECT * FROM FIRSTTABLE
WHERE ID=20;</userinput>
-<i><systemoutput> ID |NAME
+</b><i><systemoutput> ID |NAME
------------------------
20 |TWENTY
1 row selected</systemoutput></i></codeblock></stepxmp></step>
<step><cmd>Load the SQL script <userinput>toursDB.sql</userinput> to create
other tables and load data to work with (this step is optional).</cmd><stepxmp><codeblock
-frame="topbot"><userinput>run 'toursDB.sql';</userinput>
+frame="topbot"><b><userinput>run 'toursDB.sql';</userinput></b>
<i><systemoutput>0 rows inserted/updated/deleted
1 row inserted/updated/deleted
</systemoutput>
<b><apiname>===> Other output messages not shown <=====</apiname></b></i>
</codeblock></stepxmp></step>
-<step><cmd>Exit the IJ tool.</cmd><stepxmp><codeblock frame="topbot"><userinput>exit;</userinput>
+<step><cmd>Exit the IJ tool.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>exit;</userinput></b>
</codeblock></stepxmp></step>
<step><cmd>Browse the key files created by the activity.</cmd><stepxmp><ul>
<li>The <b><filepath><varname>derby.log</varname></filepath></b> message and
Modified: db/derby/docs/trunk/src/workingwithderby/twwdactivity1_Setup.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/twwdactivity1_Setup.dita?rev=397327&r1=397326&r2=397327&view=diff
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdactivity1_Setup.dita (original)
+++ db/derby/docs/trunk/src/workingwithderby/twwdactivity1_Setup.dita Wed Apr 26 16:01:44 2006
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
- "../dtd/task.dtd">
+ "task.dtd">
<!--
Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
@@ -22,7 +22,8 @@
IJ tool. The Derby embedded driver is used to create and connect to the database
firstdb. A few basic SQL commands are demonstrated.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>DERBY_HOME</indexterm><indexterm>IJ tool</indexterm></keywords>
+<keywords><indexterm>DERBY_HOME</indexterm><indexterm>IJ tool</indexterm>
+</keywords>
</metadata></prolog>
<taskbody>
<context>In preparation for performing this activity the environment variable <varname>DERBY_HOME</varname> needs
@@ -39,29 +40,32 @@
<step><cmd>Setting the <varname>DERBY_HOME</varname> environment variable.</cmd>
</step>
<step><cmd>Creating the <codeph>DERBYDBS</codeph> work directory</cmd></step>
-<step><cmd>Change directory (<userinput>cd</userinput>) to the work directory</cmd>
+<step><cmd>Changing the directory (<userinput>cd</userinput>) to the work
+directory</cmd></step>
+<step><cmd>Copying the <userinput>toursDB.sql</userinput> script from the
+Derby <codeph>demo</codeph> subdirectory into the <codeph>DERBYDBS</codeph> directory.</cmd>
</step>
-<step><cmd>Copy the <userinput>toursDB.sql</userinput> script from the Derby <codeph>demo</codeph> subdirectory
-into the <codeph>DERBYDBS</codeph> directory.</cmd></step>
</steps>
</taskbody>
<task id="activity_setup">
<title>Setup Activities</title>
<taskbody>
-<example>Open a command window and perform the following activity sequence:<codeblock
-frame="topbot"><b><apiname>On Windows platforms:</apiname></b>
-<userinput> set DERBY_HOME=C:\derby</userinput>
-<userinput> md DERBYDBS</userinput>
-<userinput> cd DERBYDBS</userinput>
-<userinput> copy %DERBY_HOME%\demo\scripts\toursDB.sql . </userinput>
-
-<b><apiname>On UNIX Korn Shell platforms:</apiname></b>
-<userinput> export DERBY_HOME=/opt/derby</userinput>
-<userinput> mkdir DERBYDBS</userinput>
-<userinput> cd DERBYDBS</userinput>
-<userinput> cp $DERBY_HOME/demo/scripts/toursDB.sql . </userinput>
-
-</codeblock><note type="important">A command prompt will be displayed after
+<example>Open a command window and perform the following activity sequence:<dl>
+<dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>set DERBY_HOME=C:\derby</userinput>
+<userinput>md DERBYDBS</userinput>
+<userinput>cd DERBYDBS</userinput>
+<userinput>copy %DERBY_HOME%\demo\scripts\toursDB.sql . </userinput></b>
+</codeblock></dd>
+</dlentry><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>export DERBY_HOME=/opt/derby</userinput>
+<userinput>mkdir DERBYDBS</userinput>
+<userinput>cd DERBYDBS</userinput>
+<userinput>cp $DERBY_HOME/demo/scripts/toursDB.sql . </userinput></b>
+</codeblock></dd>
+</dlentry></dl><note type="important">A command prompt will be displayed after
each command is executed. If an error is displayed please double check the
spelling and reenter the command.</note></example>
</taskbody>
Added: db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita?rev=397327&view=auto
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita (added)
+++ db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita Wed Apr 26 16:01:44 2006
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "task.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<task id="twwdactivity2" rev="1.1" xml:lang="en-us">
+<title>Activity 2: Run SQL using the Client Driver</title>
+<shortdesc>This activity uses Derby within a Client-Server configuration by
+using the Network Server. The <codeph>ij</codeph> tool is the client application
+that connects to the Derby Network Server. A database called <codeph>seconddb</codeph> is
+created and some basic SQL commands are executed.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Network Server</indexterm><indexterm>Client Driver</indexterm>
+</keywords>
+</metadata></prolog>
+<taskbody>
+<prereq>This activity assumes that you know how to open a command shell, change
+directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory
+and set the <varname>DERBY_HOME</varname> environment variable.</prereq>
+<context>Two command windows (labelled <codeph>Shell-1</codeph> and <codeph>Shell-2</codeph>)
+are used in this activity. <codeph>Shell-1</codeph> is used to start the Derby
+Network Server and display Network Server messages. <codeph>Shell-2</codeph> is
+used to establish a client connection to the Network Server using <codeph>ij</codeph> and
+then perform some basic SQL operations.</context>
+<steps>
+<step><cmd>Open a command window that we'll call <codeph>Shell-1</codeph>.
+Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory
+and set the <varname>DERBY_HOME</varname> environment variable.</cmd></step>
+<step><cmd>Start the Network Server.</cmd><stepxmp><dl><dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar %DERBY_HOME%\lib\derbynet.jar start</userinput></b>
+<i><systemoutput>Server is ready to accept connections on port 1527.</systemoutput></i></codeblock></dd>
+</dlentry></dl><dl><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar $DERBY_HOME/lib/derbynet.jar start</userinput></b>
+<i><systemoutput>Server is ready to accept connections on port 1527.</systemoutput></i></codeblock></dd>
+<dd></dd>
+</dlentry></dl></stepxmp><stepresult>A Network Server startup message is displayed
+in the <codeph>Shell-1</codeph> command window.</stepresult></step>
+<step><cmd>Open another command window that we'll call <codeph>Shell-2</codeph>.
+Change directory (<userinput>cd</userinput>) to the <codeph>DERBYDBS</codeph> directory
+and set the <varname>DERBY_HOME</varname> environment variable.</cmd></step>
+<step><cmd>Start <codeph>ij</codeph>.</cmd><stepxmp><dl><dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar %DERBY_HOME%\lib\derbyrun.jar ij</userinput></b>
+<i><systemoutput>ij version 10.2</systemoutput></i>
+</codeblock></dd>
+</dlentry></dl><dl><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar $DERBY_HOME/lib/derbyrun.jar ij</userinput></b>
+<i><systemoutput>ij version 10.2</systemoutput></i></codeblock></dd>
+</dlentry></dl></stepxmp><stepresult>All subsequent commands are entered from
+the network client, and are therefore entered in the <codeph>Shell-2</codeph> command
+window.</stepresult></step>
+<step><cmd>Create and open a connection to the database using the client driver.</cmd>
+<stepxmp><codeblock frame="topbot"><b><userinput>CONNECT 'jdbc:derby://localhost:1527/seconddb;create=true';</userinput>
+</b></codeblock><note type="remember">A client connection URL contains a hostname
+and a port number: <codeph>//localhost:1527/</codeph>.</note></stepxmp></step>
+<step><cmd>Create a table with two columns (<codeph>ID</codeph> and <codeph>NAME</codeph>)
+using SQL.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>CREATE TABLE SECONDTABLE
+ (ID INT PRIMARY KEY,
+ NAME VARCHAR(14));</userinput></b>
+<i><systemoutput>0 rows inserted/updated/deleted</systemoutput></i>
+</codeblock></stepxmp></step>
+<step><cmd>Insert three records into the table.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>INSERT INTO SECONDTABLE VALUES
+ (100,'ONE HUNDRED'),(200,'TWO HUNDRED'),(300,'THREE HUNDRED');</userinput>
+</b><i><systemoutput>3 rows inserted/updated/deleted</systemoutput></i>
+</codeblock></stepxmp></step>
+<step><cmd>Select all of the records in the table.</cmd><stepxmp><codeblock
+frame="topbot"><b><userinput>SELECT * FROM SECONDTABLE;</userinput></b>
+<i><systemoutput> ID |NAME
+ ------------------------
+ 100 |ONE HUNDRED
+ 200 |TWO HUNDRED
+ 300 |THREE HUNDRED
+
+3 rows selected</systemoutput></i></codeblock></stepxmp></step>
+<step><cmd>Select a subset of records from the table by qualifying the command.</cmd>
+<stepxmp><codeblock frame="topbot">ij> <b><userinput>SELECT * FROM SECONDTABLE WHERE ID=200;</userinput></b>
+<i><systemoutput> ID |NAME
+ ------------------------
+ 200 |TWO HUNDRED
+
+1 row selected</systemoutput></i> </codeblock></stepxmp></step>
+<step><cmd>Exit <codeph>ij</codeph>.</cmd><stepxmp><codeblock frame="topbot"><b><userinput>exit;</userinput></b></codeblock></stepxmp>
+</step>
+<step><cmd>Shut down the Derby Network Server.</cmd><stepxmp><dl><dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar %DERBY_HOME%\lib\derbynet.jar shutdown</userinput></b>
+<i><systemoutput>Shutdown successful.</systemoutput></i>
+</codeblock></dd>
+</dlentry></dl><dl><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>java -jar $DERBY_HOME/lib/derbynet.jar shutdown</userinput></b>
+<i><systemoutput>Shutdown successful.</systemoutput></i>
+</codeblock></dd>
+</dlentry></dl></stepxmp><stepresult>The server shutdown confirmation appears
+in both command windows.</stepresult></step>
+</steps>
+<postreq><b>Activity notes</b><p>The client connection URL contains network
+information (a hostname and portnumber) not found in the URL for an embedded
+connection. This information tells the client driver the "location" of the
+Network Server. The client driver sends requests to and receives responses
+from the Network Server.</p><p>In this activity the Derby database engine
+is embedded in the Network Server and returns data to the <codeph>ij</codeph> client
+(a client/server configuration). In contrast, establishing a connection using
+an embedded URL (one without <codeph>//localhost:1527/</codeph>) would have
+caused the Derby engine to be embedded in the <codeph>ij</codeph> application
+(an embedded configuration).</p><p>Network Server start up and shutdown messages
+are written to the <codeph>derby.log</codeph> log file along with the standard
+database engine messages. For example:<codeblock frame="topbot"><i><systemoutput>Server is ready to accept connections on port 1527.</systemoutput
+></i>
+ ...( database engine messages not shown )...
+<i><systemoutput>Shutdown successful.</systemoutput></i></codeblock></p><p>Though
+not demonstrated here, multiple client programs can connect to Network Server
+and access the database simultaneously in this configuration.</p></postreq>
+</taskbody>
+</task>
Propchange: db/derby/docs/trunk/src/workingwithderby/twwdactivity2.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita?rev=397327&view=auto
==============================================================================
--- db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita (added)
+++ db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita Wed Apr 26 16:01:44 2006
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "task.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<task id="twwdactivity3_Setup" rev="1.1" xml:lang="en-us">
+<title>Activity 3: Run a JDBC program using the Embedded driver</title>
+<shortdesc>This activity loads the Derby database engine using a simple Java
+JDBC program. JDBC is the Java Database Connectivity API and is also the native
+API for Derby. The program uses the embedded driver to create (if needed)
+and then connect to the <codeph>jdbcDemoDB</codeph> database. You can then
+populate a table within the database with text. The program demonstrates some
+basic JDBC processing along with related error handling.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>WwdEmbedded.java<indexterm>running</indexterm></indexterm>
+<indexterm>CLASSPATH</indexterm></keywords>
+</metadata></prolog>
+<taskbody>
+<prereq>This activity assumes that you have opened a command window, navigated
+to the <codeph>DERBYDBS</codeph> directory, and set the <varname>DERBY_HOME</varname> environment
+variable.</prereq>
+<context>The <varname>CLASSPATH</varname> environment variable is used by
+Java to locate the binary files (<term>jarfiles</term> and <term>classfiles</term>)
+needed to run Derby and other Java applications. Before performing this activity,
+you need to set the <varname>CLASSPATH</varname> and compile the <codeph>WwdEmbedded.java</codeph> Java
+program. </context>
+<steps>
+<step><cmd>Copy the program files into the <codeph>DERBYDBS</codeph> directory
+and set the <varname>CLASSPATH</varname>:</cmd><stepxmp><dl><dlentry>
+<dt>On Windows platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>copy %DERBY_HOME%\demo\workingwithderby\* .
+set CLASSPATH=%DERBY_HOME%\lib\derby.jar;.</userinput></b>
+</codeblock></dd>
+</dlentry><dlentry>
+<dt>On UNIX Korn Shell platforms:</dt>
+<dd><codeblock frame="topbot"><b><userinput>cp $DERBY_HOME/demo/workingwithderby/* .
+export CLASSPATH=$DERBY_HOME/lib/derby.jar:.</userinput></b>
+</codeblock></dd>
+</dlentry></dl><note type="important">Include the dot (<b>.</b>) at the end
+of each command so that your current working directory is included in the <varname>CLASSPATH</varname> and
+the files are copied to the correct location.</note></stepxmp></step>
+<step><cmd>Compile the <codeph>WwdEmbedded.java</codeph> program:</cmd><stepxmp><codeblock
+frame="topbot"><b><userinput>javac WwdEmbedded.java</userinput></b>
+</codeblock><note type="important">Only a command prompt will be displayed
+if the compilation is successful. The binary file <codeph>WwdEmbedded.class</codeph> will
+be created. If an error is displayed please verify that the Java development
+kit is properly installed.</note></stepxmp></step>
+<step><cmd>Run the program:</cmd><info>The <codeph>WwdEmbedded.java</codeph> program
+populates a table with wish list items. It is a simple Java program that prompts
+the User for text input (up to 32 characters), stores the text entered in
+a database table and then lists the items stored in the table. The program
+will continue to ask for wish list items until the word <userinput>exit</userinput> is
+entered or a problem is encountered. Some basic information on program progress
+is displayed at the beginning and the end of the program.</info><stepxmp><codeblock
+frame="topbot"><b><userinput>java WwdEmbedded</userinput></b>
+<i><systemoutput>org.apache.derby.jdbc.EmbeddedDriver loaded.
+Connected to database jdbcDemoDB
+ . . . . creating table WISH_LIST
+Enter wish-list item (enter exit to end):</systemoutput></i>
+<b><userinput>a peppermint stick</userinput></b>
+<i><systemoutput> _________________________________________________________
+On 2006-09-21 15:11:50.412 I wished for a peppermint stick
+ ________________________________________________________
+Enter wish-list item (enter exit to end):</systemoutput></i>
+<b><userinput>an all expenses paid vacation</userinput></b>
+<i><systemoutput> ________________________________________________________
+On 2006-09-21 15:11:50.412 I wished for a peppermint stick
+On 2006-09-21 15:12:47.024 I wished for an all expenses paid vacation
+ ________________________________________________________
+Enter wish-list item (enter exit to end):</systemoutput></i>
+<b><userinput>exit</userinput></b>
+<i><systemoutput>Closed connection
+Database shut down normally
+Working With Derby JDBC program ending.</systemoutput></i></codeblock></stepxmp>
+</step>
+</steps>
+</taskbody>
+</task>
Propchange: db/derby/docs/trunk/src/workingwithderby/twwdactivity3_Setup.dita
------------------------------------------------------------------------------
svn:eol-style = native