Specification

ZaphodsMap can be implemented on any platform.

ZaphodsMap: a branch for each software package...

ZaphodsMap System

The ZaphodsMap System consists of five components.

an environment variable called ZaphodsMap pointing to the ZaphodsMap root folder
a global settings file named ZMGlobal.xml
Zaphod branches (sub folders off the root)
Software keybox files
Local keybox files

Navigating through these files according to the ZaphodsMap rules leads to a keyed file, which presumably contains software configuration settings. (You may think of other uses besides configuration data.)

The remainder of this page endeavors to explain how this leads to a utopian software configuration system.

Naming

A combination of 3 strings leads to a keyed file.

Branch Name: This is a subfolder off ZaphodsMap root, and should represent the software publisher in some way.; Example: HREFTools\webhub\cv003\
KeyGroup Name: This is within a ZMKeybox.xml file, and could represent the software product.; Example: WebHub
Key Name: This is with a KeyGroup tag and represents the keyed file.; Example: security

Username and Context

Two additional attributes, username and context, are optional when looking for a key. The username is taken to be the logged-in user. Context is explained here.

Variables

Any ZaphodsMap XML file may contain variables, which are scoped to the tag in which they are contained (up to a maximum of the entire file).

This means that a savvy administrator can define a variable once and then use that variable many times in the document. A good example would be a configuration file involving domain names. If the same name were repeated many times, and that domain name was likely to change in the future, the administrator could set up a variable declaring the domain name once.

By default, the { and } symbols are used to delimit variables. These delimiters can be overriden on a file by file basis in case they are not convenient for a particular application.

ZaphodsMap Rules of Precedence

Please read this particular section after you have eyeballed the rest of the specification.

Context

Context can be defined in the single global file named ZMGlobal.xml, or in ZMContext.xml in the branch, or in ZMContext.xml in the local folder of the application. The idea of context works independently of everything. The priority is local, then branch, then global.

Keybox

It current looks for application_name + suffix, then it looks for the branch one. The more difficult one would look for application_Name + suffix, then ZMKeybox.xml in the local app folder, then it would look for the branch one.

Objectives

The whole point of the system is to be able to access a program-specific configuration file (or files), and the location of that file is called a "Zaphod Key". A key is uniquely identified by the combination of ZaphodBranch, KeyGroup and KeyName. [[point to balance power of programmer and computer administrator. --ed]

The key value is the full path and filename of the configuration file.

Key groups, names and values are stored in Keybox files.

Software keyboxes and local keyboxes use an identical XSD file. (That means their structure is identical.

A local keybox is in the same directory as an application, and is used if it exists, in preference to the central software keybox.

A program accesses the full path to a filename by specifying a ZaphodBranch, KeyGroup and KeyName. The TZaphodsMap component also gives access to the configuration file with enhanced XML access methods. The enhancements are the support of simplified XPath syntax and support of "context."

A Sample using a few products to show how the process works

In the following examples, "HREFTools" and "LDI" are software publishing companies. "SlimLogger," "WebHub," and "FirebirdEntMgr" are software products.

The environment variable name "ZaphodsMap", the filenames "ZMGlobal.xml", "ZMKeybox.xml" and "ZMContext.xml", plus the structure (XSD) of each XML file, are fixed. All other pathnames and filenames may be varied by the user.

Environment Variable

ZaphodsMap = d:\AppsData\ZaphodsMap\

On disk structure

Here you can see the folders and files on-disk, for a user who has installed three different software packages that use ZaphodsMap. One of those packages (WebHub), has been installed twice using two different sub-versions.

You should be able to count one (1) ZMKeybox.xml file per software package, plus an overriding local keybox with FirebirdEntMgr.

One File in the root folder

The root folder was defined by the ZaphodsMap environment variable. The one file is always named ZMGlobal.xml. At present, the sole purpose of the global file is to define the context for the computer.

This is what a ZMGlobal.xml file looks like:

Contents of ZaphodsMap\ZMGlobal.xml xsd

A given computer should only have one (1) ZMGlobal.xml file.

Several Branch folder examples

As you may recall, a "branch" refers to a software publisher and/or software product. A branch is a folder on disk, always positioned exactly beneath the ZaphodsMap root folder.

We will look at files used by the three product examples: SlimLogger, WebHub and FirebirdEntMgr.

SlimLogger

The SlimLogger example uses a single ZMKeybox, located in the branch folder. The keybox contains a single KeyGroup and a three Keys.

Contents of ZaphodsMap\HREFTools\SlimLogger\ZMKeybox.xml xsd

The SlimLogger keybox does not use any variables nor any context, but it could.

WebHub

The WebHub example shows a ZMContext file, which overrides the global context.

Contents of ZaphodsMap\HREFTools\WebHub\cv003\ZMContext.xml xsd

Contents of ZaphodsMap\HREFTools\WebHub\cv003\ZMKeybox.xml xsd

FirebirdEntMgr

Contents of ZaphodsMap\LDI\FirebirdEntMgr\ZMKeybox.xml xsd

NB: FirebirdEntMgr\FirebirdEntMgr-ZMKeybox.xml has the same syntax as the branch keybox

Keyed file examples

Contents of WebHubInstallationConfig.xml xsd

Contents of WHMaster.xml xsd

Contents of WHLicense.xml xsd

Contents of WHSystemMessages.xml xsd

This web site content is licensed under a Creative Commons Attribution 2.5 License. The ZaphodsMap web site is published by HREF Tools Corp. If you use ZaphodsMap, please mention ZaphodsMap.com at least once in your software source and at least once in your software documentation. All other trademarks are the property of their respective owners.