feat: Introduce MixpanelApi Builder pattern and expose JsonSerializer option

.github/workflows/release.yml

@@ -71,6 +71,9 @@ jobs:
         echo "VERSION=$VERSION" >> $GITHUB_ENV
         echo "version=$VERSION" >> $GITHUB_OUTPUT
         mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
+        cd mixpanel-java-extension-jackson
+        mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
+        cd ..
 
     - name: Set version from input
       id: set-version-input
@@ -80,15 +83,27 @@ jobs:
         echo "VERSION=$VERSION" >> $GITHUB_ENV
         echo "version=$VERSION" >> $GITHUB_OUTPUT
         mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
+        cd mixpanel-java-extension-jackson
+        mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
+        cd ..
 
-    - name: Run tests
+    - name: Run tests - Main SDK
       run: mvn clean test
 
+    - name: Run tests - Jackson Extension
+      run: |
+        cd mixpanel-java-extension-jackson
+        mvn clean test
+        cd ..
+
     - name: Deploy to Maven Central
       env:
         GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
       run: |
         mvn clean deploy -Dgpg.passphrase=$GPG_PASSPHRASE
+        cd mixpanel-java-extension-jackson
+        mvn clean deploy -Dgpg.passphrase=$GPG_PASSPHRASE
+        cd ..
 
     - name: Create GitHub Release
       if: startsWith(github.ref, 'refs/tags/')
@@ -98,7 +113,7 @@ jobs:
         script: |
           const releaseBody = `## Mixpanel Java SDK v${process.env.VERSION}
 
-          ### Maven
+          ### Maven - Main SDK
           \`\`\`xml
           <dependency>
               <groupId>com.mixpanel</groupId>
@@ -107,11 +122,21 @@ jobs:
           </dependency>
           \`\`\`
 
+          ### Maven - Jackson Extension (Optional)
+          \`\`\`xml
+          <dependency>
+              <groupId>com.mixpanel</groupId>
+              <artifactId>mixpanel-java-extension-jackson</artifactId>
+              <version>${process.env.VERSION}</version>
+          </dependency>
+          \`\`\`
+
           ### Changes
           See [CHANGELOG](https://github.com/mixpanel/mixpanel-java/blob/master/CHANGELOG.md) for details.
 
           ### Links
-          - [Maven Central](https://central.sonatype.com/artifact/com.mixpanel/mixpanel-java/${process.env.VERSION})
+          - [Maven Central - Main SDK](https://central.sonatype.com/artifact/com.mixpanel/mixpanel-java/${process.env.VERSION})
+          - [Maven Central - Jackson Extension](https://central.sonatype.com/artifact/com.mixpanel/mixpanel-java-extension-jackson/${process.env.VERSION})
           - [JavaDoc](http://mixpanel.github.io/mixpanel-java/)`;
 
           await github.rest.repos.createRelease({
@@ -133,12 +158,24 @@ jobs:
     - name: Wait for Maven Central sync
       run: sleep 300  # Wait 5 minutes for synchronization
 
-    - name: Verify artifact on Maven Central
+    - name: Verify artifacts on Maven Central
       run: |
         VERSION=${{ needs.release.outputs.version }}
+
+        # Verify main SDK
         RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" https://repo1.maven.org/maven2/com/mixpanel/mixpanel-java/${VERSION}/mixpanel-java-${VERSION}.jar)
         if [ $RESPONSE -eq 200 ]; then
-          echo "✅ Artifact successfully published to Maven Central"
+          echo "✅ Main SDK successfully published to Maven Central"
+        else
+          echo "⚠️ Main SDK not yet available on Maven Central (HTTP $RESPONSE)"
+        fi
+
+        # Verify Jackson extension
+        RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" https://repo1.maven.org/maven2/com/mixpanel/mixpanel-java-extension-jackson/${VERSION}/mixpanel-java-extension-jackson-${VERSION}.jar)
+        if [ $RESPONSE -eq 200 ]; then
+          echo "✅ Jackson extension successfully published to Maven Central"
         else
-          echo "⚠️ Artifact not yet available on Maven Central (HTTP $RESPONSE). This is normal - it may take up to 30 minutes to appear."
-        fi
+          echo "⚠️ Jackson extension not yet available on Maven Central (HTTP $RESPONSE)"
+        fi
+
+        echo "Note: Artifacts may take up to 30 minutes to appear on Maven Central"

README.md

@@ -2,13 +2,13 @@ This is the official Mixpanel tracking library for Java.
 
 ## Latest Version
 
-##### _May 08, 2024_ - [v1.5.3](https://github.com/mixpanel/mixpanel-java/releases/tag/mixpanel-java-1.5.3)
+See the [releases page](https://github.com/mixpanel/mixpanel-java/releases) for the latest version.
 
-```
+```xml
 <dependency>
     <groupId>com.mixpanel</groupId>
     <artifactId>mixpanel-java</artifactId>
-    <version>1.5.3</version>
+    <version>1.6.1</version>
 </dependency>
 ```
 
@@ -33,9 +33,13 @@ are built by `MessageBuilder` objects, and those messages can be consumed by the
 
 ### Gzip Compression
 
-The library supports gzip compression for both tracking events (`/track`) and importing historical events (`/import`). To enable gzip compression, pass `true` to the `MixpanelAPI` constructor:
+The library supports gzip compression for both tracking events (`/track`) and importing historical events (`/import`). To enable gzip compression, use the builder:
 
-    MixpanelAPI mixpanel = new MixpanelAPI(true); // Enable gzip compression
+```java
+MixpanelAPI mixpanel = new MixpanelAPI.Builder()
+    .useGzipCompression(true)
+    .build();
+```
 
 Gzip compression can reduce bandwidth usage and improve performance, especially when sending large batches of events.
 
@@ -45,32 +49,37 @@ The library supports importing historical events (events older than 5 days that
 
 ### High-Performance JSON Serialization (Optional)
 
-For applications that import large batches of events (e.g., using the `/import` endpoint), the library supports optional high-performance JSON serialization using Jackson. When Jackson is available on the classpath, the library automatically uses it for JSON serialization, providing **up to 5x performance improvement** for large batches.
+For applications that import large batches of events (e.g., using the `/import` endpoint), the library supports optional high-performance JSON serialization using Jackson. The Jackson extension provides **up to 5x performance improvement** for large batches.
 
-To enable high-performance serialization, add the Jackson dependency to your project:
+To enable high-performance serialization, add the Jackson extension to your project:
 
 ```xml
 <dependency>
-    <groupId>com.fasterxml.jackson.core</groupId>
-    <artifactId>jackson-databind</artifactId>
-    <version>2.20.0</version>
+    <groupId>com.mixpanel</groupId>
+    <artifactId>mixpanel-java-extension-jackson</artifactId>
+    <version>1.6.1</version>
 </dependency>
 ```
 
+Then configure the MixpanelAPI to use it:
+
+```java
+import com.mixpanel.mixpanelapi.internal.JacksonSerializer;
+
+MixpanelAPI mixpanel = new MixpanelAPI.Builder()
+    .jsonSerializer(new JacksonSerializer())
+    .build();
+```
+
 **Key benefits:**
-- **Automatic detection**: The library automatically detects and uses Jackson when available
-- **Backward compatible**: No code changes required - all public APIs remain unchanged
 - **Significant performance gains**: 2-5x faster serialization for batches of 50+ messages
 - **Optimal for `/import`**: Most beneficial when importing large batches (up to 2000 events)
-- **Fallback support**: Gracefully falls back to org.json if Jackson is not available
 
 The performance improvement is most noticeable when:
 - Importing historical data via the `/import` endpoint
 - Sending batches of 50+ events
 - Processing high-volume event streams
 
-No code changes are required to benefit from this optimization - simply add the Jackson dependency to your project.
-
 ## Feature Flags
 
 The Mixpanel Java SDK supports feature flags with both local and remote evaluation modes.
@@ -90,7 +99,9 @@ LocalFlagsConfig config = LocalFlagsConfig.builder()
     .pollingIntervalSeconds(60)
     .build();
 
-MixpanelAPI mixpanel = new MixpanelAPI(config);
+MixpanelAPI mixpanel = new MixpanelAPI.Builder()
+    .flagsConfig(config)
+    .build();
 
 // Start polling for flag definitions
 mixpanel.getLocalFlags().startPollingForDefinitions();
@@ -127,7 +138,7 @@ RemoteFlagsConfig config = RemoteFlagsConfig.builder()
     .projectToken("YOUR_PROJECT_TOKEN")
     .build();
 
-try (MixpanelAPI mixpanel = new MixpanelAPI(config)) {
+try (MixpanelAPI mixpanel = new MixpanelAPI.Builder().flagsConfig(config).build()) {
     Map<String, Object> context = new HashMap<>();
     context.put("distinct_id", "user-456");
 

mixpanel-java-extension-jackson/README.md

@@ -0,0 +1,53 @@
+# Mixpanel Java SDK - Jackson Extension
+
+High-performance Jackson serializer extension for the Mixpanel Java SDK. This extension provides improved JSON serialization performance for large batch operations.
+
+## Installation
+
+Add this dependency to your project:
+
+### Maven
+```xml
+<dependency>
+    <groupId>com.mixpanel</groupId>
+    <artifactId>mixpanel-java-extension-jackson</artifactId>
+    <version>1.6.1</version>
+</dependency>
+```
+
+### Gradle
+```gradle
+implementation 'com.mixpanel:mixpanel-java-extension-jackson:1.6.1'
+```
+
+This extension includes:
+- `mixpanel-java` (core SDK)
+- `jackson-core` 2.20.0
+
+## Usage
+
+To use the Jackson serializer, pass an instance to the MixpanelAPI builder:
+
+```java
+import com.mixpanel.mixpanelapi.MixpanelAPI;
+import com.mixpanel.mixpanelapi.internal.JacksonSerializer;
+
+MixpanelAPI mixpanel = new MixpanelAPI.Builder()
+    .jsonSerializer(new JacksonSerializer())
+    .build();
+```
+
+## Key benefits
+- **Significant performance gains**: 2-5x faster serialization for batches of 50+ messages
+- **Optimal for `/import`**: Most beneficial when importing large batches (up to 2000 events)
+
+The performance improvement is most noticeable when:
+- Importing historical data via the `/import` endpoint
+- Sending batches of 50+ events
+- Processing high-volume event streams
+
+## License
+
+```
+See LICENSE File for details.
+```