harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769121 [1/2] - /harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/
Date Mon, 27 Apr 2009 19:33:29 GMT
Author: tellison
Date: Mon Apr 27 19:33:29 2009
New Revision: 769121

URL: http://svn.apache.org/viewvc?rev=769121&view=rev
Log:
Apply slightly modified patch for HARMONY-6183 (Javadocs for java.util.prefs.*)
Corrected a comment (see JIRA) and added a missing @code tag.

Modified:
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/BackingStoreException.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesFactoryImpl.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesImpl.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/InvalidPreferencesFormatException.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeEvent.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeListener.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeEvent.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeListener.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/Preferences.java
    harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferencesFactory.java

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java
Mon Apr 27 19:33:29 2009
@@ -34,21 +34,11 @@
 import org.apache.harmony.prefs.internal.nls.Messages;
 
 /**
- * This class is partly implementation of <code>Preferences</code>, which can
be 
- * used to simplify <code>Preferences</code> provider's implementation. 
- * <p>
- * This class define nine abstract SPI methods, which must be implemented by 
- * preference provider. And provider can also override other methods of this 
- * class. Some SPI methods will throw <code>BackingStoreException</code>, 
- * including <code>childrenNamesSpi()</code>, <code>flushSpi()</code>,

- * <code>keysSpi()</code>, <code>removeNodeSpi()</code>, 
- * <code>syncSpi()</code>; <code>getSpi(String, String)</code> never
throws any 
- * exceptions; the last SPI methods, <code>putSpi(String)</code>, 
- * <code>removeSpi(String)</code> and <code>childSpi(String)</code>
won't throw 
- * <code>BackingStoreException</code>, but in some implementations, they may

- * throw <code>SecurityException</code> due to lacking the permission to access

- * backing end storage.</p>
- * 
+ * This abstract class is a partial implementation of the abstract class
+ * Preferences, which can be used to simplify {@code Preferences} provider's
+ * implementation. This class defines nine abstract SPI methods, which must be
+ * implemented by a preference provider.
+ *
  * @since 1.4
  * @see Preferences
  */
@@ -105,14 +95,17 @@
      */
     /** Marker class for 'lock' field. */
     private static class Lock {}
-    /** The object used to lock this node. */
+
+    /**
+     * The object used to lock this node.
+     */
     protected final Object lock;
     
     /**
-     * This field is true if this node is created while it doesn't exist in the 
-     * backing store. This field's default value is false, and it is checked when 
-     * the node creation is completed, and if it is true, the node change event 
-     * will be fired for this node's parent.
+     * This field is true if this node is created while it doesn't exist in the
+     * backing store. This field's default value is false, and it is checked
+     * when the node creation is completed, and if it is true, the node change
+     * event will be fired for this node's parent.
      */
     protected boolean newNode;
 
@@ -141,17 +134,18 @@
      * -----------------------------------------------------------
      */
     /**
-     * Construct a new <code>AbstractPreferences</code> instance using given

-     * parent node and node name. 
+     * Constructs a new {@code AbstractPreferences} instance using the given
+     * parent node and node name.
      *
      * @param parent
-     * 				the parent node of this node, can be null, which means this 
-     * 				node is root
+     *            the parent node of the new node or {@code null} to indicate
+     *            that the new node is a root node.
      * @param name
-     * 				the name of this node, can be empty(""), which means this 
-     * 				node is root
+     *            the name of the new node or an empty string to indicate that
+     *            this node is called "root".
      * @throws IllegalArgumentException
-     * 				if name contains slash, or be empty if parent is not null
+     *             if the name contains a slash character or is empty if {@code
+     *             parent} is not {@code null}.
      */
     protected AbstractPreferences(AbstractPreferences parent, String name) {
         if ((null == parent ^ name.length() == 0) || name.indexOf("/") >= 0) { //$NON-NLS-1$
@@ -174,24 +168,28 @@
      * -----------------------------------------------------------
      */
     /**
-     * Return arrays of all cached children node.
+     * Returns an array of all cached child nodes.
      * 
-     * @return arrays of all cached children node.
+     * @return the array of cached child nodes.
      */
     protected final AbstractPreferences[] cachedChildren() {
         return cachedNode.values().toArray(new AbstractPreferences[cachedNode.size()]);
     }
 
     /**
-     * Return the child node with given name, or null if it doesn't exist. The 
-     * given name must be valid and this node cannot be removed. Invocation of 
-     * this method implies that the node with given name is not cached(or, has 
-     * been removed.)
+     * Returns the child node with the specified name or {@code null} if it
+     * doesn't exist. Implementers can assume that the name supplied to this
+     * method will be a valid node name string (conforming to the node naming
+     * format) and will not correspond to a node that has been cached or
+     * removed.
      * 
-     * @param name	the given child name to be got 
-     * @return		the child node with given name, or null if it doesn't exist 
+     * @param name
+     *            the name of the desired child node.
+     * @return the child node with the given name or {@code null} if it doesn't
+     *         exist.
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected AbstractPreferences getChild(String name)
             throws BackingStoreException {
@@ -211,11 +209,11 @@
     }
 
     /**
-     * Return true if and only if this node has been removed by invoking 
-     * {@link #removeNode() removeNode}. 
+     * Returns whether this node has been removed by invoking the method {@code
+     * removeNode()}.
      *
-     * @return true if and only if this node has been removed by invoking 
-     * 			{@link #removeNode() removeNode}
+     * @return {@code true}, if this node has been removed, {@code false}
+     *         otherwise.
      */
     protected boolean isRemoved() {
         synchronized (lock) {
@@ -224,104 +222,118 @@
     }
 
     /**
-     * Flush changes of this node to the backing store. This method should only 
-     * flush this node, and should not include the descendant nodes. The 
-     * implementation which want to flush all nodes at once should override 
-     * {@link #flush() flush()} method. 
+     * Flushes changes of this node to the backing store. This method should
+     * only flush this node and should not include the descendant nodes. Any
+     * implementation that wants to provide functionality to flush all nodes
+     * at once should override the method {@link #flush() flush()}.
      *
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected abstract void flushSpi() throws BackingStoreException;
     
     /**
-     * Return names of this node's all children , or empty array if this node has 
-     * no child. Cached children name is not required to be returned.
+     * Returns the names of all of the child nodes of this node or an empty
+     * array if this node has no children. The names of cached children are not
+     * required to be returned.
      *
-     * @return names of this node's all children
+     * @return the names of this node's children.
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected abstract String[] childrenNamesSpi() throws BackingStoreException;
 
     /**
-     * Return the child preference node with the given name, and create new one if 
-     * it does not exist. Invoker of this method should assure that the given name 
-     * are valid as well as this node is not removed. Invocation of this method 
-     * implies that the node with given name is not cached(or, has been removed.)
-     * If the named node has just been removed, implementation of this method must 
-     * create a new one instead of reactivated the removed one. 
+     * Returns the child preference node with the given name, creating it
+     * if it does not exist. The caller of this method should ensure that the
+     * given name is valid and that this node has not been removed or cached.
+     * If the named node has just been removed, the implementation
+     * of this method must create a new one instead of reactivating the removed
+     * one.
      * <p>
-     * The new creation is not required to be persisted immediately until the flush 
-     * method is invoked.</p>
+     * The new creation is not required to be persisted immediately until the
+     * flush method will be invoked.
+     * </p>
      * 
      * @param name
-     * @return AbstractPreferences
+     *            the name of the child preference to be returned.
+     * @return the child preference node.
      */
     protected abstract AbstractPreferences childSpi(String name);
 
 
     /**
-     * Put the given key-value pair into this node. Invoker of this method should
-     * assure that both the given values are valid as well as this node 
-     * is not removed.
+     * Puts the given key-value pair into this node. Caller of this method
+     * should ensure that both of the given values are valid and that this
+     * node has not been removed.
      *
-     * @param name	the given preference key
-     * @param value the given preference value
+     * @param name
+     *            the given preference key.
+     * @param value
+     *            the given preference value.
      */
     protected abstract void putSpi(String name, String value);
 
     /**
-     * Get the preference value mapped to the given key. Invoker of this method 
-     * should assure that given key are valid as well as this node is not removed. 
-     * This method should not throw exceptions, but if it does, the invoker should 
-     * catch it and deal with it as null return value.
+     * Gets the preference value mapped to the given key. The caller of this
+     * method should ensure that the given key is valid and that this node has
+     * not been removed. This method should not throw any exceptions but if it
+     * does, the caller will ignore the exception, regarding it as a {@code
+     * null} return value.
      *
-     * @param key	the given key to be searched for
-     * @return the preference value mapped to the given key
+     * @param key
+     *            the given key to be searched for.
+     * @return the preference value mapped to the given key.
      */
     protected abstract String getSpi(String key);
 
 
     /**
-     * Return all keys of this node's preferences, or empty array if no preference 
-     * found on this node. Invoker of this method should assure that this node is 
-     * not removed.
+     * Returns an array of all preference keys of this node or an empty array if
+     * no preferences have been found. The caller of this method should ensure
+     * that this node has not been removed.
      *
-     * @return all keys of this node's preferences
+     * @return the array of all preference keys.
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected abstract String[] keysSpi() throws BackingStoreException;
 
     /**
-     * Remove this node from the preference hierarchy tree. The invoker of this 
-     * method should assure that this node has no child node, which means the 
-     * {@link Preferences#removeNode() Preferences.removeNode()} should invoke 
-     * this method multi-times in bottom-up pattern. The removal is not required 
-     * to be persisted at once until the it is flushed.  
+     * Removes this node from the preference hierarchy tree. The caller of this
+     * method should ensure that this node has no child nodes, which means the
+     * method {@link Preferences#removeNode() Preferences.removeNode()} should
+     * invoke this method multiple-times in bottom-up pattern. The removal is
+     * not required to be persisted until after it is flushed.
      *
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected abstract void removeNodeSpi() throws BackingStoreException;
 
     /**
-     * Remove the preference with the given key. Invoker of this method 
-     * should assure that given key are valid as well as this node is not removed. 
+     * Removes the preference with the specified key. The caller of this method
+     * should ensure that the given key is valid and that this node has not been
+     * removed.
      * 
-     * @param key	the given key to removed
+     * @param key
+     *            the key of the preference that is to be removed.
      */
     protected abstract void removeSpi(String key);
 
     /**
-     * Synchronize this node with the backing store. This method should only 
-     * synchronize this node, and should not include the descendant nodes. The 
-     * implementation which want to synchronize all nodes at once should override 
-     * {@link #sync() sync()} method. 
+     * Synchronizes this node with the backing store. This method should only
+     * synchronize this node and should not include the descendant nodes. An
+     * implementation that wants to provide functionality to synchronize all
+     * nodes at once should override the method {@link #sync() sync()}.
      * 
      * @throws BackingStoreException
-     * 				if backing store is unavailable or causes operation failure
+     *             if the backing store is unavailable or causes an operation
+     *             failure.
      */
     protected abstract void syncSpi() throws BackingStoreException;
 

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/BackingStoreException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/BackingStoreException.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/BackingStoreException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/BackingStoreException.java
Mon Apr 27 19:33:29 2009
@@ -18,8 +18,8 @@
 package java.util.prefs;
 
 /**
- * An exception to indicate that some error was encountered while accessing
- * the backing store.
+ * An exception to indicate that an error was encountered while accessing the
+ * backing store.
  *
  * @since 1.4
  */
@@ -28,20 +28,22 @@
     private static final long serialVersionUID = 859796500401108469L;
 
     /**
-     * Constructs a new <code>BackingStoreException</code> instance using an

+     * Constructs a new {@code BackingStoreException} instance with a detailed
      * exception message.
      * 
-     * @param s the exception message.
+     * @param s
+     *            the detailed exception message.
      */
     public BackingStoreException (String s) {
         super(s);
     }
 
     /**
-     * Constructs a new <code>BackingStoreException</code> instance using a
-     * nested <code>Throwable</code> instance.
-     *	
-     * @param t the nested <code>Throwable</code> instance.
+     * Constructs a new {@code BackingStoreException} instance with a nested
+     * {@code Throwable}.
+     *
+     * @param t
+     *            the nested {@code Throwable}.
      */
     public BackingStoreException (Throwable t) {
         super(t);

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesFactoryImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesFactoryImpl.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesFactoryImpl.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesFactoryImpl.java
Mon Apr 27 19:33:29 2009
@@ -17,8 +17,8 @@
 package java.util.prefs;
 
 /**
- * Default implementation of <code>PreferencesFactory</code> for Linux 
- * platform, using file system as back end.
+ * The default implementation of <code>PreferencesFactory</code> for the Linux
+ * platform, using the file system as its back end.
  * 
  * @since 1.4
  */

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesImpl.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesImpl.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/FilePreferencesImpl.java
Mon Apr 27 19:33:29 2009
@@ -28,8 +28,8 @@
 import org.apache.harmony.prefs.internal.nls.Messages;
 
 /**
- * Default implementation of <code>AbstractPreferences</code> for Linux platform,
- * using file system as back end.
+ * The default implementation of <code>AbstractPreferences</code> for the Linux
+ * platform, using the file system as its back end.
  * 
  * TODO some sync mechanism with backend, Performance - check file edit date
  * 

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/InvalidPreferencesFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/InvalidPreferencesFormatException.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/InvalidPreferencesFormatException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/InvalidPreferencesFormatException.java
Mon Apr 27 19:33:29 2009
@@ -18,44 +18,44 @@
 package java.util.prefs;
 
 /**
- * An exception to indicate that the input XML file is not well-formed or 
- * validating to the appropriate document type, which is specified by 
- * <code>Preferences</code>. 
- * 
- * @see Preferences
- *
- * @since 1.4
+ * An exception to indicate that the input XML file is not well-formed or could
+ * not be validated against the appropriate document type (specified by
+ * in the {@code Preferences}).
  */
 public class InvalidPreferencesFormatException extends Exception {
 
     private static final long serialVersionUID = -791715184232119669L;
 
     /**
-     * Constructs a new <code>InvalidPreferencesFormatException</code> instance
using an 
-     * exception message.
+     * Constructs a new {@code InvalidPreferencesFormatException} instance with
+     * a detailed exception message.
      * 
-     * @param s the exception message.
+     * @param s
+     *            the detailed exception message.
      */
     public InvalidPreferencesFormatException (String s) {
         super(s);
     }
 
     /**
-     * Constructs a new <code>InvalidPreferencesFormatException</code> instance
using a 
-     * exception message and a nested <code>Throwable</code> instance.
+     * Constructs a new {@code InvalidPreferencesFormatException} instance with
+     * a detailed exception message and a nested {@code Throwable}.
      * 
-     * @param s the exception message.
-     * @param t the nested <code>Throwable</code> instance.
+     * @param s
+     *            the detailed exception message.
+     * @param t
+     *            the nested {@code Throwable}.
      */
     public InvalidPreferencesFormatException (String s, Throwable t) {
         super(s,t);
     }
 
     /**
-     * Constructs a new <code>InvalidPreferencesFormatException</code> instance
using a
-     * nested <code>Throwable</code> instance.
-     *	
-     * @param t the nested <code>Throwable</code> instance.
+     * Constructs a new {@code InvalidPreferencesFormatException} instance with
+     * a nested {@code Throwable}.
+     *
+     * @param t
+     *            the nested {@code Throwable}.
      */
     public InvalidPreferencesFormatException (Throwable t) {
         super(t);

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeEvent.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeEvent.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeEvent.java
Mon Apr 27 19:33:29 2009
@@ -24,11 +24,12 @@
 import java.io.IOException;
 
 /**
- * This is the event class to indicate one child of the preferences node has 
+ * This is the event class to indicate that one child of the preference node has
  * been added or deleted.
  * <p>
- * Please note that this class cannot be serialized actually, so relevant 
- * serialization methods only throw <code>NotSerializableException</code>.</p>
+ * Please note that the serialization functionality has not yet been
+ * implemented, so the serialization methods do nothing but throw a {@code
+ * NotSerializableException}.
  * 
  * @see java.util.prefs.Preferences
  * @see java.util.prefs.NodeChangeListener
@@ -43,11 +44,13 @@
     private final Preferences child;
 
     /**
-     * Construct a new <code>NodeChangeEvent</code> instance.
+     * Constructs a new {@code NodeChangeEvent} instance.
      * 
-     * @param p the <code>Preferences</code> instance that this event happened,
this object is
-     *            considered as event's source.
-     * @param c the child <code>Preferences</code> instance that was added or
deleted.
+     * @param p
+     *            the {@code Preferences} instance that fired this event; this object is
+     *            considered as the event source.
+     * @param c
+     *            the child {@code Preferences} instance that was added or deleted.
      */
     public NodeChangeEvent (Preferences p, Preferences c) {
         super(p);
@@ -56,34 +59,34 @@
     }
 
     /**
-     * Get the <code>Preferences</code> instance that this event happened.
+     * Gets the {@code Preferences} instance that fired this event.
      * 
-     * @return the <code>Preferences</code> instance that this event happened.
+     * @return the {@code Preferences} instance that fired this event.
      */
     public Preferences getParent() {
         return parent;
     }
 
     /**
-     * Get the child <code>Preferences</code> node that was added or removed.
+     * Gets the child {@code Preferences} node that was added or removed.
      * 
-     * @return the child <code>Preferences</code> node that was added or removed.
+     * @return the added or removed child {@code Preferences} node.
      */
     public Preferences getChild() {
         return child;
     }
 
     /**
-     * This method always throws a <code>NotSerializableException</code>, because

-     * this object cannot be serialized,  
+     * This method always throws a <code>NotSerializableException</code>,
+     * because this object cannot be serialized,
      */
     private void writeObject (ObjectOutputStream out) throws IOException {
         throw new NotSerializableException();
     }
 
     /**
-     * This method always throws a <code>NotSerializableException</code>, because

-     * this object cannot be serialized,  
+     * This method always throws a <code>NotSerializableException</code>,
+     * because this object cannot be serialized,
      */
     private void readObject (ObjectInputStream in) throws IOException, ClassNotFoundException
{
         throw new NotSerializableException();

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeListener.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeListener.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/NodeChangeListener.java
Mon Apr 27 19:33:29 2009
@@ -20,8 +20,9 @@
 import java.util.prefs.NodeChangeEvent;
 
 /**
- * This interface is used to handle preferences node change event. Implementation 
- * of this interface can be installed by <code>Preferences</code> instance.
+ * This interface is used to handle preference node change events. The
+ * implementation of this interface can be installed by the {@code Preferences}
+ * instance.
  * 
  * @see Preferences
  * @see NodeChangeEvent
@@ -30,16 +31,19 @@
  */
 public interface NodeChangeListener extends EventListener {
     /**
-     * This method gets called whenever a child is added to a node.
+     * This method gets called whenever a child node is added to another node.
      * 
-     * @param e Node change event.
+     * @param e
+     *            the node change event.
      */
     public void childAdded (NodeChangeEvent e);
 
     /**
-     * This method gets called whenever a child is removed from a node.
+     * This method gets called whenever a child node is removed from another
+     * node.
      * 
-     * @param e Node change event.
+     * @param e
+     *            the node change event.
      */
     public void childRemoved (NodeChangeEvent e);
 }

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeEvent.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeEvent.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeEvent.java
Mon Apr 27 19:33:29 2009
@@ -24,12 +24,12 @@
 import java.util.EventObject;
 
 /**
- * This is the event class to indicate some preferences has been added, 
- * deleted or updated.
+ * This is the event class to indicate that a preference has been added, deleted
+ * or updated.
  * <p>
- * Please note that this class cannot be serialized actually, so relevant 
- * serialization methods only throw <code>NotSerializableException</code>.
- * </p>
+ * Please note that although the class is marked as {@code Serializable} by
+ * inheritance from {@code EventObject}, this type is not intended to be serialized
+ * so the serialization methods do nothing but throw a {@code NotSerializableException}.
  * 
  * @see java.util.prefs.Preferences
  * @see java.util.prefs.PreferenceChangeListener
@@ -47,13 +47,16 @@
     private final String value;
 
     /**
-     * Construct a new <code>PreferenceChangeEvent</code> instance.
+     * Construct a new {@code PreferenceChangeEvent} instance.
      * 
-     * @param p the <code>Preferences</code> instance that this event happened,
this object is
-     *            considered as event's source.
-     * @param k the changed preference's key
-     * @param v the new value of the changed preference, this value can be null, which means
the
-     *            preference is removed.
+     * @param p
+     *            the {@code Preferences} instance that fired this event; this object is
+     *            considered as the event's source.
+     * @param k
+     *            the changed preference key.
+     * @param v
+     *            the new value of the changed preference, this value can be
+     *            {@code null}, which means the preference has been removed.
      */
     public PreferenceChangeEvent(Preferences p, String k, String v) {
         super(p);
@@ -63,45 +66,45 @@
     }
 
     /**
-     * Get the changed preference's key.
+     * Gets the key of the changed preference.
      * 
-     * @return the changed preference's key
+     * @return the changed preference's key.
      */
     public String getKey() {
         return key;
     }
 
     /**
-     * Get the new value of the changed preference, or null if this preference 
-     * is removed.
+     * Gets the new value of the changed preference or {@code null} if the
+     * preference has been removed.
      * 
-     * @return the new value of the changed preference, or null if this preference 
-     * is removed.
+     * @return the new value of the changed preference or {@code null} if the
+     *         preference has been removed.
      */
     public String getNewValue() {
         return value;
     }
 
     /**
-     * Get the <code>Preferences</code> instance that this event happened.
+     * Gets the {@code Preferences} instance that fired this event.
      * 
-     * @return the <code>Preferences</code> instance that this event happened.
+     * @return the {@code Preferences} instance that fired this event.
      */
     public Preferences getNode() {
         return node;
     }
 
     /**
-     * This method always throws a <code>NotSerializableException</code>, because

-     * this object cannot be serialized,  
+     * This method always throws a <code>NotSerializableException</code>,
+     * because this object cannot be serialized,
      */
     private void writeObject(ObjectOutputStream out) throws IOException {
         throw new NotSerializableException();
     }
 
     /**
-     * This method always throws a <code>NotSerializableException</code>, because

-     * this object cannot be serialized,  
+     * This method always throws a <code>NotSerializableException</code>,
+     * because this object cannot be serialized,
      */
     private void readObject(ObjectInputStream in) throws IOException{
         throw new NotSerializableException();

Modified: harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeListener.java?rev=769121&r1=769120&r2=769121&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeListener.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/PreferenceChangeListener.java
Mon Apr 27 19:33:29 2009
@@ -19,8 +19,9 @@
 import java.util.EventListener;
 
 /**
- * This interface is used to handle preferences change event. Implementation 
- * of this interface can be installed by <code>Preferences</code> instance.
+ * This interface is used to handle preferences change events. The
+ * implementation of this interface can be installed by the {@code Preferences}
+ * instance.
  * 
  * @see Preferences
  * @see PreferenceChangeEvent
@@ -31,10 +32,12 @@
 public interface PreferenceChangeListener extends EventListener {
 
     /**
-     * This method gets invoked whenever some preference is added, deleted or updated.
+     * This method gets invoked whenever a preference is added, deleted or
+     * updated.
      * 
-     * @param pce the event instance which describes the changed Preferences instance and
-     *            preferences value.
+     * @param pce
+     *            the event instance which describes the changed {@code Preferences}
+     *            instance and the preference value.
      */
     void preferenceChange (PreferenceChangeEvent pce);
 }



Mime
View raw message