8367237: Thread-Safety Usage Warning for java.text.Collator Classes

Reviewed-by: jlu
Backport-of: 64155dfac068cf01bcab6adb401b360499f33a5f

Author: Kieran Farrell

src/java.base/share/classes/java/text/Collator.java

@@ -111,8 +111,13 @@
  * <br>
  * @apiNote {@code CollationKey}s from different
  * {@code Collator}s can not be compared. See the class description
- * for {@link CollationKey}
- * for an example using {@code CollationKey}s.
+ * for {@link CollationKey} for an example using {@code CollationKey}s.
+ *
+ * @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.
  *
  * @see         RuleBasedCollator
  * @see         CollationKey

src/java.base/share/classes/java/text/RuleBasedCollator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,10 +38,6 @@
 
 package java.text;
 
-import java.text.Normalizer;
-import java.util.Vector;
-import java.util.Locale;
-
 /**
  * The {@code RuleBasedCollator} class is a concrete subclass of
  * {@code Collator} that provides a simple, data-driven, table
@@ -239,6 +235,11 @@
  * </pre>
  * </blockquote>
  *
+ * @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.
+ *
  * @see        Collator
  * @see        CollationElementIterator
  * @author     Helena Shih, Laura Werner, Richard Gillam