db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dag H. Wanvik (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2389) DOCS - Move Derby system and properties info from Tuning Guide into Reference Manual
Date Fri, 13 Feb 2009 16:50:59 GMT

    [ 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 <andersmo@stud.ntnu.no> 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 <Oystein.Grovlen@sun.com> 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.


Mime
View raw message