Merge remote-tracking branch 'aosp/upstream-master' into merge am: 22b92531fc am: 7902e5747e am: a3c4e39314

Original change: https://android-review.googlesource.com/c/platform/external/mobly-snippet-lib/+/1932020

Change-Id: Id8702566f1ba34c44a867e3f61f4af94b7b4006d

4 files changed, 181 insertions, 0 deletions

diff --git a/examples/ex3_async_event/README.md b/examples/ex3_async_event/README.md
new file mode 100644
index 0000000..edb4fbd
--- /dev/null
+++ b/examples/ex3_async_event/README.md
@@ -0,0 +1,41 @@
+# Async Event RPC Example
+
+This example shows you how to use the @AsyncRpc annotation of Mobly snippet lib
+to handle asynchronous callbacks.
+
+See the source code in `ExampleAsyncSnippet.java` for details.
+
+## Running the example code
+
+This folder contains a fully working example of a standalone snippet apk.
+
+1.  Compile the example
+
+        ./gradlew examples:ex3_async_event:assembleDebug
+
+1.  Install the apk on your phone
+
+        adb install -r ./examples/ex3_async_event/build/outputs/apk/debug/ex3_async_event-debug.apk
+
+1.  Use `snippet_shell` from mobly to trigger `tryEvent()`:
+
+        snippet_shell.py com.google.android.mobly.snippet.example3
+
+        >>> handler = s.tryEvent(42)
+        >>> print("Not blocked, can do stuff here")
+        >>> event = handler.waitAndGet('AsyncTaskResult') # Blocks until the event is received
+
+        Now let's see the content of the event
+
+        >>> import pprint
+        >>> pprint.pprint(event)
+        {
+            'callbackId': '2-1',
+            'name': 'AsyncTaskResult',
+            'time': 20460228696,
+            'data': {
+                'exampleData': "Here's a simple event.",
+                'successful': True,
+                'secretNumber': 12
+            }
+        }
diff --git a/examples/ex3_async_event/build.gradle b/examples/ex3_async_event/build.gradle
new file mode 100644
index 0000000..7327fc4
--- /dev/null
+++ b/examples/ex3_async_event/build.gradle
@@ -0,0 +1,26 @@
+apply plugin: 'com.android.application'
+
+android {
+    compileSdkVersion 31
+
+    defaultConfig {
+        applicationId "com.google.android.mobly.snippet.example3"
+        minSdkVersion 26
+        targetSdkVersion 31
+        versionCode 1
+        versionName "0.0.1"
+    }
+    lintOptions {
+        abortOnError false
+        checkAllWarnings true
+        warningsAsErrors true
+        disable 'HardwareIds','MissingApplicationIcon','GoogleAppIndexingWarning','InvalidPackage','OldTargetApi'
+    }
+}
+
+dependencies {
+    // The 'compile project' dep is to compile against the snippet lib source in
+    // this repo. For your own snippets, you'll want to use the regular 'compile' dep instead:
+    // compile 'com.google.android.mobly:mobly-snippet-lib:1.3.1'
+    implementation project(':mobly-snippet-lib')
+}
diff --git a/examples/ex3_async_event/src/main/AndroidManifest.xml b/examples/ex3_async_event/src/main/AndroidManifest.xml
new file mode 100644
index 0000000..dcc724b
--- /dev/null
+++ b/examples/ex3_async_event/src/main/AndroidManifest.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.google.android.mobly.snippet.example3">
+
+    <application android:allowBackup="false">
+        <meta-data
+            android:name="mobly-snippets"
+            android:value="com.google.android.mobly.snippet.example3.ExampleAsyncSnippet" />
+    </application>
+
+    <instrumentation
+        android:name="com.google.android.mobly.snippet.SnippetRunner"
+        android:targetPackage="com.google.android.mobly.snippet.example3" />
+
+</manifest>
diff --git a/examples/ex3_async_event/src/main/java/com/google/android/mobly/snippet/example3/ExampleAsyncSnippet.java b/examples/ex3_async_event/src/main/java/com/google/android/mobly/snippet/example3/ExampleAsyncSnippet.java
new file mode 100644
index 0000000..a2b22fa
--- /dev/null
+++ b/examples/ex3_async_event/src/main/java/com/google/android/mobly/snippet/example3/ExampleAsyncSnippet.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2017 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.google.android.mobly.snippet.example3;
+
+import com.google.android.mobly.snippet.Snippet;
+import com.google.android.mobly.snippet.event.EventCache;
+import com.google.android.mobly.snippet.event.SnippetEvent;
+import com.google.android.mobly.snippet.rpc.AsyncRpc;
+import com.google.android.mobly.snippet.util.Log;
+
+public class ExampleAsyncSnippet implements Snippet {
+
+    private final EventCache mEventCache = EventCache.getInstance();
+
+    /**
+     * This is a sample asynchronous task.
+     *
+     * In real world use cases, it can be a {@link android.content.BroadcastReceiver}, a Listener,
+     * or any other kind asynchronous callback class.
+     */
+    public class AsyncTask implements Runnable {
+
+        private final String mCallbackId;
+        private final int mSecretNumber;
+
+        public AsyncTask(String callbackId, int secreteNumber) {
+            this.mCallbackId = callbackId;
+            this.mSecretNumber = secreteNumber;
+        }
+
+        /**
+         * Sleeps for 10s then post a {@link SnippetEvent} with some data.
+         *
+         * If the sleep is interrupted, a {@link SnippetEvent} signaling failure will be posted instead.
+         */
+        public void run() {
+            Log.d("Sleeping for 10s before posting an event.");
+            SnippetEvent event = new SnippetEvent(mCallbackId, "AsyncTaskResult");
+            try {
+                Thread.sleep(10000);
+            } catch (InterruptedException e) {
+                event.getData().putBoolean("successful", false);
+                event.getData().putString("reason", "Sleep was interrupted.");
+                mEventCache.postEvent(event);
+            }
+            event.getData().putBoolean("successful", true);
+            event.getData().putString("exampleData", "Here's a simple event.");
+            event.getData().putInt("secretNumber", mSecretNumber);
+            mEventCache.postEvent(event);
+        }
+    }
+
+    /**
+     * An Rpc method demonstrating the async event mechanism.
+     *
+     * This call returns immediately, but starts a task in a separate thread which will post an
+     * event 10s after the task was started.
+     *
+     * Expect to see an event on the client side that looks like:
+     *
+     *    {
+     *        'callbackId': '2-1',
+     *        'name': 'AsyncTaskResult',
+     *        'time': 20460228696,
+     *        'data': {
+     *            'exampleData': "Here's a simple event.",
+     *            'successful': True,
+     *            'secretNumber': 12
+     *        }
+     *    }
+     *
+     * @param callbackId The ID that should be used to tag {@link SnippetEvent} objects triggered by
+     *                   this method.
+     * @throws InterruptedException
+     */
+    @AsyncRpc(description = "This triggers an async event and returns.")
+    public void tryEvent(String callbackId, int secretNumber) throws InterruptedException {
+        Runnable asyncTask = new AsyncTask(callbackId, secretNumber);
+        Thread thread = new Thread(asyncTask);
+        thread.start();
+    }
+    @Override
+    public void shutdown() {}
+}