docs(flags): Document local eval with Java SDK

Author: dustinbyrne

contents/docs/feature-flags/adding-feature-flag-code.mdx

@@ -26,6 +26,7 @@ import IOSFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/featu
 import FlutterFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/feature-flags-code-flutter.mdx'
 import ElixirFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/feature-flags-code-elixir.mdx'
 import DotNetFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/feature-flags-code-dotnet.mdx'
+import JavaFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/feature-flags-code-java.mdx'
 
 <!-- prettier-ignore -->
 <Tab.Group tabs={['Web', 'React', 'Node.js', 'Python', 'PHP', 'Ruby', 'Go', 'React Native', 'Android', 'iOS', 'Flutter', 'Java', 'Rust', 'Elixir', '.NET', 'api']}>
@@ -82,9 +83,7 @@ import DotNetFeatureFlagsCode from '../integrate/feature-flags-code/_snippets/fe
            <FlutterFeatureFlagsCode />
         </Tab.Panel>
         <Tab.Panel>
-            <blockquote class='warning-note'>
-                Feature flags are not supported yet in our <a href="/docs/libraries/java">Java SDK</a>. However, you can integrate them into your project by using the <a href="/docs/feature-flags/adding-feature-flag-code?tab=api">PostHog API</a>.
-            </blockquote>
+            <JavaFeatureFlagsCode />
         </Tab.Panel>
         <Tab.Panel>
             <blockquote class='warning-note'>

contents/docs/integrate/_snippets/install-java.mdx

@@ -1,14 +1,14 @@
 The best way to install the PostHog Java SDK is with a build system like Gradle or Maven. This ensures you can easily upgrade to the latest versions.
 
-Look up the latest version in [com.posthog.posthog-server](https://central.sonatype.com/artifact/com.posthog/posthog-server).
+Look up the latest version of [`com.posthog.posthog-server`](https://central.sonatype.com/artifact/com.posthog/posthog-server).
 
 #### Gradle
 
 All you need to do is add the `posthog-server` module to your `build.gradle`:
 
 ```gradle_kotlin file=build.gradle
 dependencies {
-  implementation 'com.posthog:posthog-server:1.+'
+  implementation 'com.posthog:posthog-server:2.+'
 }
 ```
 
@@ -26,7 +26,7 @@ All you need to do is add the `posthog-server` module to your `pom.xml`:
 
 #### Other
 
-See [com.posthog.posthog-server](https://central.sonatype.com/artifact/com.posthog/posthog-server) in the Maven Central Repository. Clicking on the latest version shows you options for adding dependencies for other build systems.
+See [`com.posthog.posthog-server`](https://central.sonatype.com/artifact/com.posthog/posthog-server) in the Maven Central Repository. Clicking on the latest version shows you options for adding dependencies for other build systems.
 
 ### Setup
 
@@ -42,13 +42,31 @@ class Sample {
   public static void main(String args[]) {
     PostHogConfig config = PostHogConfig
             .builder(POSTHOG_API_KEY)
-            .host(POSTHOG_HOST)
+            .host(POSTHOG_HOST) // TIP: host is optional if you use https://us.i.posthog.com
             .build();
 
-    PostHogInterface postHog = PostHog.with(config);
+    PostHogInterface posthog = PostHog.with(config);
 
-    postHog.close();  // send the last events in queue
+    posthog.flush(); // send any remaining events
+    posthog.close(); // shut down the client
   }
 }
 ```
 
+## Integrating with Spring
+
+To see how to integrate the PostHog SDK with Spring, check out this [sample project](https://github.com/PostHog/posthog-android/tree/main/posthog-samples/posthog-spring-sample).
+
+## Debug mode
+
+If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. 
+
+To see detailed logging, set the debug configuration option to true.
+
+```java
+  PostHogConfig config = PostHogConfig
+          .builder(POSTHOG_API_KEY)
+          .host(POSTHOG_HOST)
+          .debug(true)
+          .build();
+```

contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-java.mdx

@@ -0,0 +1,26 @@
+### Boolean feature flags
+
+```java
+
+if (posthog.isFeatureEnabled("distinct_id_of_your_user", "flag-key")) {
+    // Do something differently for this user
+
+    // Optional: fetch the payload
+    Object matchedFlagPayload = PostHog.getFeatureFlagPayload("distinct_id_of_your_user", "flag-key")
+}
+```
+
+### Multivariate feature flags
+
+```java
+if ("variant-key".equals(posthog.getFeatureFlag("distinct_id_of_your_user", "flag-key"))) { // replace 'variant-key' with the key of your variant
+    // Do something differently for this user
+
+    // Optional: fetch the payload
+    Object matchedFlagPayload = PostHog.getFeatureFlagPayload("distinct_id_of_your_user", "flag-key")
+}
+```
+
+import JavaOverrideServerProperties from './override-server-properties/java.mdx'
+
+<JavaOverrideServerProperties />

contents/docs/integrate/feature-flags-code/_snippets/override-server-properties/java.mdx

@@ -0,0 +1,24 @@
+import OverrideServerPropertiesIntro from './override-server-properties-intro.mdx'
+
+<OverrideServerPropertiesIntro />
+
+```java
+import com.posthog.server.PostHogFeatureFlagOptions;
+
+posthog.getFeatureFlag(
+    'distinct_id_of_the_user',
+    'flag-key',
+    PostHogFeatureFlagOptions
+        .builder()
+        .defaultValue(false)
+        .group("your_group_type", "your_group_id")
+        .group("another_group_type", "your_group_id")
+        .groupProperty("your_group_type", "group_property_name", "value")
+        .groupProperty("another_group_type", "group_property_name", "value")
+        .personProperty("property_name", "value")
+        .build());
+```
+
+import OverrideGeoIPPropertiesSDK from './override-geoip-properties-SDKs.mdx'
+
+<OverrideGeoIPPropertiesSDK />

contents/docs/libraries/java/index.mdx

@@ -179,7 +179,127 @@ PostHogConfig config = PostHogConfig
 
 ### Local evaluation
 
-While planned, local evaluation of feature flags is not yet supported in the Java SDK. All feature flag evaluations occur remotely via the PostHog API.
+import LocalEvaluationIntro from "../feature-flags/snippets/local-evaluation-intro.mdx"
+
+<LocalEvaluationIntro />
+
+Local evaluation improves performance by fetching flag definitions once and evaluating them locally, rather than making API calls for each flag check.
+
+#### Configuration
+
+To enable local evaluation, you need:
+
+1. A **personal API key** (not your project API key)
+   - Generate one at: PostHog → Settings → Account → Personal API Keys
+2. Enable `localEvaluation` in your config
+
+```java
+PostHogConfig config = PostHogConfig
+    .builder(POSTHOG_API_KEY)
+    .host(POSTHOG_HOST)
+    .personalApiKey("phx_your_personal_api_key_here")
+    .localEvaluation(true)
+    .pollIntervalSeconds(30)  // Optional: customize the rate which flag definitions are polled (default: 30s)
+    .build();
+```
+
+> **Note:** Setting the `personalApiKey` automatically enables `localEvaluation` unless explicitly set to `false`.
+
+#### Usage with person and group properties
+
+For local evaluation to work, you must provide person properties, groups, or group properties that are used in your flag's [release conditions](/docs/feature-flags/creating-feature-flags#release-conditions).
+
+Use `PostHogFeatureFlagOptions` to provide these properties:
+
+**Basic flag evaluation:**
+```java
+boolean isEnabled = postHog.isFeatureEnabled("distinct-id", "flag-key");
+```
+
+**With person properties:**
+```java
+PostHogFeatureFlagOptions options = PostHogFeatureFlagOptions
+    .builder()
+    .defaultValue(false)
+    .personProperty("plan", "premium")
+    .personProperty("email", "[email protected]")
+    .build();
+
+boolean isEnabled = postHog.isFeatureEnabled("distinct-id", "flag-key", options);
+```
+
+**With groups:**
+```java
+PostHogFeatureFlagOptions options = PostHogFeatureFlagOptions
+    .builder()
+    .defaultValue(false)
+    .group("company", "company_id_in_your_db")
+    .build();
+
+boolean isEnabled = postHog.isFeatureEnabled("distinct-id", "flag-key", options);
+```
+
+**With group properties:**
+```java
+PostHogFeatureFlagOptions options = PostHogFeatureFlagOptions
+    .builder()
+    .defaultValue(false)
+    .group("company", "company_id_in_your_db")
+    .groupProperty("company", "industry", "technology")
+    .groupProperty("company", "employees", 500)
+    .build();
+
+boolean isEnabled = postHog.isFeatureEnabled("distinct-id", "flag-key", options);
+```
+
+**Multivariate flags:**
+```java
+PostHogFeatureFlagOptions options = PostHogFeatureFlagOptions
+    .builder()
+    .defaultValue("control")
+    .personProperty("plan", "premium")
+    .group("company", "company_id_in_your_db")
+    .groupProperty("company", "industry", "technology")
+    .build();
+
+Object flagValue = postHog.getFeatureFlag("distinct-id", "algorithm", options);
+String algorithm = flagValue instanceof String ? (String) flagValue : "control";
+switch (algorithm) {
+    case "neural_network":
+        useNeuralNetwork();
+        break;
+    case "collaborative_filtering":
+        useCollaborativeFiltering();
+        break;
+    default:
+        useControlAlgorithm();
+}
+```
+
+#### How it works
+
+1. **On initialization:** PostHog fetches all feature flag definitions using your personal API key
+2. **Periodic updates:** Flag definitions are refreshed every 30 seconds (configurable via `pollIntervalSeconds`)
+3. **Local evaluation:** When you call `getFeatureFlag` or `isFeatureEnabled`, PostHog evaluates the flag locally using the cached definitions
+4. **Automatic fallback:** If local evaluation fails (e.g., missing cohort data), PostHog automatically falls back to making an API call
+5. **Fallback caching:** In the event that a flag must be evaluated remotely with an API call, the result is cached according to the [Feature flag caching](#feature-flag-caching) section.
+#### Benefits
+
+- **Reduced latency**: No API call needed for most flag evaluations
+- **Lower costs**: Fewer API requests (polling is billed as ~10 flag requests per poll)
+- **Offline support**: Flags continue to work with cached definitions
+
+#### Limitations
+
+Local evaluation is **not possible** for flags that:
+
+1. Have **experience continuity** enabled (set when you check "persist flag across authentication steps")
+2. Are linked to an **early access feature**
+3. Depend on **static cohorts**
+
+For these flags, PostHog automatically falls back to remote evaluation via the API.
+
+For more details, see our [local evaluation guide](/docs/feature-flags/local-evaluation).
 
 ### Feature flag caching