Administering the Java DB Database

The Registry uses the Java DB database. Java DB is a commercial release of the Apache Software Foundation's open source relational database project. The Apache project is called Derby.

By default, the database is located in the directory RegistryDomain-base/3.0/data/registry/soar/. Database backups are placed in the directory RegistryDomain-base/3.0/backup/, with a subdirectory name that contains the date of the backup (for example, 20060419-004759).

By default, the Java DB database runs in embedded mode. This means that it runs in the same JVM as Service Registry, and it can accept a connection from only one client, Service Registry. No remote connections are possible. When Java DB runs in embedded mode, you can back up the database only when it is not running (an offline backup). For instructions, see To Perform an Offline Backup of the Database.

If you need to be able to back up the database while the registry domain is running (an online backup), you must run the Java DB database in Network Server mode. For instructions, see To Switch From Embedded Mode to Network Server Mode and To Perform an Online Backup of the Database.

When it runs in Network Server mode, Java DB can accept multiple client connections in a familiar client/server configuration. For example, both Service Registry and a SQL client could concurrently communicate with Java DB. When Java DB runs in Network Server mode, it uses a database port whose default value is 1527. Clients such as Service Registry use this port to communicate with the database.

When Java DB runs in Network Server mode, Service Registry runs in Network Client mode.

A database that runs in Network Server mode must be password protected so that only authenticated clients can use it. You can also protect the database this way when it runs in embedded mode, but it is not essential to do so.

By default, the properties in the file ServiceRegistry-base/install/install.properties are set so that Java DB runs in embedded mode. Table 1–3 shows these settings.

Table 1–3 Default Property Settings for Java DB

Property Setting	Description
registry.install.clientDatabase=false	Enables embedded mode
registry.install.RequireDatabaseAuthentication=false	Does not require database authentication
registry.install.DatabaseUserID=APP	Sets user ID to APP (not used)
registry.install.DatabasePassword=app123	Sets password to app123 (not used)

For more details on Java DB, consult the Java DB documentation at the Java DB web site.

To Require Database Authentication

By default, database authentication is not required. It is possible to require authentication when the database is running in embedded mode, and it is necessary to require authentication when the database is running in Network Server mode.

1. Change to the Service Registry install directory:

   cd ServiceRegistry-base/install

2. Open your copy of the install.properties file in a text editor.

3. Change the setting of the registry.install.RequireDatabaseAuthentication property from false to true.

4. Edit the setting of the registry.install.DatabaseUserID property.

   For embedded mode, this value can be either APP or empty:

   registry.install.DatabaseUserID=APP

   registry.install.DatabaseUserID=

   For Network Server mode, this value must be APP.

5. Edit the setting of the registry.install.DatabasePassword property.

   The password must contain at least 6 characters. The default value is app123.

6. Save and close the file.

7. Stop and restart the Application Server domain for the Registry. To do so, execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file appserver.domain.bounce

   where props-file is the path name of the copy of install.properties file that you edited in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.

To Perform an Offline Backup of the Database

If the database is running in embedded mode, you must perform an offline backup.

1. Change to the Service Registry install directory:

   cd ServiceRegistry-base/install

2. Execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file appserver.domain.stop

   where props-file is the path name of the copy of install.properties file that you edited in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.

3. Execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file backup.db

4. Restart the domain by executing the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file appserver.domain.start

To Switch From Embedded Mode to Network Server Mode

To switch from embedded mode (the default) to Network Server mode, change the setting of the registry.install.clientDatabase property from false to true, and require database authentication.

After editing the property, recreate the database resources, then stop and restart the Application Server.

1. Change to the Service Registry install directory:

   cd ServiceRegistry-base/install

2. Open your copy of the install.properties file in a text editor.

3. Change the setting of the property registry.install.clientDatabase from false to true.

4. Change the setting of the registry.install.RequireDatabaseAuthentication property from false to true.

5. Edit the setting of the registry.install.DatabaseUserID property, if necessary.

   For Network Server mode, this value must be APP.

6. Edit the setting of the registry.install.DatabasePassword property.

   Any length is valid. The default value is app123.

7. Save and close the file.

8. Recreate the database connection pool and its associated resource. To do so, execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file appserver.jdbcResource.update

   where props-file is the path name of the copy of install.properties file that you edited in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.

9. Stop and restart the Application Server domain for the Registry. To do so, execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file appserver.domain.bounce

10. Start the Java DB database. To do so, execute the following command:

    asadmin start-database --dbhome database-directory

    By default, this command places the database and its log file in the current directory. Use the --dbhome option to specify the location of your database (normally, this is RegistryDomain-base/3.0/data/registry/soar).

Next Steps

If the database is running in Network Server mode, you can perform an online backup of the database.

Later, if you want to return to embedded mode, follow the same steps, with the following exceptions:

• Change the setting of the registry.install.clientDatabase property from true to false.

• If you want to stop requiring database authentication, change the setting of the registry.install.RequireDatabaseAuthentication property from true to false.

• If you want to continue requiring database authentication, change the user ID and password if you wish. The registry.install.DatabaseUserID value must be either APP or empty. The registry.install.DatabasePassword value can be any length.

• Do not execute step 10. You do not need to start the database separately.

To Perform an Online Backup of the Database

1. Change to the Service Registry install directory:

   cd ServiceRegistry-base/install

2. Verify that the property registry.install.clientDatabase in your copy of the install.properties file is set to true.

3. Execute the following command (all on one line):

   Ant-base/ant -f build-install.xml Dinstall.properties=props-file backup.db

   where props-file is the path name of the copy of install.properties file that you edited in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.