From 709cf243896b71cf2b6dd34f613f805bdacbf094 Mon Sep 17 00:00:00 2001
From: Matthew Pope <popematt@amazon.com>
Date: Wed, 13 Mar 2024 15:09:38 -0700
Subject: [PATCH] Adds recommendation to use IonElement

---
 README.md                                  | 15 +++++++++++++++
 src/main/java/com/amazon/ion/IonValue.java | 21 +++++++++++++++------
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d6322fa5cc..de1b515882 100644
--- a/README.md
+++ b/README.md
@@ -67,3 +67,18 @@ to the official one.
 A great way to get started is to use the [Ion cookbook](https://amazon-ion.github.io/ion-docs/guides/cookbook.html).
 The [API documentation](http://www.javadoc.io/doc/com.amazon.ion/ion-java) will give a lot
 of detailed information about how to use the library.
+
+### Alternatives
+
+If you are looking for an in-memory Ion data model, this library provides `IonValue`, but you should consider 
+using `IonElement` from [`ion-element-kotlin`](https://github.com/amazon-ion/ion-element-kotlin) instead.
+
+`IonElement` is a better choice than `IonValue` as long as you can work within its limitations. `IonElement` has
+significantly less memory overhead than `IonValue`. It is immutable and does not have references to parent values, so
+it is always threadsafe, and unlike `IonValue` there is no need to make deep copies of `IonElement`.
+The limitations of `IonElement` are that it does not support symbols with unknown text, it will bring a dependency
+on the Kotlin Stdlib, and you may need to change some logic in your application if it relies on being able to access the
+parent container of an Ion value.
+
+The Ion maintainers recommend using `IonElement` instead of `IonValue` whenever possible. For more information, see 
+"[Why is IonElement needed?](https://github.com/amazon-ion/ion-element-kotlin#user-content-why-is-ionelement-needed)"
diff --git a/src/main/java/com/amazon/ion/IonValue.java b/src/main/java/com/amazon/ion/IonValue.java
index 74e8285886..db65ffd687 100644
--- a/src/main/java/com/amazon/ion/IonValue.java
+++ b/src/main/java/com/amazon/ion/IonValue.java
@@ -169,6 +169,21 @@
  * <code>latch</code> in this example provides a way to synchronize
  * when {@link #makeReadOnly()} happens in the first thread relative
  * to {@link #isNullValue()} being invoked on the second thread.
+ *
+ * <h2>Alternatives</h2>
+ *
+ * The Ion maintainers recommend using {@code IonElement} instead of {@code IonValue} whenever possible.
+ * <p>
+ * {@code IonElement} is a better choice than {@code IonValue} as long as you can work within its limitations.
+ * {@code IonElement} has significantly less memory overhead than {@code IonValue}. It is immutable and does not have a
+ * single-parent restriction, so it is always threadsafe, and unlike {@code IonValue} there is no need to make deep
+ * copies of {@code IonElement}. The limitations of {@code IonElement} are that it does not support symbols with unknown
+ * text, it will bring a dependency on the Kotlin Stdlib, and you may need to change some logic in your application if
+ * your logic relies on being able to access the parent container of an Ion value.
+ * <p>
+ * For more information, see
+ * "<a href="https://github.com/amazon-ion/ion-element-kotlin#user-content-why-is-ionelement-needed">Why is IonElement needed?</a>"
+ *
  */
 public interface IonValue
     extends Cloneable
@@ -278,7 +293,6 @@ public interface IonValue
      *
      * @throws UnsupportedOperationException if this is an {@link IonDatagram}.
      *
-
      */
     public IonValue topLevelValue();
 
@@ -300,7 +314,6 @@ public interface IonValue
      * @return the (ordered) annotations on the current value, or an empty
      * array (not {@code null}) if there are none.
      *
-
      */
     public SymbolToken[] getTypeAnnotationSymbols();
 
@@ -338,7 +351,6 @@ public interface IonValue
      * If null or empty array, then all annotations are removed.
      * Any duplicates are preserved.
      *
-
      */
     public void setTypeAnnotationSymbols(SymbolToken... annotations);
 
@@ -376,7 +388,6 @@ public interface IonValue
      * and performs a deep write, including the contents of
      * any containers encountered.
      *
-
      */
     public void writeTo(IonWriter writer);
 
@@ -479,7 +490,6 @@ public IonValue clone()
      *
      * @return Ion text data equivalent to this value.
      *
-
      */
     public String toPrettyString();
 
@@ -493,7 +503,6 @@ public IonValue clone()
      *
      * @return Ion text data equivalent to this value.
      *
-
      */
     public String toString(IonTextWriterBuilder writerBuilder);