Add manual push completion handler support for iOS (#4335)

Fixed #3541 

* Add manual push completion handler support for iOS

Added Display.notifyPushCompletion() to allow applications to manually signal when they have finished handling a push notification on iOS.
This is useful for apps that need to perform background tasks (like playing audio) before the app is suspended.
This feature is enabled by setting the build hint `ios.delayPushCompletion` to `true`.

* Add manual push completion handler support for iOS

Added Display.notifyPushCompletion() to allow applications to manually signal when they have finished handling a push notification on iOS.
This is useful for apps that need to perform background tasks (like playing audio) before the app is suspended.
This feature is enabled by setting the build hint `ios.delayPushCompletion` to `true`.

* Implement cross-platform push completion handling for background tasks.

Added Display.notifyPushCompletion() to manually signal the completion of a background push task (e.g. playing audio).
On iOS, this delays the call to the system completion handler if the `ios.delayPushCompletion` or `delayPushCompletion` property is set.
On Android, this releases a partial WakeLock acquired when the push is received, preventing the device from sleeping during the task if the `android.delayPushCompletion` or `delayPushCompletion` property is set.
Updated `IOSImplementation`, `AndroidImplementation`, and `PushNotificationService` to support this logic.

* Implement cross-platform push completion handling for background tasks (opt-in).

Added Display.notifyPushCompletion() to manually signal the completion of a background push task.
This mechanism is OPT-IN via the `delayPushCompletion` (or `android.delayPushCompletion`/`ios.delayPushCompletion`) build hint.

If the hint is present and true:
- Android: Acquires a `PARTIAL_WAKE_LOCK` upon receiving a push, preventing the device from sleeping until `notifyPushCompletion()` is called (or timeout).
- iOS: Ensures the `remote-notification` background mode is enabled and delays firing the system completion handler until `notifyPushCompletion()` is called.

If the hint is NOT present (default behavior):
- Android: No wake lock is acquired.
- iOS: The completion handler is fired immediately after the push callback.

Updated `IOSImplementation`, `AndroidImplementation`, `PushNotificationService`, `AndroidGradleBuilder`, and `IPhoneBuilder`.

* Implement cross-platform push completion handling for background tasks (opt-in).

Added Display.notifyPushCompletion() to manually signal the completion of a background push task.
This mechanism is OPT-IN via the `delayPushCompletion` (or `android.delayPushCompletion`/`ios.delayPushCompletion`) build hint.

If the hint is present and true:
- Android: Acquires a `PARTIAL_WAKE_LOCK` upon receiving a push, preventing the device from sleeping until `notifyPushCompletion()` is called (or timeout).
- iOS: Ensures the `remote-notification` background mode is enabled and delays firing the system completion handler until `notifyPushCompletion()` is called.

The builders (`IPhoneBuilder`, `AndroidGradleBuilder`) have been updated to check for this hint and automatically:
1. Inject the permission (Android) or capability (iOS) into the native project configuration.
2. Inject the `delayPushCompletion` property into the runtime environment so the logic in `PushNotificationService` and `IOSImplementation` activates.

Updated the developer guide to document this new feature.

* Fix compilation error in AndroidImplementation.

Corrected the placement of `notifyPushCompletion()` in `AndroidImplementation.java` to resolve the "java.lang.Override is not a repeatable annotation type" error caused by improper nesting with `notifyCommandBehavior`.

This completes the cross-platform push completion support feature, which is OPT-IN via the `delayPushCompletion` build hint.

If the hint is present and true:
- Android: Acquires a `PARTIAL_WAKE_LOCK` upon receiving a push, releasing it only when `notifyPushCompletion()` is called.
- iOS: Delays firing the system completion handler until `notifyPushCompletion()` is called.

Builders have been updated to inject the necessary permissions and runtime properties.
Developer guide documentation has been updated.

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

CodenameOne/src/com/codename1/impl/CodenameOneImplementation.java

@@ -1263,6 +1263,12 @@ public void screenshot(SuccessCallback<Image> callback) {
         callback.onSucess(img);
     }
 
+    /**
+     * Notifies the platform that push notification processing is complete.
+     */
+    public void notifyPushCompletion() {
+    }
+
     /**
      * Returns true if the platform supports a native image cache.  The native image cache
      * is different than just {@link FileSystemStorage#hasCachesDir()}.  A native image cache

CodenameOne/src/com/codename1/ui/Display.java

@@ -5152,6 +5152,22 @@ public void screenshot(SuccessCallback<Image> callback) {
         impl.screenshot(callback);
     }
 
+    /**
+     * Notifies the platform that push notification processing is complete.
+     * This is useful on iOS where the app is woken up in the background to handle
+     * a push notification and needs to signal completion to avoid being suspended
+     * prematurely.
+     * <p>
+     * If the {@code ios.delayPushCompletion} build hint (or property) is set to "true",
+     * Codename One will NOT automatically signal completion after the {@link com.codename1.push.PushCallback#push(String)}
+     * method returns. Instead, the application MUST invoke this method manually
+     * when it has finished its background work (e.g. playing audio, downloading content).
+     * </p>
+     */
+    public void notifyPushCompletion() {
+        impl.notifyPushCompletion();
+    }
+
                            /**
      * Convenience method to schedule a task to run on the EDT after {@literal timeout}ms.
      *

Ports/Android/src/com/codename1/impl/android/AndroidImplementation.java

@@ -52,7 +52,8 @@
 import android.graphics.drawable.Drawable;
 import android.media.AudioManager;
 import android.net.Uri;
-import android.os.Vibrator;
+import android.os.Vibrator;
+import android.os.PowerManager;
 import android.telephony.TelephonyManager;
 import android.util.DisplayMetrics;
 import android.util.Log;
@@ -280,6 +281,19 @@ public static void setActivity(CodenameOneActivity aActivity) {
     private int displayHeight;
     static CodenameOneActivity activity;
     static ComponentName activityComponentName;
+    private static PowerManager.WakeLock pushWakeLock;
+    public static void acquirePushWakeLock(long timeout) {
+        if (getContext() == null) return;
+        try {
+            if (pushWakeLock == null) {
+                PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
+                pushWakeLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "CN1:PushWakeLock");
+            }
+            pushWakeLock.acquire(timeout);
+        } catch (Exception ex) {
+            com.codename1.io.Log.e(ex);
+        }
+    }
 
     private static Context context;
     RelativeLayout relativeLayout;
@@ -2783,7 +2797,18 @@ public void exitApplication() {
         android.os.Process.killProcess(android.os.Process.myPid());
     }
 
-    @Override
+    @Override
+    public void notifyPushCompletion() {
+        if (pushWakeLock != null && pushWakeLock.isHeld()) {
+            try {
+                pushWakeLock.release();
+            } catch (Exception ex) {
+                com.codename1.io.Log.e(ex);
+            }
+        }
+    }
+
+    @Override
     public void notifyCommandBehavior(int commandBehavior) {
         if (commandBehavior == Display.COMMAND_BEHAVIOR_NATIVE) {
             if (getActivity() instanceof CodenameOneActivity) {

Ports/Android/src/com/codename1/impl/android/PushNotificationService.java

@@ -109,9 +109,20 @@ public void onDestroy() {
     public void push(final String value) {
         final PushCallback callback = getPushCallbackInstance();
         if(callback != null) {
+            final boolean delayPushCompletion = "true".equals(Display.getInstance().getProperty("delayPushCompletion", "false")) ||
+                    "true".equals(Display.getInstance().getProperty("android.delayPushCompletion", "false"));
+            if (delayPushCompletion) {
+                AndroidImplementation.acquirePushWakeLock(30000);
+            }
             Display.getInstance().callSerially(new Runnable() {
                 public void run() {
-                    callback.push(value);
+                    try {
+                        callback.push(value);
+                    } finally {
+                        if (!delayPushCompletion) {
+                            Display.getInstance().notifyPushCompletion();
+                        }
+                    }
                 }
             });
         } else {

Ports/iOSPort/src/com/codename1/impl/ios/IOSImplementation.java

@@ -8115,7 +8115,10 @@ public void run() {
 
                         pushCallback.push(message);
                     } finally {
-                        nativeInstance.firePushCompletionHandler();
+                        if (!"true".equals(Display.getInstance().getProperty("delayPushCompletion", "false")) &&
+                            !"true".equals(Display.getInstance().getProperty("ios.delayPushCompletion", "false"))) {
+                            nativeInstance.firePushCompletionHandler();
+                        }
                     }
                 }
             });

docs/developer-guide/Push-Notifications.asciidoc

@@ -87,6 +87,44 @@ NOTE: On iOS, hidden push messages (push type 2) will not be delivered when the
 
 TIP: You can set the `android.background_push_handling` build hint to "true" to deliver push messages on Android when the app is minimized (running in the background).  There is no equivalent setting on other platforms currently.
 
+[[delay-push-completion]]
+=== Handling Long-Running Background Push Tasks
+
+By default, the platform signals the completion of the push processing immediately after your `push(String)` callback returns.  However, some tasks, such as playing audio (e.g. for Push-To-Talk apps), require more time to complete.  If the app is in the background, the OS might suspend the app before the task completes if it thinks the push handling is finished.
+
+To handle this, you can opt-in to manually signaling the completion of the push task using the `delayPushCompletion` build hint.
+
+1.  Add the `delayPushCompletion=true` build hint to your `codenameone_settings.properties`.
+2.  In your `push(String)` callback, start your asynchronous task.
+3.  When your task is complete, call `Display.getInstance().notifyPushCompletion()`.
+
+Example:
+
+[source,java]
+----
+public void push(String message) {
+    if (isAudioMessage(message)) {
+        // Play audio asynchronously
+        playAudio(message, new Runnable() {
+            public void run() {
+                // Audio finished playing
+                Display.getInstance().notifyPushCompletion();
+            }
+        });
+    } else {
+        // For standard messages, we can notify immediately or let it timeout (safest to notify)
+        Display.getInstance().notifyPushCompletion();
+    }
+}
+----
+
+**How it works:**
+
+*   **Android:** The system acquires a `PARTIAL_WAKE_LOCK` when the push is received, keeping the CPU running even if the screen is off.  Calling `notifyPushCompletion()` releases this lock.  The lock has a safety timeout (e.g., 30 seconds) to prevent battery drain if you forget to call it.
+*   **iOS:** The system delays calling the completion handler passed to the push delegate.  This gives your app background execution time.  Calling `notifyPushCompletion()` invokes the system completion handler.
+
+NOTE: If you enable this feature, you **must** call `Display.getInstance().notifyPushCompletion()` in all code paths of your `push()` callback to ensure the device can sleep/suspend properly.
+
 
 === Testing Push Support
 

maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/AndroidGradleBuilder.java

@@ -1163,6 +1163,10 @@ public boolean build(File sourceZip, final BuildRequest request) throws BuildExc
         playFlag = "true";
 
         gpsPermission = request.getArg("android.gpsPermission", "false").equals("true");
+        if (request.getArg("android.delayPushCompletion", "false").equals("true") ||
+                request.getArg("delayPushCompletion", "false").equals("true")) {
+            wakeLock = true;
+        }
         mediaPlaybackPermission = false;
         try {
             scanClassesForPermissions(dummyClassesDir, new Executor.ClassScanner() {
@@ -3894,6 +3898,10 @@ private String createOnDestroyCode(BuildRequest request) {
 
     private String createPostInitCode(BuildRequest request) {
         String retVal = "";
+        if (request.getArg("android.delayPushCompletion", "false").equals("true") ||
+                request.getArg("delayPushCompletion", "false").equals("true")) {
+            retVal += "Display.getInstance().setProperty(\"android.delayPushCompletion\", \"true\");\n";
+        }
         return retVal;
     }
 

maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/IPhoneBuilder.java

@@ -956,8 +956,14 @@ public void usesClassMethod(String cls, String method) {
                     + "    private boolean stopped = false;\n";
 
                 stubSourceCode += decodeFunction();
+                String delayPushCompletion = "";
+                if ("true".equals(request.getArg("ios.delayPushCompletion", "false")) ||
+                    "true".equals(request.getArg("delayPushCompletion", "false"))) {
+                    delayPushCompletion = "        Display.getInstance().setProperty(\"ios.delayPushCompletion\", \"true\");\n";
+                }
                 stubSourceCode += "    public void run() {\n"
                     + "        Display.getInstance().setProperty(\"package_name\", PACKAGE_NAME);\n"
+                    + delayPushCompletion
                     + "        Display.getInstance().setProperty(\"AppVersion\", APPLICATION_VERSION);\n"
                     + "        Display.getInstance().setProperty(\"AppName\", APPLICATION_NAME);\n"
                     + newStorage
@@ -2380,7 +2386,8 @@ public boolean accept(File file, String string) {
             }
         }
         String backgroundModesStr = request.getArg("ios.background_modes", null);
-        if (includePush) {
+        if (includePush || "true".equals(request.getArg("ios.delayPushCompletion", "false")) ||
+                "true".equals(request.getArg("delayPushCompletion", "false"))) {
             if (backgroundModesStr == null || !backgroundModesStr.contains("remote-notification")) {
                 if (backgroundModesStr == null) {
                     backgroundModesStr = "";