ICU-10700 Add documentation to JAVA about not registering services in the middle...

X-SVN-Rev: 35414

diff --git a/icu4j/main/classes/collate/src/com/ibm/icu/text/Collator.java b/icu4j/main/classes/collate/src/com/ibm/icu/text/Collator.java
index c28c8f596e044992c12223ff6cf5e3dd92cc5ae7..c1eaa2ec266292520363e2b6da72d3e2c7fa357b 100644 (file)
--- a/icu4j/main/classes/collate/src/com/ibm/icu/text/Collator.java
+++ b/icu4j/main/classes/collate/src/com/ibm/icu/text/Collator.java
@@ -636,6 +636,10 @@ public abstract class Collator implements Comparator<Object>, Freezable<Collator
      * {@icu} Registers a collator as the default collator for the provided locale.  The
      * collator should not be modified after it is registered.
      *
+     * Because ICU may choose to cache Collator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Collator.getInstance to avoid undefined behavior.
+     *
      * @param collator the collator to register
      * @param locale the locale for which this is the default collator
      * @return an object that can be used to unregister the registered collator.
@@ -648,6 +652,10 @@ public abstract class Collator implements Comparator<Object>, Freezable<Collator
 
     /**
      * {@icu} Registers a collator factory.
+     * 
+     * Because ICU may choose to cache Collator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Collator.getInstance to avoid undefined behavior.
      *
      * @param factory the factory to register
      * @return an object that can be used to unregister the registered factory.

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java b/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java
index 57dfb2dfd72814429ff5b6250c0b357f0b9bb6a8..0cad42e6bc5d9951fd97f2dab7aa22cf36fb75a0 100644 (file)
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java
@@ -769,6 +769,11 @@ s     */
      * {@icu} Registers a new break iterator of the indicated kind, to use in the given
      * locale.  Clones of the iterator will be returned if a request for a break iterator
      * of the given kind matches or falls back to this locale.
+     * 
+     * Because ICU may choose to cache BreakIterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * BreakIterator.getInstance to avoid undefined behavior.
+     * 
      * @param iter the BreakIterator instance to adopt.
      * @param locale the Locale for which this instance is to be registered
      * @param kind the type of iterator for which this instance is to be registered
@@ -783,6 +788,11 @@ s     */
      * {@icu} Registers a new break iterator of the indicated kind, to use in the given
      * locale.  Clones of the iterator will be returned if a request for a break iterator
      * of the given kind matches or falls back to this locale.
+     * 
+     * Because ICU may choose to cache BreakIterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * BreakIterator.getInstance to avoid undefined behavior.
+     * 
      * @param iter the BreakIterator instance to adopt.
      * @param locale the Locale for which this instance is to be registered
      * @param kind the type of iterator for which this instance is to be registered

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java
index 1c22e2048deecf5309ce90f65b5d19cf26eb60c7..ac040f57a095f559f569576c5e4e7a1f82124e7b 100644 (file)
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java
@@ -982,6 +982,11 @@ public abstract class NumberFormat extends UFormat {
      * {@icu} Registers a new NumberFormatFactory.  The factory is adopted by
      * the service and must not be modified.  The returned object is a
      * key that can be used to unregister this factory.
+     * 
+     * Because ICU may choose to cache NumberFormat objects internally, this must
+     * be called at application startup, prior to any calls to
+     * NumberFormat.getInstance to avoid undefined behavior.
+     * 
      * @param factory the factory to register
      * @return a key with which to unregister the factory
      * @stable ICU 2.6

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/util/Currency.java b/icu4j/main/classes/core/src/com/ibm/icu/util/Currency.java
index 6ae06aecf025e4b1aed49f285f58f1ba8d89a922..e62c9b735427c017b520f4a01113857015f86abd 100644 (file)
--- a/icu4j/main/classes/core/src/com/ibm/icu/util/Currency.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/util/Currency.java
@@ -265,6 +265,11 @@ public class Currency extends MeasureUnit {
     /**
      * Registers a new currency for the provided locale.  The returned object
      * is a key that can be used to unregister this currency object.
+     * 
+     * Because ICU may choose to cache Currency objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Currency.getInstance to avoid undefined behavior.
+     * 
      * @param currency the currency to register
      * @param locale the ulocale under which to register the currency
      * @return a registry key that can be used to unregister this currency

diff --git a/icu4j/main/classes/translit/src/com/ibm/icu/text/Transliterator.java b/icu4j/main/classes/translit/src/com/ibm/icu/text/Transliterator.java
index a814a0cd5c1e65e8c29c80d1b369e4a081c95a4c..0dc321ee62e37f709d8c848d95ce85fd2dc82f97 100644 (file)
--- a/icu4j/main/classes/translit/src/com/ibm/icu/text/Transliterator.java
+++ b/icu4j/main/classes/translit/src/com/ibm/icu/text/Transliterator.java
@@ -1712,6 +1712,11 @@ public abstract class Transliterator implements StringTransform  {
     /**
      * Register a factory object with the given ID.  The factory
      * method should return a new instance of the given transliterator.
+     * 
+     * Because ICU may choose to cache Transliterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Transliterator.getInstance to avoid undefined behavior.
+     * 
      * @param ID the ID of this transliterator
      * @param factory the factory object
      * @stable ICU 2.0
@@ -1722,6 +1727,11 @@ public abstract class Transliterator implements StringTransform  {
 
     /**
      * Register a Transliterator object with the given ID.
+     * 
+     * Because ICU may choose to cache Transliterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Transliterator.getInstance to avoid undefined behavior.
+     * 
      * @param trans the Transliterator object
      * @stable ICU 2.2
      */
@@ -1731,6 +1741,11 @@ public abstract class Transliterator implements StringTransform  {
 
     /**
      * Register a Transliterator object with the given ID.
+     * 
+     * Because ICU may choose to cache Transliterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Transliterator.getInstance to avoid undefined behavior.
+     * 
      * @param ID the ID of this transliterator
      * @param trans the Transliterator object
      */
@@ -1742,6 +1757,11 @@ public abstract class Transliterator implements StringTransform  {
      * Register an ID as an alias of another ID.  Instantiating
      * alias ID produces the same result as instantiating the original ID.
      * This is generally used to create short aliases of compound IDs.
+     * 
+     * Because ICU may choose to cache Transliterator objects internally, this must
+     * be called at application startup, prior to any calls to
+     * Transliterator.getInstance to avoid undefined behavior.
+     * 
      * @param aliasID The new ID being registered.
      * @param realID The existing ID that the new ID should be an alias of.
      * @stable ICU 3.6