Sync client: support applying filter variable updates

Author: greenrobot-team

CHANGELOG.md

@@ -5,6 +5,11 @@ Notable changes to the ObjectBox Java library.
 For more insights into what changed in the database libraries, [check the ObjectBox C changelog](https://github.com/objectbox/objectbox-c/blob/main/CHANGELOG.md).
 
 ## Next release
+                    
+### Sync
+
+- SyncClient: support updating filter variables. After login, stage updates using put and remove, then schedule to send
+  them to the server with `applyFilterVariables()`.
 
 ## 5.2.0 - 2026-02-16
 

objectbox-java/src/main/java/io/objectbox/sync/SyncClient.java

@@ -145,15 +145,25 @@ public interface SyncClient extends Closeable {
      * Eventually, existing values for the same name are replaced.
      * <p>
      * Sync client filter variables can be used in server-side Sync filters to filter out objects that do not match the
-     * filter. Filter variables must be added before login, so before calling {@link #start()}.
+     * filter.
+     * <p>
+     * Filter variables can be set in two states:
+     * <ol>
+     *   <li>Before login (e.g. before calling {@link #start()} or setting credentials): no
+     *       {@link #applyFilterVariables()} call required.</li>
+     *   <li>After login: updates are staged as "pending" until {@link #applyFilterVariables()} is called.</li>
+     * </ol>
      *
      * @see #removeFilterVariable
      * @see #removeAllFilterVariables
+     * @see #applyFilterVariables()
      */
     void putFilterVariable(String name, String value);
 
     /**
      * Removes a previously added Sync filter variable value.
+     * <p>
+     * If used after login, see {@link #putFilterVariable} for notes about {@link #applyFilterVariables}.
      *
      * @see #putFilterVariable
      * @see #removeAllFilterVariables
@@ -162,12 +172,27 @@ public interface SyncClient extends Closeable {
 
     /**
      * Removes all previously added Sync filter variable values.
+     * <p>
+     * If used after login, see {@link #putFilterVariable} for notes about {@link #applyFilterVariables}.
      *
      * @see #putFilterVariable
      * @see #removeFilterVariable
      */
     void removeAllFilterVariables();
 
+    /**
+     * Applies all pending Sync filter variable updates (from {@link #putFilterVariable} and
+     * {@link #removeFilterVariable} calls).
+     * <p>
+     * If the client is connected, sends the updated variables to the server. If the client is not connected,
+     * the updated variables will be included in the next login message.
+     *
+     * @see #putFilterVariable
+     * @see #removeFilterVariable
+     * @see #removeAllFilterVariables
+     */
+    void applyFilterVariables();
+
     /**
      * Sets credentials to authenticate the client with the server.
      * <p>

objectbox-java/src/main/java/io/objectbox/sync/SyncClientImpl.java

@@ -233,6 +233,10 @@ public void removeAllFilterVariables() {
         nativeRemoveAllFilterVariables(getHandle());
     }
 
+    public void applyFilterVariables() {
+        nativeApplyFilterVariables(getHandle());
+    }
+
     @Override
     public void setLoginCredentials(List<SyncCredentials> credentials) {
         if (credentials.size() == 1) {
@@ -467,6 +471,9 @@ public ObjectsMessageBuilder startObjectsMessage(long flags, @Nullable String to
     // extern "C" JNIEXPORT void JNICALL Java_io_objectbox_sync_SyncClientImpl_nativeRemoveAllFilterVariables(JNIEnv* env, jobject, jlong handle)
     private native void nativeRemoveAllFilterVariables(long handle);
 
+    // extern "C" JNIEXPORT void JNICALL Java_io_objectbox_sync_SyncClientImpl_nativeApplyFilterVariables(JNIEnv* env, jobject, jlong handle)
+    private native void nativeApplyFilterVariables(long handle);
+
     private native void nativeSetLoginInfo(long handle, long credentialsType, @Nullable byte[] credentials);
 
     private native void nativeSetLoginInfoUserPassword(long handle, long credentialsType, String username, String password);

tests/objectbox-java-test/src/test/java/io/objectbox/sync/ConnectivityMonitorTest.java

@@ -187,6 +187,10 @@ public void removeFilterVariable(String name) {
         public void removeAllFilterVariables() {
         }
 
+        @Override
+        public void applyFilterVariables() {
+        }
+
         @Override
         public void setLoginCredentials(SyncCredentials credentials) {
         }