Merge pull request #136 from contentstack/staging

DX | 06-04-2026 | Release

Author: harshitha-cstk

Changelog.md

@@ -3,6 +3,10 @@
 A brief description of what changes project contains
 ## Mar 23, 2026
 
+#### v1.4.0
+
+- Enhancement: Added `Utils.getVariantMetadataTags(JSONObject, String)` and `Utils.getVariantMetadataTags(JSONArray, String)` as the canonical API for the `data-csvariants` payload. `Utils.getDataCsvariantsAttribute(...)` is deprecated and delegates to `getVariantMetadataTags(...)` for backward compatibility.
+
 #### v1.3.0
 
 - Enhancement: Variant Utility

pom.xml

@@ -4,7 +4,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.contentstack.sdk</groupId>
     <artifactId>utils</artifactId>
-    <version>1.3.0</version>
+    <version>1.4.0</version>
     <packaging>jar</packaging>
     <name>Contentstack-utils</name>
     <description>Java Utils SDK for Contentstack Content Delivery API, Contentstack is a headless CMS</description>
@@ -20,16 +20,16 @@
         <maven-source-plugin.version>2.2.1</maven-source-plugin.version>
         <maven-javadoc-plugin.version>3.1.1</maven-javadoc-plugin.version>
         <junit.version>4.13.2</junit.version>
-        <jsoup.version>1.18.3</jsoup.version>
+        <jsoup.version>1.22.1</jsoup.version>
         <json.simple.version>1.1.1</json.simple.version>
         <maven-site-plugin.version>3.3</maven-site-plugin.version>
         <maven-gpg-plugin.version>1.5</maven-gpg-plugin.version>
         <central-publishing-maven-plugin.version>0.8.0</central-publishing-maven-plugin.version>
         <maven-release-plugin.version>2.5.3</maven-release-plugin.version>
         <validation-version>2.0.1.Final</validation-version>
-        <json-version>20250517</json-version>
-        <spring-web-version>6.2.17</spring-web-version>
-        <org.apache.commons-text>1.14.0</org.apache.commons-text>
+        <json-version>20251224</json-version>
+        <spring-web-version>7.0.6</spring-web-version>
+        <org.apache.commons-text>1.15.0</org.apache.commons-text>
     </properties>
 
     <developers>

src/main/java/com/contentstack/utils/Utils.java

@@ -337,7 +337,16 @@ public static JSONArray getVariantAliases(JSONArray entries, String contentTypeU
         return variantResults;
     }
 
-    public static JSONObject getDataCsvariantsAttribute(JSONObject entry, String contentTypeUid) {
+    /**
+     * Builds the {@code data-csvariants} attribute value from one or more entries (variant metadata
+     * for personalization). Prefer this over {@link #getDataCsvariantsAttribute(JSONObject, String)}.
+     *
+     * @param entry          one CDA entry, or {@code null} for an empty attribute
+     * @param contentTypeUid content type UID (required when {@code entry} is non-null)
+     * @return {@link JSONObject} with key {@code data-csvariants} whose value is a JSON string of the
+     *         variant metadata array
+     */
+    public static JSONObject getVariantMetadataTags(JSONObject entry, String contentTypeUid) {
 
         if (entry == null) {
             JSONObject result = new JSONObject();
@@ -346,10 +355,16 @@ public static JSONObject getDataCsvariantsAttribute(JSONObject entry, String con
         }
         JSONArray entries = new JSONArray();
         entries.put(entry);
-        return getDataCsvariantsAttribute(entries, contentTypeUid);
+        return getVariantMetadataTags(entries, contentTypeUid);
     }
 
-    public static JSONObject getDataCsvariantsAttribute(JSONArray entries, String contentTypeUid) {
+    /**
+     * @param entries        array of CDA entries, or {@code null} for an empty attribute
+     * @param contentTypeUid content type UID (required, non-empty)
+     * @return {@link JSONObject} with key {@code data-csvariants} whose value is a JSON string of the
+     *         variant metadata array
+     */
+    public static JSONObject getVariantMetadataTags(JSONArray entries, String contentTypeUid) {
 
         JSONObject result = new JSONObject();
         if (entries == null) {
@@ -366,6 +381,24 @@ public static JSONObject getDataCsvariantsAttribute(JSONArray entries, String co
         return result;
     }
 
+    /**
+     * @deprecated Use {@link #getVariantMetadataTags(JSONObject, String)} instead. Retained for
+     *             backward compatibility with earlier releases.
+     */
+    @Deprecated
+    public static JSONObject getDataCsvariantsAttribute(JSONObject entry, String contentTypeUid) {
+        return getVariantMetadataTags(entry, contentTypeUid);
+    }
+
+    /**
+     * @deprecated Use {@link #getVariantMetadataTags(JSONArray, String)} instead. Retained for
+     *             backward compatibility with earlier releases.
+     */
+    @Deprecated
+    public static JSONObject getDataCsvariantsAttribute(JSONArray entries, String contentTypeUid) {
+        return getVariantMetadataTags(entries, contentTypeUid);
+    }
+
     private static JSONArray extractVariantAliasesFromEntry(JSONObject entry) {
         JSONArray variantArray = new JSONArray();
         JSONObject publishDetails = entry.optJSONObject("publish_details");

src/test/java/com/contentstack/utils/UtilTests.java

@@ -206,13 +206,13 @@ public void testGetVariantAliasesSingleEntry() throws IOException {
     }
 
     @Test
-    public void testGetDataCsvariantsAttributeSingleEntry() throws IOException {
+    public void testGetVariantMetadataTagsSingleEntry() throws IOException {
         final String json = "src/test/resources/variant_entry_single.json";
         JSONObject full = new ReadResource().readJson(json);
         JSONObject entry = full.getJSONObject("entry");
         String contentTypeUid = "movie";
 
-        JSONObject result = Utils.getDataCsvariantsAttribute(entry, contentTypeUid);
+        JSONObject result = Utils.getVariantMetadataTags(entry, contentTypeUid);
 
         Assert.assertTrue(result.has("data-csvariants"));
         String dataCsvariantsStr = result.getString("data-csvariants");
@@ -253,13 +253,13 @@ public void testGetVariantAliasesMultipleEntries() throws IOException {
     }
 
     @Test
-    public void testGetDataCsvariantsAttributeMultipleEntries() throws IOException {
+    public void testGetVariantMetadataTagsMultipleEntries() throws IOException {
         final String json = "src/test/resources/variant_entries.json";
         JSONObject full = new ReadResource().readJson(json);
         JSONArray entries = full.getJSONArray("entries");
         String contentTypeUid = "movie";
 
-        JSONObject result = Utils.getDataCsvariantsAttribute(entries, contentTypeUid);
+        JSONObject result = Utils.getVariantMetadataTags(entries, contentTypeUid);
 
         Assert.assertTrue(result.has("data-csvariants"));
         String dataCsvariantsStr = result.getString("data-csvariants");
@@ -295,12 +295,24 @@ public void testGetVariantAliasesThrowsWhenContentTypeUidEmpty() throws IOExcept
     }
 
     @Test
-    public void testGetDataCsvariantsAttributeWhenEntryNull() {
-        JSONObject result = Utils.getDataCsvariantsAttribute((JSONObject) null, "landing_page");
+    public void testGetVariantMetadataTagsWhenEntryNull() {
+        JSONObject result = Utils.getVariantMetadataTags((JSONObject) null, "landing_page");
         Assert.assertTrue(result.has("data-csvariants"));
         Assert.assertEquals("[]", result.getString("data-csvariants"));
     }
 
+    @Test
+    public void testGetDataCsvariantsAttributeDelegatesToGetVariantMetadataTags() throws IOException {
+        final String json = "src/test/resources/variant_entry_single.json";
+        JSONObject full = new ReadResource().readJson(json);
+        JSONObject entry = full.getJSONObject("entry");
+        String contentTypeUid = "movie";
+        JSONObject fromNew = Utils.getVariantMetadataTags(entry, contentTypeUid);
+        @SuppressWarnings("deprecation")
+        JSONObject fromOld = Utils.getDataCsvariantsAttribute(entry, contentTypeUid);
+        Assert.assertEquals(fromNew.toString(), fromOld.toString());
+    }
+
 }