|
I found that both bootAll and noAutoBoot seem to work fine, so here are topics for them -- plus an updated map file and "Derby properties" topic.
The new topics are src/tuning/rtunpropernoautoboot.dita src/tuning/rtunproperbootall.dita The modified topic is src/tuning/ctunproper22250.dita I've included a The new topics are basically the same as the Cloudscape ones, except that I left out the following note from each: NOTE: For information on what databases are considered part of the current system when it starts up, see 'cloudscape.service'. We don't describe that property, either: http://www.novell.com/documentation/extendas37/docs/help/java/jdkee/cloudscape/doc/html/coredocs/proper29.htm#1010777 I haven't checked to see if that property is supported, too. Who knows where this could lead??? If someone knows a reason why Derby should not document support for bootAll and noAutoBoot, please speak up. There may be some reason why they haven't been in the docs up to now. Kim> We don't describe that property, either:
Kim> : Kim> cloudscape.service Kim> : Kim> I haven't checked to see if that property is supported, too. Who knows Kim> where this could lead??? Kim> Kim> If someone knows a reason why Derby should not document support for Kim> bootAll and noAutoBoot, please speak up. There may be some reason why Kim> they haven't been in the docs up to now. Yes, that would be good. I checked your changes and they look good to me, but I hestitate to commit them until someone who knows the history better than I do comments on it. In general, I like the documentation to reflect reality, so either we should document this feature, or remove it. Please speak up, if you know anything about this! :) No comments seen yet from old Derbyites ;)
I did some testing which seems to indicate that only databases specified in: derby.service.<dbdir>=serviceDirectory settings are actually ever autobooted (more than one setting works). Another database I had in derby.system.home was *not* autobooted, although that should also be part of the derby system and also be autobooted according the old Cloudscape docs.. Need to dig some more. > The new topics are basically the same as the Cloudscape ones
Just a comment that IBM Cloudscape's 5.1 and previous documentation is copyright IBM. While Derby is based upon IBM's contribution to the ASF, IBM contributed the code & documentation that ended up in ASF's subversion, any other Cloudscape materials are not freely available to be copied into ASF's repositories. As an ASF project we need to be careful over the source of any contribution or change, the contributor must have the rights to contribute the code or documentation, see the Apache ICLA. That's a very good point, Dan. Since the IBM docs are the only source of information on these properties, we really cannot document them without violating that copyright.
This fact, plus the fact that no one has been able to confirm whether or not these properties work as described, leads me to think that we should NOT add documentation for these properties to the Tuning Guide, but instead should remove any mention of them from other manuals (mainly the Developer's Guide). Specifically: 1) Remove the following paragraph from http://db.apache.org/derby/docs/dev/devguide/cdevdvlp27715.html: You can also configure your system to automatically boot all databases in the system when it starts up; see derby.system.bootAll in the Tuning Derby manual. Because of the time needed to boot a database, the number of databases in the system directory affects startup performance if you use that configuration. 2) Change the following paragraph in http://db.apache.org/derby/docs/dev/devguide/cdevcsecure60146.html from Encrypted databases cannot be booted automatically along with all other system databases on system startup (see "derby.system.bootAll" in Tuning Derby). Instead, you boot encrypted databases when you first connect to the database. to You boot encrypted databases when you first connect to the database. 3) Change the following paragraph in http://db.apache.org/derby/docs/dev/devguide/cdevadvjdbc41138.html from Databases in a system are not automatically booted until you connect with them. You can configure your system to retain the former behavior, in which case the steps described in this section will continue to work. See "derby.system.bootAll" in Tuning Derby. to Databases in a system are not automatically booted until you connect with them. 4) Possibly remove the topic http://db.apache.org/derby/docs/dev/tuning/ctunperf16556.html, whose text is below. If there is no way to boot databases at startup, this topic has no purpose. It doesn't actually say *how* to boot databases at startup, though the bootAll and noAutoBoot properties both have index entries. Is there any other way? By default, Derby does not boot databases (and some core Derby classes) in the system at Derby startup but only at connection time. For multi-user systems, you might want to reduce connection time by booting one or all databases at startup instead. For embedded systems, you might want to boot the database in a separate thread (either as part of the startup, or in a connection request). For more information, see Shielding users from Derby class-loading events. Would this make more sense? If so, I'll file a patch to do this. I didn't intend to mean that these properties could not be documented, only that it needs to be done in a legally clean way, as with any other contribution.
> Since the IBM docs are the only source of information on these properties That's not true, the code describes exactly how they work. :-) > the fact that no one has been able to confirm whether or not these properties work as described Hasn't Dag been describing how these properties do work? Hm ... I can read Java code but not with great confidence. I don't have the source code checked out, though I could do so temporarily if need be. Is the javadoc for these properties helpful?
Dag had been helping but was hoping that someone with more knowledge would back him up, I believe. After checking out the source code and hunting for information on how bootAll and noAutoBoot work, I can only conclude that Dan really was joking when he used that smiley face. There's no way I could document these properties based on the source code. If someone else can, that would be helpful.
Any attempt I could make to rewrite the property descriptions in the patch I submitted would still owe enough to the IBM docs to violate their copyright. I see only two options: 1) Someone with knowledge of the properties but no knowledge of the IBM docs produces a writeup that I could base new property descriptions on. 2) We back out the references to the properties (as described in my 11/30 comment) and don't document them at all. Since there appears to be no one who fits the description for option 1, we're left with option 2. > I can only conclude that Dan really was joking
Not really, by definition the code describes exactly what the property does. it may take some effort to understand the code, but it is the code. I guess we can start with these comments from org.apache.derby.iapi.reference.Property.java, maybe that's enough for a start to document this, combined with Dag's findings in the comment above:
"only databases specified in: derby.service.<dbdir>=serviceDirectory settings are actually ever autobooted (more than one setting works). " /** derby.system.bootAll <BR> Automatically boot any services at start up time. When set to true this services will be booted at startup, otherwise services will be booted on demand. */ String BOOT_ALL = "derby.system.bootAll"; /** derby.database.noAutoBoot <BR> Don't automatically boot this service at start up time. When set to true this service will only be booted on demand, otherwise the service will be booted at startup time if possible. */ String NO_AUTO_BOOT = "derby.database.noAutoBoot"; Further, there is the test org.apache.derbyTesting.functionTests.tests.store.BootAllTest.java which describes some of the tests, and thus the behavior... And test org.apache.derbyTesting.functionTests.tests.store.databaseProperties.sql with it's expected output in ...functionTests.master.databaseProperties.out to show some behavior. I haven't looked at derby.service.*; judging from the source, that's not a property in itself, but the starting string for a number of properties used by the Monitors...Frankly, I'd suggest not documenting those, but referring users to the actual source code... Thanks very much, Myrna. That is all I found, too. I guess that's all there is. I suppose if I reduced the topics to that minimal information, we could not be accused of copyright violation.
Terminology issue, though: we don't mention "services" in the docs. Would it be okay to change "services" to "databases" and "on demand" to "on the first connection"? I don't find anything very helpful in BootAllTest.java. Also, databaseProperties.sql and databaseProperties.out appear to show only that the noAutoBoot property can be set without error -- they don't seem to show its behavior. There is also the problem that Dag and I seem to have observed different behavior. I found that setting derby.system.bootAll=true in my derby.properties file caused the databases in that directory to autoboot when I started the Network Server. Dag found that he had to specify derby.service.<dbdir>=serviceDirectory to get the databases to boot. It would be helpful to resolve that apparent contradiction. We don't document any derby.service properties currently and, as you suggest, we don't want to. Is it just an issue of whether the user is actually in the same directory as the databases when starting the Network Server? Did some more research..
I find that if derby.system.home is explicitly set, autoboot will happen for databases located in the directory pointed to by that property (not if in subdirs tho). Additionally, any databases pointed to with one or more settings of derby.service.<dbdir>=serviceDirectory are also booted at engine boot time. In my first experiment I did not have derby.system.home explicitly set, hence my observation. I also checked the code to verify this. derby.database.noAutoBoot is a static database property. So it can be can be set with a call to syscs_util.syscs_set_database_property('derby.database.noAutoBoot', 'true'); If it set to true, that database will not boot, even if that database is otherwise determined to be a candidate for autoboot according to the above rules. So, it can be used to exclude some database(s) from the otherwise general rule of auto-booting all databases found in derby.system.home and via the serviceDirectory method. Thanks, Dag, that's very helpful. I'll add it to the documentation.
In my experience I don't need to set derby.system.home explicitly if the databases to be booted are in the directory from which I start the network server. Does that make sense? > In my experience I don't need to set derby.system.home explicitly if
> the databases to be booted are in the directory from which I start the > network server. Does that make sense? In the normal case (boot the database when required), yes. But with derby.system.bootAll=true, I find that an explicit setting of derby.system.home is required for the databases in the current directory to be auto-booted, i.e. once the Derby engine is booted (not only network server from command line; it applies whenever the engine is booted as far as I can see). Are you seeing autoboot of databases in current directory happen even if derby.system.home is *not* set explicitly? I am not able to reproduce that... As best I can tell, yes, I am seeing an autoboot of the databases in the current directory. The only line in my derby.properties file is
derby.system.bootAll=true Unless there is some mechanism that sets derby.system.home under the covers somewhere, it's not set as far as I know. In a directory that has three databases, I start the Network Server: java -jar $DERBY_HOME/lib/derbyrun.jar server start Security manager installed using the Basic server security policy. Apache Derby Network Server - 10.3.1.4 - (561794) started and ready to accept connections on port 1527 at 2007-12-11 15:33:29.313 GMT Apache Derby Network Server - 10.3.1.4 - (561794) shutdown at 2007-12-11 18:08:09.617 GMT The following shows up in derby.log, indicating that two of the databases autobooted: ---------------------------------------------------------------- 2007-12-11 15:33:28.639 GMT: Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance c013800d-0116-c9d6-d6d5-fffff516f185 on database directory /home/chaase/javadb/DERBYDBS/jdbcDemoDB Database Class Loader started - derby.database.classpath='' ---------------------------------------------------------------- 2007-12-11 15:33:29.163 GMT: Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance a816c00e-0116-c9d6-d6d5-fffff516f185 on database directory /home/chaase/javadb/DERBYDBS/seconddb Database Class Loader started - derby.database.classpath='' Apache Derby Network Server - 10.3.1.4 - (561794) started and ready to accept connections on port 1527 at 2007-12-11 15:33:29.313 GMT For the other database, I previously made that syscs_util.syscs_set_database_property call, so its service.properties file includes the following line: derby.database.noAutoBoot=true So that one doesn't autoboot. I haven't tried using the embedded driver yet. I tried using the embedded driver and got no autobooting even if I set derby.system.home explicitly in the derby.properties file, as far as I could tell.
jdench 50 =>java -jar $DERBY_HOME/lib/derbyrun.jar ij ij version 10.3 ij> show connections; No connections available. ij> exit; jdench 51 => And derby.log is empty. But I would have expected that, since it was my understanding that autobooting only applied to the Network Server. And the really weird thing is that if I then start the Network Server again, *with* derby.system.home set in my derby.properties file, the databases *don't* autoboot! Exactly the opposite behavior from yours! When I remove the derby.system.home setting, they autoboot the same as before. Very strange. Oops, I just read the Tuning Guide topic that says "Any property except derby.system.home can be set by including it in the derby.properties file." (http://db.apache.org/derby/docs/dev/tuning/ctunproper51399.html)
Hm, so do I set it on the java command line? or where? The documentation on the property itself (http://db.apache.org/derby/docs/dev/tuning/rtunproper32066.html) does say that the default value is the current directory. So I shouldn't have to set it explicitly -- but the documentation says I ought to (without saying why -- or how): Default Current directory (the value of the JVM system property user.dir). If you do not explicitly set the derby.system.home property when starting Derby, the default is the directory in which Derby was started. Note: You should always explicitly set the value of derby.system.home. I'll keep looking. I now find that if I set derby.system.home on the command line, autobooting works correctly with the embedded driver:
jdench 61 =>java -Dderby.system.home=. -jar $DERBY_HOME/lib/derbyrun.jar ij ij version 10.3 ij> show connections ; No connections available. ij> exit; jdench 62 =>more derby.log ---------------------------------------------------------------- 2007-12-11 18:57:46.498 GMT: Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance c013800d-0116-ca91-e113-00000000002e on database directory /home/chaase/javadb/DERBYDBS/jdbcDemoDB Database Class Loader started - derby.database.classpath='' ---------------------------------------------------------------- 2007-12-11 18:57:47.030 GMT: Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance a816c00e-0116-ca91-e113-00000000002e on database directory /home/chaase/javadb/DERBYDBS/seconddb Database Class Loader started - derby.database.classpath='' 2007-12-11 18:57:47.243 GMT: Shutting down instance a816c00e-0116-ca91-e113-00000000002e ---------------------------------------------------------------- 2007-12-11 18:57:47.295 GMT: Shutting down instance c013800d-0116-ca91-e113-00000000002e ---------------------------------------------------------------- So now we are observing the same behavior, almost -- you still can't get autobooting to work if you start the Network Server in the same directory as the databases, without specifying derby.system.home? Here is another patch, created with much help from Dag, Dan, and Myrna, and without consulting the IBM docs, so I hope the information is both correct and sufficiently original.
Some of the information (Scope, Dynamic or static) is based on deduction from similar properties, using language consistent with the documentation of those other properties. Please let me know what further fixes are needed. M src/tuning/ctunproper22250.dita M src/tuning/tuningderby.ditamap A src/tuning/rtunpropernoautoboot.dita A src/tuning/rtunproperbootall.dita I found the reason why we observe different behaviors with the network server: Since you run with
the default security manager, you actually get derby.system.home set as a system property as a side effect (see line ca line 586 in NetworkServerControl.java) as part of the set-up of the security manager. I ran without the security manager, so I did not get it set. I do think though, that the old behavior was buggy: I can't see why one should need to set derby.system.home explicitly to get the auto-boot behavior. Unless someone can explain why this should be so, I'll file a bug for that. The new docs look good to me. You specify that derby.system.home needs to be
set (rather than just saying Derby system directory), which is correct, but see above comment. Maybe we should add a rationale for the autoboot property: It is useful if one wants to avoid a delay at first connection time. After a crash, a boot which requires recovery can take quite some time, and it may be good to get that out of the way as soon as Derby is restarted. Thank you, Dag -- for the suggestion and for clearing up the mystery about derby.system.home. I hope you file that bug. The property is supposed to have the current directory as a default, regardless of the security policy setting.
Attaching +1
Thanks for your work on this, Kim! Committed as svn 605046. I did the build and the resulting output looked good.
Merged to 10.3 trunk as svn 605056, closing.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
|
Bug
Closed
Minor
Documentation for derby.system.bootAll is missing
derby.system.bootAll=true
in a directory that had three databases in it, all three of them booted when I started the Network Server:
----------------------------------------------------------------
2007-08-10 19:58:28.395 GMT:
Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance c013800d-0114-515b-3e0b-fffff516f185
on database directory /home/chaase/javadb/DERBYDBS/firstdb
Database Class Loader started - derby.database.classpath=''
----------------------------------------------------------------
2007-08-10 19:58:30.294 GMT:
Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance a816c00e-0114-515b-3e0b-fffff516f185
on database directory /home/chaase/javadb/DERBYDBS/jdbcDemoDB
Database Class Loader started - derby.database.classpath=''
----------------------------------------------------------------
2007-08-10 19:58:30.779 GMT:
Booting Derby version The Apache Software Foundation - Apache Derby - 10.3.1.4 - (561794): instance 601a400f-0114-515b-3e0b-fffff516f185
on database directory /home/chaase/javadb/DERBYDBS/seconddb
Database Class Loader started - derby.database.classpath=''
Apache Derby Network Server - 10.3.1.4 - (561794) started and ready to accept connections on port 1527 at 2007-08-10 19:58:31.644 GMT
So I should add topics for derby.system.bootAll and derby.database.noAutoBoot to the Tuning Guide. I haven't tested that derby.database.noAutoBoot works, though. I will try that to make sure before documenting that property.