[
https://issues.apache.org/jira/browse/DERBY-2389?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12673298#action_12673298
]
Dag H. Wanvik commented on DERBY-2389:
--------------------------------------
Really good to see this clean-up, Kim! :) Sorry for the late review.
I am ok with committing now, and fixing up the remaining items in a
follow-up patch if that seems better than respinning this large patch.
I applied the patch and it built cleanly; I scanned the text for
references to Tuning Derby and found only one outdated link, see
below.
- Dev guide (I reviewed this material by reading the pdf-version's new
section on Working with properties in its entirety; so some comments
below relate to issues with the original material from the Tuning
guide, not to changes introduced by moving the material. Feel free
to ignore such comments, fix them now, or make separate JIRAs for
them as you see fit :-)
* "Derby and Security"
"Configuring security in a client/server environment"
"This procedure requires a system with multiple databases and some
administrative
resources.
1. Configure security features as system properties. See Tuning Derby."
***************
Outdated link.
* working with properties
- properties overview
The sentence "When you change these properties, they affect any
tables or indexes created after this change" occurs twice; under
both system and database scope. Above, the term conglomerate is
introduced and defined. Suggest use it in this sentence (why else
define it?)
Also I am a bit wary of the sentence itself, I would invert its
structure to make clearer we are only talking about what happens
for such properties in relation to conglomerates:
"When you change these properties, they affect any
conglomerates created after this change"
Suggest:
"For properties that affect conglomerates, changing the value of
such properties only affect conglomerates created after the
change. Conglomerates created earlier are unaffected".
* Setting Derby properties:
- In the reference to "IBM Application Developer Kits": Make this
generic (not?) or include reference to Sun's Java as well..
- "not as properties of the type discussed in this book"
"book" is misleading now; use section instead?
- «For more information, see "java.sql.DriverManager.getConnection
method" and "Setting attributes for the database connection URL"
in the Derby Reference Manual.»
After moving, maybe it is now reasonable here to refer directly with
a link to the proper section in the dev guide as well?
- "There should be one derby.properties file per system, not per
database."
Suggest:
"There can be only one derby.properties file per system, not one
per database."
- "Database-wide properties, which affect a single database, are
stored within the database itself. This allows different
databases within a single Derby system to have different
properties and ensures that the properties are correctly set
when a database is moved away from its original system or
copied."
suggest:
"... and ensures that the properties are correctly retained
when a database is moved away..."
- "Note: You should use database-wide properties wherever possible
for ease of deployment."
I think this point should be explained more at the outset of the
"working with properties section" to give the user an idea up
front that system properties are practical at development time,
but database properties are preferrable at deployment time. I
think we (used to?) have such an explanation somewhere.. can't
find it right now...
- "If you specify an invalid value, Derby uses the default value for
the property."
So, if a subsequent SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY is
called, does it return the default or the non-valid value set?
The reference manual section doesn't explain this either:
http://db.apache.org/derby/docs/dev/ref/rrefsetdbpropproc.html
- Typo: "Client applications can set database-wide because
* "properties" missing
they are set via SQL statements."
- "Client applications can set dynamic system-wide properties in an
SQL statement, as shown in the example in Using a Properties
object within an application or statement."
This seems to refer to URL attribute setting on the client side,
not dynamic system-wide properties? It also seems to contradict
the earlier statement in this section:
"In a client/server environment, you must set the system
properties for the server's system."
* Case study
- "java -Dderby.system.home=c:\system_directory MyApp"
and others should be marked as Windows-centric.
This example could use an extra blank line, IMHO:
java -Dderby.system.home=c:\system_directory
-Dderby.storage.pageSize=4096 MyApp
CREATE TABLE anothertable (a INT, b VARCHAR(10))
The rest of the changes i reviewed by looking at the diffs and the HTML pages.
- adminguide/cadminlockvti83889.html OK
- getstart/rgsdocs17307.html OK
- ref/crefproper22250.html OK
- ref/crefproper51399.html OK
- ref/rrefproper24390.html OK
- ref/rrefproper32213.html OK
- ref/rrefsqlj31783.html
The reference to Tuning guide here for cursors was removed I see.
I guess you could make it applicable by just rewording it a bit, e.g. as
"For more information about how indexes affect performance, see.."
but it's not essential here, so removing it is fine too.
- tuning/ctunpropref11181.html
"how to tune systems" " also contain tuning tips"
No need for both of the above? Seems confusing..
- tuning/ctunpropref23947.html OK
- devguide/cdevconcepts22300.html OK
Good new link here!
- devguide/cdevcsecure864692.html OK
- devguide/cdevdgpref23947.html
Good catches here; missing stuff!
- devguide/cdevdvlp13018.html OK
- devguide/cdevdvlp39943.html OK
- devguide/cdevdvlp846110.html
"Note: You should work with database-level properties wherever possible."
This statement should explained, I think, perhaps referring to a
general section explaining recommended usage of system level
("flexible at development time") vs. database level properties
("safest for deployment")
> DOCS - Move Derby system and properties info from Tuning Guide into Reference
> Manual
> ------------------------------------------------------------------------------------
>
> Key: DERBY-2389
> URL: https://issues.apache.org/jira/browse/DERBY-2389
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 10.4.2.0
> Reporter: Laura Stewart
> Assignee: Kim Haase
> Attachments: DERBY-2389-adminguide.diff, DERBY-2389-adminguide.stat,
> DERBY-2389-adminguide.zip, DERBY-2389-devguide.diff,
> DERBY-2389-devguide.stat, DERBY-2389-devguide.zip, DERBY-2389-getstart.diff,
> DERBY-2389-getstart.stat, DERBY-2389-getstart.zip, DERBY-2389-phase2.diff,
> DERBY-2389-phase2.stat, DERBY-2389-phase2.zip, DERBY-2389-ref.diff,
> DERBY-2389-ref.stat, DERBY-2389-ref.zip, DERBY-2389-ref2.zip,
> DERBY-2389-tuning.diff, DERBY-2389-tuning.stat, DERBY-2389-tuning.zip,
> derbydev.pdf, tuningderby.pdf
>
>
> From Derby User list:
> On 2/21/07, Anders Morken <[email protected]> wrote:
> > Shooting from the hip here, but one thing that has occured to me a few
> > times as I've browsed the docs to figure something out is that I
> > intuitively expect Derby system and database properties (especially the
> > non-performance-related) to be documented in the reference guide, not
> > the tuning guide. =)
> On 2/21/07, Oystein Grovlen - Sun Norway <[email protected]> wrote:
> > I agree on this. I would have preferred that all "facts" where
> > presented in the Reference Manual, and that the other manuals where more
> > "pedagogical" presentations of the same material. Currently, it is not
> > very intuitive to determine which manual has the information you are
> > looking for.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
