System-Wide Properties

You can set system-wide properties programmatically (as a command-line option to the JVM when starting the application or within application code) or in the text file derby.properties.

You can set properties programmatically--either in application code before booting the Derby driver or as a command-line option to the JVM when booting the application that starts up Derby. When you set properties programmatically, these properties persist only for the duration of the application. Properties set programmatically are not written to the derby.properties file or made persistent in any other way by Derby.

Note:

Setting properties programmatically works only for the application that starts up Derby; for example, for an application in an embedded environment or for the application server that starts up a server product. It does not work for client applications connecting to a server that is running.

You can set system-wide properties as parameters to the JVM command line when starting up the application or framework in which Derby is embedded.

• IBM Application Developer Kits

  With the IBM^(R) SDK, you set JVM system properties using a -D flag on the Java command line. For example:

  java -Dderby.system.home=C:\home\Derby\ 
      -Dderby.storage.pageSize=8192 JDBCTest
  
  

For other JVMs, see the JVM-specific documentation on setting system properties.

In embedded mode, your application runs in the same JVM as Derby, so you can also set system properties within an application using a Properties object before loading the Derby JDBC driver. The following example sets derby.system.home on Windows.

Properties p = System.getProperties();
p.put("derby.system.home", "C:\databases\tours");

Note:

If you pass in a Properties object as an argument to the DriverManager.getConnection call when connecting to a database, those properties are used as database connection URL attributes, not as properties of the type discussed in this book.

You can set persistent system-wide properties in a text file called derby.properties, which must be placed in the directory specified by the derby.system.home property. There should be one derby.properties file per system, not per database. The file must be created in the system directory. In a client/server environment, that directory is on the server. (For more information about a Derby system and the system directory, see "Derby System" in the Derby Developer's Guide.)

Derby does not:

• provide this file
• automatically create this file for you
• automatically write any properties or values to this file

Instead, you must create, write, and edit this file yourself.

The file should be in the format created by the java.util.Properties.save method.

The following is the text of a sample properties file:

derby.infolog.append=true 
derby.storage.pageSize=8192
derby.storage.pageReservedSpace=60

Properties set this way are persistent for the system until changed, until the file is removed from the system, or until the system is booted in some other directory (in which case Derby would be looking for derby.properties in that new directory). If a database is removed from a system, system-wide properties do not "travel" with the database unless explicitly set again.

You can find out the value of a system property if you set it programmatically. You cannot find out the value of a system property if you set it in the derby.properties file.

For example, if you set the value of the derby.storage.pageSize system-wide property in your program or on the command line, the following code will retrieve its value from the System Properties object:

Properties sprops = System.getProperties(); 
System.out.println("derby.storage.pageSize value: " 
+ sprops.getProperty("derby.storage.pageSize"));