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
- 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.
- The data directory tree is empty on a pristine install. No files will be shipped in this directory
tree.
-
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.
-
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).
- 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.
-
The log and tempdata directory trees are empty
on a pristine install. No files will be
shipped in these directory trees.
-
Contents of these directory trees are subject to removal by
uninstall, install and upgrade and are not handled by the backup/restore/reset
tools.
-
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.
- 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.
-
Read-only data files can ship anywhere else in the product
directory tree (outside data, tempdata and log) including the new
proddata directory tree.
-
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.
-
Contents of directory trees outside data, tempdata
and log are replaced during an upgrade install.
-
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.
-
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.
- 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:
- data.dirpath.x (to specify the root of a directory tree
containing persistent data)
- data.filepath.x (to specify a single file)
- data.exclude.dirpath.x (to specify the root of a directory tree
to exclude from persistent data)
- data.exclude.filepath.x (to specify a single file to exclude from
persistent data)
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:
- 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).
- Update code to create all problem determination files only
under the log directory.
- Update code to create all non-problem determination temporary
data files only under tempdata tree.
- 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.