Blog: What I learned, forgot and learned again about Java Preferences

I'm not an expert in Java, but I have been using and teaching it for a really long time. One thing I've always struggled with is the right way to manage settings and preferences, especially stacking different levels of settings (defaults, setup time and run time). The various systems I worked on in grad school were massively over complicated (to the extent where I think in my masters’ system, configuration was probably a third of the whole system).

For the Game Tracker I set out to keep things really simple, and ideally to do things "the right way". Given that I don't actually work in software development with anyone other than myself, figuring out "the right way" can be a bit of a struggle sometimes. Still I'm trying to start modelling my own technology learning after Julia Even's approach and learn and focus on what I have learned.

For handling settings, I've used Java's Properties quite a bit (they made up a big portion of my PhD system, which was *much* more streamlined than my masters). Having an API to handle getting simple values in and out of a file is really useful. Preferences are an extra layer on top of that, where you hand over keeping track of the storage to the JVM.

While I'm still a little grouchy about Preferences not being transparent to the user or the programmer. They do feel like "the right way" to keep track of settings. I was especially confused when I cam back to the Game Tracker after a long break and so had to relearn a lot about Preferences. Hopefully this will be a good overview and collection of the good resources I found.

Overview

As I mentioned, preferences let you hand off worrying about where your information gets stored. All you have to do is tell Java that you would like this class’s preferences and then either read or store a value. When you end your program, Java will store everything and the next time you run your program your preferences will be there.

You can recompile or even completely delete and replace your program and your preferences will still be there. If you’ve ever deleted and then reinstalled a program and been surprised that it remembered everything from before, that’s preferences in action. (And that bit where stuff just gets magically remembered is why I’m sometimes uncomfortable with the idea of preferences, sometimes you just want a program to go away, but we’ll talk about that later.)

When we’re talking about preferences, we’re talking about the small pieces of information you need to make your program run. For example, with the game tracker the list of games is too big to go in preferences, but keeping the file name where I'm keeping the list of games makes sense. There’s not a strict limit, but keeping too much data in your preferences isn’t a great idea. Additionally, everything is handled as a string by Java so you want to avoid storing anything complex, like an object, and should keep in mind that you’ll have to handle moving numeric data back and forth.

Using Java Preferences

You access Java preferences through a java.util.prefs.Preferences object. We’ll talk about how you *get* a Preferences object shortly, but once you have an object you can treat it as a dictionary. You have a put(String key, String value) method where you can store a value under a key and a get(String key) method which gives you the last value you stored under key.

If you have other types of data, you have to handle them separately. The good news is that you don’t have to do any parsing, there are putBoolean(), putDouble(), putInt() methods and getBoolean(), getDouble(), getInt() methods (and actually there’s a pair of methods for every primitive Java type).

You get a Preferences object by asking the Preferences system for it. Similar to the way you ask System for System.out, there are static methods on the Preferences class for getting your Preferences object. Unlike System.out where there’s only one object to get back, there’s actually many possible objects.

Each package in your program gets its own preferences, so when you ask Preferences for your object, you need to give it your class so it knows which package’s preferences to give back. The static method Preferences.systemNodeForPackage(Class theClass), takes a class object and so you can statically give it a class like CLI.class. *

That there are actually two kinds of preferences. System Preferences (which is what you get if you use the method above) and User Preferences. System preferences are shared by every user on a computer, but the user preferences are unique for each user. Generally user preferences are the right place to store things unless you have a strong reason why everyone needs to share. To get the user preferences, you’ll use the static method Preferences.userNodeForPackage().

From there you’re pretty good to go. The first time someone runs your program you can store their preferences and there after you can access and update them as necessary. I’m not sure it’s the “right way” but I think you should also offer your users a chance to see what’s stored in preferences and a way to remove them (the Preference class has methods to do both). I still need to implement this in the Game Tracker, but I think transparency is good to keep in mind.

My GameTracker Example

The last time I worked on the Game Tracker I reorganized a lot of the components. At this point ** I’m really only keeping two preferences for Game Tracker; the name of the persistence manager and the  file name of the file which has the game and play session data.

The persistence manager is managed in the CLI class. As the CLI class is starting it figures out which PersistenceManager it needs and then calls a factory to return an instance of that manager.  For every preference, I keep a constant string in the class to keep the key value, and I’ll often also keep a default value as well.

When the CLI starts, it processes the command line arguments (a story for another day) and checks if the option for the persistence manager has been set. If the value has been set, the CLI saves the value in the preferences. Then the CLI consults the preferences for the name of the persistence manager (with the default). This means that the value that’s loaded is either the new value that was just passed in, the preference that was set before or the default value if it’s never been set.

    private static final String PERSISTENCE_MANAGER_PREF = "gametracker.persistence_manager";
    private static final String PERSISTENCE_MANAGER_DEFAULT = "CSV";

if (cl.hasOption("datamanager")) {
  Preferences.userNodeForPackage(CLI.class).
    put(PERSISTENCE_MANAGER_PREF, cl.getOptionValue("datamanager"));
}

persistenceManager = PersistenceManagerFactory.getManager(
  Preferences.userNodeForPackage(CLI.class).get(
    PERSISTENCE_MANAGER_PREF, PERSISTENCE_MANAGER_DEFAULT), args);

Within the CSVPersistenceManager, the only preference kept is the data file name. Like the name of the persistence manager in the CLI, I keep the name of the preference and the default value as constants, although here the preference name actually sits in the super class FilePersistenceManager.

In FilePersistenceManager:

protected static final String DATA_FILE_PERF = "gametracker.datafile";

In CSVPersistenceManager:

private static final String DATA_FILE_DEFAULT = "gametracker.csv";

Persistence managers are passed the arguments off the command line, so as in the CLI, the super class checks the arguments if there’s a value for the datafile and that is taken and loaded into the preferences.

if (cl.hasOption("datafile")){
  Preferences.userNodeForPackage(
    FilePersistenceManager.class).put(
      DATA_FILE_PERF, cl.getOptionValue("datafile"));
}

The CSVPersistenceManager then checks the preferences to find the filename for the data file.

datafile = new File(
  Preferences.userNodeForPackage(FilePersistenceManager.class).get(
    DATA_FILE_PERF, DATA_FILE_DEFAULT));

The data file can be changed from the setFile method in FilePersistenceManager.

public void setFile(String fileName) {
  Preferences.userNodeForPackage(
    FilePersistenceManagerMenu.class).put(DATA_FILE_PERF, fileName);
      datafile = new File(fileName);
}

I’m not getting a ton of use out of preferences right now. I was doing more before I started streamlining, but right at the moment those are the only two things I need to keep track of. Again, I’m not sure I’m “doing it right,” but this setup seems to work for me. 

The Magic Inside

As I said, the great thing about preferences is that the JVM and the operating system really take care of it for you. So if you’re happy to trust the “magic system” to keep stuff up and running, then you’re good to go. On the other hand if you’re trying to figure out what the hell is going on, then let’s talk about it.

I ended up researching this because when I came back to the GameTracker after a long break, I had no idea what was going on or why the software (which I wrote) knew where the files were without me telling it (also sometimes I’m bad at taking notes - but I did have an issue on the topic for myself). This was especially a problem because I was looking for a local configuration file, which just wasn’t there.

I set out to figure out what was going on. Thankfully a number of people have written pretty good explanations of the preferences system. I decided that I could add a little bit by bringing those articles together and the best way to learn anything is always to teach it (or in this case blog about it).

So with that being said, there are two things to talk about if we want to open up the magic inside.

How are the preferences organized?

At the JVM level, all preferences are kept in trees. There’s the system tree and a tree for each user. (So as a programmer you have access to two trees, the system and the current user). 

Each node in the tree represents a package. The root of the tree is the empty package and it’s named “/”.  Then every package below the root is its own node. If we take my GameTracker as an example, the CLI.java main class is in package ca.kendon.gametracker.cli. That means that the root node has a child node, “ca/”, which has a child node “kendon/”, which has a child node “gametracker/”, which has a child node “cli/”.

A tree diagram of the CLI class's preference.

Since we have multiple packages with preferences (.cli and .core)  both of those packages's preferences would be held under their common parent.  so "gametracker/" would be the parent to both both "cli/" and "core/"

A tree diagram showing the common ancestors for both the "cli/" and "core/" packages.

Notice that the names of the preference node have those slashes at the end. If you ask for the full name of the node the CLI preferences are in it will be "/ca/kendon/gametracker/cli”. If that seems like a file name... well that might be important later (in some contexts).

Where are the preferences stored?

The JVM has its nice abstraction of preferences in trees, but that doesn’t help when your question is “where is that value *actually* stored?” Now we actually have to take a look under the JVM and see what the operating system is up to. Preferences exist in all operating systems, not just for Java but for any software that needs to remember things. Of course, since all operating systems have their own ideas about where stuff is, there’s a different answer for every operating system. For a quick overview we’ll look at Windows, MacOS and Linux.

Victor Kropp has a really good post on the details.

Windows 10

As windows is wont to do with all of its configuration information, things are stored in the registry. 

User preferences are found at HKEY_CURRENT_USER\Software\JavaSoft\Prefs

System preferences are found HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Prefs

Remember that you can look at the registry using the Registry Editor (regedit) utility, which is installed by default in Windows.

MacOS

On MacOS, preferences are stored in the Library. Since we have two types of preferences, system and user, MacOS actually has two types of libraries (system and user) for preferences.

System preferences are found in /Library/Preferences/ in a file called com.apple.java.util.prefs.plist

Each user’s preferences are found in their home directory in ~/Library/Preferences/ in a file *also* called com.apple.java.util.prefs.plist

plists are Apple’s favourite way to store things in a way that slightly frustrates everyone … well it frustrates me certainly. They’re XML files (often compressed) which can be a pain to actually look at. On the command line you can run the command:

defaults read ~/Library/Preferences/com.apple.java.util.prefs.plist

Which will show you the preferences for your own user.  For example mine includes:

        "gametracker/" =         {
            "cli/" =             {
                "gametracker.persistence_manager" = "CSV";
            };
            "core/" =             {

                "data_file" = "data/games.data";
            };
        };

If this seems a little overbuilt it's the weird collision of Apple's plists and xml files which always end up having some weird structures.

Linux

On Linux, preferences for each node are stored in its own file (in case you’d wondered why the Java name for preferences looked so much like a file name).

System Preferences are stored starting in the directory /etc/.java/.systemPrefs/

User preferences are stored in each user’s home directory under ~/.java/.systemPrefs/

Under those directories, the JVM builds a directory structure that matches the preference nodes, with the leaf nodes being files. In my Game Tracker Example, that means that the "gametracker.persistence_manager" = "CSV" preference is stored in the file ~/.java/.systemPrefs/ca/kendon/gametracker/cli. 

This makes a lot of sense to my *nix-centric brain and I think explains a lot about the structure they chose when setting up preferences in *nix environments.

Conclusion

I'm always wary of systems that aren't transparent to the user, but preferences provide a good way to keep track of the details about a program without making a mess or requiring a lot of overhead. I still have a lot to learn, already, I'm wondering about some of the things I'm doing to update the preferences from the program. Hopefully this overview provides a place to get started and answers a few of the questions the preferences seem to draw. 

Footnotes

* I *think* you can use the this identifier to get the class dynamically, but I'm not sure whether or not that's a bad idea. (Thus far I've found I've made mistakes using the literal class - copy and paste errors - so using this may be smarter.)

** This is a snapshot of the GameTracker from early November 2021.