[LANG-1810] Deprecate SOFT_MAX_ARRAY_LENGTH in favor of MAX_ARRAY_LENGTH (#1559)

* [LANG-1810] Deprecate SOFT_MAX_ARRAY_LENGTH in favor of MAX_ARRAY_LENGTH

* [LANG-1810] Add test coverage for MAX_ARRAY_LENGTH

* [LANG-1810] Rename new constant to SAFE_MAX_ARRAY_LENGTH and update Javadoc

---------

Co-authored-by: yelimkoo <lydia@tooning.io>

Author: debbs061

src/main/java/org/apache/commons/lang3/ArrayUtils.java

@@ -194,9 +194,18 @@ public class ArrayUtils {
      * The {@code SOFT_MAX_ARRAY_LENGTH} constant from Java's internal ArraySupport class.
      *
      * @since 3.19.0
+     * @deprecated This variable will be final in 4.0; to guarantee immutability now, use {@link #SAFE_MAX_ARRAY_LENGTH}.
      */
+    @Deprecated
     public static int SOFT_MAX_ARRAY_LENGTH = Integer.MAX_VALUE - 8;
 
+    /**
+     * The {@code MAX_ARRAY_LENGTH} constant from Java's internal ArraySupport class.
+     *
+     * @since 3.21.0
+     */
+    public static final int SAFE_MAX_ARRAY_LENGTH = Integer.MAX_VALUE - 8;
+
     /**
      * Copies the given array and adds the given element at the end of the new array.
      * <p>

src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java

@@ -6958,4 +6958,9 @@ void testToStringDefault() {
         assertEquals("{<null>}", ArrayUtils.toString(new String[]{null}, "<empty>"));
         assertEquals("{pink,blue}", ArrayUtils.toString(new String[]{"pink", "blue"}, "<empty>"));
     }
+
+    @Test
+    void testMaxArrayLength() {
+        assertEquals(Integer.MAX_VALUE - 8, ArrayUtils.SAFE_MAX_ARRAY_LENGTH);
+    }
 }