Add a pigeon sample that demonstrates a "realistic" integration scenario with middleware and business logic (#465)

Author: xster

add_to_app/README.md

@@ -10,11 +10,13 @@ standalone Flutter module.
   - Whether to build the Flutter module from source each time the app builds or
     rely on a separately pre-built module.
   - Whether plugins are needed by the Flutter module used in the app.
+* Show Flutter being integrated ergonomically with applications with existing
+  middleware and business logic data classes.
 
 ## Installing Cocoapods
 
 The iOS samples in this repo require the latest version of Cocoapods. To install
-it, run the following command on a MacOS machine:
+it, run the following command on a macOS machine:
 
 ```bash
 sudo gem install cocoapods
@@ -26,20 +28,26 @@ See https://guides.cocoapods.org/using/getting-started.html for more details.
 
 ### Flutter modules
 
-There are two Flutter modules included in the codebase:
+There are three Flutter modules included in the codebase:
 
 * `flutter_module` displays the dimensions of the screen, a button that
   increments a simple counter, and an optional exit button.
 * `flutter_module_using_plugin` does everything `flutter_module` does and adds
   another button that will open the Flutter documentation in a browser using the
   [`url_launcher`](https://pub.dev/packages/url_launcher) Flutter plugin.
+* `flutter_module_books` simulates an integration scenario with existing
+  platform business logic and middleware. It uses the [`pigeon`](https://pub.dev/packages/pigeon)
+  plugin to make integration easier by generating the platform channel
+  interop inside wrapper API and data classes that are shared between the
+  platform and Flutter.
+
 
 Before using them, you need to resolve the Flutter modules' dependencies. Do so
 by running this command from within the `flutter_module` and
 `flutter_module_using_plugin` directories:
 
 ```bash
-flutter packages get
+flutter pub get
 ```
 
 ### Android and iOS applications
@@ -139,6 +147,50 @@ Flutter frameworks, see this article in the Flutter GitHub wiki:
 
 https://flutter.dev/docs/development/add-to-app/ios/project-setup
 
+### `android_books` and `ios_books (TODO)`
+
+These apps integrate the `flutter_books` module using the simpler build-together
+project setup. They simulate a mock scenario where an existing book catalog
+list app already exists. Flutter is used to implement an additional book details
+page.
+
+* Similar to `android_fullscreen` and `ios_fullscreen`.
+* An existing books catalog app is already implemented in Kotlin and Swift.
+* The platform-side app has existing middleware constraints that should also
+  be the middleware foundation for the additional Flutter screen.
+    * On Android, the Kotlin app already uses GSON and OkHttp for networking and
+      references the Google Books API as a data source. These same libraries
+      also underpin the data fetched and shown in the Flutter screen.
+    * iOS TODO.
+* The platform application interfaces with the Flutter book details page using
+  idiomatic platform API conventions rather than Flutter conventions.
+    * On Android, the Flutter activity receives the book to show via activity
+      intent and returns the edited book by setting the result intent on the
+      activity. No Flutter concepts are leaked into the consumer activity.
+    * iOS TODO.
+* The [pigeon](https://pub.dev/packages/pigeon) plugin is used to generate
+  interop APIs and data classes. The same `Book` model class is used within the
+  Kotlin/Swift program, the Dart program and in the interop between Kotlin/Swift
+  and Dart. No manual platform channel plumbing needed for interop.
+    * The `api.dart/java/mm` files generated from the
+      `flutter_module_books/pigeon/schema.dart` file are checked into source
+      control. Therefore `pigeon` is only a dev dependency with no runtime
+      requirements.
+    * If the `schema.dart` is modified, the generated classes can be updated with
+
+        ```shell
+        flutter pub run pigeon \
+            --input pigeon/schema.dart \
+            --java_out ../android_books/app/src/main/java/dev/flutter/example/books/Api.java \
+            --java_package "dev.flutter.example.books"
+        ```
+
+      in the `flutter_module_books` directory.
+
+Once you've understood the basics of add-to-app with `android_fullscreen` and
+`ios_fullscreen`, this is a good sample to demonstrate how to integrate Flutter
+in a slightly more realistic setting with existing business logic.
+
 ## Questions/issues
 
 If you have a general question about incorporating Flutter into an existing

add_to_app/android_books/.gitignore

@@ -0,0 +1,14 @@
+*.iml
+.gradle
+/local.properties
+/.idea/caches
+/.idea/libraries
+/.idea/modules.xml
+/.idea/workspace.xml
+/.idea/navEditor.xml
+/.idea/assetWizardSettings.xml
+.DS_Store
+/build
+/captures
+.externalNativeBuild
+.cxx

add_to_app/android_books/app/.gitignore

@@ -0,0 +1 @@
+/build

add_to_app/android_books/app/build.gradle

@@ -0,0 +1,49 @@
+apply plugin: 'com.android.application'
+apply plugin: 'kotlin-android'
+apply plugin: 'kotlin-android-extensions'
+
+android {
+    compileSdkVersion 29
+    buildToolsVersion "29.0.3"
+
+    defaultConfig {
+        applicationId "dev.flutter.example.books"
+        minSdkVersion 16
+        targetSdkVersion 29
+        versionCode 1
+        versionName "1.0"
+
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+}
+
+dependencies {
+    implementation fileTree(dir: "libs", include: ["*.jar"])
+    implementation "com.squareup.okhttp3:okhttp:4.7.2"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation 'androidx.core:core-ktx:1.3.0'
+    implementation 'androidx.appcompat:appcompat:1.1.0'
+    implementation "androidx.activity:activity-ktx:1.1.0"
+    implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
+    implementation 'com.google.android.material:material:1.1.0'
+    implementation 'com.google.code.gson:gson:2.8.6'
+    implementation project(path: ':flutter')
+    testImplementation 'junit:junit:4.13'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.1'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
+
+}

add_to_app/android_books/app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

add_to_app/android_books/app/src/androidTest/java/dev/flutter/example/books/ExampleInstrumentedTest.kt

@@ -0,0 +1,27 @@
+package dev.flutter.example.books
+
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.ext.junit.runners.AndroidJUnit4
+
+import org.junit.Test
+import org.junit.runner.RunWith
+
+import org.junit.Assert.*
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * See [testing documentation](http://d.android.com/tools/testing).
+ */
+@RunWith(AndroidJUnit4::class)
+class MainActivityTest {
+    @Test
+    fun useAppContext() {
+        // Context of the app under test.
+        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
+        assertEquals("dev.flutter.example.books", appContext.packageName)
+    }
+
+    // The app should be hermetic (with offline books JSON) before adding
+    // more tests.
+}

add_to_app/android_books/app/src/main/AndroidManifest.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="dev.flutter.example.books">
+
+    <application
+        android:name=".BookApplication"
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme">
+        <activity android:name=".MainActivity">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+        <activity
+            android:name=".FlutterBookActivity"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize" />
+    </application>
+    <uses-permission android:name="android.permission.INTERNET" />
+
+</manifest>

add_to_app/android_books/app/src/main/java/dev/flutter/example/books/Api.java

@@ -0,0 +1,143 @@
+// Autogenerated from Pigeon (v0.1.0), do not edit directly.
+// See also: https://pub.dev/packages/pigeon
+
+package dev.flutter.example.books;
+
+import java.util.HashMap;
+
+import io.flutter.plugin.common.BasicMessageChannel;
+import io.flutter.plugin.common.BinaryMessenger;
+import io.flutter.plugin.common.StandardMessageCodec;
+
+/** Generated class from Pigeon. */
+public class Api {
+
+  /** Generated class from Pigeon that represents data sent in messages. */
+  public static class Book {
+    private String title;
+    public String getTitle() { return title; }
+    public void setTitle(String setterArg) { this.title = setterArg; }
+
+    private String subtitle;
+    public String getSubtitle() { return subtitle; }
+    public void setSubtitle(String setterArg) { this.subtitle = setterArg; }
+
+    private String author;
+    public String getAuthor() { return author; }
+    public void setAuthor(String setterArg) { this.author = setterArg; }
+
+    private String description;
+    public String getDescription() { return description; }
+    public void setDescription(String setterArg) { this.description = setterArg; }
+
+    private String publishDate;
+    public String getPublishDate() { return publishDate; }
+    public void setPublishDate(String setterArg) { this.publishDate = setterArg; }
+
+    private Long pageCount;
+    public Long getPageCount() { return pageCount; }
+    public void setPageCount(Long setterArg) { this.pageCount = setterArg; }
+
+    HashMap toMap() {
+      HashMap<String, Object> toMapResult = new HashMap<String, Object>();
+      toMapResult.put("title", title);
+      toMapResult.put("subtitle", subtitle);
+      toMapResult.put("author", author);
+      toMapResult.put("description", description);
+      toMapResult.put("publishDate", publishDate);
+      toMapResult.put("pageCount", pageCount);
+      return toMapResult;
+    }
+    static Book fromMap(HashMap map) {
+      Book fromMapResult = new Book();
+      fromMapResult.title = (String)map.get("title");
+      fromMapResult.subtitle = (String)map.get("subtitle");
+      fromMapResult.author = (String)map.get("author");
+      fromMapResult.description = (String)map.get("description");
+      fromMapResult.publishDate = (String)map.get("publishDate");
+      fromMapResult.pageCount = (map.get("pageCount") instanceof Integer) ? (Integer)map.get("pageCount") : (Long)map.get("pageCount");
+      return fromMapResult;
+    }
+  }
+
+  /** Generated class from Pigeon that represents Flutter messages that can be called from Java.*/
+  public static class FlutterBookApi {
+    private BinaryMessenger binaryMessenger;
+    public FlutterBookApi(BinaryMessenger argBinaryMessenger){
+      this.binaryMessenger = argBinaryMessenger;
+    }
+    public interface Reply<T> {
+      void reply(T reply);
+    }
+    public void displayBookDetails(Book argInput, Reply<Void> callback) {
+      BasicMessageChannel<Object> channel =
+          new BasicMessageChannel<Object>(binaryMessenger, "dev.flutter.pigeon.FlutterBookApi.displayBookDetails", new StandardMessageCodec());
+      HashMap inputMap = argInput.toMap();
+      channel.send(inputMap, new BasicMessageChannel.Reply<Object>() {
+        public void reply(Object channelReply) {
+          callback.reply(null);
+        }
+      });
+    }
+  }
+
+  /** Generated interface from Pigeon that represents a handler of messages from Flutter.*/
+  public interface HostBookApi {
+    void cancel();
+    void finishEditingBook(Book arg);
+
+    /** Sets up an instance of `HostBookApi` to handle messages through the `binaryMessenger` */
+    static void setup(BinaryMessenger binaryMessenger, HostBookApi api) {
+      {
+        BasicMessageChannel<Object> channel =
+            new BasicMessageChannel<Object>(binaryMessenger, "dev.flutter.pigeon.HostBookApi.cancel", new StandardMessageCodec());
+        if (api != null) {
+          channel.setMessageHandler(new BasicMessageChannel.MessageHandler<Object>() {
+            public void onMessage(Object message, BasicMessageChannel.Reply<Object> reply) {
+              HashMap<String, HashMap> wrapped = new HashMap<String, HashMap>();
+              try {
+                api.cancel();
+                wrapped.put("result", null);
+              }
+              catch (Exception exception) {
+                wrapped.put("error", wrapError(exception));
+              }
+              reply.reply(wrapped);
+            }
+          });
+        } else {
+          channel.setMessageHandler(null);
+        }
+      }
+      {
+        BasicMessageChannel<Object> channel =
+            new BasicMessageChannel<Object>(binaryMessenger, "dev.flutter.pigeon.HostBookApi.finishEditingBook", new StandardMessageCodec());
+        if (api != null) {
+          channel.setMessageHandler(new BasicMessageChannel.MessageHandler<Object>() {
+            public void onMessage(Object message, BasicMessageChannel.Reply<Object> reply) {
+              Book input = Book.fromMap((HashMap)message);
+              HashMap<String, HashMap> wrapped = new HashMap<String, HashMap>();
+              try {
+                api.finishEditingBook(input);
+                wrapped.put("result", null);
+              }
+              catch (Exception exception) {
+                wrapped.put("error", wrapError(exception));
+              }
+              reply.reply(wrapped);
+            }
+          });
+        } else {
+          channel.setMessageHandler(null);
+        }
+      }
+    }
+  }
+  private static HashMap wrapError(Exception exception) {
+    HashMap<String, Object> errorMap = new HashMap<String, Object>();
+    errorMap.put("message", exception.toString());
+    errorMap.put("code", null);
+    errorMap.put("details", null);
+    return errorMap;
+  }
+}