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 */ AbstractPreferences(AbstractPreferences parent, String name)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 */ absolutePath()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 */ path()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 */ isUserNode()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 */ name()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 */ toString()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 */ cachedChildren()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 */ childrenNames()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 */ node(String path)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 */ getNode(String path)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 */ nodeExists(String path)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 existsNode(String path)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 */ getChild(String name)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 */ isRemoved()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 */ parent()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. exportNode(OutputStream os)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. exportSubtree(OutputStream os)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 */ keys()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 */ get(String key, String defaultVal)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 */ getBoolean(String key, boolean defaultVal)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 */ getByteArray(String key, byte[] defaultVal)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 */ decode64(String s)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 */ getDouble(String key, double defaultVal)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 */ getFloat(String key, float defaultVal)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 */ getInt(String key, int defaultVal)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 */ getLong(String key, long defaultVal)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 */ put(String key, String value)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 */ putBoolean(String key, boolean value)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 */ putByteArray(String key, byte[] value)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 */ encode64(byte[] b)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 */ putDouble(String key, double value)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 */ putFloat(String key, float value)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 */ putInt(String key, int value)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 */ putLong(String key, long value)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 */ remove(String key)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 */ clear()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 */ flush()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 */ sync()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 */ flushNode(boolean sync)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 */ removeNode()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 */ purge()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 */ addNodeChangeListener(NodeChangeListener listener)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 */ addPreferenceChangeListener(PreferenceChangeListener listener)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 */ removeNodeChangeListener(NodeChangeListener listener)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 */ removePreferenceChangeListener(PreferenceChangeListener listener)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 */ fire(final PreferenceChangeEvent event)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 */ fire(final NodeChangeEvent event, final boolean added)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 */ childrenNamesSpi()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 */ childSpi(String name)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 */ keysSpi()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 */ getSpi(String key)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 */ putSpi(String key, String value)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 */ removeSpi(String key)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 */ flushSpi()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 */ syncSpi()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 */ removeNodeSpi()1391 protected abstract void removeNodeSpi() throws BackingStoreException; 1392 } 1393