svn commit: r611279 - in /db/derby/docs/trunk/src/tools: rtoolsijcomref22318.dita rtoolsijproprefdatasource.dita

[my...@apache.org]

Author: myrnavl
Date: Fri Jan 11 11:51:40 2008
New Revision: 611279

URL: http://svn.apache.org/viewvc?rev=611279&view=rev
Log:
DERBY-2733 - adjusting documentation on ij.dataSource and ij connect command to better reflect current behavior of ij with dataSources.

Modified:
    db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita
    db/derby/docs/trunk/src/tools/rtoolsijproprefdatasource.dita

Modified: db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita?rev=611279&r1=611278&r2=611279&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita (original)
+++ db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita Fri Jan 11 11:51:40 2008
@@ -28,8 +28,8 @@
     [ AS <b><i>Identifier</i></b> ] [ USER <b><i>String </i></b>
      PASSWORD <b><i>String</i></b> ]</b></codeblock> </refsyn>
 <section><title>Description</title><p>Connects to the database indicated by
-the <i>ConnectionURLString</i>. Specifically, takes the value of the string
-database connection URL and issues a <codeph>java.sql.DriverManager.getConnection</codeph> request
+the <i>ConnectionURLString</i>. Specifically, takes the value of the string (the 
+database connection URL) and issues a <codeph>getConnection</codeph> request using <codeph>java.sql.DriverManager</codeph> or a <codeph>javax.sql.DataSource</codeph> implementation (see the <xref href="rtoolsijproprefdatasource.dita#rtoolsijproprefdatasource">ij.dataSource</xref> property)
 to set the current connection to that database connection URL.</p><p>You have
 the option of specifying a name for your connection. Use the <xref href="rtoolsijcomref39198.dita#rtoolsijcomref39198">Set
 Connection</xref> command to switch between connections. If you do not name

Modified: db/derby/docs/trunk/src/tools/rtoolsijproprefdatasource.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsijproprefdatasource.dita?rev=611279&r1=611278&r2=611279&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsijproprefdatasource.dita (original)
+++ db/derby/docs/trunk/src/tools/rtoolsijproprefdatasource.dita Fri Jan 11 11:51:40 2008
@@ -25,15 +25,19 @@
 <refbody>
 <section><title>Function</title><p>The <codeph>ij.dataSource</codeph> property
 specifies the datasource to be used to access the database. When specifying
-a datasource, <ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not use the DriverManager mechanism to establish connections.</p> </section>
-<refsyn><title>Syntax</title>To establish a connection using <codeph>ij.dataSource</codeph>,
-you need to set the <codeph>ij.dataSource.databaseName</codeph> property. If you want to create
-the database, specify the <codeph>ij.dataSource.createDatabase</codeph> property
-as well.
-<codeblock>ij.dataSource=<varname>dataSourcename</varname>
+a datasource, <codeph>ij</codeph> does
+not use the DriverManager mechanism to establish connections. </p> </section>
+<refsyn><title>Syntax</title>
+When you set the <codeph>ij.dataSource</codeph> property <codeph>ij</codeph> will automatically try to connect to a database. To establish a connection to a specific database using <codeph>ij.dataSource</codeph>, set the <codeph>ij.dataSource.databaseName</codeph> property. If you do not set this property, <codeph>ij</codeph> will start with an error. 
+If you want to create the database, specify the <codeph>ij.dataSource.createDatabase</codeph> property as well as <codeph>ij.dataSource.databaseName</codeph>. 
+Do not specify <codeph>ij.protocol</codeph> when setting <codeph>ij.dataSource</codeph> as that would activate the DriverManager mechanism. 
+<codeblock>ij.dataSource=<varname>datasource class name</varname>
 ij.dataSource.databaseName=<varname>databasename</varname>
-[ij.dataSource.createDatabase=create]</codeblock></refsyn>
+[ij.dataSource.createDatabase=create]</codeblock>
+If you do not specify <codeph>ij.dataSource.databaseName</codeph> and get an error indicating no database was found, you can still connect to a database by using <codeph>ij</codeph>'s 
+<xref href="rtoolsijcomref22318.dita#rtoolsijcomref22318"><codeph>connect</codeph> command</xref>. 
+You should not specify the protocol (for example jdbc:derby:) in the <codeph>connect</codeph> command when using <codeph>ij.dataSource</codeph>.
+</refsyn>
 <example><title>Example 1</title> 
 <p>In the following example, <codeph>ij</codeph> connects to a database named 
 <codeph>sample</codeph> using an <codeph>EmbeddedDataSource</codeph>. The 
@@ -44,6 +48,9 @@
 # If your application runs on JDK 1.6 or higher, then you should
 # specify the JDBC4 variant of this DataSource:
 # org.apache.derby.jdbc.EmbeddedDataSource40.
+# If your application runs with a jvm supporting JSR169, you cannot use
+# org.apache.derby.jdbc.EmbeddedDataSource, instead, use: 
+# org.apache.derby.jdbc.EmbeddedSimpleDataSource.
 #</varname><b>
 java -Dij.dataSource=org.apache.derby.jdbc.EmbeddedDataSource
 -Dij.dataSource.databaseName=sample -Dij.dataSource.createDatabase=create
@@ -53,21 +60,19 @@
 * = current connection
 ij> </codeblock> </example>
 <example><title>Example 2</title> 
-<p>In the following example, <codeph>ij</codeph> starts using an <codeph>EmbeddedSimpleDataSource</codeph>, then creates a database named <codeph>smalldb</codeph> using the 
-<codeph>connect</codeph> command, specifying <codeph>;create=true</codeph> to create the
-database if it does not already exist.
+<p>In the following example, <codeph>ij</codeph> starts using an 
+<codeph>EmbeddedSimpleDataSource</codeph>, without specifying 
+<codeph>ij.dataSource.databaseName</codeph>. This results in an error indicating 
+no database was found. After the error, the <codeph>connect</codeph> command 
+is used to create and connect to a database named <codeph>smalldb</codeph>.
 </p>
 <codeblock>
 <varname>#
-# If your application runs with a jvm supporting JSR169, you cannot use
-# org.apache.derby.jdbc.EmbeddedDataSource, but you can use 
-# org.apache.derby.jdbc.EmbeddedSimpleDataSource instead.
-# Because specifying a protocol would automatically attempt to load a driver,
-# when using ij.dataSource you should omit the protocol on connect.
-# This is especially relevant with JSR169 because java.sql.Driver is not supported.
+# Start ij using EmbeddedSimpleDataSource
 #</varname><b>
 java -Dij.dataSource=org.apache.derby.jdbc.EmbeddedSimpleDataSource
-  org.apache.derby.tools.ij</b>
+  org.apache.derby.tools.ij</b> 
+ERROR XJ004: Database '' not found.
 ij version <ph conref="../conrefs.dita#vers/shortversionnumber"></ph> 
 ij> connect 'smalldb;create=true'; 
 ij> </codeblock> </example>