A DESCRIPTION OF THE REQUEST :
Every single new user of the Java language that I have encountered uses the Vector and Hashtable classes, for no  customer  reason other than they are familiar with the names and not aware of the preferred classes (List/ArrayList, Map/HashMap).

Please (PLEASE!) at least modify the JavaDocs for these classes to add highly visible text (preferably bright red and 40pt) to direct new users to the appropriate classes, unless they REALLY want the synchronization behavior. And even then they should be directed to either the Collections.synchronizedXX wrapper methods, or the various vastly superior alternatives in "java.util.concurrent".

JUSTIFICATION :
It may be the case that Sun's JVM implementations are  customer  at eliding unnecessary locking, but this assumption may not be true of other VMs. And regardless, there's just no reason to be even risking unnecessary synchronization when the only reason it is incurred is because the programmer is clueless.

There's even an outside chance that this is a deadlock risk if someone uses the Vector/Hashtable intrinsic monitor lock, not realizing that it might conflict with the internal implementation of those classes.

I see that an RFE to deprecate these classes has already been rejected, so while I firmly disagree with that rejection, I'll take a different approach to suggesting that this problem be addressed in some way.

(A final observation, even several moderately experienced Java programmers I have encountered were also unaware of the synchronization behavior, and pseudo-deprecation, of these classes.)

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
  Programmers, especially those new to Java, will use the List and Map classes for the traditional "vector" and "hashtable" type functionality when they don't require synchronization, and thus *guarantee* that code that doesn't require the synchronization won't ever incur any penalties on any platform/JVM implementation.

Even better, if they actually do want synchronization, use the superior options in "java.util.concurrent", or at a minimum, *still* use the List and Map classes and use the Collections synchronization wrappers.

Documentation that directs users to the better alternatives, both synchronized and not, that completely eliminate any need or justification for retaining/using the Vector and Hashtable classes.
ACTUAL -
Javadoc documentation that does not indicate that there are better alternatives to Vector and Hashtable, for any possible use of those classes.

Lots of code that makes use of these outdated classes with unnecessary synchronization (and an inefficient synchronization implementation even when it is).
Posted Date : 2007-07-23 09:31:56.0

N/A

I agree that some in-class javadoc denigration is in order.
Note, however, that Vector and Hashtable continue to be maintained,
and are still the best choices if portability is the top priority.
Posted Date : 2007-07-23 16:43:15.0

Here's a proposed patch:

diff --git a/src/share/classes/java/util/Hashtable.java b/src/share/classes/java/util/Hashtable.java
--- a/src/share/classes/java/util/Hashtable.java
+++ b/src/share/classes/java/util/Hashtable.java
@@ -100,9 +100,15 @@ import java.io.*;
  *
  * <p>As of the Java 2 platform v1.2, this class was retrofitted to
  * implement the {@link Map} interface, making it a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
- * Collections Framework</a>.  Unlike the new collection
- * implementations, {@code Hashtable} is synchronized.
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ *
+ * Java Collections Framework</a>.  Unlike the new collection
+ * implementations, {@code Hashtable} is synchronized.  If a
+ * thread-safe implementation is not needed, it is recommended to use
+ * {@link HashMap} in place of {@code Hashtable}.  If a thread-safe
+ * highly-concurrent implementation is desired, then it is recommended
+ * to use {@link java.util.concurrent.ConcurrentHashMap} in place of
+ * {@code Hashtable}.
  *
  * @author  Arthur van Hoff
  * @author  Josh Bloch
diff --git a/src/share/classes/java/util/Vector.java b/src/share/classes/java/util/Vector.java
--- a/src/share/classes/java/util/Vector.java
+++ b/src/share/classes/java/util/Vector.java
@@ -64,15 +64,15 @@ package java.util;
  *
  * <p>As of the Java 2 platform v1.2, this class was retrofitted to
  * implement the {@link List} interface, making it a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
- * Collections Framework</a>.  Unlike the new collection
- * implementations, {@code Vector} is synchronized.
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ * Java Collections Framework</a>.  Unlike the new collection
+ * implementations, {@code Vector} is synchronized.  If a thread-safe
+ * implementation is not needed, it is recommended to use {@link
+ * ArrayList} in place of {@code Vector}.
  *
  * @author  Lee Boynton
  * @author  Jonathan Payne
  * @see Collection
- * @see List
- * @see ArrayList
  * @see LinkedList
  * @since   JDK1.0
  */
Posted Date : 2008-03-06 23:29:45.0

+1

The purpose of documentation is to help the user to do the right thing.