feat: add Map-based helper methods for Event properties

src/demo/build.gradle

@@ -42,3 +42,10 @@ task runWithJavaExec(type: JavaExec) {
     classpath = sourceSets.main.runtimeClasspath
     main = "com.amplitude.Demo"
 }
+
+task runLocalUploadDemo(type: JavaExec) {
+    group = "Execution"
+    description = "Run LocalUploadDemo"
+    classpath = sourceSets.main.runtimeClasspath
+    main = "com.demo.amplitude.LocalUploadDemo"
+}

src/demo/java/com/demo/amplitude/LocalUploadDemo.java

@@ -7,6 +7,7 @@
 import org.json.JSONObject;
 
 import java.util.concurrent.TimeUnit;
+import java.util.HashMap;
 
 public class LocalUploadDemo {
 
@@ -42,7 +43,7 @@ public void onLogEventServerResponse(Event event, int status, String message) {
         };
     client.setCallbacks(callback);
 
-    // GROUPS AND GROUP PROPERTIES
+    // GROUPS AND GROUP PROPERTIES - Traditional JSONObject approach
     JSONObject groups = new JSONObject()
             .put("org", "engineering")
             .put("department", "sdk");
@@ -64,25 +65,74 @@ public void onLogEventServerResponse(Event event, int status, String message) {
     groupIdentifyEvent.groupProperties = groupProps;
     client.logEvent(groupIdentifyEvent);
 
-    // Track an event
-    client.logEvent(new Event("Test Event 1", userId));
+    // GROUPS AND GROUP PROPERTIES - Using new helper methods
+    java.util.Map<String, Object> groupsMap = new HashMap<>();
+    groupsMap.put("new-org", "engineering");
+    groupsMap.put("new-department", "sdk");
+
+    Event groupEventWithHelpers = new Event("$identify", userId)
+        .setGroups(groupsMap)
+        .setUserProperties(groupsMap);
+    client.logEvent(groupEventWithHelpers);
+
+    Event groupIdentifyWithHelpers = new Event("$groupidentify", userId)
+        .addGroup("new-org", "engineering")
+        .addGroup("new-department", "sdk")
+        .addGroupProperty("new-technology", "java")
+        .addGroupProperty("new-location", "toronto");
+    client.logEvent(groupIdentifyWithHelpers);
+
+    // USING NEW HELPER METHODS - Map-based approach
+    java.util.Map<String, Object> eventPropsMap = new HashMap<>();
+    eventPropsMap.put("method", "email");
+    eventPropsMap.put("source", "web");
+
+    java.util.Map<String, Object> userPropsMap = new HashMap<>();
+    userPropsMap.put("plan", "premium");
+    userPropsMap.put("age", 30);
+
+    Event eventWithMapProps = new Event("User Login - new way", userId)
+        .setEventProperties(eventPropsMap)
+        .setUserProperties(userPropsMap);
+    client.logEvent(eventWithMapProps);
+
+    // event props and user props using old JSONObject approach
+    Event eventWithJSONObjectProps = new Event("Purchase Complete - old way", userId);
+    eventWithJSONObjectProps.eventProperties = new JSONObject()
+        .put("item_id", "SKU-123")
+        .put("price", 29.99)
+        .put("currency", "USD");
+    eventWithJSONObjectProps.userProperties = new JSONObject()
+        .put("total_purchases", 5)
+        .put("last_purchase_date", "2025-11-07");
+    client.logEvent(eventWithJSONObjectProps);
+
 
     // Flush events to the server
     client.flushEvents();
+    int totalEvents = 10; //10000000;
 
-    for (int i = 0; i < 10000000; i++) {
+    for (int i = 0; i < totalEvents; i++) {
       Event ampEvent = new Event("General" + (i % 20), "Test_UserID_B" + (i % 5000));
       while (client.shouldWait(ampEvent)) {
         System.out.println("Client is busy. Waiting for log event " + ampEvent.eventType);
         TimeUnit.SECONDS.sleep(60L);
       }
-      ampEvent.userProperties =
-          new JSONObject()
-              .put("property1", "p" + i)
-              .put("property2", "p" + i)
-              .put("property3", "p" + i)
-              .put("property4", "p" + i)
-              .put("property5", "p" + i);
+      // Traditional approach using JSONObject directly
+      // ampEvent.userProperties =
+      //     new JSONObject()
+      //         .put("property1", "p" + i)
+      //         .put("property2", "p" + i)
+      //         .put("property3", "p" + i)
+      //         .put("property4", "p" + i)
+      //         .put("property5", "p" + i);
+
+      // New approach using helper methods - cleaner and no JSONObject needed
+      ampEvent.addUserProperty("property1", "p" + i)
+              .addUserProperty("property2", "p" + i)
+              .addUserProperty("property3", "p" + i)
+              .addUserProperty("property4", "p" + i)
+              .addUserProperty("property5", "p" + i);
       client.logEvent(ampEvent);
     }
   }

src/main/java/com/amplitude/Event.java

@@ -5,6 +5,7 @@
 import org.json.JSONObject;
 
 import java.util.Iterator;
+import java.util.Map;
 import java.util.UUID;
 
 public class Event {
@@ -230,6 +231,130 @@ public Event(String eventType, String userId, String deviceId) {
     this.deviceId = deviceId;
   }
 
+  /**
+   * Set event properties from a Map. This replaces any existing event properties.
+   *
+   * @param properties Map of key-value pairs for event properties
+   * @return this Event for method chaining
+   */
+  public Event setEventProperties(Map<String, Object> properties) {
+    if (properties == null) {
+      this.eventProperties = null;
+    } else {
+      this.eventProperties = new JSONObject(properties);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update a single event property. If event properties is null, it will be initialized.
+   *
+   * @param key Property key
+   * @param value Property value
+   * @return this Event for method chaining
+   */
+  public Event addEventProperty(String key, Object value) {
+    if (this.eventProperties == null) {
+      this.eventProperties = new JSONObject();
+    }
+    this.eventProperties.put(key, value);
+    return this;
+  }
+
+  /**
+   * Set user properties from a Map. This replaces any existing user properties.
+   *
+   * @param properties Map of key-value pairs for user properties
+   * @return this Event for method chaining
+   */
+  public Event setUserProperties(Map<String, Object> properties) {
+    if (properties == null) {
+      this.userProperties = null;
+    } else {
+      this.userProperties = new JSONObject(properties);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update a single user property. If user properties is null, it will be initialized.
+   *
+   * @param key Property key
+   * @param value Property value
+   * @return this Event for method chaining
+   */
+  public Event addUserProperty(String key, Object value) {
+    if (this.userProperties == null) {
+      this.userProperties = new JSONObject();
+    }
+    this.userProperties.put(key, value);
+    return this;
+  }
+
+  /**
+   * Set groups from a Map. This replaces any existing groups. This feature is only available to
+   * Enterprise customers who have purchased the Accounts add-on.
+   *
+   * @param groups Map of key-value pairs representing groups
+   * @return this Event for method chaining
+   */
+  public Event setGroups(Map<String, Object> groups) {
+    if (groups == null) {
+      this.groups = null;
+    } else {
+      this.groups = new JSONObject(groups);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update a single group. If groups is null, it will be initialized. This feature is only
+   * available to Enterprise customers who have purchased the Accounts add-on.
+   *
+   * @param key Group key
+   * @param value Group value
+   * @return this Event for method chaining
+   */
+  public Event addGroup(String key, Object value) {
+    if (this.groups == null) {
+      this.groups = new JSONObject();
+    }
+    this.groups.put(key, value);
+    return this;
+  }
+
+  /**
+   * Set group properties from a Map. This replaces any existing group properties. This feature is
+   * only available to Enterprise customers who have purchased the Accounts add-on.
+   *
+   * @param properties Map of key-value pairs for group properties
+   * @return this Event for method chaining
+   */
+  public Event setGroupProperties(Map<String, Object> properties) {
+    if (properties == null) {
+      this.groupProperties = null;
+    } else {
+      this.groupProperties = new JSONObject(properties);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update a single group property. If group properties is null, it will be initialized.
+   * This feature is only available to Enterprise customers who have purchased the Accounts add-on.
+   *
+   * @param key Property key
+   * @param value Property value
+   * @return this Event for method chaining
+   */
+  public Event addGroupProperty(String key, Object value) {
+    if (this.groupProperties == null) {
+      this.groupProperties = new JSONObject();
+    }
+    this.groupProperties.put(key, value);
+    return this;
+  }
+
   /** @return the JSONObject that represents the event data of this event */
   public JSONObject toJsonObject() {
     JSONObject event = new JSONObject();