{"id":224,"date":"2007-09-20T00:00:00","date_gmt":"2007-09-20T00:00:00","guid":{"rendered":"http:\/\/www.strongd.net\/?p=224"},"modified":"2007-09-20T00:00:00","modified_gmt":"2007-09-20T00:00:00","slug":"Beyond Preferences API Basics","status":"publish","type":"post","link":"https:\/\/www.strongd.net\/?p=224","title":{"rendered":"Beyond Preferences API Basics"},"content":{"rendered":"

The Preferences API was first covered here shortly after it was introduced with the 1.4 version of the standard platform: the July 15, 2003 article, the Preferences API<\/A>. <\/P>
\n

That article described how to get and set user specific preferences. There is more to the Preferences API than just getting and setting user specific settings. There are system preferences, import and export preferences, and event notifications associated with preferences. There is even a way to provide your own custom location for storage of preferences. The first three options mentioned will be described here. Creating a custom preferences factory will be left to a later tip. <\/P>
\n

System Preferences<\/B> <\/P>
\n

The Preferences API provides for two separate sets of preferences. The first set is for the individual user, allows multiple users on the same machine to have different settings defined. These are called user preferences. Each user who shares the same machine can have his or her own unique set of values associated with a group of preferences. Something like this could be like a user password or starting directory. You don’t want every person on the same machine to have the same password and home directory. Well, I would hope you don’t want that. <\/P>
\n

The other form of preferences is the system type. All users of a machine share the same set of system preferences. For instance, the location of an installed printer would typically be a system preference. You wouldn’t necessarily have a different set of printers installed for different users. Everyone running on one machine would know about all printers known by that machine. <\/P>
\n

Another example of a system preference would be the high score of a game. There should only be one overall high score. That’s what a system preference would be used for. In the previous tip you saw how userNodeForPackge()<\/CODE> — and subsequently userRoot()<\/CODE> — was used to acquire the user’s preference node, the following example shows how to get the appropriate part of the system preferences tree with systemNodeForPackage()<\/CODE> — or systemRoot()<\/CODE> for the root. Other than the method call to get the right preference node, the API usage is identical. <\/P>
\n

The example is a simple game, using the game term loosely here. It picks a random number from 0 to 99. If the number is higher than the previously saved number, it updates the “high score.” The example also shows the current high score. The Preferences API usage is rather simple. The example just gets the saved value with getSavedHighScore()<\/CODE> , providing a default of -1 if no high score had been saved yet, and updateHighScore(int value)<\/CODE> to store the new high score. The HIGH_SCORE<\/CODE> key is a constant shared by the new Preferences API accesses. <\/P>
  private static int getSavedHighScore() {<\/CODE>
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);<\/CODE>
    return systemNode.getInt(HIGH_SCORE, -1);<\/CODE>
  }<\/CODE>

  private static void updateHighScore(int value) {<\/CODE>
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);<\/CODE>
    systemNode.putInt(HIGH_SCORE, value);<\/CODE>
 }<\/CODE>

Here’s what the whole program looks like:

import java.util.*;<\/CODE>
import java.util.prefs.*;<\/CODE>
import javax.swing.*;<\/CODE>
import java.awt.*;<\/CODE>
import java.awt.event.*;<\/CODE>

public class High {<\/CODE>
  static JLabel highScore = new JLabel();<\/CODE>
  static JLabel score = new JLabel();<\/CODE>
  static Random random = new Random(new Date().getTime());<\/CODE>
  private static final String HIGH_SCORE = “High.highScore”;<\/CODE>

  public static void main (String args[]) {<\/CODE>
    \/* — Uncomment these lines to clear saved score<\/CODE>
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);<\/CODE>
    systemNode.remove(HIGH_SCORE);<\/CODE>
    *\/<\/CODE>

    EventQueue.invokeLater(<\/CODE>
      new Runnable() {<\/CODE>
        public void run() {<\/CODE>
          JFrame frame = new JFrame(“High Score”);<\/CODE>
          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);<\/CODE>
          updateHighScoreLabel(getSavedHighScore());<\/CODE>
          frame.add(highScore, BorderLayout.NORTH);<\/CODE>
          frame.add(score, BorderLayout.CENTER);<\/CODE>
          JButton button = new JButton(“Play”);<\/CODE>
          ActionListener listener = new ActionListener() {<\/CODE>
            public void actionPerformed(ActionEvent e) {<\/CODE>
              int next = random.nextInt(100);<\/CODE>
              score.setText(Integer.toString(next));<\/CODE>
              int old = getSavedHighScore();<\/CODE>
              if (next > old) {<\/CODE>
                Toolkit.getDefaultToolkit().beep();<\/CODE>
                updateHighScore(next);<\/CODE>
                updateHighScoreLabel(next);<\/CODE>
              }<\/CODE>
            }<\/CODE>
          };<\/CODE>
          button.addActionListener(listener);<\/CODE>
          frame.add(button, BorderLayout.SOUTH);<\/CODE>
          frame.setSize(200, 200);<\/CODE>
          frame.setVisible(true);<\/CODE>
        }<\/CODE>
      }<\/CODE>
    );<\/CODE>
  }<\/CODE>

  private static void updateHighScoreLabel(int value) {<\/CODE>
    if (value == -1) {<\/CODE>
      highScore.setText(“”);<\/CODE>
    } else {<\/CODE>
      highScore.setText(Integer.toString(value));<\/CODE>
    }<\/CODE>
  }<\/CODE>

  private static int getSavedHighScore() {<\/CODE>
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);<\/CODE>
    return systemNode.getInt(HIGH_SCORE, -1);<\/CODE>
  }<\/CODE>

  private static void updateHighScore(int value) {<\/CODE>
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);<\/CODE>
    systemNode.putInt(HIGH_SCORE, value);<\/CODE>
 }<\/CODE>
}<\/CODE>

\n

And, here’s what the screen looks like after a few runs. The 61 score is not apt to be your high score, but it certainly could be. <\/P>
\"\"

\n

You can try running the application as different users to see that they all share the same high score. <\/P>
\n

Import and Export<\/B> <\/P>
\n

In the event that you wish to transfer preferences from one user to another or from one system to another, you can export the preferences from that one user\/system, and then import them to the other side. When preferences are exported, they are exported into an XML formatted document whose DTD is specified by http:\/\/java.sun.com\/dtd\/preferences.dtd<\/CODE> , though you don’t really need to know that. You can export either a whole subtree with the exportSubtree()<\/CODE> method or just a single node with the exportNode()<\/CODE> method. Both methods accept an OutputStream<\/CODE> argument to specify where to store things. The XML document will be UTF-8 character encoded. Importing of the data then happens via the importPreferences()<\/CODE> method, which takes an InputStream<\/CODE> argument. From an API perspective, there is no difference in importing a system node\/tree or a user node. <\/P>
\n

Adding a few lines of code to the previous example will export the newly updated high score to the file high.xml. Much of the added code is responsible for launching a new thread to save the file and for handling exceptions. There are only three lines to export the single node: <\/P>    Thread runner = new Thread(new Runnable() {<\/CODE>
      public void run() {<\/CODE>
        try {<\/CODE>
          FileOutputStream fis = new FileOutputStream(“high.xml”);<\/CODE>
          systemNode.exportNode(fis);<\/CODE>
          fis.close();<\/CODE>
        } catch (Exception e) {<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
        }<\/CODE>
      }<\/CODE>
    });<\/CODE>
    runner.start();<\/CODE>

When exported, the file will look something like the following:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”no”?><\/CODE>
<!DOCTYPE preferences SYSTEM “http:\/\/java.sun.com\/dtd\/preferences.dtd”><\/CODE>
<preferences EXTERNAL_XML_VERSION=”1.0″><\/CODE>
  <root type=”system”><\/CODE>
    <map\/><\/CODE>
    <node name=”<unnamed>”><\/CODE>
      <map><\/CODE>
        <entry key=”High.highScore” value=”95″\/><\/CODE>
      <\/map><\/CODE>
    <\/node><\/CODE>
  <\/root><\/CODE>
<\/preferences><\/CODE>

\n

Notice the root element has a type attribute that says “system<\/CODE> “. This states the type of node it is. The node also has a name attribute valued at “<unnamed><\/CODE> “. Since the High<\/CODE> class was not placed in a package, you get to work in the unnamed system node area. The entry attribute provide the current high score value, 95 in the example here, though your value could differ. <\/P>
\n

While we won’t include any import code in the example here, the way to import is just a static method call on Preferences, passing in the appropriate input stream: <\/P>  FileInputStream fis = new FileInputStream(“high.xml”);<\/CODE>
  Preferences.importPreferences(fis);<\/CODE>
  fis.close();<\/CODE>

\n

Since the XML file includes information about whether the preferences are system or user type, the import call doesn’t have to explicitly include this bit of information. Besides the typical IOExceptions<\/CODE> that can happen, the import call will throw an InvalidPreferencesFormatException<\/CODE> if the file format is invalid. Exporting can also throw a BackingStoreException<\/CODE> if the data to export can’t be read correctly from the backing store. <\/P>
\n

Event Notifications <\/P>
\n

The original version of the High<\/CODE> game updated the high score preference, then explicitly made a call to update the label on the screen. A better way to perform this action would be to add a listener to the preferences node, then a value change can automatically trigger the label to update its value. That way, if the high score is ever updated from multiple places, you won’t need to remember to add code to update the label after saving the updated value. <\/P>
\n

The two lines: <\/P>  updateHighScore(next);<\/CODE>
  updateHighScoreLabel(next);<\/CODE>

can become one with the addition of the right listeners.

  updateHighScore(next);<\/CODE>

\n

There is a PreferenceChangeListener<\/CODE> and its associated PreferenceChangeEvent<\/CODE> for just such a task. The listener will be notified for all changes to the associated node, so you need to check for which key-value pair was modified, as shown here. <\/P>    PreferenceChangeListener changeListener =<\/CODE>
        new PreferenceChangeListener() {<\/CODE>

      public void preferenceChange(PreferenceChangeEvent e) {<\/CODE>
        if (HIGH_SCORE.equals(e.getKey())) {<\/CODE>
          String newValue = e.getNewValue();<\/CODE>
          int value = Integer.valueOf(newValue);<\/CODE>
          updateHighScoreLabel(value);<\/CODE>
        }<\/CODE>
      }<\/CODE>
    };<\/CODE>
    systemNode.addPreferenceChangeListener(changeListener);<\/CODE>

\n

The PreferenceChangeEvent<\/CODE> has three important properties: the key, new new value, and the node itself. The new value doesn’t have all the convenience methods of Preferences though. For example, you can’t retrieve the value as an int. Instead you must manually convert the value yourself. Here’s what the modified High<\/CODE> class looks like: <\/P>import java.awt.*;<\/CODE>
import java.awt.event.*;<\/CODE>
import java.io.*;<\/CODE>
import java.util.*;<\/CODE>
import java.util.prefs.*;<\/CODE>
import javax.swing.*;<\/CODE>

public class High {<\/CODE>
  static JLabel highScore = new JLabel();<\/CODE>
  static JLabel score = new JLabel();<\/CODE>
  static Random random = new Random(new Date().getTime());<\/CODE>
  private static final String HIGH_SCORE = “High.highScore”;<\/CODE>
  static Preferences systemNode =<\/CODE>
  Preferences.systemNodeForPackage(High.class);<\/CODE>

  public static void main (String args[]) {<\/CODE>
    \/* — Uncomment these lines to clear saved score<\/CODE>
    systemNode.remove(HIGH_SCORE);<\/CODE>
    *\/<\/CODE>

    PreferenceChangeListener changeListener =<\/CODE>
        new PreferenceChangeListener() {<\/CODE>

      public void preferenceChange(PreferenceChangeEvent e) {<\/CODE>
        if (HIGH_SCORE.equals(e.getKey())) {<\/CODE>
          String newValue = e.getNewValue();<\/CODE>
          int value = Integer.valueOf(newValue);<\/CODE>
          updateHighScoreLabel(value);<\/CODE>
        }<\/CODE>
      }<\/CODE>
    };<\/CODE>
    systemNode.addPreferenceChangeListener(changeListener);<\/CODE>

    EventQueue.invokeLater(<\/CODE>
      new Runnable() {<\/CODE>
        public void run() {<\/CODE>
          JFrame frame = new JFrame(“High Score”);<\/CODE>
          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);<\/CODE>
          updateHighScoreLabel(getSavedHighScore());<\/CODE>
          frame.add(highScore, BorderLayout.NORTH);<\/CODE>
          frame.add(score, BorderLayout.CENTER);<\/CODE>
          JButton button = new JButton(“Play”);<\/CODE>
          ActionListener listener = new ActionListener() {<\/CODE>
            public void actionPerformed(ActionEvent e) {<\/CODE>
              int next = random.nextInt(100);<\/CODE>
              score.setText(Integer.toString(next));<\/CODE>
              int old = getSavedHighScore();<\/CODE>
              if (next > old) {<\/CODE>
                Toolkit.getDefaultToolkit().beep();<\/CODE>
                updateHighScore(next);<\/CODE>
              }<\/CODE>
            }<\/CODE>
          };<\/CODE>
          button.addActionListener(listener);<\/CODE>
          frame.add(button, BorderLayout.SOUTH);<\/CODE>
          frame.setSize(200, 200);<\/CODE>
          frame.setVisible(true);<\/CODE>
        }<\/CODE>
      }<\/CODE>
    );<\/CODE>
  }<\/CODE>

  private static void updateHighScoreLabel(int value) {<\/CODE>
    if (value == -1) {<\/CODE>
      highScore.setText(“”);<\/CODE>
    } else {<\/CODE>
      highScore.setText(Integer.toString(value));<\/CODE>
    }<\/CODE>
  }<\/CODE>

  private static int getSavedHighScore() {<\/CODE>
    return systemNode.getInt(HIGH_SCORE, -1);<\/CODE>
  }<\/CODE>

  private static void updateHighScore(int value) {<\/CODE>
    systemNode.putInt(HIGH_SCORE, value);<\/CODE>
    \/\/ Save XML in separate thread<\/CODE>
    Thread runner = new Thread(new Runnable() {<\/CODE>
      public void run() {<\/CODE>
        try {<\/CODE>
          FileOutputStream fis = new FileOutputStream(“high.xml”);<\/CODE>
          systemNode.exportNode(fis);<\/CODE>
          fis.close();<\/CODE>
        } catch (Exception e) {<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
          Toolkit.getDefaultToolkit().beep();<\/CODE>
        }<\/CODE>
      }<\/CODE>
    });<\/CODE>
    runner.start();<\/CODE>
  }<\/CODE>
}<\/CODE>

\n

In addition to the PreferenceChangeListener\/Event<\/CODE> class pair, there is a NodeChangeListener<\/CODE> and NodeChangeEvent<\/CODE> combo for notification of preference changes. However, these are for notification nodes additions and removals, not changing values of specific nodes. Of course, if you are writing something like a Preferences viewer, clearly you’d want to know if\/when nodes appear and disappear so these classes may be of interest, too. <\/P>
\n

The whole Preferences API can be quite handy to store data beyond the life of your application without having to rely on a database system. For more information on the API, see the article Sir, What is Your Preference?<\/A><\/P>
\n

<\/DIV><\/p>\n","protected":false},"excerpt":{"rendered":"

The Preferences API was first covered here shortly after it was introduced with the 1.4 version of the standard platform: the July 15, 2003 article, the Preferences API. That article described how to get and set user specific preferences. There is more to the Preferences API than just getting and setting user specific settings. There … Continue reading Beyond Preferences API Basics<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-224","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/www.strongd.net\/index.php?rest_route=\/wp\/v2\/posts\/224","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.strongd.net\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.strongd.net\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.strongd.net\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.strongd.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=224"}],"version-history":[{"count":0,"href":"https:\/\/www.strongd.net\/index.php?rest_route=\/wp\/v2\/posts\/224\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.strongd.net\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=224"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.strongd.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=224"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.strongd.net\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=224"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}