001    /* AbstractPreferences -- Partial implementation of a Preference node
002       Copyright (C) 2001, 2003, 2004, 2006  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.util.prefs;
040    
041    import gnu.classpath.toolkit.DefaultDaemonThreadFactory;
042    import gnu.java.lang.CPStringBuilder;
043    import gnu.java.util.prefs.NodeWriter;
044    
045    import java.io.ByteArrayOutputStream;
046    import java.io.IOException;
047    import java.io.OutputStream;
048    import java.util.ArrayList;
049    import java.util.Collection;
050    import java.util.HashMap;
051    import java.util.Iterator;
052    import java.util.TreeSet;
053    import java.util.concurrent.Executor;
054    import java.util.concurrent.Executors;
055    
056    /**
057     * Partial implementation of a Preference node.
058     *
059     * @since 1.4
060     * @author Mark Wielaard (mark@klomp.org)
061     */
062    public abstract class AbstractPreferences extends Preferences {
063    
064        // protected fields
065    
066        /**
067         * Object used to lock this preference node. Any thread only locks nodes
068         * downwards when it has the lock on the current node. No method should
069         * synchronize on the lock of any of its parent nodes while holding the
070         * lock on the current node.
071         */
072        protected final Object lock = new Object();
073    
074        /**
075         * Set to true in the contructor if the node did not exist in the backing
076         * store when this preference node object was created. Should be set in
077         * the constructor of a subclass. Defaults to false. Used to fire node
078         * changed events.
079         */
080        protected boolean newNode = false;
081    
082        // private fields
083    
084        /**
085         * The parent preferences node or null when this is the root node.
086         */
087        private final AbstractPreferences parent;
088    
089        /**
090         * The name of this node.
091         * Only when this is a root node (parent == null) the name is empty.
092         * It has a maximum of 80 characters and cannot contain any '/' characters.
093         */
094        private final String name;
095    
096        /** True when this node has been remove, false otherwise. */
097        private boolean removed = false;
098    
099        /**
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    }