feat(java-sdk): Add a server-side stateless interface #284

dustinbyrne · 2025-09-22T19:27:47Z

This is a revival of #225:

Create PostHogStateless base class
Add PostHogStatelessInterface
Refactor PostHog to extend PostHogStateless
Update all method signatures to use stateless pattern
Add stateless tests

Additionally, the goal here is to avoid introducing any functional changes to the Android SDK or public interfaces.

💡 Motivation and Context

To expand the core library to support stateless server-side Java applications. Additional Java interoperability changes should follow in another release.

💚 How did you test it?

According to the previous PR:

No new server-side code here, so existing Android tests should suffice for confidence in these changes.

I've added additional unit tests to validate stateless behavior.

📝 Checklist

I reviewed the submitted code.
I added tests to verify the changes.
I updated the docs if needed.
No breaking change or entry added to the changelog.

- Create PostHogStateless base class - Add PostHogStatelessInterface - Refactor PostHog to extend PostHogStateless - Update all method signatures to use stateless pattern - Fix compatibility issues

dustinbyrne · 2025-09-23T21:09:07Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+    private var isPersonProcessingEnabled: Boolean = false
+        get() {
+            synchronized(personProcessingLock) {
+                if (!isPersonProcessingLoaded) {
+                    isPersonProcessingEnabled = getPreferences().getValue(PERSON_PROCESSING) as? Boolean
+                        ?: false
+                    isPersonProcessingLoaded = true
+                }
+            }
+            return field
+        }
+        set(value) {
+            synchronized(personProcessingLock) {
+                // only set if it's different to avoid IO since this is called more often
+                if (field != value) {
+                    field = value
+                    getPreferences().setValue(PERSON_PROCESSING, value)
+                }
+            }
+        }


This is moved, unchanged, from PostHog.isPersonProcessingEnabled

dustinbyrne · 2025-09-23T21:12:24Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+    protected fun mergeGroups(givenGroups: Map<String, String>?): Map<String, String>? {
+        val preferences = getPreferences()
+
+        @Suppress("UNCHECKED_CAST")
+        val groups = preferences.getValue(GROUPS) as? Map<String, String>
+        val newGroups = mutableMapOf<String, String>()
+
+        groups?.let {
+            newGroups.putAll(it)
+        }
+
+        givenGroups?.let {
+            newGroups.putAll(it)
+        }
+
+        return newGroups.ifEmpty { null }
+    }


This is moved, unchanged, from PostHog.mergeGroups

dustinbyrne · 2025-09-23T21:13:34Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+    @Suppress("DEPRECATION")
+    protected fun buildEvent(
+        event: String,
+        distinctId: String,
+        properties: MutableMap<String, Any>,
+    ): PostHogEvent? {
+        // sanitize the properties or fallback to the original properties
+        val sanitizedProperties = config?.propertiesSanitizer?.sanitize(properties)?.toMutableMap() ?: properties
+        val postHogEvent = PostHogEvent(event, distinctId, properties = sanitizedProperties)
+        var eventChecked: PostHogEvent? = postHogEvent
+
+        val beforeSendList = config?.beforeSendList ?: emptyList()
+
+        for (beforeSend in beforeSendList) {
+            try {
+                eventChecked = beforeSend.run(postHogEvent)
+                if (eventChecked == null) {
+                    config?.logger?.log("Event $event was rejected in beforeSend function")
+                    return null
+                }
+            } catch (e: Throwable) {
+                config?.logger?.log("Error in beforeSend function: $e")
+                return null
+            }
+        }
+
+        return eventChecked
+    }


This is moved, unchanged, from PostHog.buildEvent

dustinbyrne · 2025-09-23T21:16:18Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+    protected fun requirePersonProcessing(
+        functionName: String,
+        ignoreMessage: Boolean = false,
+    ): Boolean {
+        if (config?.personProfiles == PersonProfiles.NEVER) {
+            if (!ignoreMessage) {
+                config?.logger?.log("$functionName was called, but `personProfiles` is set to `never`. This call will be ignored.")
+            }
+            return false
+        }
+        isPersonProcessingEnabled = true
+        return true
+    }


This is moved, unchanged, from PostHog.requirePersonProcessing

dustinbyrne · 2025-09-23T21:18:53Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+    private fun hasPersonProcessing(): Boolean {
+        return !(
+            config?.personProfiles == PersonProfiles.NEVER ||
+                (
+                    config?.personProfiles == PersonProfiles.IDENTIFIED_ONLY &&
+                        !isPersonProcessingEnabled
+                )
+        )
+    }


This is moved with a slight logical change (isIdentified is no longer checked) from PostHog.hasPersonProcessing

so the caller should check isIdentified then otherwise it would be different than before

Thanks. isIdentified is being called again (see #284 (comment)).

dustinbyrne · 2025-09-23T21:23:59Z

posthog/src/main/java/com/posthog/PostHog.kt

-
-            props["\$process_person_profile"] = hasPersonProcessing()


This was also removed by the previous branch. Is this correct?

no idea, it should not be gone afaik
we also have on iOS https://github.com/PostHog/posthog-ios/blob/f381818bc153f63fbe13d6822e65cc7233ba4647/PostHog/PostHogSDK.swift#L293

Thanks. I moved all the logic for person processing flags and person profiles back into their original locations (72cdf86). Looking at other server-side/stateless SDKs, it doesn't look like this needs to be a consideration.

dustinbyrne · 2025-09-23T21:27:00Z

posthog/src/main/java/com/posthog/PostHogStateless.kt

+            }
+        }
+
+    private fun buildProperties(


This implementation does differ from the method in PostHog.kt. To my eyes it looked to remove behavior related to session replays, which seems correct.

dustinbyrne · 2025-09-23T21:32:43Z

posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt

+    override fun isFeatureEnabled(
+        key: String,
+        defaultValue: Boolean,
+    ): Boolean {


Re-adding this may have been a mistake during rebase: c5fc361

Yes, this was not intended to be added back in. I've fixed this in d4485b2.

marandaneto · 2025-09-24T06:59:07Z

posthog/api/posthog.api

 	public fun alias (Ljava/lang/String;)V
 	public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V
 	public fun close ()V
-	public fun debug (Z)V


why did we have the debug one?

It moved into PostHogStateless. It should still be callable from this class given we now inherit from PostHogStateless.

marandaneto · 2025-09-24T07:03:28Z

I've not tested anything, one thing to consider is that these changes should not affect react native and flutter
so we have to compile both SDKs pointing to this branch and make sure compilation/feature behaviour stays the same since both SDKs rely on this SDK to do native things

interface Looking at other server-side SDKs, these don't look to be considered.

dustinbyrne · 2025-09-24T22:08:10Z

@marandaneto Thanks for the insights, they've been super helpful. I was able to compile against this branch in both posthog-flutter and posthog-react-native-session-replay. Running the examples, both projects appear to be working as expected.

marandaneto · 2025-09-25T08:29:45Z

@dustinbyrne https://github.com/PostHog/posthog-android/blob/main/RELEASING.md
let me know if you need any assistance

dustinbyrne force-pushed the feat/stateless-iface-2 branch 4 times, most recently from d0d4433 to f32533e Compare September 23, 2025 18:29

feat: Add a server-side stateless interface

72e8663

- Create PostHogStateless base class - Add PostHogStatelessInterface - Refactor PostHog to extend PostHogStateless - Update all method signatures to use stateless pattern - Fix compatibility issues

dustinbyrne force-pushed the feat/stateless-iface-2 branch from f32533e to 72e8663 Compare September 23, 2025 18:35

dustinbyrne marked this pull request as ready for review September 23, 2025 19:15

dustinbyrne requested a review from a team as a code owner September 23, 2025 19:15

dustinbyrne changed the title ~~feat(java-sdk): Add a stateless interface~~ feat(java-sdk): Add a server-side stateless interface Sep 23, 2025

dustinbyrne requested a review from a team September 23, 2025 20:25

dustinbyrne commented Sep 23, 2025

View reviewed changes

fixup! feat: Add a server-side stateless interface

d4485b2

marandaneto reviewed Sep 24, 2025

View reviewed changes

Move person processing / person profile logic out of the stateless

72cdf86

interface Looking at other server-side SDKs, these don't look to be considered.

marandaneto approved these changes Sep 25, 2025

View reviewed changes

dustinbyrne merged commit c3ca27d into main Sep 25, 2025
9 checks passed

dustinbyrne deleted the feat/stateless-iface-2 branch September 25, 2025 14:39

feat(java-sdk): Add a server-side stateless interface #284

feat(java-sdk): Add a server-side stateless interface #284

Uh oh!

Conversation

dustinbyrne commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

Uh oh!

dustinbyrne Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dustinbyrne Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dustinbyrne Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marandaneto commented Sep 24, 2025

Uh oh!

dustinbyrne commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marandaneto commented Sep 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dustinbyrne commented Sep 22, 2025 •

edited

Loading

dustinbyrne Sep 23, 2025 •

edited

Loading

dustinbyrne Sep 23, 2025 •

edited

Loading

dustinbyrne Sep 23, 2025 •

edited

Loading

dustinbyrne commented Sep 24, 2025 •

edited

Loading