Summary

Inform users of java.text.Collator and java.text.RuleBasedCollator the recommended approach when using the classes in a multi-threaded environment.

Problem

While behaviorally correct, re-using a java.text.Collator instance in a multi threaded environment leads to slower than expected performance. Since the state is mutable, and thread-safety achieved via synchronization, concurrent usage leads to threads stuck in a blocked state for significant periods of time. This has been observed to lead to performance degradation in an application.

Solution

It has been found that using a dedicated instance per each thread leads to better performance and (of course) resolves the thread contention issues reported when using a single instance concurrently.

Note that since the Collator and RuleBasedCollator classes are designed to be thread-safe and it is not a goal to label all such implementations as non thread-safe, the following wording is done as implementation-specific.

• Provide an implementation note that suggests to users that creating a new Collator instance per each thread is the suggested approach. It also calls out the potential thread contention when used otherwise.
• This applies to both Collator and RuleBasedCollator, where the former (which is an abstract class) warns about instances returned by the factory methods when the standard provider is in use.

Specification

In Collator, add the following implementation note to the class specification,

+ * @implNote Significant thread contention may occur during concurrent usage
+ * of the JDK Reference Implementation's {@link RuleBasedCollator}, which is the
+ * subtype returned by the default provider of the {@link #getInstance()} factory
+ * methods. As such, users should consider retrieving a separate instance for
+ * each thread when used in multithreaded environments.

In RuleBasedCollator, add the following implementation note to the class specification,

+ * @implNote For this implementation, concurrent usage of this class may
+ * lead to significant thread contention since {@code synchronized} is employed
+ * to ensure thread-safety. As such, users of this class should consider creating
+ * a separate instance for each thread when used in multithreaded environments.