You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/27 21:33:29 UTC
svn commit: r769121 [1/2] -
/harmony/enhanced/classlib/trunk/modules/prefs/src/main/java/java/util/prefs/
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);
}