The Persistent Layer of Configuration Utils

The default implementation of Configuration Utils uses the Java Preferences API. It's oficial documentation should be read to know the details if needed. We will focus here only on the need to know basis of where the information is stored to facilitate backup, restore and manage of repository space.

Where is the data stored?

The Java Preferences API has a SO dependent implementation.

In Unix/Linux boxes it uses a file-based repository. In Windows boxes it used the proprietary Windows Registry.

Unix/Linux

As stated in these operation systems the repository will be files on a specific directory. The user running the JVM/Application Server must have full access to this directory in order to function properly.

Let's see the actual directory structure in a Linux box:

root@linux-box:~$ tree /etc/.java/ -a
/etc/.java/
`-- .systemPrefs
    |-- .system.lock
    |-- .systemRootModFile
    `-- TestConfigurations
        |-- annotatedPojo
        |   `-- prefs.xml
        |-- bean
        |   `-- prefs.xml
        |-- prefs.xml
        |-- properties
        |   `-- prefs.xml
        `-- temporaryAnnotatedPojo
            `-- prefs.xml

Now as you can see the data is stored in a directory named "/etc/.java". Notice the "." (dot) notation on all directories so they are considered as hidden for browsing users.

You can notice two main things here:

  1. The structure is composed of hierarchical directories that represent the ConfigID and SectionID saved.
  2. The properties themselves are plain XML files.

This shows us how easy it is to browse the saved repository, even without the Java Preferences API. You can use any tool to search and edit data, there are no proprietary tools or algorithms in place.

The prefs.xml files

Let's take a look into the real deal. The files where our preferences are kept.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map SYSTEM "http://java.sun.com/dtd/preferences.dtd">
<map MAP_XML_VERSION="1.0">
  <entry key="Address" value="Washington DC - President's Street 1"/>
  <entry key="Age" value="300"/>
  <entry key="BirthDate" value="Fri Nov 02 00:00:00 GMT 2007"/>
  <entry key="Name" value="Abraham Lincoln"/>
</map>

Here we have all data in plain text. This is what makes finding a given key or value possible even without the knowledge of it's place in the directory (configID/sectionID) structure, you can use text file searching do identify where a given key is stored. Here we see the data converted to string, like date values for instance.

Note: Extra care should be used if editing these files by hand. If the structure of the file is corrupted the configuration map will be lost. If an invalid value like "3a2" for a number is places this value will be lost (although Configuration Utils will recover from it, but obviously without the value being recovered).

Backup/Restore

As you have surely guessed by now you only have to backup the "/etc/.java" directory to backup the repository. Simple as that.

Restore is simply deleting the directory and restoring the backups files in place.

Other administration concerns
  • The directory must be fully accessible by the users that launch JVMs that wish to access the repository
  • If the data is private, you should remove the default read access on this directory so that users can't browse the data in the files at the Operating System level.

Windows

In windows the repository is composed of a node in the system registry.

All administration information can and should be then gathered directly from Microsoft's documentation and will not be described here.

For reference purposes we list here some of Microsoft's articles containing information on this issue:

Here you should find all you need to know on how to administer the Windows Registry and how to access it.

Where in the registry hierarchy is the data?

While browsing the registry let's see how we can find the data related to our Configurations Repository.

All data is stored inside the node "HKEY_LOCAL_MACHINE/software/JavaSoft/Prefs/".

The hierarchical directory structure that we listed previously on the Linux example will be present bellow this registry node.

There are some details you should be aware.

  • The registry nodes, keys and values in windows registry are not case sensitive. This forces the Java Preferences to implement a workaround. Upper case characters will be escaped. This is lousy for legibility, but is needed to allow case-insensitive behavior. I.e.: "ThisNodeName" will become "/This/Node/Name", "THISNAME" will become "/T/H/I/S/N/A/M/E". Nasty!
  • All keys are saved in plain text. Anyone can view them. Anyone with Registry access that is.
A glimpse of the data

All we need now is to see the data itself.

Take a look at the following screen shot of the registry editor

ScreenShot of the registry with the Java Preferences API nodes

As you can see, the same hierarchy is implemented in the registry, under the "HKEY_LOCAL_MACHINE/software/JavaSoft/Prefs/". All values have the upper case characters escaped, as stated before. You can search in the registry like you normally would do, just keep in mind of the escaped characters or you'll find nothing.