Rules for data files for IBM Director Version 4

In this release, IBM Director will move to a common model for handling persistent data files across Windows and Linux platforms. This is necessary to facilitate backup/restore/reset of persistent data files via new tools that will ship with the product, and to facilitate preservation of persistent data files across release upgrades. The rules for the new model are outlined below. It is important that each IBM Director Extension ensure the persistent data fits into the model and is thus treated appropriately during product install, uninstall, version upgrade install, and by the backup, restore and reset tools.

Data file rules

  1. Persistent data files are defined to be files which are to be preserved across upgrades and saved/restored/deleted by the backup/restore/reset tools. All persistent data files must reside under the data directory tree or be identified using the extension interface described below.
    1. The data directory tree is empty on a pristine install. No files will be shipped in this directory tree.
    2. All files outside the data directory tree are subject to removal or replacement by the uninstall, install and upgrade and are not handled by the backup/restore/reset tools.
    3. Components must appropriately handle absence of any files in the data directory tree. One option is to "seed" it at runtime with default data (see proddata below).
  2. Temporary files are defined to be files which are created dynamically at runtime and are NOT to be preserved across upgrades and handled by the backup/restore/reset tools. All temporary files intended for problem determination (e.g., RAS logs, .stdout files, .err files) must reside under the log directory. All temporary files not intended for problem determination must reside under the tempdata directory tree.
    1. The log and tempdata directory trees are empty on a pristine install. No files will be shipped in these directory trees.
    2. Contents of these directory trees are subject to removal by uninstall, install and upgrade and are not handled by the backup/restore/reset tools.
    3. You must not create temporary files outside these directory trees because they will NOT be cleaned up by uninstall, leaving residue on the system which might cause later problems for the customer and problems for our own product install process.
  3. In general, the only directories your code should write to are data, log and tempdata. All files outside these directory trees should generally be considered "read-only". One known exception to this rule is the "auto import" function which will mark an imported file as consumed by renaming the file at first launch time.
  4. Read-only data files can ship anywhere else in the product directory tree (outside data, tempdata and log) including the new proddata directory tree.
    1. Files outside data, tempdata and log that we installed are removed by uninstall. Files outside data, tempdata and log that we did NOT install are not touched by uninstall.
    2. Contents of directory trees outside data, tempdata and log are replaced during an upgrade install.
    3. Components might ship "seed" data files such as default properties files in a read-only directory. If this option is used, the seed file must have the same name as the real data file stored in the data directory, such that a customer or support might copy the seed file to the data file and tweak the contents if so desired. The component might read the seed file when the data file is not present in the data directory then save it back to the data directory.
    4. The proddata/defaults directory has the special quality that at install time any directory tree content here that does not already exist in the data directory tree is copied to the data directory tree. So you can ship properties files containing defaults proddata to have them automatically seeded to the data directory. If the properties file contains properties that are intended for customers, 3rd parties or support to tweak, you should include comments in the files and access via the com.tivoli.twg.libs.CommentedProperties class which preserves comments.
  5. MIGRATION: Any files which were previously defined as persistent data files which resided outside the data directory must be properly moved and migrated intact to the data directory: there can be no customer impact or loss of configuration or state due to moving these files. Any extension or modification of these files (due to new code levels) must properly update these files without loss of existing customer data or settings.

The exceptions and extensions interface

An SDK interface is defined for extensions to handle persistent data that cannot fit into the model described above. If you have a valid reason for keeping persistent data files outside the data directory you must use this interface. A valid reason would be an external interface that requires data files to be stored in a specific directory. The extension interface consists of new property keys on the .TWGExt and .TWGSubagent properties files:

where x is a unique integer. Like pathname values for the existing classpath.append.x and classpath.prepend.x property keys, data pathname values must be relative to the product root directory and both '/' and '\' file separators are acceptable in pathnames.

Actions required to integrate with IBM Director Version 4:

  1. Update code to keep all persistent data files (that are to be preserved across upgrades) in the data tree and handle absence of any files under data tree (e.g., use hard-coded properties or a seed file shipped outside data tree).
  2. Update code to create all problem determination files only under the log directory.
  3. Update code to create all non-problem determination temporary data files only under tempdata tree.
  4. Update code to NOT use hard-coded pathnames for data, tempdata and log directories. Java code (agent, libs) must use TWGEnvironment methods getDataDirectory(), getLogDirectory() and getTempDataDirectory(). Native C++ code must use methods in libs class CmdLine: UserDataPath() and LoggingPath(). UNIX scripts must dot in script .twgdirs (note the leading dot in the name) which sets environment variables for the directories.