[jira] Commented: (DERBY-391) Tools and Utilities guide does not document ij.datasource, ij.user, nor ij.password

["John H. Embretsen (JIRA)" <de...@db.apache.org>]

    [ http://issues.apache.org/jira/browse/DERBY-391?page=comments#action_12360068 ] 

John H. Embretsen commented on DERBY-391:
-----------------------------------------

Thanks for providing the patch! I have not used the ij tool much myself, but I have the following comments to the patch:

*** rtoolsijproprefpassword.html (ij.password) ***

I don't think saying "When you connect like ij.password, and ij creates the database..." makes much sense, really. I think I understand what is meant by this, but in my opinion something like this will be better:

"When you specify the ij.password property, and use ij to create the database, you will always need to use the password in order to access the database, unless you set up additional users."

*** rtoolsijproprefuser.html (ij.user) ***

1.
This might be nitpicking, but I think the example provided may be somewhat misleading. In my opinion, the example gives the impression that it is possible to execute the example commands without connecting to a database first. The main reason for this is that the java command is followed by "ij version 10.2" (which is the first thing you see when starting ij), and the command "set schema finance;". This indicates that the example shows a continuous sequence of commands, including the java command (see the examples for other ij properties, e.g. ij.showErrorCode). However, ij displays an error message if you try to use "set schema finance;" before connecting to a database. Including something like
"ij> connect 'jdbc:derby:sampleDB';" 
after "ij version 10.2" will correct this, I believe.

2.
What is the meaning of "ij.password;" in this example (bottom line)?

3.
Shouldn't all examples follow "Conventions for ij examples" (http://db.apache.org/derby/docs/dev/tools/rtoolsijcomref1003067.html)?
(This basically means making user input in ij bold text).

Feel free to comment on my comments ;)


> Tools and Utilities guide does not document ij.datasource, ij.user, nor ij.password
> -----------------------------------------------------------------------------------
>
>          Key: DERBY-391
>          URL: http://issues.apache.org/jira/browse/DERBY-391
>      Project: Derby
>         Type: Improvement
>   Components: Documentation
>     Versions: 10.1.1.0
>     Reporter: Myrna van Lunteren
>     Priority: Minor
>      Fix For: 10.2.0.0
>  Attachments: rtoolsijproprefdatasource.html, rtoolsijproprefpassword.html, rtoolsijproprefuser.html
>
> The Tools and Utilities guide documents the ij properties. 
> However, it does not have any documentation about the following properties
> ij.datasource
> ij.password
> ij.user
> I suggest something like this (but someone else should review):
> ij.dataSource
> Function
> This property allows one to specify the datasource that should be used to access the database. When specifying a datasource, Derby does *not* use the DriverManager mechanism to establish connections. For more information about DataSources, refer to the JDBC documentation and to the Derby Developer's Guide, section Using Derby as a J2EE Resource Manager.
> To establish a connection using ij.dataSource, you need to use additional ij.dataSource properties to set some additional properties:
> ij.dataSource.databaseName
> ij.dataSource.createDatabase
> Syntax 
> ij.dataSource=<datasourcename> ij.dataSource.databaseName=<databaseName> [ij.dataSource.createDatabase=create]
> Example
> java -Dij.dataSource=org.apache.derby.jdbc.EmbeddedDataSource
> -Dij.dataSource.databaseName=toursDB -Dij.dataSource.createDatabase=create"
> ij.password
>   Function
>   Specifies the password used to make connections with.
>   When you connect like this, and ij creates the database, you will allways need to know that password in order to access the database, unless you set up additional users. For more information about authentication see the Derby Developer's Guide.
> Syntax 
> ij.pasword=password
> Example
> java -Dij.user=me -Dij.password=mine org.apache.derby.tools.ij
> See also
> ij.user; Derby Developer's Guide - Derby and Security
> ij.user
>   Function
>   Specifies the user with which connections are made by default.
>   When you connect like this, ij assumes that the database schema to be used is the same as the username provided. However, certain database objects cannot be created until a schema exists, i.e. until a create schema <name> has been issued, followed by a set schema <name>, or fully qualifying the database objects to be created. If no user is specified, no set schema has been issued, or create statements do not qualify the schema, all database objects are assumed to be under schema 'APP'. 
> Syntax 
> ij.user=username
> Example
> java -Dij.user=me -Dij.password=mine org.apache.derby.tools.ij
> ij version 10.1
> ij> set schema finance;
> ij> select * from accounts;
> ij.password; Derby Developer's Guide - Derby and Security

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
   http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
   http://www.atlassian.com/software/jira