libjava/classpath/java/util/prefs/AbstractPreferences.java

   1 /* AbstractPreferences -- Partial implementation of a Preference node
   2    Copyright (C) 2001, 2003, 2004, 2006  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util.prefs;
  40
  41 import gnu.classpath.toolkit.DefaultDaemonThreadFactory;
  42 import gnu.java.lang.CPStringBuilder;
  43 import gnu.java.util.prefs.NodeWriter;
  44
  45 import java.io.ByteArrayOutputStream;
  46 import java.io.IOException;
  47 import java.io.OutputStream;
  48 import java.util.ArrayList;
  49 import java.util.Collection;
  50 import java.util.HashMap;
  51 import java.util.Iterator;
  52 import java.util.TreeSet;
  53 import java.util.concurrent.Executor;
  54 import java.util.concurrent.Executors;
  55
  56 /**
  57  * Partial implementation of a Preference node.
  58  *
  59  * @since 1.4
  60  * @author Mark Wielaard (mark@klomp.org)
  61  */
  62 public abstract class AbstractPreferences extends Preferences {
  63
  64     // protected fields
  65
  66     /**
  67      * Object used to lock this preference node. Any thread only locks nodes
  68      * downwards when it has the lock on the current node. No method should
  69      * synchronize on the lock of any of its parent nodes while holding the
  70      * lock on the current node.
  71      */
  72     protected final Object lock = new Object();
  73
  74     /**
  75      * Set to true in the contructor if the node did not exist in the backing
  76      * store when this preference node object was created. Should be set in
  77      * the constructor of a subclass. Defaults to false. Used to fire node
  78      * changed events.
  79      */
  80     protected boolean newNode = false;
  81
  82     // private fields
  83
  84     /**
  85      * The parent preferences node or null when this is the root node.
  86      */
  87     private final AbstractPreferences parent;
  88
  89     /**
  90      * The name of this node.
  91      * Only when this is a root node (parent == null) the name is empty.
  92      * It has a maximum of 80 characters and cannot contain any '/' characters.
  93      */
  94     private final String name;
  95
  96     /** True when this node has been remove, false otherwise. */
  97     private boolean removed = false;
  98
  99     /**
 100      * Holds all the child names and nodes of this node that have been
 101      * accessed by earlier <code>getChild()</code> or <code>childSpi()</code>
 102      * invocations and that have not been removed.
 103      */
 104     private HashMap<String, AbstractPreferences> childCache
 105       = new HashMap<String, AbstractPreferences>();
 106
 107     /**
 108      * A list of all the registered NodeChangeListener objects.
 109      */
 110     private ArrayList<NodeChangeListener> nodeListeners;
 111
 112     /**
 113      * A list of all the registered PreferenceChangeListener objects.
 114      */
 115     private ArrayList<PreferenceChangeListener> preferenceListeners;
 116
 117     // constructor
 118
 119     /**
 120      * Creates a new AbstractPreferences node with the given parent and name.
 121      *
 122      * @param parent the parent of this node or null when this is the root node
 123      * @param name the name of this node, can not be null, only 80 characters
 124      *             maximum, must be empty when parent is null and cannot
 125      *             contain any '/' characters
 126      * @exception IllegalArgumentException when name is null, greater then 80
 127      *            characters, not the empty string but parent is null or
 128      *            contains a '/' character
 129      */
 130     protected AbstractPreferences(AbstractPreferences parent, String name) {
 131         if (  (name == null)                            // name should be given
 132            || (name.length() > MAX_NAME_LENGTH)         // 80 characters max
 133            || (parent == null && name.length() != 0)    // root has no name
 134            || (parent != null && name.length() == 0)    // all other nodes do
 135            || (name.indexOf('/') != -1))                // must not contain '/'
 136             throw new IllegalArgumentException("Illegal name argument '"
 137                                                + name
 138                                                + "' (parent is "
 139                                                + (parent == null ? "" : "not ")
 140                                                + "null)");
 141         this.parent = parent;
 142         this.name = name;
 143     }
 144
 145     // identification methods
 146
 147     /**
 148      * Returns the absolute path name of this preference node.
 149      * The absolute path name of a node is the path name of its parent node
 150      * plus a '/' plus its own name. If the node is the root node and has no
 151      * parent then its path name is "" and its absolute path name is "/".
 152      */
 153     public String absolutePath() {
 154         if (parent == null)
 155             return "/";
 156         else
 157             return parent.path() + '/' + name;
 158     }
 159
 160     /**
 161      * Private helper method for absolutePath. Returns the empty string for a
 162      * root node and otherwise the parentPath of its parent plus a '/'.
 163      */
 164     private String path() {
 165         if (parent == null)
 166             return "";
 167         else
 168             return parent.path() + '/' + name;
 169     }
 170
 171     /**
 172      * Returns true if this node comes from the user preferences tree, false
 173      * if it comes from the system preferences tree.
 174      */
 175     public boolean isUserNode() {
 176         AbstractPreferences root = this;
 177         while (root.parent != null)
 178             root = root.parent;
 179         return root == Preferences.userRoot();
 180     }
 181
 182     /**
 183      * Returns the name of this preferences node. The name of the node cannot
 184      * be null, can be mostly 80 characters and cannot contain any '/'
 185      * characters. The root node has as name "".
 186      */
 187     public String name() {
 188         return name;
 189     }
 190
 191     /**
 192      * Returns the String given by
 193      * <code>
 194      * (isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
 195      * </code>
 196      */
 197     public String toString() {
 198         return (isUserNode() ? "User":"System")
 199                + " Preference Node: "
 200                + absolutePath();
 201     }
 202
 203     /**
 204      * Returns all known unremoved children of this node.
 205      *
 206      * @return All known unremoved children of this node
 207      */
 208     protected final AbstractPreferences[] cachedChildren()
 209     {
 210       Collection<AbstractPreferences> vals = childCache.values();
 211       return vals.toArray(new AbstractPreferences[vals.size()]);
 212     }
 213
 214     /**
 215      * Returns all the direct sub nodes of this preferences node.
 216      * Needs access to the backing store to give a meaningfull answer.
 217      * <p>
 218      * This implementation locks this node, checks if the node has not yet
 219      * been removed and throws an <code>IllegalStateException</code> when it
 220      * has been. Then it creates a new <code>TreeSet</code> and adds any
 221      * already cached child nodes names. To get any uncached names it calls
 222      * <code>childrenNamesSpi()</code> and adds the result to the set. Finally
 223      * it calls <code>toArray()</code> on the created set. When the call to
 224      * <code>childrenNamesSpi</code> thows an <code>BackingStoreException</code>
 225      * this method will not catch that exception but propagate the exception
 226      * to the caller.
 227      *
 228      * @exception BackingStoreException when the backing store cannot be
 229      *            reached
 230      * @exception IllegalStateException when this node has been removed
 231      */
 232     public String[] childrenNames() throws BackingStoreException {
 233         synchronized(lock) {
 234             if (isRemoved())
 235                 throw new IllegalStateException("Node removed");
 236
 237             TreeSet<String> childrenNames = new TreeSet<String>();
 238
 239             // First get all cached node names
 240             childrenNames.addAll(childCache.keySet());
 241
 242             // Then add any others
 243             String names[] = childrenNamesSpi();
 244             for (int i = 0; i < names.length; i++) {
 245                 childrenNames.add(names[i]);
 246             }
 247
 248             // And return the array of names
 249             String[] children = new String[childrenNames.size()];
 250             childrenNames.toArray(children);
 251             return children;
 252
 253         }
 254     }
 255
 256     /**
 257      * Returns a sub node of this preferences node if the given path is
 258      * relative (does not start with a '/') or a sub node of the root
 259      * if the path is absolute (does start with a '/').
 260      * <p>
 261      * This method first locks this node and checks if the node has not been
 262      * removed, if it has been removed it throws an exception. Then if the
 263      * path is relative (does not start with a '/') it checks if the path is
 264      * legal (does not end with a '/' and has no consecutive '/' characters).
 265      * Then it recursively gets a name from the path, gets the child node
 266      * from the child-cache of this node or calls the <code>childSpi()</code>
 267      * method to create a new child sub node. This is done recursively on the
 268      * newly created sub node with the rest of the path till the path is empty.
 269      * If the path is absolute (starts with a '/') the lock on this node is
 270      * droped and this method is called on the root of the preferences tree
 271      * with as argument the complete path minus the first '/'.
 272      *
 273      * @exception IllegalStateException if this node has been removed
 274      * @exception IllegalArgumentException if the path contains two or more
 275      * consecutive '/' characters, ends with a '/' charactor and is not the
 276      * string "/" (indicating the root node) or any name on the path is more
 277      * than 80 characters long
 278      */
 279     public Preferences node(String path) {
 280         synchronized(lock) {
 281             if (isRemoved())
 282                 throw new IllegalStateException("Node removed");
 283
 284             // Is it a relative path?
 285             if (!path.startsWith("/")) {
 286
 287                 // Check if it is a valid path
 288                 if (path.indexOf("//") != -1 || path.endsWith("/"))
 289                     throw new IllegalArgumentException(path);
 290
 291                 return getNode(path);
 292             }
 293         }
 294
 295         // path started with a '/' so it is absolute
 296         // we drop the lock and start from the root (omitting the first '/')
 297         Preferences root = isUserNode() ? userRoot() : systemRoot();
 298         return root.node(path.substring(1));
 299
 300     }
 301
 302     /**
 303      * Private helper method for <code>node()</code>. Called with this node
 304      * locked. Returns this node when path is the empty string, if it is not
 305      * empty the next node name is taken from the path (all chars till the
 306      * next '/' or end of path string) and the node is either taken from the
 307      * child-cache of this node or the <code>childSpi()</code> method is called
 308      * on this node with the name as argument. Then this method is called
 309      * recursively on the just constructed child node with the rest of the
 310      * path.
 311      *
 312      * @param path should not end with a '/' character and should not contain
 313      *        consecutive '/' characters
 314      * @exception IllegalArgumentException if path begins with a name that is
 315      *            larger then 80 characters.
 316      */
 317     private Preferences getNode(String path) {
 318         // if mark is dom then goto end
 319
 320         // Empty String "" indicates this node
 321         if (path.length() == 0)
 322             return this;
 323
 324         // Calculate child name and rest of path
 325         String childName;
 326         String childPath;
 327         int nextSlash = path.indexOf('/');
 328         if (nextSlash == -1) {
 329             childName = path;
 330             childPath = "";
 331         } else {
 332             childName = path.substring(0, nextSlash);
 333             childPath = path.substring(nextSlash+1);
 334         }
 335
 336         // Get the child node
 337         AbstractPreferences child;
 338         child = (AbstractPreferences)childCache.get(childName);
 339         if (child == null) {
 340
 341             if (childName.length() > MAX_NAME_LENGTH)
 342                throw new IllegalArgumentException(childName);
 343
 344             // Not in childCache yet so create a new sub node
 345             child = childSpi(childName);
 346             childCache.put(childName, child);
 347             if (child.newNode && nodeListeners != null)
 348               fire(new NodeChangeEvent(this, child), true);
 349         }
 350
 351         // Lock the child and go down
 352         synchronized(child.lock) {
 353             return child.getNode(childPath);
 354         }
 355     }
 356
 357     /**
 358      * Returns true if the node that the path points to exists in memory or
 359      * in the backing store. Otherwise it returns false or an exception is
 360      * thrown. When this node is removed the only valid parameter is the
 361      * empty string (indicating this node), the return value in that case
 362      * will be false.
 363      *
 364      * @exception BackingStoreException when the backing store cannot be
 365      *            reached
 366      * @exception IllegalStateException if this node has been removed
 367      *            and the path is not the empty string (indicating this node)
 368      * @exception IllegalArgumentException if the path contains two or more
 369      * consecutive '/' characters, ends with a '/' charactor and is not the
 370      * string "/" (indicating the root node) or any name on the path is more
 371      * then 80 characters long
 372      */
 373     public boolean nodeExists(String path) throws BackingStoreException {
 374         synchronized(lock) {
 375             if (isRemoved() && path.length() != 0)
 376                 throw new IllegalStateException("Node removed");
 377
 378             // Is it a relative path?
 379             if (!path.startsWith("/")) {
 380
 381                 // Check if it is a valid path
 382                 if (path.indexOf("//") != -1 || path.endsWith("/"))
 383                     throw new IllegalArgumentException(path);
 384
 385                 return existsNode(path);
 386             }
 387         }
 388
 389         // path started with a '/' so it is absolute
 390         // we drop the lock and start from the root (omitting the first '/')
 391         Preferences root = isUserNode() ? userRoot() : systemRoot();
 392         return root.nodeExists(path.substring(1));
 393
 394     }
 395
 396     private boolean existsNode(String path) throws BackingStoreException {
 397
 398         // Empty String "" indicates this node
 399         if (path.length() == 0)
 400             return(!isRemoved());
 401
 402         // Calculate child name and rest of path
 403         String childName;
 404         String childPath;
 405         int nextSlash = path.indexOf('/');
 406         if (nextSlash == -1) {
 407             childName = path;
 408             childPath = "";
 409         } else {
 410             childName = path.substring(0, nextSlash);
 411             childPath = path.substring(nextSlash+1);
 412         }
 413
 414         // Get the child node
 415         AbstractPreferences child;
 416         child = (AbstractPreferences)childCache.get(childName);
 417         if (child == null) {
 418
 419             if (childName.length() > MAX_NAME_LENGTH)
 420                throw new IllegalArgumentException(childName);
 421
 422             // Not in childCache yet so create a new sub node
 423             child = getChild(childName);
 424
 425             if (child == null)
 426                 return false;
 427
 428             childCache.put(childName, child);
 429         }
 430
 431         // Lock the child and go down
 432         synchronized(child.lock) {
 433             return child.existsNode(childPath);
 434         }
 435     }
 436
 437     /**
 438      * Returns the child sub node if it exists in the backing store or null
 439      * if it does not exist. Called (indirectly) by <code>nodeExists()</code>
 440      * when a child node name can not be found in the cache.
 441      * <p>
 442      * Gets the lock on this node, calls <code>childrenNamesSpi()</code> to
 443      * get an array of all (possibly uncached) children and compares the
 444      * given name with the names in the array. If the name is found in the
 445      * array <code>childSpi()</code> is called to get an instance, otherwise
 446      * null is returned.
 447      *
 448      * @exception BackingStoreException when the backing store cannot be
 449      *            reached
 450      */
 451     protected AbstractPreferences getChild(String name)
 452                                     throws BackingStoreException
 453     {
 454         synchronized(lock) {
 455             // Get all the names (not yet in the cache)
 456             String[] names = childrenNamesSpi();
 457             for (int i=0; i < names.length; i++)
 458                 if (name.equals(names[i]))
 459                     return childSpi(name);
 460
 461             // No child with that name found
 462             return null;
 463         }
 464     }
 465
 466     /**
 467      * Returns true if this node has been removed with the
 468      * <code>removeNode()</code> method, false otherwise.
 469      * <p>
 470      * Gets the lock on this node and then returns a boolean field set by
 471      * <code>removeNode</code> methods.
 472      */
 473     protected boolean isRemoved() {
 474         synchronized(lock) {
 475             return removed;
 476         }
 477     }
 478
 479     /**
 480      * Returns the parent preferences node of this node or null if this is
 481      * the root of the preferences tree.
 482      * <p>
 483      * Gets the lock on this node, checks that the node has not been removed
 484      * and returns the parent given to the constructor.
 485      *
 486      * @exception IllegalStateException if this node has been removed
 487      */
 488     public Preferences parent() {
 489         synchronized(lock) {
 490             if (isRemoved())
 491                 throw new IllegalStateException("Node removed");
 492
 493             return parent;
 494         }
 495     }
 496
 497     // export methods
 498
 499     // Inherit javadoc.
 500     public void exportNode(OutputStream os)
 501                                     throws BackingStoreException,
 502                                            IOException
 503     {
 504         NodeWriter nodeWriter = new NodeWriter(this, os);
 505         nodeWriter.writePrefs();
 506     }
 507
 508     // Inherit javadoc.
 509     public void exportSubtree(OutputStream os)
 510                                     throws BackingStoreException,
 511                                            IOException
 512     {
 513         NodeWriter nodeWriter = new NodeWriter(this, os);
 514         nodeWriter.writePrefsTree();
 515     }
 516
 517     // preference entry manipulation methods
 518
 519     /**
 520      * Returns an (possibly empty) array with all the keys of the preference
 521      * entries of this node.
 522      * <p>
 523      * This method locks this node and checks if the node has not been
 524      * removed, if it has been removed it throws an exception, then it returns
 525      * the result of calling <code>keysSpi()</code>.
 526      *
 527      * @exception BackingStoreException when the backing store cannot be
 528      *            reached
 529      * @exception IllegalStateException if this node has been removed
 530      */
 531     public String[] keys() throws BackingStoreException {
 532         synchronized(lock) {
 533             if (isRemoved())
 534                 throw new IllegalStateException("Node removed");
 535
 536             return keysSpi();
 537         }
 538     }
 539
 540
 541     /**
 542      * Returns the value associated with the key in this preferences node. If
 543      * the default value of the key cannot be found in the preferences node
 544      * entries or something goes wrong with the backing store the supplied
 545      * default value is returned.
 546      * <p>
 547      * Checks that key is not null and not larger then 80 characters,
 548      * locks this node, and checks that the node has not been removed.
 549      * Then it calls <code>keySpi()</code> and returns
 550      * the result of that method or the given default value if it returned
 551      * null or throwed an exception.
 552      *
 553      * @exception IllegalArgumentException if key is larger then 80 characters
 554      * @exception IllegalStateException if this node has been removed
 555      * @exception NullPointerException if key is null
 556      */
 557     public String get(String key, String defaultVal) {
 558         if (key.length() > MAX_KEY_LENGTH)
 559             throw new IllegalArgumentException(key);
 560
 561         synchronized(lock) {
 562             if (isRemoved())
 563                 throw new IllegalStateException("Node removed");
 564
 565             String value;
 566             try {
 567                 value = getSpi(key);
 568             } catch (ThreadDeath death) {
 569                 throw death;
 570             } catch (Throwable t) {
 571                 value = null;
 572             }
 573
 574             if (value != null) {
 575                 return value;
 576             } else {
 577                 return defaultVal;
 578             }
 579         }
 580     }
 581
 582     /**
 583      * Convenience method for getting the given entry as a boolean.
 584      * When the string representation of the requested entry is either
 585      * "true" or "false" (ignoring case) then that value is returned,
 586      * otherwise the given default boolean value is returned.
 587      *
 588      * @exception IllegalArgumentException if key is larger then 80 characters
 589      * @exception IllegalStateException if this node has been removed
 590      * @exception NullPointerException if key is null
 591      */
 592     public boolean getBoolean(String key, boolean defaultVal) {
 593         String value = get(key, null);
 594
 595         if ("true".equalsIgnoreCase(value))
 596             return true;
 597
 598         if ("false".equalsIgnoreCase(value))
 599             return false;
 600
 601         return defaultVal;
 602     }
 603
 604     /**
 605      * Convenience method for getting the given entry as a byte array.
 606      * When the string representation of the requested entry is a valid
 607      * Base64 encoded string (without any other characters, such as newlines)
 608      * then the decoded Base64 string is returned as byte array,
 609      * otherwise the given default byte array value is returned.
 610      *
 611      * @exception IllegalArgumentException if key is larger then 80 characters
 612      * @exception IllegalStateException if this node has been removed
 613      * @exception NullPointerException if key is null
 614      */
 615     public byte[] getByteArray(String key, byte[] defaultVal) {
 616         String value = get(key, null);
 617
 618         byte[] b = null;
 619         if (value != null) {
 620             b = decode64(value);
 621         }
 622
 623         if (b != null)
 624             return b;
 625         else
 626             return defaultVal;
 627     }
 628
 629     /**
 630      * Helper method for decoding a Base64 string as an byte array.
 631      * Returns null on encoding error. This method does not allow any other
 632      * characters present in the string then the 65 special base64 chars.
 633      */
 634     private static byte[] decode64(String s) {
 635         ByteArrayOutputStream bs = new ByteArrayOutputStream((s.length()/4)*3);
 636         char[] c = new char[s.length()];
 637         s.getChars(0, s.length(), c, 0);
 638
 639         // Convert from base64 chars
 640         int endchar = -1;
 641         for(int j = 0; j < c.length && endchar == -1; j++) {
 642             if (c[j] >= 'A' && c[j] <= 'Z') {
 643                 c[j] -= 'A';
 644             } else if (c[j] >= 'a' && c[j] <= 'z') {
 645                 c[j] = (char) (c[j] + 26 - 'a');
 646             } else if (c[j] >= '0' && c[j] <= '9') {
 647                 c[j] = (char) (c[j] + 52 - '0');
 648             } else if (c[j] == '+') {
 649                 c[j] = 62;
 650             } else if (c[j] == '/') {
 651                 c[j] = 63;
 652             } else if (c[j] == '=') {
 653                 endchar = j;
 654             } else {
 655                 return null; // encoding exception
 656             }
 657         }
 658
 659         int remaining = endchar == -1 ? c.length : endchar;
 660         int i = 0;
 661         while (remaining > 0) {
 662             // Four input chars (6 bits) are decoded as three bytes as
 663             // 000000 001111 111122 222222
 664
 665             byte b0 = (byte) (c[i] << 2);
 666             if (remaining >= 2) {
 667                 b0 += (c[i+1] & 0x30) >> 4;
 668             }
 669             bs.write(b0);
 670
 671             if (remaining >= 3) {
 672                 byte b1 = (byte) ((c[i+1] & 0x0F) << 4);
 673                 b1 += (byte) ((c[i+2] & 0x3C) >> 2);
 674                 bs.write(b1);
 675             }
 676
 677             if (remaining >= 4) {
 678                 byte b2 = (byte) ((c[i+2] & 0x03) << 6);
 679                 b2 += c[i+3];
 680                 bs.write(b2);
 681             }
 682
 683             i += 4;
 684             remaining -= 4;
 685         }
 686
 687         return bs.toByteArray();
 688     }
 689
 690     /**
 691      * Convenience method for getting the given entry as a double.
 692      * When the string representation of the requested entry can be decoded
 693      * with <code>Double.parseDouble()</code> then that double is returned,
 694      * otherwise the given default double value is returned.
 695      *
 696      * @exception IllegalArgumentException if key is larger then 80 characters
 697      * @exception IllegalStateException if this node has been removed
 698      * @exception NullPointerException if key is null
 699      */
 700     public double getDouble(String key, double defaultVal) {
 701         String value = get(key, null);
 702
 703         if (value != null) {
 704             try {
 705                 return Double.parseDouble(value);
 706             } catch (NumberFormatException nfe) { /* ignore */ }
 707         }
 708
 709         return defaultVal;
 710     }
 711
 712     /**
 713      * Convenience method for getting the given entry as a float.
 714      * When the string representation of the requested entry can be decoded
 715      * with <code>Float.parseFloat()</code> then that float is returned,
 716      * otherwise the given default float value is returned.
 717      *
 718      * @exception IllegalArgumentException if key is larger then 80 characters
 719      * @exception IllegalStateException if this node has been removed
 720      * @exception NullPointerException if key is null
 721      */
 722     public float getFloat(String key, float defaultVal) {
 723         String value = get(key, null);
 724
 725         if (value != null) {
 726             try {
 727                 return Float.parseFloat(value);
 728             } catch (NumberFormatException nfe) { /* ignore */ }
 729         }
 730
 731         return defaultVal;
 732     }
 733
 734     /**
 735      * Convenience method for getting the given entry as an integer.
 736      * When the string representation of the requested entry can be decoded
 737      * with <code>Integer.parseInt()</code> then that integer is returned,
 738      * otherwise the given default integer value is returned.
 739      *
 740      * @exception IllegalArgumentException if key is larger then 80 characters
 741      * @exception IllegalStateException if this node has been removed
 742      * @exception NullPointerException if key is null
 743      */
 744     public int getInt(String key, int defaultVal) {
 745         String value = get(key, null);
 746
 747         if (value != null) {
 748             try {
 749                 return Integer.parseInt(value);
 750             } catch (NumberFormatException nfe) { /* ignore */ }
 751         }
 752
 753         return defaultVal;
 754     }
 755
 756     /**
 757      * Convenience method for getting the given entry as a long.
 758      * When the string representation of the requested entry can be decoded
 759      * with <code>Long.parseLong()</code> then that long is returned,
 760      * otherwise the given default long value is returned.
 761      *
 762      * @exception IllegalArgumentException if key is larger then 80 characters
 763      * @exception IllegalStateException if this node has been removed
 764      * @exception NullPointerException if key is null
 765      */
 766     public long getLong(String key, long defaultVal) {
 767         String value = get(key, null);
 768
 769         if (value != null) {
 770             try {
 771                 return Long.parseLong(value);
 772             } catch (NumberFormatException nfe) { /* ignore */ }
 773         }
 774
 775         return defaultVal;
 776     }
 777
 778     /**
 779      * Sets the value of the given preferences entry for this node.
 780      * Key and value cannot be null, the key cannot exceed 80 characters
 781      * and the value cannot exceed 8192 characters.
 782      * <p>
 783      * The result will be immediately visible in this VM, but may not be
 784      * immediately written to the backing store.
 785      * <p>
 786      * Checks that key and value are valid, locks this node, and checks that
 787      * the node has not been removed. Then it calls <code>putSpi()</code>.
 788      *
 789      * @exception NullPointerException if either key or value are null
 790      * @exception IllegalArgumentException if either key or value are to large
 791      * @exception IllegalStateException when this node has been removed
 792      */
 793     public void put(String key, String value) {
 794         if (key.length() > MAX_KEY_LENGTH
 795             || value.length() > MAX_VALUE_LENGTH)
 796             throw new IllegalArgumentException("key ("
 797                                                + key.length() + ")"
 798                                                + " or value ("
 799                                                + value.length() + ")"
 800                                                + " to large");
 801         synchronized(lock) {
 802             if (isRemoved())
 803                 throw new IllegalStateException("Node removed");
 804
 805             putSpi(key, value);
 806
 807             if (preferenceListeners != null)
 808               fire(new PreferenceChangeEvent(this, key, value));
 809         }
 810
 811     }
 812
 813     /**
 814      * Convenience method for setting the given entry as a boolean.
 815      * The boolean is converted with <code>Boolean.toString(value)</code>
 816      * and then stored in the preference entry as that string.
 817      *
 818      * @exception NullPointerException if key is null
 819      * @exception IllegalArgumentException if the key length is to large
 820      * @exception IllegalStateException when this node has been removed
 821      */
 822     public void putBoolean(String key, boolean value) {
 823         put(key, Boolean.toString(value));
 824     }
 825
 826     /**
 827      * Convenience method for setting the given entry as an array of bytes.
 828      * The byte array is converted to a Base64 encoded string
 829      * and then stored in the preference entry as that string.
 830      * <p>
 831      * Note that a byte array encoded as a Base64 string will be about 1.3
 832      * times larger then the original length of the byte array, which means
 833      * that the byte array may not be larger about 6 KB.
 834      *
 835      * @exception NullPointerException if either key or value are null
 836      * @exception IllegalArgumentException if either key or value are to large
 837      * @exception IllegalStateException when this node has been removed
 838      */
 839     public void putByteArray(String key, byte[] value) {
 840         put(key, encode64(value));
 841     }
 842
 843     /**
 844      * Helper method for encoding an array of bytes as a Base64 String.
 845      */
 846     private static String encode64(byte[] b) {
 847         CPStringBuilder sb = new CPStringBuilder((b.length/3)*4);
 848
 849         int i = 0;
 850         int remaining = b.length;
 851         char c[] = new char[4];
 852         while (remaining > 0) {
 853             // Three input bytes are encoded as four chars (6 bits) as
 854             // 00000011 11112222 22333333
 855
 856             c[0] = (char) ((b[i] & 0xFC) >> 2);
 857             c[1] = (char) ((b[i] & 0x03) << 4);
 858             if (remaining >= 2) {
 859                 c[1] += (char) ((b[i+1] & 0xF0) >> 4);
 860                 c[2] = (char) ((b[i+1] & 0x0F) << 2);
 861                 if (remaining >= 3) {
 862                     c[2] += (char) ((b[i+2] & 0xC0) >> 6);
 863                     c[3] = (char) (b[i+2] & 0x3F);
 864                 } else {
 865                     c[3] = 64;
 866                 }
 867             } else {
 868                 c[2] = 64;
 869                 c[3] = 64;
 870             }
 871
 872             // Convert to base64 chars
 873             for(int j = 0; j < 4; j++) {
 874                 if (c[j] < 26) {
 875                     c[j] += 'A';
 876                 } else if (c[j] < 52) {
 877                     c[j] = (char) (c[j] - 26 + 'a');
 878                 } else if (c[j] < 62) {
 879                     c[j] = (char) (c[j] - 52 + '0');
 880                 } else if (c[j] == 62) {
 881                     c[j] = '+';
 882                 } else if (c[j] == 63) {
 883                     c[j] = '/';
 884                 } else {
 885                     c[j] = '=';
 886                 }
 887             }
 888
 889             sb.append(c);
 890             i += 3;
 891             remaining -= 3;
 892         }
 893
 894         return sb.toString();
 895     }
 896
 897     /**
 898      * Convenience method for setting the given entry as a double.
 899      * The double is converted with <code>Double.toString(double)</code>
 900      * and then stored in the preference entry as that string.
 901      *
 902      * @exception NullPointerException if the key is null
 903      * @exception IllegalArgumentException if the key length is to large
 904      * @exception IllegalStateException when this node has been removed
 905      */
 906     public void putDouble(String key, double value) {
 907         put(key, Double.toString(value));
 908     }
 909
 910     /**
 911      * Convenience method for setting the given entry as a float.
 912      * The float is converted with <code>Float.toString(float)</code>
 913      * and then stored in the preference entry as that string.
 914      *
 915      * @exception NullPointerException if the key is null
 916      * @exception IllegalArgumentException if the key length is to large
 917      * @exception IllegalStateException when this node has been removed
 918      */
 919     public void putFloat(String key, float value) {
 920         put(key, Float.toString(value));
 921     }
 922
 923     /**
 924      * Convenience method for setting the given entry as an integer.
 925      * The integer is converted with <code>Integer.toString(int)</code>
 926      * and then stored in the preference entry as that string.
 927      *
 928      * @exception NullPointerException if the key is null
 929      * @exception IllegalArgumentException if the key length is to large
 930      * @exception IllegalStateException when this node has been removed
 931      */
 932     public void putInt(String key, int value) {
 933         put(key, Integer.toString(value));
 934     }
 935
 936     /**
 937      * Convenience method for setting the given entry as a long.
 938      * The long is converted with <code>Long.toString(long)</code>
 939      * and then stored in the preference entry as that string.
 940      *
 941      * @exception NullPointerException if the key is null
 942      * @exception IllegalArgumentException if the key length is to large
 943      * @exception IllegalStateException when this node has been removed
 944      */
 945     public void putLong(String key, long value) {
 946         put(key, Long.toString(value));
 947     }
 948
 949     /**
 950      * Removes the preferences entry from this preferences node.
 951      * <p>
 952      * The result will be immediately visible in this VM, but may not be
 953      * immediately written to the backing store.
 954      * <p>
 955      * This implementation checks that the key is not larger then 80
 956      * characters, gets the lock of this node, checks that the node has
 957      * not been removed and calls <code>removeSpi</code> with the given key.
 958      *
 959      * @exception NullPointerException if the key is null
 960      * @exception IllegalArgumentException if the key length is to large
 961      * @exception IllegalStateException when this node has been removed
 962      */
 963     public void remove(String key) {
 964         if (key.length() > MAX_KEY_LENGTH)
 965             throw new IllegalArgumentException(key);
 966
 967         synchronized(lock) {
 968             if (isRemoved())
 969                 throw new IllegalStateException("Node removed");
 970
 971             removeSpi(key);
 972
 973             if (preferenceListeners != null)
 974               fire(new PreferenceChangeEvent(this, key, null));
 975         }
 976     }
 977
 978     /**
 979      * Removes all entries from this preferences node. May need access to the
 980      * backing store to get and clear all entries.
 981      * <p>
 982      * The result will be immediately visible in this VM, but may not be
 983      * immediatly written to the backing store.
 984      * <p>
 985      * This implementation locks this node, checks that the node has not been
 986      * removed and calls <code>keys()</code> to get a complete array of keys
 987      * for this node. For every key found <code>removeSpi()</code> is called.
 988      *
 989      * @exception BackingStoreException when the backing store cannot be
 990      *            reached
 991      * @exception IllegalStateException if this node has been removed
 992      */
 993     public void clear() throws BackingStoreException {
 994         synchronized(lock) {
 995             if (isRemoved())
 996                 throw new IllegalStateException("Node Removed");
 997
 998             String[] keys = keys();
 999             for (int i = 0; i < keys.length; i++) {
1000                 removeSpi(keys[i]);
1001             }
1002         }
1003     }
1004
1005     /**
1006      * Writes all preference changes on this and any subnode that have not
1007      * yet been written to the backing store. This has no effect on the
1008      * preference entries in this VM, but it makes sure that all changes
1009      * are visible to other programs (other VMs might need to call the
1010      * <code>sync()</code> method to actually see the changes to the backing
1011      * store.
1012      * <p>
1013      * Locks this node, calls the <code>flushSpi()</code> method, gets all
1014      * the (cached - already existing in this VM) subnodes and then calls
1015      * <code>flushSpi()</code> on every subnode with this node unlocked and
1016      * only that particular subnode locked.
1017      *
1018      * @exception BackingStoreException when the backing store cannot be
1019      *            reached
1020      */
1021     public void flush() throws BackingStoreException {
1022         flushNode(false);
1023     }
1024
1025     /**
1026      * Writes and reads all preference changes to and from this and any
1027      * subnodes. This makes sure that all local changes are written to the
1028      * backing store and that all changes to the backing store are visible
1029      * in this preference node (and all subnodes).
1030      * <p>
1031      * Checks that this node is not removed, locks this node, calls the
1032      * <code>syncSpi()</code> method, gets all the subnodes and then calls
1033      * <code>syncSpi()</code> on every subnode with this node unlocked and
1034      * only that particular subnode locked.
1035      *
1036      * @exception BackingStoreException when the backing store cannot be
1037      *            reached
1038      * @exception IllegalStateException if this node has been removed
1039      */
1040     public void sync() throws BackingStoreException {
1041         flushNode(true);
1042     }
1043
1044
1045     /**
1046      * Private helper method that locks this node and calls either
1047      * <code>flushSpi()</code> if <code>sync</code> is false, or
1048      * <code>flushSpi()</code> if <code>sync</code> is true. Then it gets all
1049      * the currently cached subnodes. For every subnode it calls this method
1050      * recursively with this node no longer locked.
1051      * <p>
1052      * Called by either <code>flush()</code> or <code>sync()</code>
1053      */
1054     private void flushNode(boolean sync) throws BackingStoreException {
1055         String[] keys = null;
1056         synchronized(lock) {
1057             if (sync) {
1058                 syncSpi();
1059             } else {
1060                 flushSpi();
1061             }
1062             keys = (String[]) childCache.keySet().toArray(new String[]{});
1063         }
1064
1065         if (keys != null) {
1066             for (int i = 0; i < keys.length; i++) {
1067                 // Have to lock this node again to access the childCache
1068                 AbstractPreferences subNode;
1069                 synchronized(lock) {
1070                     subNode = (AbstractPreferences) childCache.get(keys[i]);
1071                 }
1072
1073                 // The child could already have been removed from the cache
1074                 if (subNode != null) {
1075                     subNode.flushNode(sync);
1076                 }
1077             }
1078         }
1079     }
1080
1081     /**
1082      * Removes this and all subnodes from the backing store and clears all
1083      * entries. After removal this instance will not be useable (except for
1084      * a few methods that don't throw a <code>InvalidStateException</code>),
1085      * even when a new node with the same path name is created this instance
1086      * will not be usable again.
1087      * <p>
1088      * Checks that this is not a root node. If not it locks the parent node,
1089      * then locks this node and checks that the node has not yet been removed.
1090      * Then it makes sure that all subnodes of this node are in the child cache,
1091      * by calling <code>childSpi()</code> on any children not yet in the cache.
1092      * Then for all children it locks the subnode and removes it. After all
1093      * subnodes have been purged the child cache is cleared, this nodes removed
1094      * flag is set and any listeners are called. Finally this node is removed
1095      * from the child cache of the parent node.
1096      *
1097      * @exception BackingStoreException when the backing store cannot be
1098      *            reached
1099      * @exception IllegalStateException if this node has already been removed
1100      * @exception UnsupportedOperationException if this is a root node
1101      */
1102     public void removeNode() throws BackingStoreException {
1103         // Check if it is a root node
1104         if (parent == null)
1105             throw new UnsupportedOperationException("Cannot remove root node");
1106
1107         synchronized (parent.lock) {
1108             synchronized(this.lock) {
1109                 if (isRemoved())
1110                     throw new IllegalStateException("Node Removed");
1111
1112                 purge();
1113             }
1114             parent.childCache.remove(name);
1115         }
1116     }
1117
1118     /**
1119      * Private helper method used to completely remove this node.
1120      * Called by <code>removeNode</code> with the parent node and this node
1121      * locked.
1122      * <p>
1123      * Makes sure that all subnodes of this node are in the child cache,
1124      * by calling <code>childSpi()</code> on any children not yet in the
1125      * cache. Then for all children it locks the subnode and calls this method
1126      * on that node. After all subnodes have been purged the child cache is
1127      * cleared, this nodes removed flag is set and any listeners are called.
1128      */
1129     private void purge() throws BackingStoreException
1130     {
1131         // Make sure all children have an AbstractPreferences node in cache
1132         String children[] = childrenNamesSpi();
1133         for (int i = 0; i < children.length; i++) {
1134             if (childCache.get(children[i]) == null)
1135                 childCache.put(children[i], childSpi(children[i]));
1136         }
1137
1138         // purge all children
1139         Iterator i = childCache.values().iterator();
1140         while (i.hasNext()) {
1141             AbstractPreferences node = (AbstractPreferences) i.next();
1142             synchronized(node.lock) {
1143                 node.purge();
1144             }
1145         }
1146
1147         // Cache is empty now
1148         childCache.clear();
1149
1150         // remove this node
1151         removeNodeSpi();
1152         removed = true;
1153
1154         if (nodeListeners != null)
1155           fire(new NodeChangeEvent(parent, this), false);
1156     }
1157
1158     // listener methods
1159
1160     /**
1161      * Add a listener which is notified when a sub-node of this node
1162      * is added or removed.
1163      * @param listener the listener to add
1164      */
1165     public void addNodeChangeListener(NodeChangeListener listener)
1166     {
1167       synchronized (lock)
1168         {
1169           if (isRemoved())
1170             throw new IllegalStateException("node has been removed");
1171           if (listener == null)
1172             throw new NullPointerException("listener is null");
1173           if (nodeListeners == null)
1174             nodeListeners = new ArrayList<NodeChangeListener>();
1175           nodeListeners.add(listener);
1176         }
1177     }
1178
1179     /**
1180      * Add a listener which is notified when a value in this node
1181      * is added, changed, or removed.
1182      * @param listener the listener to add
1183      */
1184     public void addPreferenceChangeListener(PreferenceChangeListener listener)
1185     {
1186       synchronized (lock)
1187         {
1188           if (isRemoved())
1189             throw new IllegalStateException("node has been removed");
1190           if (listener == null)
1191             throw new NullPointerException("listener is null");
1192           if (preferenceListeners == null)
1193             preferenceListeners = new ArrayList<PreferenceChangeListener>();
1194           preferenceListeners.add(listener);
1195         }
1196     }
1197
1198     /**
1199      * Remove the indicated node change listener from the list of
1200      * listeners to notify.
1201      * @param listener the listener to remove
1202      */
1203     public void removeNodeChangeListener(NodeChangeListener listener)
1204     {
1205       synchronized (lock)
1206         {
1207           if (isRemoved())
1208             throw new IllegalStateException("node has been removed");
1209           if (listener == null)
1210             throw new NullPointerException("listener is null");
1211           if (nodeListeners != null)
1212             nodeListeners.remove(listener);
1213         }
1214     }
1215
1216     /**
1217      * Remove the indicated preference change listener from the list of
1218      * listeners to notify.
1219      * @param listener the listener to remove
1220      */
1221     public void removePreferenceChangeListener (PreferenceChangeListener listener)
1222     {
1223       synchronized (lock)
1224         {
1225           if (isRemoved())
1226             throw new IllegalStateException("node has been removed");
1227           if (listener == null)
1228             throw new NullPointerException("listener is null");
1229           if (preferenceListeners != null)
1230             preferenceListeners.remove(listener);
1231         }
1232     }
1233
1234     /**
1235      * Send a preference change event to all listeners.  Note that
1236      * the caller is responsible for holding the node's lock, and
1237      * for checking that the list of listeners is not null.
1238      * @param event the event to send
1239      */
1240     private void fire(final PreferenceChangeEvent event)
1241     {
1242       for (final PreferenceChangeListener listener : preferenceListeners)
1243         {
1244           Runnable dispatcher = new Runnable() {
1245             public void run()
1246             {
1247               listener.preferenceChange(event);
1248             }
1249           };
1250
1251           Executor executor =
1252             Executors.newSingleThreadExecutor(new DefaultDaemonThreadFactory());
1253           executor.execute(dispatcher);
1254         }
1255     }
1256
1257     /**
1258      * Send a node change event to all listeners.  Note that
1259      * the caller is responsible for holding the node's lock, and
1260      * for checking that the list of listeners is not null.
1261      * @param event the event to send
1262      */
1263     private void fire(final NodeChangeEvent event, final boolean added)
1264     {
1265       for (final NodeChangeListener listener : nodeListeners)
1266         {
1267           Runnable dispatcher = new Runnable() {
1268             public void run()
1269             {
1270               if (added)
1271                 listener.childAdded(event);
1272               else
1273                 listener.childRemoved(event);
1274             }
1275           };
1276
1277           Executor executor =
1278             Executors.newSingleThreadExecutor(new DefaultDaemonThreadFactory());
1279           executor.execute(dispatcher);
1280         }
1281     }
1282
1283     // abstract spi methods
1284
1285     /**
1286      * Returns the names of the sub nodes of this preference node.
1287      * This method only has to return any not yet cached child names,
1288      * but may return all names if that is easier. It must not return
1289      * null when there are no children, it has to return an empty array
1290      * in that case. Since this method must consult the backing store to
1291      * get all the sub node names it may throw a BackingStoreException.
1292      * <p>
1293      * Called by <code>childrenNames()</code> with this node locked.
1294      */
1295     protected abstract String[] childrenNamesSpi() throws BackingStoreException;
1296
1297     /**
1298      * Returns a child note with the given name.
1299      * This method is called by the <code>node()</code> method (indirectly
1300      * through the <code>getNode()</code> helper method) with this node locked
1301      * if a sub node with this name does not already exist in the child cache.
1302      * If the child node did not aleady exist in the backing store the boolean
1303      * field <code>newNode</code> of the returned node should be set.
1304      * <p>
1305      * Note that this method should even return a non-null child node if the
1306      * backing store is not available since it may not throw a
1307      * <code>BackingStoreException</code>.
1308      */
1309     protected abstract AbstractPreferences childSpi(String name);
1310
1311     /**
1312      * Returns an (possibly empty) array with all the keys of the preference
1313      * entries of this node.
1314      * <p>
1315      * Called by <code>keys()</code> with this node locked if this node has
1316      * not been removed. May throw an exception when the backing store cannot
1317      * be accessed.
1318      *
1319      * @exception BackingStoreException when the backing store cannot be
1320      *            reached
1321      */
1322     protected abstract String[] keysSpi() throws BackingStoreException;
1323
1324     /**
1325      * Returns the value associated with the key in this preferences node or
1326      * null when the key does not exist in this preferences node.
1327      * <p>
1328      * Called by <code>key()</code> with this node locked after checking that
1329      * key is valid, not null and that the node has not been removed.
1330      * <code>key()</code> will catch any exceptions that this method throws.
1331      */
1332     protected abstract String getSpi(String key);
1333
1334     /**
1335      * Sets the value of the given preferences entry for this node.
1336      * The implementation is not required to propagate the change to the
1337      * backing store immediately. It may not throw an exception when it tries
1338      * to write to the backing store and that operation fails, the failure
1339      * should be registered so a later invocation of <code>flush()</code>
1340      * or <code>sync()</code> can signal the failure.
1341      * <p>
1342      * Called by <code>put()</code> with this node locked after checking that
1343      * key and value are valid and non-null.
1344      */
1345     protected abstract void putSpi(String key, String value);
1346
1347     /**
1348      * Removes the given key entry from this preferences node.
1349      * The implementation is not required to propagate the change to the
1350      * backing store immediately.  It may not throw an exception when it tries
1351      * to write to the backing store and that operation fails, the failure
1352      * should be registered so a later invocation of <code>flush()</code>
1353      * or <code>sync()</code> can signal the failure.
1354      * <p>
1355      * Called by <code>remove()</code> with this node locked after checking
1356      * that the key is valid and non-null.
1357      */
1358     protected abstract void removeSpi(String key);
1359
1360     /**
1361      * Writes all entries of this preferences node that have not yet been
1362      * written to the backing store and possibly creates this node in the
1363      * backing store, if it does not yet exist. Should only write changes to
1364      * this node and not write changes to any subnodes.
1365      * Note that the node can be already removed in this VM. To check if
1366      * that is the case the implementation can call <code>isRemoved()</code>.
1367      * <p>
1368      * Called (indirectly) by <code>flush()</code> with this node locked.
1369      */
1370     protected abstract void flushSpi() throws BackingStoreException;
1371
1372     /**
1373      * Writes all entries of this preferences node that have not yet been
1374      * written to the backing store and reads any entries that have changed
1375      * in the backing store but that are not yet visible in this VM.
1376      * Should only sync this node and not change any of the subnodes.
1377      * Note that the node can be already removed in this VM. To check if
1378      * that is the case the implementation can call <code>isRemoved()</code>.
1379      * <p>
1380      * Called (indirectly) by <code>sync()</code> with this node locked.
1381      */
1382     protected abstract void syncSpi() throws BackingStoreException;
1383
1384     /**
1385      * Clears this node from this VM and removes it from the backing store.
1386      * After this method has been called the node is marked as removed.
1387      * <p>
1388      * Called (indirectly) by <code>removeNode()</code> with this node locked
1389      * after all the sub nodes of this node have already been removed.
1390      */
1391     protected abstract void removeNodeSpi() throws BackingStoreException;
1392 }